include/a/str.h

   1 /*!
   2  @file str.h
   3  @brief basic string library
   4 */
   5
   6 #ifndef LIBA_STR_H
   7 #define LIBA_STR_H
   8
   9 #include "a.h"
  10 #include <stdarg.h>
  11 #include <string.h>
  12
  13 /*!
  14  @ingroup liba
  15  @addtogroup a_str basic string library
  16  @{
  17 */
  18
  19 // clang-format off
  20 #define A_STR_INIT {A_NULL, 0, 0}
  21 // clang-format on
  22
  23 /*!
  24  @brief instance structure for basic string
  25 */
  26 typedef struct a_str
  27 {
  28     char *ptr_; /*!< string */
  29     a_size num_; /*!< length */
  30     a_size mem_; /*!< memory */
  31 } a_str;
  32
  33 /*!
  34  @brief string for a pointer to string structure
  35  @param[in] ctx points to an instance of string structure
  36  @return string
  37 */
  38 A_INTERN char *a_str_ptr(a_str const *ctx) { return ctx->ptr_; }
  39
  40 /*!
  41  @brief length for a pointer to string structure
  42  @param[in] ctx points to an instance of string structure
  43  @return size of length
  44 */
  45 A_INTERN a_size a_str_len(a_str const *ctx) { return ctx->num_; }
  46
  47 /*!
  48  @brief memory for a pointer to string structure
  49  @param[in] ctx points to an instance of string structure
  50  @return size of memory
  51 */
  52 A_INTERN a_size a_str_mem(a_str const *ctx) { return ctx->mem_; }
  53
  54 /*!
  55  @brief access specified character for a pointer to string structure
  56  @param[in] ctx points to an instance of string structure
  57  @param[in] idx index of character less than memory
  58  @note should check if string is empty
  59  @return specified character
  60 */
  61 A_INTERN char a_str_at_(a_str const *ctx, a_size idx) { return ctx->ptr_[idx]; }
  62
  63 /*!
  64  @brief access specified character for a pointer to string structure
  65  @param[in] ctx points to an instance of string structure
  66  @param[in] idx index of character less than length
  67  @return specified character
  68   @retval 0 out of bounds
  69 */
  70 A_INTERN char a_str_at(a_str const *ctx, a_size idx)
  71 {
  72     return idx < ctx->num_ ? ctx->ptr_[idx] : 0;
  73 }
  74
  75 /*!
  76  @brief access specified character for a pointer to string structure
  77  @param[in] ctx points to an instance of string structure
  78  @param[in] idx index of character -length < idx < length
  79  @return specified character
  80   @retval 0 out of bounds
  81 */
  82 A_INTERN char a_str_idx(a_str const *ctx, a_diff idx)
  83 {
  84     a_size const num = idx >= 0 ? a_size_c(idx) : a_size_c(idx) + ctx->num_;
  85     return num < ctx->num_ ? ctx->ptr_[num] : 0;
  86 }
  87
  88 /*!
  89  @brief set length for a pointer to string structure
  90  @param[in] ctx points to an instance of string structure
  91  @param[in] num new length for a pointer to string structure
  92  @note length must less than memory
  93 */
  94 A_INTERN void a_str_setlen_(a_str *ctx, a_size num) { ctx->num_ = num; }
  95
  96 /*!
  97  @brief set length for a pointer to string structure
  98  @param[in] ctx points to an instance of string structure
  99  @param[in] num new length for a pointer to string structure
 100  @return the execution state of the function
 101   @retval 0 success
 102   @retval 1 failure
 103 */
 104 A_INTERN int a_str_setlen(a_str *ctx, a_size num)
 105 {
 106     return num < ctx->mem_ ? ((void)(ctx->num_ = num), A_SUCCESS) : A_FAILURE;
 107 }
 108
 109 /*!
 110  @brief drop all characters for a pointer to string structure
 111  @param[in] ctx points to an instance of string structure
 112 */
 113 A_INTERN void a_str_drop(a_str *ctx) { ctx->num_ = 0; }
 114
 115 #if defined(__cplusplus)
 116 extern "C" {
 117 #endif /* __cplusplus */
 118
 119 /*!
 120  @brief allocate a pointer to string structure from memory
 121 */
 122 A_EXTERN a_str *a_str_new(void);
 123
 124 /*!
 125  @brief deallocate a pointer to string structure
 126  @param[in] ctx points to an instance of string structure
 127 */
 128 A_EXTERN void a_str_die(a_str *ctx);
 129
 130 /*!
 131  @brief constructor for string structure
 132  @param[in] ctx points to an instance of string structure
 133 */
 134 A_EXTERN void a_str_ctor(a_str *ctx);
 135
 136 /*!
 137  @brief destructor for string structure
 138  @param[in] ctx points to an instance of string structure
 139 */
 140 A_EXTERN void a_str_dtor(a_str *ctx);
 141
 142 /*!
 143  @brief initialize a pointer to string structure by copying
 144  @param[in] ctx points to an instance of string structure
 145  @param[in] obj input source pointing to an instance
 146  @return the execution state of the function
 147   @retval 0 success
 148   @retval 1 failure
 149 */
 150 A_EXTERN int a_str_copy(a_str *ctx, a_str const *obj);
 151
 152 /*!
 153  @brief initialize a pointer to string structure by moving
 154  @param[in] ctx points to an instance of string structure
 155  @param[in] obj input source pointing to an instance
 156 */
 157 A_EXTERN void a_str_move(a_str *ctx, a_str *obj);
 158
 159 /*!
 160  @brief terminate a pointer to string structure
 161  @param[in] ctx points to an instance of string structure
 162  @note should use free to release this memory
 163  @return string of string structure
 164 */
 165 A_EXTERN char *a_str_exit(a_str *ctx);
 166
 167 /*!
 168  @brief allocate memory for a pointer to string structure
 169  @param[in] ctx points to an instance of string structure
 170  @param[in] mem new memory capacity of string
 171  @return the execution state of the function
 172   @retval 0 success
 173   @retval 1 failure
 174 */
 175 A_EXTERN int a_str_alloc(a_str *ctx, a_size mem);
 176 A_EXTERN int a_str_alloc_(a_str *ctx, a_size mem);
 177
 178 /*!
 179  @brief compare the string `ctx` with the memory block
 180  @param[in] ctx points to an instance of string structure
 181  @param[in] pdata points to memory block to be compared
 182  @param[in] nbyte length of memory block to be compared
 183  @return relationship between the strings
 184   @retval <0 string `ctx` < memory block
 185   @retval >0 string `ctx` > memory block
 186   @retval 0 string `ctx` == memory block
 187 */
 188 A_EXTERN int a_str_cmpn(a_str const *ctx, void const *pdata, a_size nbyte);
 189
 190 /*!
 191  @brief compare the string `ctx` with the C string `str`
 192  @param[in] ctx points to an instance of string structure
 193  @param[in] str string terminated with a null character
 194  @return relationship between the strings
 195   @retval <0 string `ctx` < C string `str`
 196   @retval >0 string `ctx` > C string `str`
 197   @retval 0 string `ctx` == C string `str`
 198 */
 199 A_EXTERN int a_str_cmps(a_str const *ctx, void const *str);
 200
 201 /*!
 202  @brief compare the string `lhs` with the string `rhs`
 203  @param[in] lhs string structure to be compared
 204  @param[in] rhs string structure to be compared
 205  @return relationship between the strings
 206   @retval <0 string `lhs` < string `rhs`
 207   @retval >0 string `lhs` > string `rhs`
 208   @retval 0 string `lhs` == string `rhs`
 209 */
 210 A_EXTERN int a_str_cmp(a_str const *lhs, a_str const *rhs);
 211
 212 /*!
 213  @brief get character for a pointer to string structure
 214  @param[in] ctx points to an instance of string structure
 215  @return parsed character
 216   @retval ~0 failure
 217 */
 218 A_EXTERN int a_str_getc(a_str *ctx);
 219 A_EXTERN int a_str_getc_(a_str *ctx);
 220
 221 /*!
 222  @brief put character to a pointer to string structure
 223  @param[in] ctx points to an instance of string structure
 224  @param[in] c character to be parsed
 225  @return parsed character
 226   @retval ~0 failure
 227 */
 228 A_EXTERN int a_str_putc(a_str *ctx, int c);
 229 A_EXTERN int a_str_putc_(a_str *ctx, int c);
 230
 231 /*!
 232  @brief get memory block to a pointer to string structure
 233  @param[in] ctx points to an instance of string structure
 234  @param[in] pdata points to memory block to get
 235  @param[in] nbyte length of memory block to get
 236  @return number of parsed characters
 237 */
 238 A_EXTERN a_size a_str_getn(a_str *ctx, void *pdata, a_size nbyte);
 239 A_EXTERN a_size a_str_getn_(a_str *ctx, void *pdata, a_size nbyte);
 240
 241 /*!
 242  @brief set memory block to a pointer to string structure
 243  @param[in] ctx points to an instance of string structure
 244  @param[in] pdata points to memory block to set
 245  @param[in] nbyte length of memory block to set
 246  @return the execution state of the function
 247   @retval 0 success
 248   @retval 1 failure
 249 */
 250 A_EXTERN int a_str_setn(a_str *ctx, void const *pdata, a_size nbyte);
 251 A_EXTERN int a_str_setn_(a_str *ctx, void const *pdata, a_size nbyte);
 252
 253 /*!
 254  @brief put memory block to a pointer to string structure
 255  @param[in] ctx points to an instance of string structure
 256  @param[in] pdata points to memory block to put
 257  @param[in] nbyte length of memory block to put
 258  @return the execution state of the function
 259   @retval 0 success
 260   @retval 1 failure
 261 */
 262 A_EXTERN int a_str_putn(a_str *ctx, void const *pdata, a_size nbyte);
 263 A_EXTERN int a_str_putn_(a_str *ctx, void const *pdata, a_size nbyte);
 264
 265 /*!
 266  @brief set C string to a pointer to string structure
 267  @param[in] ctx points to an instance of string structure
 268  @param[in] str string terminated with a null character
 269  @return the execution state of the function
 270   @retval 0 success
 271   @retval 1 failure
 272 */
 273 A_EXTERN int a_str_sets(a_str *ctx, void const *str);
 274 A_EXTERN int a_str_sets_(a_str *ctx, void const *str);
 275
 276 /*!
 277  @brief put C string to a pointer to string structure
 278  @param[in] ctx points to an instance of string structure
 279  @param[in] str string terminated with a null character
 280  @return the execution state of the function
 281   @retval 0 success
 282   @retval 1 failure
 283 */
 284 A_EXTERN int a_str_puts(a_str *ctx, void const *str);
 285 A_EXTERN int a_str_puts_(a_str *ctx, void const *str);
 286
 287 /*!
 288  @brief format string to a pointer to string structure via va_list
 289  @param[in] ctx points to an instance of string structure
 290  @param[in] fmt format of string to be parsed
 291  @param[in] va instance of variable argument
 292  @return number of parsed characters
 293 */
 294 A_EXTERN int a_str_setv(a_str *ctx, char const *fmt, va_list va) A_FORMAT(printf, 2, 0);
 295
 296 /*!
 297  @brief format string append to a pointer to string structure via va_list
 298  @param[in] ctx points to an instance of string structure
 299  @param[in] fmt format of string to be parsed
 300  @param[in] va instance of variable argument
 301  @return number of parsed characters
 302 */
 303 A_EXTERN int a_str_putv(a_str *ctx, char const *fmt, va_list va) A_FORMAT(printf, 2, 0);
 304
 305 /*!
 306  @brief format string to a pointer to string structure
 307  @param[in] ctx points to an instance of string structure
 308  @param[in] fmt format of string to be parsed
 309  @return number of parsed characters
 310 */
 311 A_EXTERN int a_str_setf(a_str *ctx, char const *fmt, ...) A_FORMAT(printf, 2, 3);
 312
 313 /*!
 314  @brief format string append to a pointer to string structure
 315  @param[in] ctx points to an instance of string structure
 316  @param[in] fmt format of string to be parsed
 317  @return number of parsed characters
 318 */
 319 A_EXTERN int a_str_putf(a_str *ctx, char const *fmt, ...) A_FORMAT(printf, 2, 3);
 320
 321 /*!
 322  @brief set the string structure obj to the string structure ctx
 323  @param[in] ctx points to an instance of string structure
 324  @param[in] obj input source pointing to an instance
 325  @return the execution state of the function
 326   @retval 0 success
 327   @retval 1 failure
 328 */
 329 A_EXTERN int a_str_set(a_str *ctx, a_str const *obj);
 330 A_EXTERN int a_str_set_(a_str *ctx, a_str const *obj);
 331
 332 /*!
 333  @brief put the string structure obj to the string structure ctx
 334  @param[in] ctx points to an instance of string structure
 335  @param[in] obj input source pointing to an instance
 336  @return the execution state of the function
 337   @retval 0 success
 338   @retval 1 failure
 339 */
 340 A_EXTERN int a_str_put(a_str *ctx, a_str const *obj);
 341 A_EXTERN int a_str_put_(a_str *ctx, a_str const *obj);
 342
 343 /*!
 344  @brief length for a pointer to string structure using UTF-8
 345  @param[in] ctx points to an instance of string structure
 346  @return number of code points
 347 */
 348 A_EXTERN a_size a_str_utflen(a_str const *ctx);
 349
 350 #if defined(__cplusplus)
 351 } /* extern "C" */
 352 #endif /* __cplusplus */
 353
 354 /*! @} a_str */
 355
 356 #endif /* a/str.h */