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