src/common/tuklib_mbstr.h

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