utility/astring.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 /****************************************************************************
  15   Allocated/allocatable strings
  16   See comments in astring.c
  17 ****************************************************************************/
  18
  19 #ifndef FC__ASTRING_H
  20 #define FC__ASTRING_H
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif /* __cplusplus */
  25
  26 #include <string.h>             /* strlen() */
  27
  28 /* utility */
  29 #include "support.h"            /* bool, fc__attribute() */
  30
  31 /* Don't let others modules using the fields directly. */
  32 #define str     _private_str_
  33 #define n       _private_n_
  34 #define n_alloc _private_n_alloc_
  35
  36 struct astring {
  37   char *str;                    /* the string */
  38   size_t n;                     /* size most recently requested */
  39   size_t n_alloc;               /* total allocated */
  40 };
  41
  42 /* Can assign this in variable declaration to initialize:
  43  * Notice a static astring var is exactly this already. */
  44 #define ASTRING_INIT { NULL, 0, 0 }
  45
  46 void astr_init(struct astring *astr) fc__attribute((nonnull (1)));
  47 void astr_free(struct astring *astr) fc__attribute((nonnull (1)));
  48
  49 static inline const char *astr_str(const struct astring *astr)
  50                                    fc__attribute((nonnull (1)));
  51 static inline size_t astr_len(const struct astring *astr)
  52                      fc__attribute((nonnull (1)));
  53 static inline size_t astr_size(const struct astring *astr)
  54                      fc__attribute((nonnull (1)));
  55 static inline size_t astr_capacity(const struct astring *astr)
  56                      fc__attribute((nonnull (1)));
  57 static inline bool astr_empty(const struct astring *astr)
  58                    fc__attribute((nonnull (1)));
  59
  60 char *astr_to_str(struct astring *astr)
  61                   fc__attribute((nonnull (1)));
  62 void astr_reserve(struct astring *astr, size_t size)
  63      fc__attribute((nonnull (1)));
  64 void astr_clear(struct astring *astr)
  65      fc__attribute((nonnull (1)));
  66 void astr_set(struct astring *astr, const char *format, ...)
  67      fc__attribute((__format__(__printf__, 2, 3)))
  68      fc__attribute((nonnull (1, 2)));
  69 void astr_add(struct astring *astr, const char *format, ...)
  70      fc__attribute((__format__(__printf__, 2, 3)))
  71      fc__attribute((nonnull (1, 2)));
  72 void astr_add_line(struct astring *astr, const char *format, ...)
  73      fc__attribute((__format__(__printf__, 2, 3)))
  74      fc__attribute((nonnull (1, 2)));
  75 void astr_break_lines(struct astring *astr, size_t desired_len)
  76      fc__attribute((nonnull (1)));
  77 const char *astr_build_or_list(struct astring *astr,
  78                                const char *const *items, size_t number);
  79 const char *astr_build_and_list(struct astring *astr,
  80                                 const char *const *items, size_t number);
  81 void astr_copy(struct astring *dest, const struct astring *src)
  82      fc__attribute((nonnull (1, 2)));
  83
  84
  85
  86 /****************************************************************************
  87   Returns the string.
  88 ****************************************************************************/
  89 static inline const char *astr_str(const struct astring *astr)
  90 {
  91   return astr->str;
  92 }
  93
  94 /****************************************************************************
  95   Returns the length of the string.
  96 ****************************************************************************/
  97 static inline size_t astr_len(const struct astring *astr)
  98 {
  99   return (NULL != astr->str ? strlen(astr->str) : 0);
 100 }
 101
 102 /****************************************************************************
 103   Returns the current size requested for the string.
 104 ****************************************************************************/
 105 static inline size_t astr_size(const struct astring *astr)
 106 {
 107   return astr->n;
 108 }
 109
 110 /****************************************************************************
 111   Returns the real size requested for the string.
 112 ****************************************************************************/
 113 static inline size_t astr_capacity(const struct astring *astr)
 114 {
 115   return astr->n_alloc;
 116 }
 117
 118 /****************************************************************************
 119   Returns whether the string is empty or not.
 120 ****************************************************************************/
 121 static inline bool astr_empty(const struct astring *astr)
 122 {
 123   return (0 == astr->n || '\0' == astr->str[0]);
 124 }
 125
 126 #undef str
 127 #undef n
 128 #undef n_alloc
 129
 130 #ifdef __cplusplus
 131 }
 132 #endif /* __cplusplus */
 133
 134 #endif  /* FC__ASTRING_H */