OLD | NEW |
(Empty) | |
| 1 /////////////////////////////////////////////////////////////////////////////// |
| 2 // |
| 3 /// \file tuklib_mstr.h |
| 4 /// \brief Utility functions for handling multibyte strings |
| 5 /// |
| 6 /// If not enough multibyte string support is available in the C library, |
| 7 /// these functions keep working with the assumption that all strings |
| 8 /// are in a single-byte character set without combining characters, e.g. |
| 9 /// US-ASCII or ISO-8859-*. |
| 10 // |
| 11 // Author: Lasse Collin |
| 12 // |
| 13 // This file has been put into the public domain. |
| 14 // You can do whatever you want with this file. |
| 15 // |
| 16 /////////////////////////////////////////////////////////////////////////////// |
| 17 |
| 18 #ifndef TUKLIB_MBSTR_H |
| 19 #define TUKLIB_MBSTR_H |
| 20 |
| 21 #include "tuklib_common.h" |
| 22 TUKLIB_DECLS_BEGIN |
| 23 |
| 24 #define tuklib_mbstr_width TUKLIB_SYMBOL(tuklib_mbstr_width) |
| 25 extern size_t tuklib_mbstr_width(const char *str, size_t *bytes); |
| 26 ///< |
| 27 /// \brief Get the number of columns needed for the multibyte string |
| 28 /// |
| 29 /// This is somewhat similar to wcswidth() but works on multibyte strings. |
| 30 /// |
| 31 /// \param str String whose width is to be calculated. If the |
| 32 /// current locale uses a multibyte character set |
| 33 /// that has shift states, the string must begin |
| 34 /// and end in the initial shift state. |
| 35 /// \param bytes If this is not NULL, *bytes is set to the |
| 36 /// value returned by strlen(str) (even if an |
| 37 /// error occurs when calculating the width). |
| 38 /// |
| 39 /// \return On success, the number of columns needed to display the |
| 40 /// string e.g. in a terminal emulator is returned. On error, |
| 41 /// (size_t)-1 is returned. Possible errors include invalid, |
| 42 /// partial, or non-printable multibyte character in str, or |
| 43 /// that str doesn't end in the initial shift state. |
| 44 |
| 45 #define tuklib_mbstr_fw TUKLIB_SYMBOL(tuklib_mbstr_fw) |
| 46 extern int tuklib_mbstr_fw(const char *str, int columns_min); |
| 47 ///< |
| 48 /// \brief Get the field width for printf() e.g. to align table columns |
| 49 /// |
| 50 /// Printing simple tables to a terminal can be done using the field field |
| 51 /// feature in the printf() format string, but it works only with single-byte |
| 52 /// character sets. To do the same with multibyte strings, tuklib_mbstr_fw() |
| 53 /// can be used to calculate appropriate field width. |
| 54 /// |
| 55 /// The behavior of this function is undefined, if |
| 56 /// - str is NULL or not terminated with '\0'; |
| 57 /// - columns_min <= 0; or |
| 58 /// - the calculated field width exceeds INT_MAX. |
| 59 /// |
| 60 /// \return If tuklib_mbstr_width(str, NULL) fails, -1 is returned. |
| 61 /// If str needs more columns than columns_min, zero is returned. |
| 62 /// Otherwise a positive integer is returned, which can be |
| 63 /// used as the field width, e.g. printf("%*s", fw, str). |
| 64 |
| 65 TUKLIB_DECLS_END |
| 66 #endif |
OLD | NEW |