12940b44dSPeter Avalos /////////////////////////////////////////////////////////////////////////////// 22940b44dSPeter Avalos // 3*e151908bSDaniel Fojt /// \file tuklib_mbstr.h 42940b44dSPeter Avalos /// \brief Utility functions for handling multibyte strings 52940b44dSPeter Avalos /// 62940b44dSPeter Avalos /// If not enough multibyte string support is available in the C library, 72940b44dSPeter Avalos /// these functions keep working with the assumption that all strings 82940b44dSPeter Avalos /// are in a single-byte character set without combining characters, e.g. 92940b44dSPeter Avalos /// US-ASCII or ISO-8859-*. 102940b44dSPeter Avalos // 112940b44dSPeter Avalos // Author: Lasse Collin 122940b44dSPeter Avalos // 132940b44dSPeter Avalos // This file has been put into the public domain. 142940b44dSPeter Avalos // You can do whatever you want with this file. 152940b44dSPeter Avalos // 162940b44dSPeter Avalos /////////////////////////////////////////////////////////////////////////////// 172940b44dSPeter Avalos 182940b44dSPeter Avalos #ifndef TUKLIB_MBSTR_H 192940b44dSPeter Avalos #define TUKLIB_MBSTR_H 202940b44dSPeter Avalos 212940b44dSPeter Avalos #include "tuklib_common.h" 222940b44dSPeter Avalos TUKLIB_DECLS_BEGIN 232940b44dSPeter Avalos 242940b44dSPeter Avalos #define tuklib_mbstr_width TUKLIB_SYMBOL(tuklib_mbstr_width) 252940b44dSPeter Avalos extern size_t tuklib_mbstr_width(const char *str, size_t *bytes); 262940b44dSPeter Avalos ///< 272940b44dSPeter Avalos /// \brief Get the number of columns needed for the multibyte string 282940b44dSPeter Avalos /// 292940b44dSPeter Avalos /// This is somewhat similar to wcswidth() but works on multibyte strings. 302940b44dSPeter Avalos /// 312940b44dSPeter Avalos /// \param str String whose width is to be calculated. If the 322940b44dSPeter Avalos /// current locale uses a multibyte character set 332940b44dSPeter Avalos /// that has shift states, the string must begin 342940b44dSPeter Avalos /// and end in the initial shift state. 352940b44dSPeter Avalos /// \param bytes If this is not NULL, *bytes is set to the 362940b44dSPeter Avalos /// value returned by strlen(str) (even if an 372940b44dSPeter Avalos /// error occurs when calculating the width). 382940b44dSPeter Avalos /// 392940b44dSPeter Avalos /// \return On success, the number of columns needed to display the 402940b44dSPeter Avalos /// string e.g. in a terminal emulator is returned. On error, 412940b44dSPeter Avalos /// (size_t)-1 is returned. Possible errors include invalid, 422940b44dSPeter Avalos /// partial, or non-printable multibyte character in str, or 432940b44dSPeter Avalos /// that str doesn't end in the initial shift state. 442940b44dSPeter Avalos 452940b44dSPeter Avalos #define tuklib_mbstr_fw TUKLIB_SYMBOL(tuklib_mbstr_fw) 462940b44dSPeter Avalos extern int tuklib_mbstr_fw(const char *str, int columns_min); 472940b44dSPeter Avalos ///< 482940b44dSPeter Avalos /// \brief Get the field width for printf() e.g. to align table columns 492940b44dSPeter Avalos /// 502940b44dSPeter Avalos /// Printing simple tables to a terminal can be done using the field field 512940b44dSPeter Avalos /// feature in the printf() format string, but it works only with single-byte 522940b44dSPeter Avalos /// character sets. To do the same with multibyte strings, tuklib_mbstr_fw() 532940b44dSPeter Avalos /// can be used to calculate appropriate field width. 542940b44dSPeter Avalos /// 552940b44dSPeter Avalos /// The behavior of this function is undefined, if 562940b44dSPeter Avalos /// - str is NULL or not terminated with '\0'; 572940b44dSPeter Avalos /// - columns_min <= 0; or 582940b44dSPeter Avalos /// - the calculated field width exceeds INT_MAX. 592940b44dSPeter Avalos /// 602940b44dSPeter Avalos /// \return If tuklib_mbstr_width(str, NULL) fails, -1 is returned. 612940b44dSPeter Avalos /// If str needs more columns than columns_min, zero is returned. 622940b44dSPeter Avalos /// Otherwise a positive integer is returned, which can be 632940b44dSPeter Avalos /// used as the field width, e.g. printf("%*s", fw, str). 642940b44dSPeter Avalos 652940b44dSPeter Avalos TUKLIB_DECLS_END 662940b44dSPeter Avalos #endif 67