src/cx/string.h

Sat, 21 Dec 2024 21:03:28 +0100

author
Mike Becker <universe@uap-core.de>
date
Sat, 21 Dec 2024 21:03:28 +0100
changeset 1040
1ecf4dbbc60c
parent 1001
5c9ec5a0a4ef
permissions
-rw-r--r--

add some more overflow treatment and make sure to set errno properly

resolves #469

576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
1 /*
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
3 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
4 * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
5 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
6 * Redistribution and use in source and binary forms, with or without
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
7 * modification, are permitted provided that the following conditions are met:
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
8 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
9 * 1. Redistributions of source code must retain the above copyright
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
10 * notice, this list of conditions and the following disclaimer.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
11 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
12 * 2. Redistributions in binary form must reproduce the above copyright
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
13 * notice, this list of conditions and the following disclaimer in the
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
14 * documentation and/or other materials provided with the distribution.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
15 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
26 * POSSIBILITY OF SUCH DAMAGE.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
27 */
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
28 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
29 * \file string.h
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
30 * \brief Strings that know their length.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
31 * \author Mike Becker
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
32 * \author Olaf Wintermann
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
33 * \copyright 2-Clause BSD License
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
34 */
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
35
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
36 #ifndef UCX_STRING_H
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
37 #define UCX_STRING_H
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
38
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
39 #include "common.h"
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
40 #include "allocator.h"
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
41
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
42 /**
806
e06249e09f99 add constant for reading out strstr sbo size - relates to #343
Mike Becker <universe@uap-core.de>
parents: 759
diff changeset
43 * The maximum length of the "needle" in cx_strstr() that can use SBO.
e06249e09f99 add constant for reading out strstr sbo size - relates to #343
Mike Becker <universe@uap-core.de>
parents: 759
diff changeset
44 */
926
8fdd8d78c14b fix several survivors of east-const and some missing consts
Mike Becker <universe@uap-core.de>
parents: 890
diff changeset
45 extern const unsigned cx_strstr_sbo_size;
806
e06249e09f99 add constant for reading out strstr sbo size - relates to #343
Mike Becker <universe@uap-core.de>
parents: 759
diff changeset
46
e06249e09f99 add constant for reading out strstr sbo size - relates to #343
Mike Becker <universe@uap-core.de>
parents: 759
diff changeset
47 /**
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
48 * The UCX string structure.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
49 */
577
26447d59a5ab wrong position of struct identifier
Mike Becker <universe@uap-core.de>
parents: 576
diff changeset
50 struct cx_mutstr_s {
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
51 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
52 * A pointer to the string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
53 * \note The string is not necessarily \c NULL terminated.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
54 * Always use the length.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
55 */
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
56 char *ptr;
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
57 /** The length of the string */
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
58 size_t length;
577
26447d59a5ab wrong position of struct identifier
Mike Becker <universe@uap-core.de>
parents: 576
diff changeset
59 };
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
60
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
61 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
62 * A mutable string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
63 */
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
64 typedef struct cx_mutstr_s cxmutstr;
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
65
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
66 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
67 * The UCX string structure for immutable (constant) strings.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
68 */
577
26447d59a5ab wrong position of struct identifier
Mike Becker <universe@uap-core.de>
parents: 576
diff changeset
69 struct cx_string_s {
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
70 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
71 * A pointer to the immutable string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
72 * \note The string is not necessarily \c NULL terminated.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
73 * Always use the length.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
74 */
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
75 const char *ptr;
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
76 /** The length of the string */
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
77 size_t length;
577
26447d59a5ab wrong position of struct identifier
Mike Becker <universe@uap-core.de>
parents: 576
diff changeset
78 };
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
79
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
80 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
81 * An immutable string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
82 */
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
83 typedef struct cx_string_s cxstring;
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
84
583
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
85 /**
645
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
86 * Context for string tokenizing.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
87 */
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
88 struct cx_strtok_ctx_s {
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
89 /**
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
90 * The string to tokenize.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
91 */
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
92 cxstring str;
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
93 /**
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
94 * The primary delimiter.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
95 */
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
96 cxstring delim;
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
97 /**
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
98 * Optional array of more delimiters.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
99 */
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
100 const cxstring *delim_more;
645
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
101 /**
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
102 * Length of the array containing more delimiters.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
103 */
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
104 size_t delim_more_count;
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
105 /**
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
106 * Position of the currently active token in the source string.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
107 */
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
108 size_t pos;
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
109 /**
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
110 * Position of next delimiter in the source string.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
111 *
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
112 * If the tokenizer has not yet returned a token, the content of this field
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
113 * is undefined. If the tokenizer reached the end of the string, this field
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
114 * contains the length of the source string.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
115 */
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
116 size_t delim_pos;
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
117 /**
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
118 * The position of the next token in the source string.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
119 */
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
120 size_t next_pos;
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
121 /**
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
122 * The number of already found tokens.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
123 */
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
124 size_t found;
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
125 /**
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
126 * The maximum number of tokens that shall be returned.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
127 */
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
128 size_t limit;
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
129 };
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
130
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
131 /**
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
132 * A string tokenizing context.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
133 */
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
134 typedef struct cx_strtok_ctx_s CxStrtokCtx;
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
135
684
380bd45bc94a change CX_STR: use compound literal in C and ctor in C++
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
136 #ifdef __cplusplus
380bd45bc94a change CX_STR: use compound literal in C and ctor in C++
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
137 extern "C" {
380bd45bc94a change CX_STR: use compound literal in C and ctor in C++
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
138
380bd45bc94a change CX_STR: use compound literal in C and ctor in C++
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
139 /**
380bd45bc94a change CX_STR: use compound literal in C and ctor in C++
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
140 * A literal initializer for an UCX string structure.
380bd45bc94a change CX_STR: use compound literal in C and ctor in C++
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
141 *
380bd45bc94a change CX_STR: use compound literal in C and ctor in C++
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
142 * @param literal the string literal
380bd45bc94a change CX_STR: use compound literal in C and ctor in C++
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
143 */
380bd45bc94a change CX_STR: use compound literal in C and ctor in C++
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
144 #define CX_STR(literal) cxstring{literal, sizeof(literal) - 1}
380bd45bc94a change CX_STR: use compound literal in C and ctor in C++
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
145
380bd45bc94a change CX_STR: use compound literal in C and ctor in C++
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
146 #else // __cplusplus
380bd45bc94a change CX_STR: use compound literal in C and ctor in C++
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
147
645
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
148 /**
583
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
149 * A literal initializer for an UCX string structure.
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
150 *
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
151 * The argument MUST be a string (const char*) \em literal.
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
152 *
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
153 * @param literal the string literal
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
154 */
684
380bd45bc94a change CX_STR: use compound literal in C and ctor in C++
Mike Becker <universe@uap-core.de>
parents: 677
diff changeset
155 #define CX_STR(literal) (cxstring){literal, sizeof(literal) - 1}
583
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
156
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
157 #endif
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
158
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
159
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
160 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
161 * Wraps a mutable string that must be zero-terminated.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
162 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
163 * The length is implicitly inferred by using a call to \c strlen().
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
164 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
165 * \note the wrapped string will share the specified pointer to the string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
166 * If you do want a copy, use cx_strdup() on the return value of this function.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
167 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
168 * If you need to wrap a constant string, use cx_str().
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
169 *
584
184e9ebfc3cc disallow NULL for cx_str() and cx_mutstr()
Mike Becker <universe@uap-core.de>
parents: 583
diff changeset
170 * @param cstring the string to wrap, must be zero-terminated
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
171 * @return the wrapped string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
172 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
173 * @see cx_mutstrn()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
174 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
175 cx_attr_nonnull
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
176 cx_attr_nodiscard
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
177 cx_attr_cstr_arg(1)
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
178 cxmutstr cx_mutstr(char *cstring);
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
179
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
180 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
181 * Wraps a string that does not need to be zero-terminated.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
182 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
183 * The argument may be \c NULL if the length is zero.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
184 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
185 * \note the wrapped string will share the specified pointer to the string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
186 * If you do want a copy, use cx_strdup() on the return value of this function.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
187 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
188 * If you need to wrap a constant string, use cx_strn().
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
189 *
584
184e9ebfc3cc disallow NULL for cx_str() and cx_mutstr()
Mike Becker <universe@uap-core.de>
parents: 583
diff changeset
190 * @param cstring the string to wrap (or \c NULL, only if the length is zero)
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
191 * @param length the length of the string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
192 * @return the wrapped string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
193 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
194 * @see cx_mutstr()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
195 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
196 cx_attr_nodiscard
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
197 cx_attr_access_rw(1, 2)
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
198 cxmutstr cx_mutstrn(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
199 char *cstring,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
200 size_t length
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
201 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
202
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
203 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
204 * Wraps a string that must be zero-terminated.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
205 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
206 * The length is implicitly inferred by using a call to \c strlen().
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
207 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
208 * \note the wrapped string will share the specified pointer to the string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
209 * If you do want a copy, use cx_strdup() on the return value of this function.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
210 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
211 * If you need to wrap a non-constant string, use cx_mutstr().
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
212 *
584
184e9ebfc3cc disallow NULL for cx_str() and cx_mutstr()
Mike Becker <universe@uap-core.de>
parents: 583
diff changeset
213 * @param cstring the string to wrap, must be zero-terminated
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
214 * @return the wrapped string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
215 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
216 * @see cx_strn()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
217 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
218 cx_attr_nonnull
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
219 cx_attr_nodiscard
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
220 cx_attr_cstr_arg(1)
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
221 cxstring cx_str(const char *cstring);
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
222
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
223
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
224 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
225 * Wraps a string that does not need to be zero-terminated.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
226 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
227 * The argument may be \c NULL if the length is zero.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
228 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
229 * \note the wrapped string will share the specified pointer to the string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
230 * If you do want a copy, use cx_strdup() on the return value of this function.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
231 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
232 * If you need to wrap a non-constant string, use cx_mutstrn().
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
233 *
584
184e9ebfc3cc disallow NULL for cx_str() and cx_mutstr()
Mike Becker <universe@uap-core.de>
parents: 583
diff changeset
234 * @param cstring the string to wrap (or \c NULL, only if the length is zero)
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
235 * @param length the length of the string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
236 * @return the wrapped string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
237 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
238 * @see cx_str()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
239 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
240 cx_attr_nodiscard
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
241 cx_attr_access_r(1, 2)
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
242 cxstring cx_strn(
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
243 const char *cstring,
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
244 size_t length
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
245 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
246
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
247 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
248 * Casts a mutable string to an immutable string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
249 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
250 * \note This is not seriously a cast. Instead you get a copy
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
251 * of the struct with the desired pointer type. Both structs still
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
252 * point to the same location, though!
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
253 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
254 * @param str the mutable string to cast
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
255 * @return an immutable copy of the string pointer
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
256 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
257 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
258 cxstring cx_strcast(cxmutstr str);
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
259
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
260 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
261 * Passes the pointer in this string to \c free().
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
262 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
263 * The pointer in the struct is set to \c NULL and the length is set to zero.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
264 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
265 * \note There is no implementation for cxstring, because it is unlikely that
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
266 * you ever have a <code>const char*</code> you are really supposed to free.
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
267 * If you encounter such situation, you should double-check your code.
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
268 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
269 * @param str the string to free
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
270 */
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
271 void cx_strfree(cxmutstr *str);
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
272
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
273 /**
583
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
274 * Passes the pointer in this string to the allocators free function.
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
275 *
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
276 * The pointer in the struct is set to \c NULL and the length is set to zero.
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
277 *
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
278 * \note There is no implementation for cxstring, because it is unlikely that
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
279 * you ever have a <code>const char*</code> you are really supposed to free.
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
280 * If you encounter such situation, you should double-check your code.
583
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
281 *
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
282 * @param alloc the allocator
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
283 * @param str the string to free
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
284 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
285 cx_attr_nonnull_arg(1)
583
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
286 void cx_strfree_a(
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
287 const CxAllocator *alloc,
583
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
288 cxmutstr *str
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
289 );
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
290
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
291 /**
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
292 * Returns the accumulated length of all specified strings.
1040
1ecf4dbbc60c add some more overflow treatment and make sure to set errno properly
Mike Becker <universe@uap-core.de>
parents: 1001
diff changeset
293 *
1ecf4dbbc60c add some more overflow treatment and make sure to set errno properly
Mike Becker <universe@uap-core.de>
parents: 1001
diff changeset
294 * If this sum overflows, errno is set to EOVERFLOW.
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
295 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
296 * \attention if the count argument is larger than the number of the
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
297 * specified strings, the behavior is undefined.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
298 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
299 * @param count the total number of specified strings
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
300 * @param ... all strings
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
301 * @return the accumulated length of all strings
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
302 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
303 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
304 size_t cx_strlen(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
305 size_t count,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
306 ...
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
307 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
308
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
309 /**
697
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
310 * Concatenates strings.
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
311 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
312 * The resulting string will be allocated by the specified allocator.
697
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
313 * So developers \em must pass the return value to cx_strfree_a() eventually.
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
314 *
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
315 * If \p str already contains a string, the memory will be reallocated and
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
316 * the other strings are appended. Otherwise, new memory is allocated.
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
317 *
1001
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
318 * If memory allocation fails, the pointer in the returned string will
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
319 * be \c NULL. Depending on the allocator, \c errno might be set.
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
320 *
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
321 * \note It is guaranteed that there is only one allocation for the
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
322 * resulting string.
697
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
323 * It is also guaranteed that the returned string is zero-terminated.
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
324 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
325 * @param alloc the allocator to use
697
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
326 * @param str the string the other strings shall be concatenated to
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
327 * @param count the number of the other following strings to concatenate
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
328 * @param ... all other strings
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
329 * @return the concatenated string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
330 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
331 cx_attr_nodiscard
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
332 cx_attr_nonnull
697
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
333 cxmutstr cx_strcat_ma(
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
334 const CxAllocator *alloc,
697
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
335 cxmutstr str,
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
336 size_t count,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
337 ...
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
338 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
339
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
340 /**
697
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
341 * Concatenates strings and returns a new string.
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
342 *
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
343 * The resulting string will be allocated by the specified allocator.
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
344 * So developers \em must pass the return value to cx_strfree_a() eventually.
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
345 *
1001
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
346 * If memory allocation fails, the pointer in the returned string will
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
347 * be \c NULL. Depending on the allocator, \c errno might be set.
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
348 *
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
349 * \note It is guaranteed that there is only one allocation for the
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
350 * resulting string.
697
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
351 * It is also guaranteed that the returned string is zero-terminated.
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
352 *
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
353 * @param alloc the allocator to use
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
354 * @param count the number of the other following strings to concatenate
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
355 * @param ... all other strings
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
356 * @return the concatenated string
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
357 */
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
358 #define cx_strcat_a(alloc, count, ...) \
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
359 cx_strcat_ma(alloc, cx_mutstrn(NULL, 0), count, __VA_ARGS__)
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
360
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
361 /**
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
362 * Concatenates strings and returns a new string.
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
363 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
364 * The resulting string will be allocated by standard \c malloc().
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
365 * So developers \em must pass the return value to cx_strfree() eventually.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
366 *
1001
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
367 * If memory allocation fails, the pointer in the returned string will
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
368 * be \c NULL and \c errno might be set.
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
369 *
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
370 * \note It is guaranteed that there is only one allocation for the
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
371 * resulting string.
589
c290f8fd979e add zero-termination guarantees
Mike Becker <universe@uap-core.de>
parents: 584
diff changeset
372 * It is also guaranteed that the returned string is zero-terminated.
c290f8fd979e add zero-termination guarantees
Mike Becker <universe@uap-core.de>
parents: 584
diff changeset
373 *
697
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
374 * @param count the number of the other following strings to concatenate
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
375 * @param ... all other strings
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
376 * @return the concatenated string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
377 */
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
378 #define cx_strcat(count, ...) \
697
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
379 cx_strcat_ma(cxDefaultAllocator, cx_mutstrn(NULL, 0), count, __VA_ARGS__)
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
380
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
381 /**
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
382 * Concatenates strings.
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
383 *
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
384 * The resulting string will be allocated by standard \c malloc().
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
385 * So developers \em must pass the return value to cx_strfree() eventually.
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
386 *
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
387 * If \p str already contains a string, the memory will be reallocated and
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
388 * the other strings are appended. Otherwise, new memory is allocated.
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
389 *
1001
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
390 * If memory allocation fails, the pointer in the returned string will
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
391 * be \c NULL and \c errno might be set.
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
392 *
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
393 * \note It is guaranteed that there is only one allocation for the
5c9ec5a0a4ef change cx_strcat variants to allow handling of ENOMEM
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
394 * resulting string.
697
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
395 * It is also guaranteed that the returned string is zero-terminated.
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
396 *
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
397 * @param str the string the other strings shall be concatenated to
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
398 * @param count the number of the other following strings to concatenate
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
399 * @param ... all other strings
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
400 * @return the concatenated string
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
401 */
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
402 #define cx_strcat_m(str, count, ...) \
ebdce4bf262b add cx_strcat_m() and cx_strcat_ma() for in-place concatenation
Mike Becker <universe@uap-core.de>
parents: 693
diff changeset
403 cx_strcat_ma(cxDefaultAllocator, str, count, __VA_ARGS__)
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
404
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
405 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
406 * Returns a substring starting at the specified location.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
407 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
408 * \attention the new string references the same memory area as the
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
409 * input string and is usually \em not zero-terminated.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
410 * Use cx_strdup() to get a copy.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
411 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
412 * @param string input string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
413 * @param start start location of the substring
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
414 * @return a substring of \p string starting at \p start
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
415 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
416 * @see cx_strsubsl()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
417 * @see cx_strsubs_m()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
418 * @see cx_strsubsl_m()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
419 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
420 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
421 cxstring cx_strsubs(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
422 cxstring string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
423 size_t start
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
424 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
425
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
426 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
427 * Returns a substring starting at the specified location.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
428 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
429 * The returned string will be limited to \p length bytes or the number
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
430 * of bytes available in \p string, whichever is smaller.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
431 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
432 * \attention the new string references the same memory area as the
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
433 * input string and is usually \em not zero-terminated.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
434 * Use cx_strdup() to get a copy.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
435 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
436 * @param string input string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
437 * @param start start location of the substring
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
438 * @param length the maximum length of the returned string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
439 * @return a substring of \p string starting at \p start
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
440 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
441 * @see cx_strsubs()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
442 * @see cx_strsubs_m()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
443 * @see cx_strsubsl_m()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
444 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
445 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
446 cxstring cx_strsubsl(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
447 cxstring string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
448 size_t start,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
449 size_t length
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
450 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
451
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
452 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
453 * Returns a substring starting at the specified location.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
454 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
455 * \attention the new string references the same memory area as the
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
456 * input string and is usually \em not zero-terminated.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
457 * Use cx_strdup() to get a copy.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
458 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
459 * @param string input string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
460 * @param start start location of the substring
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
461 * @return a substring of \p string starting at \p start
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
462 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
463 * @see cx_strsubsl_m()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
464 * @see cx_strsubs()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
465 * @see cx_strsubsl()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
466 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
467 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
468 cxmutstr cx_strsubs_m(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
469 cxmutstr string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
470 size_t start
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
471 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
472
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
473 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
474 * Returns a substring starting at the specified location.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
475 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
476 * The returned string will be limited to \p length bytes or the number
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
477 * of bytes available in \p string, whichever is smaller.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
478 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
479 * \attention the new string references the same memory area as the
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
480 * input string and is usually \em not zero-terminated.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
481 * Use cx_strdup() to get a copy.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
482 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
483 * @param string input string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
484 * @param start start location of the substring
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
485 * @param length the maximum length of the returned string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
486 * @return a substring of \p string starting at \p start
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
487 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
488 * @see cx_strsubs_m()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
489 * @see cx_strsubs()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
490 * @see cx_strsubsl()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
491 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
492 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
493 cxmutstr cx_strsubsl_m(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
494 cxmutstr string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
495 size_t start,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
496 size_t length
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
497 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
498
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
499 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
500 * Returns a substring starting at the location of the first occurrence of the
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
501 * specified character.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
502 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
503 * If the string does not contain the character, an empty string is returned.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
504 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
505 * @param string the string where to locate the character
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
506 * @param chr the character to locate
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
507 * @return a substring starting at the first location of \p chr
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
508 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
509 * @see cx_strchr_m()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
510 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
511 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
512 cxstring cx_strchr(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
513 cxstring string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
514 int chr
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
515 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
516
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
517 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
518 * Returns a substring starting at the location of the first occurrence of the
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
519 * specified character.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
520 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
521 * If the string does not contain the character, an empty string is returned.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
522 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
523 * @param string the string where to locate the character
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
524 * @param chr the character to locate
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
525 * @return a substring starting at the first location of \p chr
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
526 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
527 * @see cx_strchr()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
528 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
529 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
530 cxmutstr cx_strchr_m(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
531 cxmutstr string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
532 int chr
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
533 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
534
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
535 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
536 * Returns a substring starting at the location of the last occurrence of the
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
537 * specified character.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
538 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
539 * If the string does not contain the character, an empty string is returned.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
540 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
541 * @param string the string where to locate the character
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
542 * @param chr the character to locate
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
543 * @return a substring starting at the last location of \p chr
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
544 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
545 * @see cx_strrchr_m()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
546 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
547 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
548 cxstring cx_strrchr(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
549 cxstring string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
550 int chr
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
551 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
552
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
553 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
554 * Returns a substring starting at the location of the last occurrence of the
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
555 * specified character.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
556 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
557 * If the string does not contain the character, an empty string is returned.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
558 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
559 * @param string the string where to locate the character
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
560 * @param chr the character to locate
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
561 * @return a substring starting at the last location of \p chr
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
562 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
563 * @see cx_strrchr()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
564 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
565 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
566 cxmutstr cx_strrchr_m(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
567 cxmutstr string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
568 int chr
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
569 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
570
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
571 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
572 * Returns a substring starting at the location of the first occurrence of the
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
573 * specified string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
574 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
575 * If \p haystack does not contain \p needle, an empty string is returned.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
576 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
577 * If \p needle is an empty string, the complete \p haystack is
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
578 * returned.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
579 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
580 * @param haystack the string to be scanned
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
581 * @param needle string containing the sequence of characters to match
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
582 * @return a substring starting at the first occurrence of
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
583 * \p needle, or an empty string, if the sequence is not
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
584 * contained
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
585 * @see cx_strstr_m()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
586 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
587 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
588 cxstring cx_strstr(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
589 cxstring haystack,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
590 cxstring needle
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
591 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
592
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
593 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
594 * Returns a substring starting at the location of the first occurrence of the
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
595 * specified string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
596 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
597 * If \p haystack does not contain \p needle, an empty string is returned.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
598 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
599 * If \p needle is an empty string, the complete \p haystack is
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
600 * returned.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
601 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
602 * @param haystack the string to be scanned
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
603 * @param needle string containing the sequence of characters to match
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
604 * @return a substring starting at the first occurrence of
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
605 * \p needle, or an empty string, if the sequence is not
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
606 * contained
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
607 * @see cx_strstr()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
608 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
609 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
610 cxmutstr cx_strstr_m(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
611 cxmutstr haystack,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
612 cxstring needle
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
613 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
614
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
615 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
616 * Splits a given string using a delimiter string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
617 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
618 * \note The resulting array contains strings that point to the source
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
619 * \p string. Use cx_strdup() to get copies.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
620 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
621 * @param string the string to split
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
622 * @param delim the delimiter
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
623 * @param limit the maximum number of split items
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
624 * @param output a pre-allocated array of at least \p limit length
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
625 * @return the actual number of split items
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
626 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
627 cx_attr_nodiscard
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
628 cx_attr_nonnull
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
629 cx_attr_access_w(4, 3)
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
630 size_t cx_strsplit(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
631 cxstring string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
632 cxstring delim,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
633 size_t limit,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
634 cxstring *output
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
635 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
636
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
637 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
638 * Splits a given string using a delimiter string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
639 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
640 * The array pointed to by \p output will be allocated by \p allocator.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
641 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
642 * \note The resulting array contains strings that point to the source
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
643 * \p string. Use cx_strdup() to get copies.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
644 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
645 * \attention If allocation fails, the \c NULL pointer will be written to
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
646 * \p output and the number returned will be zero.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
647 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
648 * @param allocator the allocator to use for allocating the resulting array
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
649 * @param string the string to split
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
650 * @param delim the delimiter
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
651 * @param limit the maximum number of split items
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
652 * @param output a pointer where the address of the allocated array shall be
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
653 * written to
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
654 * @return the actual number of split items
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
655 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
656 cx_attr_nodiscard
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
657 cx_attr_nonnull
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
658 cx_attr_access_w(5)
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
659 size_t cx_strsplit_a(
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
660 const CxAllocator *allocator,
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
661 cxstring string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
662 cxstring delim,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
663 size_t limit,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
664 cxstring **output
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
665 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
666
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
667
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
668 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
669 * Splits a given string using a delimiter string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
670 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
671 * \note The resulting array contains strings that point to the source
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
672 * \p string. Use cx_strdup() to get copies.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
673 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
674 * @param string the string to split
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
675 * @param delim the delimiter
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
676 * @param limit the maximum number of split items
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
677 * @param output a pre-allocated array of at least \p limit length
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
678 * @return the actual number of split items
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
679 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
680 cx_attr_nodiscard
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
681 cx_attr_nonnull
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
682 cx_attr_access_w(4, 3)
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
683 size_t cx_strsplit_m(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
684 cxmutstr string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
685 cxstring delim,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
686 size_t limit,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
687 cxmutstr *output
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
688 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
689
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
690 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
691 * Splits a given string using a delimiter string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
692 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
693 * The array pointed to by \p output will be allocated by \p allocator.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
694 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
695 * \note The resulting array contains strings that point to the source
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
696 * \p string. Use cx_strdup() to get copies.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
697 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
698 * \attention If allocation fails, the \c NULL pointer will be written to
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
699 * \p output and the number returned will be zero.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
700 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
701 * @param allocator the allocator to use for allocating the resulting array
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
702 * @param string the string to split
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
703 * @param delim the delimiter
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
704 * @param limit the maximum number of split items
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
705 * @param output a pointer where the address of the allocated array shall be
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
706 * written to
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
707 * @return the actual number of split items
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
708 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
709 cx_attr_nodiscard
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
710 cx_attr_nonnull
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
711 cx_attr_access_w(5)
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
712 size_t cx_strsplit_ma(
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
713 const CxAllocator *allocator,
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
714 cxmutstr string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
715 cxstring delim,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
716 size_t limit,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
717 cxmutstr **output
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
718 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
719
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
720 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
721 * Compares two strings.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
722 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
723 * @param s1 the first string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
724 * @param s2 the second string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
725 * @return negative if \p s1 is smaller than \p s2, positive if \p s1 is larger
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
726 * than \p s2, zero if both strings equal
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
727 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
728 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
729 int cx_strcmp(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
730 cxstring s1,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
731 cxstring s2
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
732 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
733
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
734 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
735 * Compares two strings ignoring case.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
736 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
737 * @param s1 the first string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
738 * @param s2 the second string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
739 * @return negative if \p s1 is smaller than \p s2, positive if \p s1 is larger
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
740 * than \p s2, zero if both strings equal ignoring case
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
741 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
742 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
743 int cx_strcasecmp(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
744 cxstring s1,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
745 cxstring s2
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
746 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
747
657
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
748 /**
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
749 * Compares two strings.
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
750 *
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents: 657
diff changeset
751 * This function has a compatible signature for the use as a cx_compare_func.
657
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
752 *
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
753 * @param s1 the first string
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
754 * @param s2 the second string
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
755 * @return negative if \p s1 is smaller than \p s2, positive if \p s1 is larger
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
756 * than \p s2, zero if both strings equal
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
757 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
758 cx_attr_nodiscard
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
759 cx_attr_nonnull
657
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
760 int cx_strcmp_p(
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
761 const void *s1,
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
762 const void *s2
657
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
763 );
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
764
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
765 /**
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
766 * Compares two strings ignoring case.
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
767 *
677
b09aae58bba4 refactoring of collections to make use of destructors in map implementations
Mike Becker <universe@uap-core.de>
parents: 657
diff changeset
768 * This function has a compatible signature for the use as a cx_compare_func.
657
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
769 *
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
770 * @param s1 the first string
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
771 * @param s2 the second string
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
772 * @return negative if \p s1 is smaller than \p s2, positive if \p s1 is larger
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
773 * than \p s2, zero if both strings equal ignoring case
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
774 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
775 cx_attr_nodiscard
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
776 cx_attr_nonnull
657
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
777 int cx_strcasecmp_p(
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
778 const void *s1,
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
779 const void *s2
657
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
780 );
3eeadf666d6b add CxListComparator compatible string compare functions
Mike Becker <universe@uap-core.de>
parents: 645
diff changeset
781
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
782
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
783 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
784 * Creates a duplicate of the specified string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
785 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
786 * The new string will contain a copy allocated by \p allocator.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
787 *
589
c290f8fd979e add zero-termination guarantees
Mike Becker <universe@uap-core.de>
parents: 584
diff changeset
788 * \note The returned string is guaranteed to be zero-terminated.
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
789 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
790 * @param allocator the allocator to use
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
791 * @param string the string to duplicate
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
792 * @return a duplicate of the string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
793 * @see cx_strdup()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
794 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
795 cx_attr_nodiscard
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
796 cx_attr_nonnull
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
797 cxmutstr cx_strdup_a(
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
798 const CxAllocator *allocator,
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
799 cxstring string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
800 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
801
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
802 /**
578
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
803 * Creates a duplicate of the specified string.
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
804 *
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
805 * The new string will contain a copy allocated by standard
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
806 * \c malloc(). So developers \em must pass the return value to cx_strfree().
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
807 *
589
c290f8fd979e add zero-termination guarantees
Mike Becker <universe@uap-core.de>
parents: 584
diff changeset
808 * \note The returned string is guaranteed to be zero-terminated.
578
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
809 *
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
810 * @param string the string to duplicate
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
811 * @return a duplicate of the string
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
812 * @see cx_strdup_a()
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
813 */
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
814 #define cx_strdup(string) cx_strdup_a(cxDefaultAllocator, string)
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
815
700
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
816
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
817 /**
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
818 * Creates a duplicate of the specified string.
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
819 *
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
820 * The new string will contain a copy allocated by \p allocator.
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
821 *
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
822 * \note The returned string is guaranteed to be zero-terminated.
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
823 *
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
824 * @param allocator the allocator to use
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
825 * @param string the string to duplicate
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
826 * @return a duplicate of the string
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
827 * @see cx_strdup_m()
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
828 */
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
829 #define cx_strdup_ma(allocator, string) cx_strdup_a(allocator, cx_strcast(string))
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
830
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
831 /**
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
832 * Creates a duplicate of the specified string.
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
833 *
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
834 * The new string will contain a copy allocated by standard
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
835 * \c malloc(). So developers \em must pass the return value to cx_strfree().
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
836 *
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
837 * \note The returned string is guaranteed to be zero-terminated.
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
838 *
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
839 * @param string the string to duplicate
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
840 * @return a duplicate of the string
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
841 * @see cx_strdup_ma()
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
842 */
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
843 #define cx_strdup_m(string) cx_strdup_a(cxDefaultAllocator, cx_strcast(string))
72dccb560084 add cx_strdup_m() and cx_strdup_ma()
Mike Becker <universe@uap-core.de>
parents: 697
diff changeset
844
578
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
845 /**
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
846 * Omits leading and trailing spaces.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
847 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
848 * \note the returned string references the same memory, thus you
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
849 * must \em not free the returned memory.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
850 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
851 * @param string the string that shall be trimmed
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
852 * @return the trimmed string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
853 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
854 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
855 cxstring cx_strtrim(cxstring string);
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
856
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
857 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
858 * Omits leading and trailing spaces.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
859 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
860 * \note the returned string references the same memory, thus you
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
861 * must \em not free the returned memory.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
862 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
863 * @param string the string that shall be trimmed
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
864 * @return the trimmed string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
865 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
866 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
867 cxmutstr cx_strtrim_m(cxmutstr string);
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
868
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
869 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
870 * Checks, if a string has a specific prefix.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
871 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
872 * @param string the string to check
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
873 * @param prefix the prefix the string should have
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
874 * @return \c true, if and only if the string has the specified prefix,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
875 * \c false otherwise
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
876 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
877 cx_attr_nodiscard
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
878 bool cx_strprefix(
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
879 cxstring string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
880 cxstring prefix
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
881 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
882
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
883 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
884 * Checks, if a string has a specific suffix.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
885 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
886 * @param string the string to check
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
887 * @param suffix the suffix the string should have
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
888 * @return \c true, if and only if the string has the specified suffix,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
889 * \c false otherwise
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
890 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
891 cx_attr_nodiscard
581
c067394737ca implement more string functions
Mike Becker <universe@uap-core.de>
parents: 578
diff changeset
892 bool cx_strsuffix(
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
893 cxstring string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
894 cxstring suffix
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
895 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
896
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
897 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
898 * Checks, if a string has a specific prefix, ignoring the case.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
899 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
900 * @param string the string to check
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
901 * @param prefix the prefix the string should have
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
902 * @return \c true, if and only if the string has the specified prefix,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
903 * \c false otherwise
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
904 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
905 cx_attr_nodiscard
581
c067394737ca implement more string functions
Mike Becker <universe@uap-core.de>
parents: 578
diff changeset
906 bool cx_strcaseprefix(
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
907 cxstring string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
908 cxstring prefix
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
909 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
910
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
911 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
912 * Checks, if a string has a specific suffix, ignoring the case.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
913 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
914 * @param string the string to check
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
915 * @param suffix the suffix the string should have
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
916 * @return \c true, if and only if the string has the specified suffix,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
917 * \c false otherwise
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
918 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
919 cx_attr_nodiscard
581
c067394737ca implement more string functions
Mike Becker <universe@uap-core.de>
parents: 578
diff changeset
920 bool cx_strcasesuffix(
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
921 cxstring string,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
922 cxstring suffix
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
923 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
924
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
925 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
926 * Converts the string to lower case.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
927 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
928 * The change is made in-place. If you want a copy, use cx_strdup(), first.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
929 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
930 * @param string the string to modify
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
931 * @see cx_strdup()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
932 */
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
933 void cx_strlower(cxmutstr string);
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
934
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
935 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
936 * Converts the string to upper case.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
937 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
938 * The change is made in-place. If you want a copy, use cx_strdup(), first.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
939 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
940 * @param string the string to modify
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
941 * @see cx_strdup()
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
942 */
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
943 void cx_strupper(cxmutstr string);
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
944
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
945 /**
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
946 * Replaces a pattern in a string with another string.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
947 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
948 * The pattern is taken literally and is no regular expression.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
949 * Replaces at most \p replmax occurrences.
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
950 *
589
c290f8fd979e add zero-termination guarantees
Mike Becker <universe@uap-core.de>
parents: 584
diff changeset
951 * The returned string will be allocated by \p allocator and is guaranteed
c290f8fd979e add zero-termination guarantees
Mike Becker <universe@uap-core.de>
parents: 584
diff changeset
952 * to be zero-terminated.
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
953 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
954 * If allocation fails, or the input string is empty,
583
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
955 * the returned string will be empty.
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
956 *
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
957 * @param allocator the allocator to use
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
958 * @param str the string where replacements should be applied
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
959 * @param pattern the pattern to search for
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
960 * @param replacement the replacement string
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
961 * @param replmax maximum number of replacements
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
962 * @return the resulting string after applying the replacements
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
963 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
964 cx_attr_nodiscard
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
965 cx_attr_nonnull
583
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
966 cxmutstr cx_strreplacen_a(
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
967 const CxAllocator *allocator,
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
968 cxstring str,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
969 cxstring pattern,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
970 cxstring replacement,
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
971 size_t replmax
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
972 );
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
973
578
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
974 /**
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
975 * Replaces a pattern in a string with another string.
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
976 *
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
977 * The pattern is taken literally and is no regular expression.
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
978 * Replaces at most \p replmax occurrences.
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
979 *
589
c290f8fd979e add zero-termination guarantees
Mike Becker <universe@uap-core.de>
parents: 584
diff changeset
980 * The returned string will be allocated by \c malloc() and is guaranteed
c290f8fd979e add zero-termination guarantees
Mike Becker <universe@uap-core.de>
parents: 584
diff changeset
981 * to be zero-terminated.
578
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
982 *
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
983 * If allocation fails, or the input string is empty,
583
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
984 * the returned string will be empty.
578
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
985 *
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
986 * @param str the string where replacements should be applied
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
987 * @param pattern the pattern to search for
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
988 * @param replacement the replacement string
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
989 * @param replmax maximum number of replacements
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
990 * @return the resulting string after applying the replacements
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
991 */
583
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
992 #define cx_strreplacen(str, pattern, replacement, replmax) \
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
993 cx_strreplacen_a(cxDefaultAllocator, str, pattern, replacement, replmax)
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
994
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
995 /**
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
996 * Replaces a pattern in a string with another string.
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
997 *
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
998 * The pattern is taken literally and is no regular expression.
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
999 *
589
c290f8fd979e add zero-termination guarantees
Mike Becker <universe@uap-core.de>
parents: 584
diff changeset
1000 * The returned string will be allocated by \p allocator and is guaranteed
c290f8fd979e add zero-termination guarantees
Mike Becker <universe@uap-core.de>
parents: 584
diff changeset
1001 * to be zero-terminated.
583
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1002 *
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1003 * If allocation fails, or the input string is empty,
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1004 * the returned string will be empty.
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1005 *
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1006 * @param allocator the allocator to use
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1007 * @param str the string where replacements should be applied
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1008 * @param pattern the pattern to search for
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1009 * @param replacement the replacement string
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1010 * @return the resulting string after applying the replacements
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1011 */
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1012 #define cx_strreplace_a(allocator, str, pattern, replacement) \
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1013 cx_strreplacen_a(allocator, str, pattern, replacement, SIZE_MAX)
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1014
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1015 /**
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1016 * Replaces a pattern in a string with another string.
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1017 *
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1018 * The pattern is taken literally and is no regular expression.
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1019 * Replaces at most \p replmax occurrences.
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1020 *
589
c290f8fd979e add zero-termination guarantees
Mike Becker <universe@uap-core.de>
parents: 584
diff changeset
1021 * The returned string will be allocated by \c malloc() and is guaranteed
c290f8fd979e add zero-termination guarantees
Mike Becker <universe@uap-core.de>
parents: 584
diff changeset
1022 * to be zero-terminated.
583
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1023 *
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1024 * If allocation fails, or the input string is empty,
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1025 * the returned string will be empty.
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1026 *
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1027 * @param str the string where replacements should be applied
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1028 * @param pattern the pattern to search for
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1029 * @param replacement the replacement string
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1030 * @return the resulting string after applying the replacements
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1031 */
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1032 #define cx_strreplace(str, pattern, replacement) \
0f3c9662f9b5 add tests and missing implementations for strings
Mike Becker <universe@uap-core.de>
parents: 581
diff changeset
1033 cx_strreplacen_a(cxDefaultAllocator, str, pattern, replacement, SIZE_MAX)
578
0b2c0cb280a9 some function can be macros using the default allocator
Mike Becker <universe@uap-core.de>
parents: 577
diff changeset
1034
645
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1035 /**
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1036 * Creates a string tokenization context.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1037 *
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1038 * @param str the string to tokenize
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1039 * @param delim the delimiter (must not be empty)
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1040 * @param limit the maximum number of tokens that shall be returned
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1041 * @return a new string tokenization context
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1042 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
1043 cx_attr_nodiscard
645
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1044 CxStrtokCtx cx_strtok(
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1045 cxstring str,
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1046 cxstring delim,
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1047 size_t limit
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1048 );
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1049
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1050 /**
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1051 * Creates a string tokenization context for a mutable string.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1052 *
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1053 * @param str the string to tokenize
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1054 * @param delim the delimiter (must not be empty)
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1055 * @param limit the maximum number of tokens that shall be returned
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1056 * @return a new string tokenization context
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1057 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
1058 cx_attr_nodiscard
645
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1059 CxStrtokCtx cx_strtok_m(
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1060 cxmutstr str,
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1061 cxstring delim,
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1062 size_t limit
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1063 );
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1064
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1065 /**
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1066 * Returns the next token.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1067 *
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1068 * The token will point to the source string.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1069 *
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1070 * @param ctx the tokenization context
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1071 * @param token a pointer to memory where the next token shall be stored
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1072 * @return true if successful, false if the limit or the end of the string
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1073 * has been reached
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1074 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
1075 cx_attr_nonnull
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
1076 cx_attr_nodiscard
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
1077 cx_attr_access_w(2)
645
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1078 bool cx_strtok_next(
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1079 CxStrtokCtx *ctx,
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1080 cxstring *token
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1081 );
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1082
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1083 /**
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1084 * Returns the next token of a mutable string.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1085 *
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1086 * The token will point to the source string.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1087 * If the context was not initialized over a mutable string, modifying
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1088 * the data of the returned token is undefined behavior.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1089 *
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1090 * @param ctx the tokenization context
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1091 * @param token a pointer to memory where the next token shall be stored
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1092 * @return true if successful, false if the limit or the end of the string
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1093 * has been reached
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1094 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
1095 cx_attr_nonnull
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
1096 cx_attr_nodiscard
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
1097 cx_attr_access_w(2)
645
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1098 bool cx_strtok_next_m(
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1099 CxStrtokCtx *ctx,
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1100 cxmutstr *token
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1101 );
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1102
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1103 /**
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1104 * Defines an array of more delimiters for the specified tokenization context.
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1105 *
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1106 * @param ctx the tokenization context
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1107 * @param delim array of more delimiters
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1108 * @param count number of elements in the array
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1109 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
1110 cx_attr_nonnull
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 926
diff changeset
1111 cx_attr_access_r(2, 3)
645
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1112 void cx_strtok_delim(
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1113 CxStrtokCtx *ctx,
890
54565fd74e74 move all const keywords to the west - fixes #426
Mike Becker <universe@uap-core.de>
parents: 806
diff changeset
1114 const cxstring *delim,
645
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1115 size_t count
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1116 );
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1117
ec50abb285ad add strtok API - fixes #220
Mike Becker <universe@uap-core.de>
parents: 589
diff changeset
1118
576
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
1119 #ifdef __cplusplus
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
1120 } // extern "C"
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
1121 #endif
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
1122
ba0c4ff6698e first proposal for the string header
Mike Becker <universe@uap-core.de>
parents:
diff changeset
1123 #endif //UCX_STRING_H

mercurial