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