1 // SPDX-License-Identifier: 0BSD 2 3 /////////////////////////////////////////////////////////////////////////////// 4 // 5 /// \file tuklib_mbstr.h 6 /// \brief Utility functions for handling multibyte strings 7 /// 8 /// If not enough multibyte string support is available in the C library, 9 /// these functions keep working with the assumption that all strings 10 /// are in a single-byte character set without combining characters, e.g. 11 /// US-ASCII or ISO-8859-*. 12 // 13 // Author: Lasse Collin 14 // 15 /////////////////////////////////////////////////////////////////////////////// 16 17 #ifndef TUKLIB_MBSTR_H 18 #define TUKLIB_MBSTR_H 19 20 #include "tuklib_common.h" 21 TUKLIB_DECLS_BEGIN 22 23 #define tuklib_mbstr_width TUKLIB_SYMBOL(tuklib_mbstr_width) 24 extern size_t tuklib_mbstr_width(const char *str, size_t *bytes); 25 ///< 26 /// \brief Get the number of columns needed for the multibyte string 27 /// 28 /// This is somewhat similar to wcswidth() but works on multibyte strings. 29 /// 30 /// \param str String whose width is to be calculated. 31 /// \param bytes If this is not NULL, *bytes is set to the 32 /// value returned by strlen(str) (even if an 33 /// error occurs when calculating the width). 34 /// 35 /// \return On success, the number of columns needed to display the 36 /// string e.g. in a terminal emulator is returned. On error, 37 /// (size_t)-1 is returned. Possible errors include invalid, 38 /// partial, or non-printable multibyte character in str. 39 40 #define tuklib_mbstr_width_mem TUKLIB_SYMBOL(tuklib_mbstr_width_mem) 41 extern size_t tuklib_mbstr_width_mem(const char *str, size_t len); 42 ///< 43 /// \brief Get the number of columns needed for the multibyte buffer 44 /// 45 /// This is like tuklib_mbstr_width() except that this takes the buffer 46 /// length in bytes as the second argument. This allows using the function 47 /// for buffers that aren't terminated with '\0'. 48 /// 49 /// \param str String whose width is to be calculated. 50 /// \param len Number of bytes to read from str. 51 /// 52 /// \return On success, the number of columns needed to display the 53 /// string e.g. in a terminal emulator is returned. On error, 54 /// (size_t)-1 is returned. Possible errors include invalid, 55 /// partial, or non-printable multibyte character in str. 56 57 #define tuklib_mbstr_fw TUKLIB_SYMBOL(tuklib_mbstr_fw) 58 extern int tuklib_mbstr_fw(const char *str, int columns_min); 59 ///< 60 /// \brief Get the field width for printf() e.g. to align table columns 61 /// 62 /// Printing simple tables to a terminal can be done using the field field 63 /// feature in the printf() format string, but it works only with single-byte 64 /// character sets. To do the same with multibyte strings, tuklib_mbstr_fw() 65 /// can be used to calculate appropriate field width. 66 /// 67 /// The behavior of this function is undefined, if 68 /// - str is NULL or not terminated with '\0'; 69 /// - columns_min <= 0; or 70 /// - the calculated field width exceeds INT_MAX. 71 /// 72 /// \return If tuklib_mbstr_width(str, NULL) fails, -1 is returned. 73 /// If str needs more columns than columns_min, zero is returned. 74 /// Otherwise a positive integer is returned, which can be 75 /// used as the field width, e.g. printf("%*s", fw, str). 76 77 TUKLIB_DECLS_END 78 #endif 79