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. If the 31 /// current locale uses a multibyte character set 32 /// that has shift states, the string must begin 33 /// and end in the initial shift state. 34 /// \param bytes If this is not NULL, *bytes is set to the 35 /// value returned by strlen(str) (even if an 36 /// error occurs when calculating the width). 37 /// 38 /// \return On success, the number of columns needed to display the 39 /// string e.g. in a terminal emulator is returned. On error, 40 /// (size_t)-1 is returned. Possible errors include invalid, 41 /// partial, or non-printable multibyte character in str, or 42 /// that str doesn't end in the initial shift state. 43 44 #define tuklib_mbstr_fw TUKLIB_SYMBOL(tuklib_mbstr_fw) 45 extern int tuklib_mbstr_fw(const char *str, int columns_min); 46 ///< 47 /// \brief Get the field width for printf() e.g. to align table columns 48 /// 49 /// Printing simple tables to a terminal can be done using the field field 50 /// feature in the printf() format string, but it works only with single-byte 51 /// character sets. To do the same with multibyte strings, tuklib_mbstr_fw() 52 /// can be used to calculate appropriate field width. 53 /// 54 /// The behavior of this function is undefined, if 55 /// - str is NULL or not terminated with '\0'; 56 /// - columns_min <= 0; or 57 /// - the calculated field width exceeds INT_MAX. 58 /// 59 /// \return If tuklib_mbstr_width(str, NULL) fails, -1 is returned. 60 /// If str needs more columns than columns_min, zero is returned. 61 /// Otherwise a positive integer is returned, which can be 62 /// used as the field width, e.g. printf("%*s", fw, str). 63 64 TUKLIB_DECLS_END 65 #endif 66