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" 22TUKLIB_DECLS_BEGIN 23 24#define tuklib_mbstr_width TUKLIB_SYMBOL(tuklib_mbstr_width) 25extern 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) 46extern 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 65TUKLIB_DECLS_END 66#endif 67