1 /////////////////////////////////////////////////////////////////////////////// 2 // 3 /// \file tuklib_mbstr.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 67