rename __call__ to mf in cython.mf
[liba.git] / include / a / str.h
blobb7b334ad87c28dcede97299eb0c73fa270f868f9
1 /*!
2 @file str.h
3 @brief basic string library
4 */
6 #ifndef LIBA_STR_H
7 #define LIBA_STR_H
9 #include "a.h"
10 #include <stdarg.h>
11 #include <string.h>
13 /*!
14 @ingroup A
15 @addtogroup A_STR basic string library
19 // clang-format off
20 #define A_STR_NUL {A_NULL, 0, 0}
21 // clang-format on
23 /*!
24 @brief instance structure for basic string
26 typedef struct a_str
28 char *ptr_; /*!< string */
29 a_size num_; /*!< length */
30 a_size mem_; /*!< memory */
31 } a_str;
33 /*!
34 @brief string for a pointer to string structure
35 @param[in] ctx points to an instance of string structure
36 @return string
38 A_INTERN char *a_str_ptr(a_str const *ctx) { return ctx->ptr_; }
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
45 A_INTERN a_size a_str_len(a_str const *ctx) { return ctx->num_; }
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
52 A_INTERN a_size a_str_mem(a_str const *ctx) { return ctx->mem_; }
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
61 A_INTERN char a_str_at_(a_str const *ctx, a_size idx) { return ctx->ptr_[idx]; }
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
70 A_INTERN char a_str_at(a_str const *ctx, a_size idx)
72 return a_likely(idx < ctx->num_) ? ctx->ptr_[idx] : 0;
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
82 A_INTERN char a_str_idx(a_str const *ctx, a_diff idx)
84 a_size const num = idx < 0 ? a_size_c(idx) + ctx->num_ : a_size_c(idx);
85 return a_likely(num < ctx->num_) ? ctx->ptr_[num] : 0;
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] len new length for a pointer to string structure
92 @note length must less than memory
94 A_INTERN void a_str_set_len_(a_str *ctx, a_size len) { ctx->num_ = len; }
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] len new length for a pointer to string structure
100 @return the execution state of the function
101 @retval 0 success
102 @retval 1 failure
104 A_INTERN int a_str_set_len(a_str *ctx, a_size len)
106 return a_likely(len < ctx->mem_) ? ((void)(ctx->num_ = len), A_SUCCESS) : A_FAILURE;
110 @brief drop all characters for a pointer to string structure
111 @param[in] ctx points to an instance of string structure
113 A_INTERN void a_str_drop(a_str *ctx) { ctx->num_ = 0; }
115 #if defined(__cplusplus)
116 extern "C" {
117 #endif /* __cplusplus */
120 @brief allocate a pointer to string structure from memory
122 A_EXTERN a_str *a_str_new(void);
125 @brief deallocate a pointer to string structure
126 @param[in] ctx points to an instance of string structure
128 A_EXTERN void a_str_die(a_str *ctx);
131 @brief constructor for string structure
132 @param[in] ctx points to an instance of string structure
134 A_EXTERN void a_str_ctor(a_str *ctx);
137 @brief destructor for string structure
138 @param[in] ctx points to an instance of string structure
140 A_EXTERN void a_str_dtor(a_str *ctx);
143 @brief initialize a pointer to string structure
144 @param[in] ctx points to an instance of string structure
145 @param[in] pdata points to data to initialize
146 @param[in] nbyte length of data to initialize
147 @return the execution state of the function
148 @retval 0 success
149 @retval 1 failure
151 A_EXTERN int a_str_init(a_str *ctx, void const *pdata, a_size nbyte);
154 @brief initialize a pointer to string structure by copying
155 @param[in] ctx points to an instance of string structure
156 @param[in] obj input source pointing to an instance
157 @return the execution state of the function
158 @retval 0 success
159 @retval 1 failure
161 A_EXTERN int a_str_copy(a_str *ctx, a_str const *obj);
164 @brief initialize a pointer to string structure by moving
165 @param[in] ctx points to an instance of string structure
166 @param[in] obj input source pointing to an instance
168 A_EXTERN void a_str_move(a_str *ctx, a_str *obj);
171 @brief terminate a pointer to string structure
172 @param[in] ctx points to an instance of string structure
173 @note should use free to release this memory
174 @return string of string structure
176 A_EXTERN char *a_str_exit(a_str *ctx);
179 @brief compare the string lhs with the string rhs
180 @param[in] lhs string structure to be compared
181 @param[in] rhs string structure to be compared
182 @return relationship between the strings
183 @retval <0 string lhs < string rhs
184 @retval >0 string lhs > string rhs
185 @retval 0 string lhs == string rhs
187 A_EXTERN int a_str_cmp(a_str const *lhs, a_str const *rhs);
190 @brief allocate memory for a pointer to string structure
191 @param[in] ctx points to an instance of string structure
192 @param[in] mem new memory capacity of string
193 @return the execution state of the function
194 @retval 0 success
195 @retval 1 failure
197 A_EXTERN int a_str_alloc(a_str *ctx, a_size mem);
198 A_EXTERN int a_str_alloc_(a_str *ctx, a_size mem);
201 @brief get character for a pointer to string structure
202 @param[in] ctx points to an instance of string structure
203 @return parsed character
204 @retval ~0 failure
206 A_EXTERN int a_str_getc(a_str *ctx);
207 A_EXTERN int a_str_getc_(a_str *ctx);
210 @brief put character to a pointer to string structure
211 @param[in] ctx points to an instance of string structure
212 @param[in] c character to be parsed
213 @return parsed character
214 @retval ~0 failure
216 A_EXTERN int a_str_putc(a_str *ctx, int c);
217 A_EXTERN int a_str_putc_(a_str *ctx, int c);
220 @brief get memory block to a pointer to string structure
221 @param[in] ctx points to an instance of string structure
222 @param[in] pdata points to memory block to get
223 @param[in] nbyte length of memory block to get
224 @return number of parsed characters
226 A_EXTERN a_size a_str_getn(a_str *ctx, void *pdata, a_size nbyte);
227 A_EXTERN a_size a_str_getn_(a_str *ctx, void *pdata, a_size nbyte);
230 @brief put memory block to a pointer to string structure
231 @param[in] ctx points to an instance of string structure
232 @param[in] pdata points to memory block to put
233 @param[in] nbyte length of memory block to put
234 @return the execution state of the function
235 @retval 0 success
236 @retval 1 failure
238 A_EXTERN int a_str_putn(a_str *ctx, void const *pdata, a_size nbyte);
239 A_EXTERN int a_str_putn_(a_str *ctx, void const *pdata, a_size nbyte);
242 @brief put string to a pointer to string structure
243 @param[in] ctx points to an instance of string structure
244 @param[in] str string terminated with a null character
245 @return the execution state of the function
246 @retval 0 success
247 @retval 1 failure
249 A_EXTERN int a_str_puts(a_str *ctx, void const *str);
250 A_EXTERN int a_str_puts_(a_str *ctx, void const *str);
253 @brief concat the string structure obj to the string structure ctx
254 @param[in] ctx points to an instance of string structure
255 @param[in] obj input source pointing to an instance
256 @return the execution state of the function
257 @retval 0 success
258 @retval 1 failure
260 A_EXTERN int a_str_cat(a_str *ctx, a_str const *obj);
261 A_EXTERN int a_str_cat_(a_str *ctx, a_str const *obj);
264 @brief format string to a pointer to string structure
265 @param[in] ctx points to an instance of string structure
266 @param[in] fmt format of string to be parsed
267 @param[in] va instance of variable argument
268 @return number of parsed characters
270 A_EXTERN int a_str_putf_(a_str *ctx, char const *fmt, va_list va) A_FORMAT(printf, 2, 0);
273 @brief format string to a pointer to string structure
274 @param[in] ctx points to an instance of string structure
275 @param[in] fmt format of string to be parsed
276 @return number of parsed characters
278 A_EXTERN int a_str_putf(a_str *ctx, char const *fmt, ...) A_FORMAT(printf, 2, 3);
281 @brief length for a pointer to string structure using UTF-8
282 @param[in] ctx points to an instance of string structure
283 @return number of code points
285 A_EXTERN a_size a_str_utflen(a_str const *ctx);
287 #if defined(__cplusplus)
288 } /* extern "C" */
289 #endif /* __cplusplus */
291 /*! @} A_STR */
293 #endif /* a/str.h */