git.marmaro.de Git - mmh/blob - h/charstring.h

   1 /* charstring.h -- dynamically-sized char array that can report size
   2  *               in both characters and bytes
   3  *
   4  * This code is Copyright (c) 2017, by the authors of nmh.  See the
   5  * COPYRIGHT file in the root directory of the nmh distribution for
   6  * complete copyright information. */
   7
   8 /*
   9  * char array that keeps track of size in both bytes and characters
  10  * Usage note:
  11  *    Don't store return value of charstring_buffer() and use later
  12  *    after intervening push_back's; use charstring_buffer_copy()
  13  *    instead.
  14  */
  15
  16 typedef struct charstring *charstring_t;
  17
  18 charstring_t charstring_create(size_t);
  19 charstring_t charstring_copy(const charstring_t) NONNULL(1);
  20 void charstring_free(charstring_t);
  21 /* Append a single-byte character: */
  22 void charstring_push_back(charstring_t, const char) NONNULL(1);
  23 /* Append possibly multi-byte character(s): */
  24 void charstring_push_back_chars(charstring_t, const char [], size_t) NONNULL(1);
  25 void charstring_append(charstring_t, const charstring_t) NONNULL(2);
  26 void charstring_append_cstring(charstring_t, const char []) NONNULL(2);
  27 void charstring_clear(charstring_t) NONNULL(1);
  28 /* Don't store return value of charstring_buffer() and use later after
  29    intervening push_back's; use charstring_buffer_copy() instead. */
  30 const char *charstring_buffer(const charstring_t) NONNULL(1);
  31 /* User is responsible for free'ing result of buffer copy. */
  32 char *charstring_buffer_copy(const charstring_t) NONNULL(1);
  33 size_t charstring_bytes(const charstring_t) NONNULL(1) PURE;
  34 size_t charstring_chars(const charstring_t) NONNULL(1) PURE;