Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/strings_requirements.md

raw
1 strings requirements
2 ================
3
4 ## Overview
5
6 The STRING object encapsulates a char* variable. This interface is access by STRING_HANDLE variables that provide further encapsulation of the interface.
7
8 ## Exposed API
9 ```c
10 typedef void* STRING_HANDLE;
11
12
13 typedef void* STRING_HANDLE;
14
15 extern STRING_HANDLE STRING_new(void);
16 extern STRING_HANDLE STRING_clone(STRING_HANDLE handle);
17 extern STRING_HANDLE STRING_construct(const char* psz);
18 extern STRING_HANDLE STRING_construct_n(const char* psz, size_t n);
19 extern STRING_HANDLE STRING_new_with_memory(const char* memory);
20 extern STRING_HANDLE STRING_new_quoted(const char* source);
21 extern STRING_HANDLE STRING_new_JSON(const char* source);
22 extern STRING_HANDLE STRING_from_byte_array(const unsigned char* source, size_t size);
23 extern void STRING_delete(STRING_HANDLE handle);
24 extern int STRING_concat(STRING_HANDLE handle, const char* s2);
25 extern int STRING_concat_with_STRING(STRING_HANDLE s1, STRING_HANDLE s2);
26 extern int STRING_quote(STRING_HANDLE handle);
27 extern int STRING_copy(STRING_HANDLE s1, const char* s2);
28 extern int STRING_copy_n(STRING_HANDLE s1, const char* s2, size_t n);
29 extern const char* STRING_c_str(STRING_HANDLE handle);
30 extern int STRING_empty(STRING_HANDLE handle);
31 extern size_t STRING_length(STRING_HANDLE handle);
32 extern int STRING_compare(STRING_HANDLE h1, STRING_HANDLE h2);
33 extern STRING_HANDLE STRING_construct_sprintf(const char* format, ...);
34 extern int STRING_sprintf(STRING_HANDLE s1, const char* format, ...);
35
36 ```
37
38 ### STRING_new
39 ```c
40 extern STRING_HANDLE STRING_new(void);
41 ```
42
43 **SRS_STRING_07_001: [** STRING_new shall allocate a new STRING_HANDLE pointing to an empty string. **]**
44
45 **SRS_STRING_07_002: [** STRING_new shall return an NULL STRING_HANDLE on any error that is encountered. **]**
46
47 ### STRING_clone
48 ```c
49 extern STRING_HANDLE STRING_clone(STRING_HANDLE handle);
50 ```
51
52 **SRS_STRING_02_001: [** STRING_clone shall produce a new string having the same content as the handle string. **]**
53
54 **SRS_STRING_02_002: [** If parameter handle is NULL then STRING_clone shall return NULL. **]**
55
56 **SRS_STRING_02_003: [** If STRING_clone fails for any reason, it shall return NULL. **]**
57
58 ### STRING_construct
59 ```c
60 extern STRING_HANDLE STRING_construct(const char*)
61 ```
62
63 **SRS_STRING_07_003: [** STRING_construct shall allocate a new string with the value of the specified const char*. **]**
64
65 **SRS_STRING_07_005: [** If the supplied const char* is NULL STRING_construct shall return a NULL value. **]**
66
67 **SRS_STRING_07_032: [** STRING_construct encounters any error it shall return a NULL value. **]**
68
69 ### STRING_new_with_memory
70 ```c
71 extern STRING_HANDLE STRING_new_with_memory(char*)
72 ```
73
74 **SRS_STRING_07_006: [** STRING_new_with_memory shall return a STRING_HANDLE by using the supplied char* memory. **]**
75
76 **SRS_STRING_07_007: [** STRING_new_with_memory shall return a NULL STRING_HANDLE if the supplied char* is NULL. **]**
77
78 ### STRING_new_quoted
79 ```c
80 extern STRING_HANDLE STRING_new_quoted(const char*)
81 ```
82 **SRS_STRING_07_008: [** STRING_new_quoted shall return a valid STRING_HANDLE Copying the supplied const char* value surrounded by quotes. **]**
83
84 **SRS_STRING_07_009: [** STRING_new_quoted shall return a NULL STRING_HANDLE if the supplied const char* is NULL. **]**
85
86 **SRS_STRING_07_031: [** STRING_new_quoted shall return a NULL STRING_HANDLE if any error is encountered. **]**
87
88 ### STRING_new_JSON
89 ```c
90 extern STRING_HANDLE STRING_new_JSON(const char* source);
91 ```
92
93 STRING_new_JSON produces a JSON value representation of the parameter passed as argument source.
94
95 **SRS_STRING_02_011: [** If source is NULL then STRING_new_JSON shall return NULL. **]**
96
97 STRING_new_JSON shall produce a STRING_HANDLE according to the following:
98
99 **SRS_STRING_02_012: [** The string shall begin with the quote character. **]**
100
101 **SRS_STRING_02_013: [** The string shall copy the characters of source "as they are" (until the '\0' character) with the following exceptions: **]**
102
103 **SRS_STRING_02_014: [** If any character has the value outside [1...127 **]** then STRING_new_JSON shall fail and return NULL.]
104 **SRS_STRING_02_016: [** If the character is " (quote) then it shall be repsented as \". **]**
105 **SRS_STRING_02_017: [** If the character is \ (backslash) then it shall represented as \\. **]**
106 **SRS_STRING_02_018: [** If the character is / (slash) then it shall be represented as \/. **]**
107 **SRS_STRING_02_019: [** If the character code is less than 0x20 then it shall be represented as \u00xx, where xx is the hex representation of the character code. **]**
108
109 **SRS_STRING_02_020: [** The string shall end with " (quote). **]**
110
111 **SRS_STRING_02_021: [** If the complete JSON representation cannot be produced, then STRING_new_JSON shall fail and return NULL. **]**
112
113 ### STRING_delete
114 ```c
115 extern void STRING_delete(STRING_HANDLE handle);
116 ```
117
118 **SRS_STRING_07_010: [** STRING_delete will free the memory allocated by the STRING_HANDLE. **]**
119
120 **SRS_STRING_07_011: [** STRING_delete will not attempt to free anything with a NULL STRING_HANDLE. **]**
121
122 ### STRING_concat
123 ```c
124 extern int STRING_concat(STRING_HANDLE handle, const char* s2)
125 ```
126 **SRS_STRING_07_012: [** STRING_concat shall concatenate the given STRING_HANDLE and the const char* value and place the value in the handle. **]**
127
128 **SRS_STRING_07_013: [** STRING_concat shall return a nonzero number if an error is encountered. **]**
129
130 ### STRING_concat
131 ```c
132 extern int STRING_concat(STRING_HANDLE handle, const char* s2)
133 ```
134 **SRS_STRING_07_034: [** String_Concat_with_STRING shall concatenate a given STRING_HANDLE variable with a source STRING_HANDLE. **]**
135
136 **SRS_STRING_07_035: [** String_Concat_with_STRING shall return a nonzero number if an error is encountered. **]**
137
138 ### STRING_quote
139 ```c
140 extern int STRING_quote(STRING_HANDLE handle)
141 ```
142 **SRS_STRING_07_014: [** STRING_quote shall "quote" the supplied STRING_HANDLE and return 0 on success. **]**
143
144 **SRS_STRING_07_015: [** STRING_quote shall return a nonzero value if any of the supplied parameters are NULL. **]**
145
146 **SRS_STRING_07_029: [** STRING_quote shall return a nonzero value if any error is encountered. **]**
147
148 ### STRING_copy
149 ```c
150 extern int STRING_copy(STRING_HANDLE s1, const char* s2)
151 ```
152 **SRS_STRING_07_016: [** STRING_copy shall copy the const char* into the supplied STRING_HANDLE. **]**
153
154 **SRS_STRING_07_017: [** STRING_copy shall return a nonzero value if any of the supplied parameters are NULL. **]**
155
156 **SRS_STRING_07_027: [** STRING_copy shall return a nonzero value if any error is encountered. **]**
157
158 **SRS_STRING_07_026: [** If the underlying char* refered to by s1 handle is equal to char* s2 than STRING_copy shall be a noop and return 0. **]**
159
160 **SRS_STRING_07_033: [** If overlapping pointer address is given to STRING_copy the behavior is undefined. **]**
161
162 ### STRING_copy_n
163
164 ```c
165 extern int STRING_copy_n(STRING_HANDLE s1, const char* s2, size_t n)
166 ```
167
168 **SRS_STRING_07_018: [** STRING_copy_n shall copy the number of characters in const char* or the size_t whichever is lesser. **]**
169
170 **SRS_STRING_07_019: [** STRING_copy_n shall return a nonzero value if STRING_HANDLE or const char* is NULL. **]**
171
172 **SRS_STRING_07_028: [** STRING_copy_n shall return a nonzero value if any error is encountered. **]**
173
174 ### STRING_c_str
175
176 ```c
177 extern const char* STRING_c_str(STRING_HANDLE handle)
178 ```
179
180 **SRS_STRING_07_020: [** STRING_c_str shall return the const char* associated with the given STRING_HANDLE. **]**
181
182 **SRS_STRING_07_021: [** STRING_c_str shall return NULL if the STRING_HANDLE is NULL. **]**
183
184 ### STRING_empty
185
186 ```c
187 extern int STRING_empty(STRING_HANDLE s1)
188 ```
189
190 **SRS_STRING_07_022: [** STRING_empty shall revert the STRING_HANDLE to an empty state. **]**
191
192 **SRS_STRING_07_023: [** STRING_empty shall return a nonzero value if the STRING_HANDLE is NULL. **]**
193
194 **SRS_STRING_07_030: [** STRING_empty shall return a nonzero value if the STRING_HANDLE is NULL. **]**
195
196 ### STRING_length
197
198 ```c
199 extern size_t STRING_length(STRING_HANDLE handle)
200 ```
201
202 **SRS_STRING_07_024: [** STRING_length shall return the length of the underlying char* for the given handle **]**
203
204 **SRS_STRING_07_025: [** STRING_length shall return zero if the given handle is NULL. **]**
205
206 ### STRING_construct_n
207
208 ```c
209 extern STRING_HANDLE STRING_construct_n(const char* psz, size_t n);
210 ```
211
212 **SRS_STRING_02_007: [** STRING_construct_n shall construct a STRING_HANDLE from first "n" characters of the string pointed to by psz parameter. **]**
213
214 **SRS_STRING_02_008: [** If psz is NULL then STRING_construct_n shall return NULL. **]**
215
216 **SRS_STRING_02_009: [** If n is bigger than the size of the string psz, then STRING_construct_n shall return NULL. **]**
217
218 **SRS_STRING_02_010: [** In all other error cases, STRING_construct_n shall return NULL. **]**
219
220 ### STRING_compare
221
222 ```c
223 extern int STRING_compare(STRING_HANDLE h1, STRING_HANDLE h2);
224 ```
225
226 **SRS_STRING_07_034: [** STRING_compare returns an integer greater than, equal to, or less than zero, accordingly as the string pointed to by s1 is greater than, equal to, or less than the string s2. **]**
227
228 **SRS_STRING_07_035: [** If h1 and h2 are both NULL then STRING_compare shall return 0. **]**
229
230 **SRS_STRING_07_036: [** If h1 is NULL and h2 is a nonNULL value then STRING_compare shall return 1. **]**
231
232 **SRS_STRING_07_037: [** If h2 is NULL and h1 is a nonNULL value then STRING_compare shall return -1. **]**
233
234 **SRS_STRING_07_038: [** STRING_compare shall compare the char s variable using the strcmp function. **]**
235
236 ### STRING_from_byte_array
237
238 ```c
239 extern STRING_HANDLE STRING_from_byte_array(const unsigned char* source, size_t size)
240 ```
241
242 STRING_from_BUFFER builds a string that has the same content (byte-by-byte) as a byte array.
243
244 **SRS_STRING_02_022: [** If `source` is NULL and size > 0 then `STRING_from_BUFFER` shall fail and return NULL. **]**
245
246 **SRS_STRING_02_023: [** Otherwise, `STRING_from_BUFFER` shall build a string that has the same content (byte-by-byte) as source and return a non-NULL handle. **]**
247
248 **SRS_STRING_02_024: [** If building the string fails, then `STRING_from_BUFFER` shall fail and return NULL. **]**
249
250 ### STRING_construct_sprintf
251
252 ```c
253 extern STRING_HANDLE STRING_construct_sprintf(const char* format, ...);
254 ```
255
256 STRING_construct_sprintf constructs the STRING_HANDLE from a printf formatting
257
258 **SRS_STRING_07_039: [** If the parameter format is NULL then STRING_construct_sprintf shall return NULL. **]**
259
260 **SRS_STRING_07_040: [** If any error is encountered STRING_construct_sprintf shall return NULL. **]**
261
262 **SRS_STRING_07_041: [** STRING_construct_sprintf shall determine the size of the resulting string and allocate the necessary memory. **]**
263
264 **SRS_STRING_07_045: [** STRING_construct_sprintf shall allocate a new string with the value of the specified printf formated const char. **]**
265
266 ### STRING_sprintf
267
268 ```c
269 extern int STRING_sprintf(STRING_HANDLE s1, const char* format, ...);
270 ```
271
272 STRING_sprintf shall append a printf format style string to the end of a STRING_HANDLE.
273
274 **SRS_STRING_07_042: [** if the parameters s1 or format are NULL then STRING_sprintf shall return non zero value. **]**
275
276 **SRS_STRING_07_043: [** If any error is encountered STRING_sprintf shall return a non zero value. **]**
277
278 **SRS_STRING_07_044: [** On success STRING_sprintf shall return 0. **]**
279
280 ### STRING_replace
281
282 ```c
283 int STRING_replace(STRING_HANDLE handle, char target, char replace)
284 ```
285
286 **SRS_STRING_07_046: [** If handle is NULL `STRING_replace` shall return a non-zero value. **]**
287
288 **SRS_STRING_07_047: [** `STRING_replace` shall replace all instances of target with replace. **]**
289
290 **SRS_STRING_07_048: [** If target and replace are equal `STRING_replace`, shall do nothing shall return zero. **]**
291
292 **SRS_STRING_07_049: [** On success `STRING_replace` shall return zero. **]**