utility/fc_utf8.h

   1 /**********************************************************************
   2  Freeciv - Copyright (C) 1996 - A Kjeldberg, L Gregersen, P Unold
   3    This program is free software; you can redistribute it and/or modify
   4    it under the terms of the GNU General Public License as published by
   5    the Free Software Foundation; either version 2, or (at your option)
   6    any later version.
   7
   8    This program is distributed in the hope that it will be useful,
   9    but WITHOUT ANY WARRANTY; without even the implied warranty of
  10    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11    GNU General Public License for more details.
  12 ***********************************************************************/
  13
  14 #ifndef FC__FC_UTF8_H
  15 #define FC__FC_UTF8_H
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif /* __cplusplus */
  20
  21 /****************************************************************************
  22   This module provides tools to make safe operations on UTF-8 strings. All
  23   functions are prefixed with fc_utf8_*. There are two main categories of
  24   functions:
  25   - the ones which truncate the strings at the first UTF-8 invalid
  26   character. They are named *_trunc();
  27   - the ones which attempts to replace the invalid characters by the
  28   replacement character (U+FFFD). They are named *_rep().
  29 ****************************************************************************/
  30
  31 extern const char fc_utf8_skip[256];
  32
  33 /* UTF-8 character functions. */
  34 bool fc_utf8_char_validate(const char *utf8_char)
  35     fc__attribute((nonnull (1)));
  36 char *fc_utf8_find_next_char(const char *utf8_char)
  37     fc__attribute((nonnull (1)));
  38 char *fc_utf8_find_prev_char(const char *utf8_char, const char *utf8_string)
  39     fc__attribute((nonnull (1, 2)));
  40 /* Jump to next UTF-8 character, assuming it is a valid UTF-8 string. */
  41 #define fc_ut8_next_char(utf8_char) \
  42     (utf8_char + fc_utf8_skip[*(unsigned char *) utf8_char])
  43
  44 /* UTF-8 string functions. */
  45 bool fc_utf8_validate(const char *utf8_string, const char **end)
  46     fc__attribute((nonnull (1)));
  47 bool fc_utf8_validate_len(const char *utf8_string, size_t byte_len,
  48                           const char **end)
  49     fc__attribute((nonnull (1)));
  50
  51 char *fc_utf8_validate_trunc(char *utf8_string)
  52     fc__attribute((nonnull (1)));
  53 char *fc_utf8_validate_trunc_len(char *utf8_string, size_t byte_len)
  54     fc__attribute((nonnull (1)));
  55 char *fc_utf8_validate_trunc_dup(const char *utf8_string)
  56     fc__attribute((nonnull (1)))
  57     fc__attribute((warn_unused_result));
  58
  59 char *fc_utf8_validate_rep_len(char *utf8_string, size_t byte_len)
  60     fc__attribute((nonnull (1)));
  61 char *fc_utf8_validate_rep_dup(const char *utf8_string)
  62     fc__attribute((nonnull (1)))
  63     fc__attribute((warn_unused_result));
  64
  65 size_t fc_utf8_strlen(const char *utf8_string)
  66     fc__attribute((nonnull (1)));
  67
  68 /* UTF-8-safe replacements of some string utilities. See also functions
  69  * defined in "support.[ch]". */
  70 size_t fc_utf8_strlcpy_trunc(char *dest, const char *src, size_t n)
  71     fc__attribute((nonnull (1, 2)));
  72 size_t fc_utf8_strlcpy_rep(char *dest, const char *src, size_t n)
  73     fc__attribute((nonnull (1, 2)));
  74 size_t fc_utf8_strlcat_trunc(char *dest, const char *src, size_t n)
  75     fc__attribute((nonnull (1, 2)));
  76 size_t fc_utf8_strlcat_rep(char *dest, const char *src, size_t n)
  77     fc__attribute((nonnull (1, 2)));
  78
  79 int fc_utf8_snprintf_trunc(char *str, size_t n, const char *format, ...)
  80     fc__attribute((__format__ (__printf__, 3, 4)))
  81     fc__attribute((nonnull (1, 3)));
  82 int fc_utf8_snprintf_rep(char *str, size_t n, const char *format, ...)
  83     fc__attribute((__format__ (__printf__, 3, 4)))
  84     fc__attribute((nonnull (1, 3)));
  85 int fc_utf8_vsnprintf_trunc(char *str, size_t n, const char *format,
  86                             va_list args)
  87     fc__attribute((nonnull (1, 3)));
  88 int fc_utf8_vsnprintf_rep(char *str, size_t n, const char *format,
  89                           va_list args)
  90     fc__attribute((nonnull (1, 3)));
  91 int cat_utf8_snprintf_trunc(char *str, size_t n, const char *format, ...)
  92     fc__attribute((__format__ (__printf__, 3, 4)))
  93     fc__attribute((nonnull (1, 3)));
  94 int cat_utf8_snprintf_rep(char *str, size_t n, const char *format, ...)
  95     fc__attribute((__format__ (__printf__, 3, 4)))
  96     fc__attribute((nonnull (1, 3)));
  97
  98 #ifdef __cplusplus
  99 }
 100 #endif /* __cplusplus */
 101
 102 #endif /* FC__FC_UTF8_H */