1.1 --- a/src/cx/string.h Wed Feb 01 18:07:16 2023 +0100
1.2 +++ b/src/cx/string.h Thu Feb 02 20:25:34 2023 +0100
1.3 @@ -79,6 +79,57 @@
1.4 typedef struct cx_string_s cxstring;
1.5
1.6 /**
1.7 + * Context for string tokenizing.
1.8 + */
1.9 +struct cx_strtok_ctx_s {
1.10 + /**
1.11 + * The string to tokenize.
1.12 + */
1.13 + cxstring str;
1.14 + /**
1.15 + * The primary delimiter.
1.16 + */
1.17 + cxstring delim;
1.18 + /**
1.19 + * Optional array of more delimiters.
1.20 + */
1.21 + cxstring const *delim_more;
1.22 + /**
1.23 + * Length of the array containing more delimiters.
1.24 + */
1.25 + size_t delim_more_count;
1.26 + /**
1.27 + * Position of the currently active token in the source string.
1.28 + */
1.29 + size_t pos;
1.30 + /**
1.31 + * Position of next delimiter in the source string.
1.32 + *
1.33 + * If the tokenizer has not yet returned a token, the content of this field
1.34 + * is undefined. If the tokenizer reached the end of the string, this field
1.35 + * contains the length of the source string.
1.36 + */
1.37 + size_t delim_pos;
1.38 + /**
1.39 + * The position of the next token in the source string.
1.40 + */
1.41 + size_t next_pos;
1.42 + /**
1.43 + * The number of already found tokens.
1.44 + */
1.45 + size_t found;
1.46 + /**
1.47 + * The maximum number of tokens that shall be returned.
1.48 + */
1.49 + size_t limit;
1.50 +};
1.51 +
1.52 +/**
1.53 + * A string tokenizing context.
1.54 + */
1.55 +typedef struct cx_strtok_ctx_s CxStrtokCtx;
1.56 +
1.57 +/**
1.58 * A literal initializer for an UCX string structure.
1.59 *
1.60 * The argument MUST be a string (const char*) \em literal.
1.61 @@ -828,6 +879,85 @@
1.62 #define cx_strreplace(str, pattern, replacement) \
1.63 cx_strreplacen_a(cxDefaultAllocator, str, pattern, replacement, SIZE_MAX)
1.64
1.65 +/**
1.66 + * Creates a string tokenization context.
1.67 + *
1.68 + * @param str the string to tokenize
1.69 + * @param delim the delimiter (must not be empty)
1.70 + * @param limit the maximum number of tokens that shall be returned
1.71 + * @return a new string tokenization context
1.72 + */
1.73 +__attribute__((__warn_unused_result__))
1.74 +CxStrtokCtx cx_strtok(
1.75 + cxstring str,
1.76 + cxstring delim,
1.77 + size_t limit
1.78 +);
1.79 +
1.80 +/**
1.81 +* Creates a string tokenization context for a mutable string.
1.82 +*
1.83 +* @param str the string to tokenize
1.84 +* @param delim the delimiter (must not be empty)
1.85 +* @param limit the maximum number of tokens that shall be returned
1.86 +* @return a new string tokenization context
1.87 +*/
1.88 +__attribute__((__warn_unused_result__))
1.89 +CxStrtokCtx cx_strtok_m(
1.90 + cxmutstr str,
1.91 + cxstring delim,
1.92 + size_t limit
1.93 +);
1.94 +
1.95 +/**
1.96 + * Returns the next token.
1.97 + *
1.98 + * The token will point to the source string.
1.99 + *
1.100 + * @param ctx the tokenization context
1.101 + * @param token a pointer to memory where the next token shall be stored
1.102 + * @return true if successful, false if the limit or the end of the string
1.103 + * has been reached
1.104 + */
1.105 +__attribute__((__warn_unused_result__, __nonnull__))
1.106 +bool cx_strtok_next(
1.107 + CxStrtokCtx *ctx,
1.108 + cxstring *token
1.109 +);
1.110 +
1.111 +/**
1.112 + * Returns the next token of a mutable string.
1.113 + *
1.114 + * The token will point to the source string.
1.115 + * If the context was not initialized over a mutable string, modifying
1.116 + * the data of the returned token is undefined behavior.
1.117 + *
1.118 + * @param ctx the tokenization context
1.119 + * @param token a pointer to memory where the next token shall be stored
1.120 + * @return true if successful, false if the limit or the end of the string
1.121 + * has been reached
1.122 + */
1.123 +__attribute__((__warn_unused_result__, __nonnull__))
1.124 +bool cx_strtok_next_m(
1.125 + CxStrtokCtx *ctx,
1.126 + cxmutstr *token
1.127 +);
1.128 +
1.129 +/**
1.130 + * Defines an array of more delimiters for the specified tokenization context.
1.131 + *
1.132 + * @param ctx the tokenization context
1.133 + * @param delim array of more delimiters
1.134 + * @param count number of elements in the array
1.135 + */
1.136 +__attribute__((__nonnull__))
1.137 +void cx_strtok_delim(
1.138 + CxStrtokCtx *ctx,
1.139 + cxstring const *delim,
1.140 + size_t count
1.141 +);
1.142 +
1.143 +
1.144 #ifdef __cplusplus
1.145 } // extern "C"
1.146 #endif
