1 | /** @file
|
---|
2 | * IPRT - String Manipluation.
|
---|
3 | */
|
---|
4 |
|
---|
5 | /*
|
---|
6 | * Copyright (C) 2006-2007 Sun Microsystems, Inc.
|
---|
7 | *
|
---|
8 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
9 | * available from http://www.virtualbox.org. This file is free software;
|
---|
10 | * you can redistribute it and/or modify it under the terms of the GNU
|
---|
11 | * General Public License (GPL) as published by the Free Software
|
---|
12 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
13 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
14 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
15 | *
|
---|
16 | * The contents of this file may alternatively be used under the terms
|
---|
17 | * of the Common Development and Distribution License Version 1.0
|
---|
18 | * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
|
---|
19 | * VirtualBox OSE distribution, in which case the provisions of the
|
---|
20 | * CDDL are applicable instead of those of the GPL.
|
---|
21 | *
|
---|
22 | * You may elect to license modified versions of this file under the
|
---|
23 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
24 | *
|
---|
25 | * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
|
---|
26 | * Clara, CA 95054 USA or visit http://www.sun.com if you need
|
---|
27 | * additional information or have any questions.
|
---|
28 | */
|
---|
29 |
|
---|
30 | #ifndef ___iprt_string_h
|
---|
31 | #define ___iprt_string_h
|
---|
32 |
|
---|
33 | #include <iprt/cdefs.h>
|
---|
34 | #include <iprt/types.h>
|
---|
35 | #include <iprt/stdarg.h>
|
---|
36 | #include <iprt/err.h> /* for VINF_SUCCESS */
|
---|
37 | #if defined(RT_OS_LINUX) && defined(__KERNEL__)
|
---|
38 | # include <linux/string.h>
|
---|
39 | #elif defined(RT_OS_FREEBSD) && defined(_KERNEL)
|
---|
40 | /*
|
---|
41 | * Kludge for the FreeBSD kernel:
|
---|
42 | * Some of the string.h stuff clashes with sys/libkern.h, so just wrap
|
---|
43 | * it up while including string.h to keep things quiet. It's nothing
|
---|
44 | * important that's clashing, after all.
|
---|
45 | */
|
---|
46 | # define strdup strdup_string_h
|
---|
47 | # include <string.h>
|
---|
48 | # undef strdup
|
---|
49 | #elif defined(RT_OS_SOLARIS) && defined(_KERNEL)
|
---|
50 | /*
|
---|
51 | * Same case as with FreeBSD kernel:
|
---|
52 | * The string.h stuff clashes with sys/system.h
|
---|
53 | * ffs = find first set bit.
|
---|
54 | */
|
---|
55 | # define ffs ffs_string_h
|
---|
56 | # include <string.h>
|
---|
57 | # undef ffs
|
---|
58 | # undef strpbrk
|
---|
59 | #else
|
---|
60 | # include <string.h>
|
---|
61 | #endif
|
---|
62 |
|
---|
63 | /*
|
---|
64 | * Supply prototypes for standard string functions provided by
|
---|
65 | * IPRT instead of the operating environment.
|
---|
66 | */
|
---|
67 | #if defined(RT_OS_DARWIN) && defined(KERNEL)
|
---|
68 | RT_C_DECLS_BEGIN
|
---|
69 | void *memchr(const void *pv, int ch, size_t cb);
|
---|
70 | char *strpbrk(const char *pszStr, const char *pszChars);
|
---|
71 | RT_C_DECLS_END
|
---|
72 | #endif
|
---|
73 |
|
---|
74 | /**
|
---|
75 | * Byte zero the specified object.
|
---|
76 | *
|
---|
77 | * This will use sizeof(Obj) to figure the size and will call memset, bzero
|
---|
78 | * or some compiler intrinsic to perform the actual zeroing.
|
---|
79 | *
|
---|
80 | * @param Obj The object to zero. Make sure to dereference pointers.
|
---|
81 | *
|
---|
82 | * @remarks Because the macro may use memset it has been placed in string.h
|
---|
83 | * instead of cdefs.h to avoid build issues because someone forgot
|
---|
84 | * to include this header.
|
---|
85 | *
|
---|
86 | * @ingroup grp_rt_cdefs
|
---|
87 | */
|
---|
88 | #define RT_ZERO(Obj) RT_BZERO(&(Obj), sizeof(Obj))
|
---|
89 |
|
---|
90 | /**
|
---|
91 | * Byte zero the specified memory area.
|
---|
92 | *
|
---|
93 | * This will call memset, bzero or some compiler intrinsic to clear the
|
---|
94 | * specified bytes of memory.
|
---|
95 | *
|
---|
96 | * @param pv Pointer to the memory.
|
---|
97 | * @param cb The number of bytes to clear. Please, don't pass 0.
|
---|
98 | *
|
---|
99 | * @remarks Because the macro may use memset it has been placed in string.h
|
---|
100 | * instead of cdefs.h to avoid build issues because someone forgot
|
---|
101 | * to include this header.
|
---|
102 | *
|
---|
103 | * @ingroup grp_rt_cdefs
|
---|
104 | */
|
---|
105 | #define RT_BZERO(pv, cb) do { memset((pv), 0, cb); } while (0)
|
---|
106 |
|
---|
107 |
|
---|
108 | /** @defgroup grp_rt_str RTStr - String Manipulation
|
---|
109 | * Mostly UTF-8 related helpers where the standard string functions won't do.
|
---|
110 | * @ingroup grp_rt
|
---|
111 | * @{
|
---|
112 | */
|
---|
113 |
|
---|
114 | RT_C_DECLS_BEGIN
|
---|
115 |
|
---|
116 |
|
---|
117 | /**
|
---|
118 | * The maximum string length.
|
---|
119 | */
|
---|
120 | #define RTSTR_MAX (~(size_t)0)
|
---|
121 |
|
---|
122 |
|
---|
123 | #ifdef IN_RING3
|
---|
124 |
|
---|
125 | /**
|
---|
126 | * Allocates tmp buffer, translates pszString from UTF8 to current codepage.
|
---|
127 | *
|
---|
128 | * @returns iprt status code.
|
---|
129 | * @param ppszString Receives pointer of allocated native CP string.
|
---|
130 | * The returned pointer must be freed using RTStrFree().
|
---|
131 | * @param pszString UTF-8 string to convert.
|
---|
132 | */
|
---|
133 | RTR3DECL(int) RTStrUtf8ToCurrentCP(char **ppszString, const char *pszString);
|
---|
134 |
|
---|
135 | /**
|
---|
136 | * Allocates tmp buffer, translates pszString from current codepage to UTF-8.
|
---|
137 | *
|
---|
138 | * @returns iprt status code.
|
---|
139 | * @param ppszString Receives pointer of allocated UTF-8 string.
|
---|
140 | * The returned pointer must be freed using RTStrFree().
|
---|
141 | * @param pszString Native string to convert.
|
---|
142 | */
|
---|
143 | RTR3DECL(int) RTStrCurrentCPToUtf8(char **ppszString, const char *pszString);
|
---|
144 |
|
---|
145 | #endif
|
---|
146 |
|
---|
147 | /**
|
---|
148 | * Free string allocated by any of the non-UCS-2 string functions.
|
---|
149 | *
|
---|
150 | * @returns iprt status code.
|
---|
151 | * @param pszString Pointer to buffer with string to free.
|
---|
152 | * NULL is accepted.
|
---|
153 | */
|
---|
154 | RTDECL(void) RTStrFree(char *pszString);
|
---|
155 |
|
---|
156 | /**
|
---|
157 | * Allocates a new copy of the given UTF-8 string.
|
---|
158 | *
|
---|
159 | * @returns Pointer to the allocated UTF-8 string.
|
---|
160 | * @param pszString UTF-8 string to duplicate.
|
---|
161 | */
|
---|
162 | RTDECL(char *) RTStrDup(const char *pszString);
|
---|
163 |
|
---|
164 | /**
|
---|
165 | * Allocates a new copy of the given UTF-8 string.
|
---|
166 | *
|
---|
167 | * @returns iprt status code.
|
---|
168 | * @param ppszString Receives pointer of the allocated UTF-8 string.
|
---|
169 | * The returned pointer must be freed using RTStrFree().
|
---|
170 | * @param pszString UTF-8 string to duplicate.
|
---|
171 | */
|
---|
172 | RTDECL(int) RTStrDupEx(char **ppszString, const char *pszString);
|
---|
173 |
|
---|
174 | /**
|
---|
175 | * Validates the UTF-8 encoding of the string.
|
---|
176 | *
|
---|
177 | * @returns iprt status code.
|
---|
178 | * @param psz The string.
|
---|
179 | */
|
---|
180 | RTDECL(int) RTStrValidateEncoding(const char *psz);
|
---|
181 |
|
---|
182 | /** @name Flags for RTStrValidateEncodingEx
|
---|
183 | */
|
---|
184 | /** Check that the string is zero terminated within the given size.
|
---|
185 | * VERR_BUFFER_OVERFLOW will be returned if the check fails. */
|
---|
186 | #define RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED RT_BIT_32(0)
|
---|
187 | /** @} */
|
---|
188 |
|
---|
189 | /**
|
---|
190 | * Validates the UTF-8 encoding of the string.
|
---|
191 | *
|
---|
192 | * @returns iprt status code.
|
---|
193 | * @param psz The string.
|
---|
194 | * @param cch The max string length. Use RTSTR_MAX to process the entire string.
|
---|
195 | * @param fFlags Reserved for future. Pass 0.
|
---|
196 | */
|
---|
197 | RTDECL(int) RTStrValidateEncodingEx(const char *psz, size_t cch, uint32_t fFlags);
|
---|
198 |
|
---|
199 | /**
|
---|
200 | * Checks if the UTF-8 encoding is valid.
|
---|
201 | *
|
---|
202 | * @returns true / false.
|
---|
203 | * @param psz The string.
|
---|
204 | */
|
---|
205 | RTDECL(bool) RTStrIsValidEncoding(const char *psz);
|
---|
206 |
|
---|
207 | /**
|
---|
208 | * Gets the number of code points the string is made up of, excluding
|
---|
209 | * the terminator.
|
---|
210 | *
|
---|
211 | *
|
---|
212 | * @returns Number of code points (RTUNICP).
|
---|
213 | * @returns 0 if the string was incorrectly encoded.
|
---|
214 | * @param psz The string.
|
---|
215 | */
|
---|
216 | RTDECL(size_t) RTStrUniLen(const char *psz);
|
---|
217 |
|
---|
218 | /**
|
---|
219 | * Gets the number of code points the string is made up of, excluding
|
---|
220 | * the terminator.
|
---|
221 | *
|
---|
222 | * This function will validate the string, and incorrectly encoded UTF-8
|
---|
223 | * strings will be rejected.
|
---|
224 | *
|
---|
225 | * @returns iprt status code.
|
---|
226 | * @param psz The string.
|
---|
227 | * @param cch The max string length. Use RTSTR_MAX to process the entire string.
|
---|
228 | * @param pcuc Where to store the code point count.
|
---|
229 | * This is undefined on failure.
|
---|
230 | */
|
---|
231 | RTDECL(int) RTStrUniLenEx(const char *psz, size_t cch, size_t *pcuc);
|
---|
232 |
|
---|
233 | /**
|
---|
234 | * Translate a UTF-8 string into an unicode string (i.e. RTUNICPs), allocating the string buffer.
|
---|
235 | *
|
---|
236 | * @returns iprt status code.
|
---|
237 | * @param pszString UTF-8 string to convert.
|
---|
238 | * @param ppUniString Receives pointer to the allocated unicode string.
|
---|
239 | * The returned string must be freed using RTUniFree().
|
---|
240 | */
|
---|
241 | RTDECL(int) RTStrToUni(const char *pszString, PRTUNICP *ppUniString);
|
---|
242 |
|
---|
243 | /**
|
---|
244 | * Translates pszString from UTF-8 to an array of code points, allocating the result
|
---|
245 | * array if requested.
|
---|
246 | *
|
---|
247 | * @returns iprt status code.
|
---|
248 | * @param pszString UTF-8 string to convert.
|
---|
249 | * @param cchString The maximum size in chars (the type) to convert. The conversion stop
|
---|
250 | * when it reaches cchString or the string terminator ('\\0').
|
---|
251 | * Use RTSTR_MAX to translate the entire string.
|
---|
252 | * @param ppaCps If cCps is non-zero, this must either be pointing to pointer to
|
---|
253 | * a buffer of the specified size, or pointer to a NULL pointer.
|
---|
254 | * If *ppusz is NULL or cCps is zero a buffer of at least cCps items
|
---|
255 | * will be allocated to hold the translated string.
|
---|
256 | * If a buffer was requested it must be freed using RTUtf16Free().
|
---|
257 | * @param cCps The number of code points in the unicode string. This includes the terminator.
|
---|
258 | * @param pcCps Where to store the length of the translated string,
|
---|
259 | * excluding the terminator. (Optional)
|
---|
260 | *
|
---|
261 | * This may be set under some error conditions,
|
---|
262 | * however, only for VERR_BUFFER_OVERFLOW and
|
---|
263 | * VERR_NO_STR_MEMORY will it contain a valid string
|
---|
264 | * length that can be used to resize the buffer.
|
---|
265 | */
|
---|
266 | RTDECL(int) RTStrToUniEx(const char *pszString, size_t cchString, PRTUNICP *ppaCps, size_t cCps, size_t *pcCps);
|
---|
267 |
|
---|
268 | /**
|
---|
269 | * Calculates the length of the string in RTUTF16 items.
|
---|
270 | *
|
---|
271 | * This function will validate the string, and incorrectly encoded UTF-8
|
---|
272 | * strings will be rejected. The primary purpose of this function is to
|
---|
273 | * help allocate buffers for RTStrToUtf16Ex of the correct size. For most
|
---|
274 | * other purposes RTStrCalcUtf16LenEx() should be used.
|
---|
275 | *
|
---|
276 | * @returns Number of RTUTF16 items.
|
---|
277 | * @returns 0 if the string was incorrectly encoded.
|
---|
278 | * @param psz The string.
|
---|
279 | */
|
---|
280 | RTDECL(size_t) RTStrCalcUtf16Len(const char *psz);
|
---|
281 |
|
---|
282 | /**
|
---|
283 | * Calculates the length of the string in RTUTF16 items.
|
---|
284 | *
|
---|
285 | * This function will validate the string, and incorrectly encoded UTF-8
|
---|
286 | * strings will be rejected.
|
---|
287 | *
|
---|
288 | * @returns iprt status code.
|
---|
289 | * @param psz The string.
|
---|
290 | * @param cch The max string length. Use RTSTR_MAX to process the entire string.
|
---|
291 | * @param pcwc Where to store the string length. Optional.
|
---|
292 | * This is undefined on failure.
|
---|
293 | */
|
---|
294 | RTDECL(int) RTStrCalcUtf16LenEx(const char *psz, size_t cch, size_t *pcwc);
|
---|
295 |
|
---|
296 | /**
|
---|
297 | * Translate a UTF-8 string into a UTF-16 allocating the result buffer.
|
---|
298 | *
|
---|
299 | * @returns iprt status code.
|
---|
300 | * @param pszString UTF-8 string to convert.
|
---|
301 | * @param ppwszString Receives pointer to the allocated UTF-16 string.
|
---|
302 | * The returned string must be freed using RTUtf16Free().
|
---|
303 | */
|
---|
304 | RTDECL(int) RTStrToUtf16(const char *pszString, PRTUTF16 *ppwszString);
|
---|
305 |
|
---|
306 | /**
|
---|
307 | * Translates pszString from UTF-8 to UTF-16, allocating the result buffer if requested.
|
---|
308 | *
|
---|
309 | * @returns iprt status code.
|
---|
310 | * @param pszString UTF-8 string to convert.
|
---|
311 | * @param cchString The maximum size in chars (the type) to convert. The conversion stop
|
---|
312 | * when it reaches cchString or the string terminator ('\\0').
|
---|
313 | * Use RTSTR_MAX to translate the entire string.
|
---|
314 | * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
|
---|
315 | * a buffer of the specified size, or pointer to a NULL pointer.
|
---|
316 | * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
|
---|
317 | * will be allocated to hold the translated string.
|
---|
318 | * If a buffer was requested it must be freed using RTUtf16Free().
|
---|
319 | * @param cwc The buffer size in RTUTF16s. This includes the terminator.
|
---|
320 | * @param pcwc Where to store the length of the translated string,
|
---|
321 | * excluding the terminator. (Optional)
|
---|
322 | *
|
---|
323 | * This may be set under some error conditions,
|
---|
324 | * however, only for VERR_BUFFER_OVERFLOW and
|
---|
325 | * VERR_NO_STR_MEMORY will it contain a valid string
|
---|
326 | * length that can be used to resize the buffer.
|
---|
327 | */
|
---|
328 | RTDECL(int) RTStrToUtf16Ex(const char *pszString, size_t cchString, PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc);
|
---|
329 |
|
---|
330 |
|
---|
331 | /**
|
---|
332 | * Get the unicode code point at the given string position.
|
---|
333 | *
|
---|
334 | * @returns unicode code point.
|
---|
335 | * @returns RTUNICP_INVALID if the encoding is invalid.
|
---|
336 | * @param psz The string.
|
---|
337 | */
|
---|
338 | RTDECL(RTUNICP) RTStrGetCpInternal(const char *psz);
|
---|
339 |
|
---|
340 | /**
|
---|
341 | * Get the unicode code point at the given string position.
|
---|
342 | *
|
---|
343 | * @returns iprt status code
|
---|
344 | * @returns VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
|
---|
345 | * @param ppsz The string.
|
---|
346 | * @param pCp Where to store the unicode code point.
|
---|
347 | * Stores RTUNICP_INVALID if the encoding is invalid.
|
---|
348 | */
|
---|
349 | RTDECL(int) RTStrGetCpExInternal(const char **ppsz, PRTUNICP pCp);
|
---|
350 |
|
---|
351 | /**
|
---|
352 | * Get the unicode code point at the given string position for a string of a
|
---|
353 | * given length.
|
---|
354 | *
|
---|
355 | * @returns iprt status code
|
---|
356 | * @retval VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
|
---|
357 | * @retval VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
|
---|
358 | *
|
---|
359 | * @param ppsz The string.
|
---|
360 | * @param pcch Pointer to the length of the string. This will be
|
---|
361 | * decremented by the size of the code point.
|
---|
362 | * @param pCp Where to store the unicode code point.
|
---|
363 | * Stores RTUNICP_INVALID if the encoding is invalid.
|
---|
364 | */
|
---|
365 | RTDECL(int) RTStrGetCpNExInternal(const char **ppsz, size_t *pcch, PRTUNICP pCp);
|
---|
366 |
|
---|
367 | /**
|
---|
368 | * Put the unicode code point at the given string position
|
---|
369 | * and return the pointer to the char following it.
|
---|
370 | *
|
---|
371 | * This function will not consider anything at or following the
|
---|
372 | * buffer area pointed to by psz. It is therefore not suitable for
|
---|
373 | * inserting code points into a string, only appending/overwriting.
|
---|
374 | *
|
---|
375 | * @returns pointer to the char following the written code point.
|
---|
376 | * @param psz The string.
|
---|
377 | * @param CodePoint The code point to write.
|
---|
378 | * This should not be RTUNICP_INVALID or any other
|
---|
379 | * character out of the UTF-8 range.
|
---|
380 | *
|
---|
381 | * @remark This is a worker function for RTStrPutCp().
|
---|
382 | *
|
---|
383 | */
|
---|
384 | RTDECL(char *) RTStrPutCpInternal(char *psz, RTUNICP CodePoint);
|
---|
385 |
|
---|
386 | /**
|
---|
387 | * Get the unicode code point at the given string position.
|
---|
388 | *
|
---|
389 | * @returns unicode code point.
|
---|
390 | * @returns RTUNICP_INVALID if the encoding is invalid.
|
---|
391 | * @param psz The string.
|
---|
392 | *
|
---|
393 | * @remark We optimize this operation by using an inline function for
|
---|
394 | * the most frequent and simplest sequence, the rest is
|
---|
395 | * handled by RTStrGetCpInternal().
|
---|
396 | */
|
---|
397 | DECLINLINE(RTUNICP) RTStrGetCp(const char *psz)
|
---|
398 | {
|
---|
399 | const unsigned char uch = *(const unsigned char *)psz;
|
---|
400 | if (!(uch & RT_BIT(7)))
|
---|
401 | return uch;
|
---|
402 | return RTStrGetCpInternal(psz);
|
---|
403 | }
|
---|
404 |
|
---|
405 | /**
|
---|
406 | * Get the unicode code point at the given string position.
|
---|
407 | *
|
---|
408 | * @returns iprt status code.
|
---|
409 | * @param ppsz Pointer to the string pointer. This will be updated to
|
---|
410 | * point to the char following the current code point.
|
---|
411 | * @param pCp Where to store the code point.
|
---|
412 | * RTUNICP_INVALID is stored here on failure.
|
---|
413 | *
|
---|
414 | * @remark We optimize this operation by using an inline function for
|
---|
415 | * the most frequent and simplest sequence, the rest is
|
---|
416 | * handled by RTStrGetCpExInternal().
|
---|
417 | */
|
---|
418 | DECLINLINE(int) RTStrGetCpEx(const char **ppsz, PRTUNICP pCp)
|
---|
419 | {
|
---|
420 | const unsigned char uch = **(const unsigned char **)ppsz;
|
---|
421 | if (!(uch & RT_BIT(7)))
|
---|
422 | {
|
---|
423 | (*ppsz)++;
|
---|
424 | *pCp = uch;
|
---|
425 | return VINF_SUCCESS;
|
---|
426 | }
|
---|
427 | return RTStrGetCpExInternal(ppsz, pCp);
|
---|
428 | }
|
---|
429 |
|
---|
430 | /**
|
---|
431 | * Get the unicode code point at the given string position for a string of a
|
---|
432 | * given maximum length.
|
---|
433 | *
|
---|
434 | * @returns iprt status code.
|
---|
435 | * @retval VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
|
---|
436 | * @retval VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
|
---|
437 | *
|
---|
438 | * @param ppsz Pointer to the string pointer. This will be updated to
|
---|
439 | * point to the char following the current code point.
|
---|
440 | * @param pcch Pointer to the maximum string length. This will be
|
---|
441 | * decremented by the size of the code point found.
|
---|
442 | * @param pCp Where to store the code point.
|
---|
443 | * RTUNICP_INVALID is stored here on failure.
|
---|
444 | *
|
---|
445 | * @remark We optimize this operation by using an inline function for
|
---|
446 | * the most frequent and simplest sequence, the rest is
|
---|
447 | * handled by RTStrGetCpNExInternal().
|
---|
448 | */
|
---|
449 | DECLINLINE(int) RTStrGetCpNEx(const char **ppsz, size_t *pcch, PRTUNICP pCp)
|
---|
450 | {
|
---|
451 | if (RT_LIKELY(*pcch != 0))
|
---|
452 | {
|
---|
453 | const unsigned char uch = **(const unsigned char **)ppsz;
|
---|
454 | if (!(uch & RT_BIT(7)))
|
---|
455 | {
|
---|
456 | (*ppsz)++;
|
---|
457 | (*pcch)--;
|
---|
458 | *pCp = uch;
|
---|
459 | return VINF_SUCCESS;
|
---|
460 | }
|
---|
461 | }
|
---|
462 | return RTStrGetCpNExInternal(ppsz, pcch, pCp);
|
---|
463 | }
|
---|
464 |
|
---|
465 | /**
|
---|
466 | * Put the unicode code point at the given string position
|
---|
467 | * and return the pointer to the char following it.
|
---|
468 | *
|
---|
469 | * This function will not consider anything at or following the
|
---|
470 | * buffer area pointed to by psz. It is therefore not suitable for
|
---|
471 | * inserting code points into a string, only appending/overwriting.
|
---|
472 | *
|
---|
473 | * @returns pointer to the char following the written code point.
|
---|
474 | * @param psz The string.
|
---|
475 | * @param CodePoint The code point to write.
|
---|
476 | * This should not be RTUNICP_INVALID or any other
|
---|
477 | * character out of the UTF-8 range.
|
---|
478 | *
|
---|
479 | * @remark We optimize this operation by using an inline function for
|
---|
480 | * the most frequent and simplest sequence, the rest is
|
---|
481 | * handled by RTStrPutCpInternal().
|
---|
482 | */
|
---|
483 | DECLINLINE(char *) RTStrPutCp(char *psz, RTUNICP CodePoint)
|
---|
484 | {
|
---|
485 | if (CodePoint < 0x80)
|
---|
486 | {
|
---|
487 | *psz++ = (unsigned char)CodePoint;
|
---|
488 | return psz;
|
---|
489 | }
|
---|
490 | return RTStrPutCpInternal(psz, CodePoint);
|
---|
491 | }
|
---|
492 |
|
---|
493 | /**
|
---|
494 | * Skips ahead, past the current code point.
|
---|
495 | *
|
---|
496 | * @returns Pointer to the char after the current code point.
|
---|
497 | * @param psz Pointer to the current code point.
|
---|
498 | * @remark This will not move the next valid code point, only past the current one.
|
---|
499 | */
|
---|
500 | DECLINLINE(char *) RTStrNextCp(const char *psz)
|
---|
501 | {
|
---|
502 | RTUNICP Cp;
|
---|
503 | RTStrGetCpEx(&psz, &Cp);
|
---|
504 | return (char *)psz;
|
---|
505 | }
|
---|
506 |
|
---|
507 | /**
|
---|
508 | * Skips back to the previous code point.
|
---|
509 | *
|
---|
510 | * @returns Pointer to the char before the current code point.
|
---|
511 | * @returns pszStart on failure.
|
---|
512 | * @param pszStart Pointer to the start of the string.
|
---|
513 | * @param psz Pointer to the current code point.
|
---|
514 | */
|
---|
515 | RTDECL(char *) RTStrPrevCp(const char *pszStart, const char *psz);
|
---|
516 |
|
---|
517 |
|
---|
518 |
|
---|
519 | #ifndef DECLARED_FNRTSTROUTPUT /* duplicated in iprt/log.h */
|
---|
520 | #define DECLARED_FNRTSTROUTPUT
|
---|
521 | /**
|
---|
522 | * Output callback.
|
---|
523 | *
|
---|
524 | * @returns number of bytes written.
|
---|
525 | * @param pvArg User argument.
|
---|
526 | * @param pachChars Pointer to an array of utf-8 characters.
|
---|
527 | * @param cbChars Number of bytes in the character array pointed to by pachChars.
|
---|
528 | */
|
---|
529 | typedef DECLCALLBACK(size_t) FNRTSTROUTPUT(void *pvArg, const char *pachChars, size_t cbChars);
|
---|
530 | /** Pointer to callback function. */
|
---|
531 | typedef FNRTSTROUTPUT *PFNRTSTROUTPUT;
|
---|
532 | #endif
|
---|
533 |
|
---|
534 | /** Format flag.
|
---|
535 | * These are used by RTStrFormat extensions and RTStrFormatNumber, mind
|
---|
536 | * that not all flags makes sense to both of the functions.
|
---|
537 | * @{ */
|
---|
538 | #define RTSTR_F_CAPITAL 0x0001
|
---|
539 | #define RTSTR_F_LEFT 0x0002
|
---|
540 | #define RTSTR_F_ZEROPAD 0x0004
|
---|
541 | #define RTSTR_F_SPECIAL 0x0008
|
---|
542 | #define RTSTR_F_VALSIGNED 0x0010
|
---|
543 | #define RTSTR_F_PLUS 0x0020
|
---|
544 | #define RTSTR_F_BLANK 0x0040
|
---|
545 | #define RTSTR_F_WIDTH 0x0080
|
---|
546 | #define RTSTR_F_PRECISION 0x0100
|
---|
547 | #define RTSTR_F_THOUSAND_SEP 0x0200
|
---|
548 |
|
---|
549 | #define RTSTR_F_BIT_MASK 0xf800
|
---|
550 | #define RTSTR_F_8BIT 0x0800
|
---|
551 | #define RTSTR_F_16BIT 0x1000
|
---|
552 | #define RTSTR_F_32BIT 0x2000
|
---|
553 | #define RTSTR_F_64BIT 0x4000
|
---|
554 | #define RTSTR_F_128BIT 0x8000
|
---|
555 | /** @} */
|
---|
556 |
|
---|
557 | /** @def RTSTR_GET_BIT_FLAG
|
---|
558 | * Gets the bit flag for the specified type.
|
---|
559 | */
|
---|
560 | #define RTSTR_GET_BIT_FLAG(type) \
|
---|
561 | ( sizeof(type) == 32 ? RTSTR_F_32BIT \
|
---|
562 | : sizeof(type) == 64 ? RTSTR_F_64BIT \
|
---|
563 | : sizeof(type) == 16 ? RTSTR_F_16BIT \
|
---|
564 | : sizeof(type) == 8 ? RTSTR_F_8BIT \
|
---|
565 | : sizeof(type) == 128? RTSTR_F_128BIT \
|
---|
566 | : 0)
|
---|
567 |
|
---|
568 |
|
---|
569 | /**
|
---|
570 | * Callback to format non-standard format specifiers.
|
---|
571 | *
|
---|
572 | * @returns The number of bytes formatted.
|
---|
573 | * @param pvArg Formatter argument.
|
---|
574 | * @param pfnOutput Pointer to output function.
|
---|
575 | * @param pvArgOutput Argument for the output function.
|
---|
576 | * @param ppszFormat Pointer to the format string pointer. Advance this till the char
|
---|
577 | * after the format specifier.
|
---|
578 | * @param pArgs Pointer to the argument list. Use this to fetch the arguments.
|
---|
579 | * @param cchWidth Format Width. -1 if not specified.
|
---|
580 | * @param cchPrecision Format Precision. -1 if not specified.
|
---|
581 | * @param fFlags Flags (RTSTR_NTFS_*).
|
---|
582 | * @param chArgSize The argument size specifier, 'l' or 'L'.
|
---|
583 | */
|
---|
584 | typedef DECLCALLBACK(size_t) FNSTRFORMAT(void *pvArg, PFNRTSTROUTPUT pfnOutput, void *pvArgOutput,
|
---|
585 | const char **ppszFormat, va_list *pArgs, int cchWidth,
|
---|
586 | int cchPrecision, unsigned fFlags, char chArgSize);
|
---|
587 | /** Pointer to a FNSTRFORMAT() function. */
|
---|
588 | typedef FNSTRFORMAT *PFNSTRFORMAT;
|
---|
589 |
|
---|
590 |
|
---|
591 | /**
|
---|
592 | * Partial implementation of a printf like formatter.
|
---|
593 | * It doesn't do everything correct, and there is no floating point support.
|
---|
594 | * However, it supports custom formats by the means of a format callback.
|
---|
595 | *
|
---|
596 | * @returns number of bytes formatted.
|
---|
597 | * @param pfnOutput Output worker.
|
---|
598 | * Called in two ways. Normally with a string and its length.
|
---|
599 | * For termination, it's called with NULL for string, 0 for length.
|
---|
600 | * @param pvArgOutput Argument to the output worker.
|
---|
601 | * @param pfnFormat Custom format worker.
|
---|
602 | * @param pvArgFormat Argument to the format worker.
|
---|
603 | * @param pszFormat Format string pointer.
|
---|
604 | * @param InArgs Argument list.
|
---|
605 | */
|
---|
606 | RTDECL(size_t) RTStrFormatV(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat, const char *pszFormat, va_list InArgs);
|
---|
607 |
|
---|
608 | /**
|
---|
609 | * Partial implementation of a printf like formatter.
|
---|
610 | * It doesn't do everything correct, and there is no floating point support.
|
---|
611 | * However, it supports custom formats by the means of a format callback.
|
---|
612 | *
|
---|
613 | * @returns number of bytes formatted.
|
---|
614 | * @param pfnOutput Output worker.
|
---|
615 | * Called in two ways. Normally with a string and its length.
|
---|
616 | * For termination, it's called with NULL for string, 0 for length.
|
---|
617 | * @param pvArgOutput Argument to the output worker.
|
---|
618 | * @param pfnFormat Custom format worker.
|
---|
619 | * @param pvArgFormat Argument to the format worker.
|
---|
620 | * @param pszFormat Format string.
|
---|
621 | * @param ... Argument list.
|
---|
622 | */
|
---|
623 | RTDECL(size_t) RTStrFormat(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat, const char *pszFormat, ...);
|
---|
624 |
|
---|
625 | /**
|
---|
626 | * Formats an integer number according to the parameters.
|
---|
627 | *
|
---|
628 | * @returns Length of the formatted number.
|
---|
629 | * @param psz Pointer to output string buffer of sufficient size.
|
---|
630 | * @param u64Value Value to format.
|
---|
631 | * @param uiBase Number representation base.
|
---|
632 | * @param cchWidth Width.
|
---|
633 | * @param cchPrecision Precision.
|
---|
634 | * @param fFlags Flags (NTFS_*).
|
---|
635 | */
|
---|
636 | RTDECL(int) RTStrFormatNumber(char *psz, uint64_t u64Value, unsigned int uiBase, signed int cchWidth, signed int cchPrecision, unsigned int fFlags);
|
---|
637 |
|
---|
638 |
|
---|
639 | /**
|
---|
640 | * Callback for formatting a type.
|
---|
641 | *
|
---|
642 | * This is registered using the RTStrFormatTypeRegister function and will
|
---|
643 | * be called during string formatting to handle the specified %R[type].
|
---|
644 | * The argument for this format type is assumed to be a pointer and it's
|
---|
645 | * passed in the @a pvValue argument.
|
---|
646 | *
|
---|
647 | * @returns Length of the formatted output.
|
---|
648 | * @param pfnOutput Output worker.
|
---|
649 | * @param pvArgOutput Argument to the output worker.
|
---|
650 | * @param pszType The type name.
|
---|
651 | * @param pvValue The argument value.
|
---|
652 | * @param cchWidth Width.
|
---|
653 | * @param cchPrecision Precision.
|
---|
654 | * @param fFlags Flags (NTFS_*).
|
---|
655 | * @param pvUser The user argument.
|
---|
656 | */
|
---|
657 | typedef DECLCALLBACK(size_t) FNRTSTRFORMATTYPE(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput,
|
---|
658 | const char *pszType, void const *pvValue,
|
---|
659 | int cchWidth, int cchPrecision, unsigned fFlags,
|
---|
660 | void *pvUser);
|
---|
661 | /** Pointer to a FNRTSTRFORMATTYPE. */
|
---|
662 | typedef FNRTSTRFORMATTYPE *PFNRTSTRFORMATTYPE;
|
---|
663 |
|
---|
664 |
|
---|
665 | /**
|
---|
666 | * Register a format handler for a type.
|
---|
667 | *
|
---|
668 | * The format handler is used to handle '%R[type]' format types, where the argument
|
---|
669 | * in the vector is a pointer value (a bit restrictive, but keeps it simple).
|
---|
670 | *
|
---|
671 | * The caller must ensure that no other thread will be making use of any of
|
---|
672 | * the dynamic formatting type facilities simultaneously with this call.
|
---|
673 | *
|
---|
674 | * @returns IPRT status code.
|
---|
675 | * @retval VINF_SUCCESS on success.
|
---|
676 | * @retval VERR_ALREADY_EXISTS if the type has already been registered.
|
---|
677 | * @retval VERR_TOO_MANY_OPEN_FILES if all the type slots has been allocated already.
|
---|
678 | *
|
---|
679 | * @param pszType The type name.
|
---|
680 | * @param pfnHandler The handler address. See FNRTSTRFORMATTYPE for details.
|
---|
681 | * @param pvUser The user argument to pass to the handler. See RTStrFormatTypeSetUser
|
---|
682 | * for how to update this later.
|
---|
683 | */
|
---|
684 | RTDECL(int) RTStrFormatTypeRegister(const char *pszType, PFNRTSTRFORMATTYPE pfnHandler, void *pvUser);
|
---|
685 |
|
---|
686 | /**
|
---|
687 | * Deregisters a format type.
|
---|
688 | *
|
---|
689 | * The caller must ensure that no other thread will be making use of any of
|
---|
690 | * the dynamic formatting type facilities simultaneously with this call.
|
---|
691 | *
|
---|
692 | * @returns IPRT status code.
|
---|
693 | * @retval VINF_SUCCESS on success.
|
---|
694 | * @retval VERR_FILE_NOT_FOUND if not found.
|
---|
695 | *
|
---|
696 | * @param pszType The type to deregister.
|
---|
697 | */
|
---|
698 | RTDECL(int) RTStrFormatTypeDeregister(const char *pszType);
|
---|
699 |
|
---|
700 | /**
|
---|
701 | * Sets the user argument for a type.
|
---|
702 | *
|
---|
703 | * This can be used if a user argument needs relocating in GC.
|
---|
704 | *
|
---|
705 | * @returns IPRT status code.
|
---|
706 | * @retval VINF_SUCCESS on success.
|
---|
707 | * @retval VERR_FILE_NOT_FOUND if not found.
|
---|
708 | *
|
---|
709 | * @param pszType The type to update.
|
---|
710 | * @param pvUser The new user argument value.
|
---|
711 | */
|
---|
712 | RTDECL(int) RTStrFormatTypeSetUser(const char *pszType, void *pvUser);
|
---|
713 |
|
---|
714 |
|
---|
715 | /**
|
---|
716 | * String printf.
|
---|
717 | *
|
---|
718 | * @returns The length of the returned string (in pszBuffer).
|
---|
719 | * @param pszBuffer Output buffer.
|
---|
720 | * @param cchBuffer Size of the output buffer.
|
---|
721 | * @param pszFormat The format string.
|
---|
722 | * @param args The format argument.
|
---|
723 | */
|
---|
724 | RTDECL(size_t) RTStrPrintfV(char *pszBuffer, size_t cchBuffer, const char *pszFormat, va_list args);
|
---|
725 |
|
---|
726 | /**
|
---|
727 | * String printf.
|
---|
728 | *
|
---|
729 | * @returns The length of the returned string (in pszBuffer).
|
---|
730 | * @param pszBuffer Output buffer.
|
---|
731 | * @param cchBuffer Size of the output buffer.
|
---|
732 | * @param pszFormat The format string.
|
---|
733 | * @param ... The format argument.
|
---|
734 | */
|
---|
735 | RTDECL(size_t) RTStrPrintf(char *pszBuffer, size_t cchBuffer, const char *pszFormat, ...);
|
---|
736 |
|
---|
737 |
|
---|
738 | /**
|
---|
739 | * String printf with custom formatting.
|
---|
740 | *
|
---|
741 | * @returns The length of the returned string (in pszBuffer).
|
---|
742 | * @param pfnFormat Pointer to handler function for the custom formats.
|
---|
743 | * @param pvArg Argument to the pfnFormat function.
|
---|
744 | * @param pszBuffer Output buffer.
|
---|
745 | * @param cchBuffer Size of the output buffer.
|
---|
746 | * @param pszFormat The format string.
|
---|
747 | * @param args The format argument.
|
---|
748 | */
|
---|
749 | RTDECL(size_t) RTStrPrintfExV(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cchBuffer, const char *pszFormat, va_list args);
|
---|
750 |
|
---|
751 | /**
|
---|
752 | * String printf with custom formatting.
|
---|
753 | *
|
---|
754 | * @returns The length of the returned string (in pszBuffer).
|
---|
755 | * @param pfnFormat Pointer to handler function for the custom formats.
|
---|
756 | * @param pvArg Argument to the pfnFormat function.
|
---|
757 | * @param pszBuffer Output buffer.
|
---|
758 | * @param cchBuffer Size of the output buffer.
|
---|
759 | * @param pszFormat The format string.
|
---|
760 | * @param ... The format argument.
|
---|
761 | */
|
---|
762 | RTDECL(size_t) RTStrPrintfEx(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cchBuffer, const char *pszFormat, ...);
|
---|
763 |
|
---|
764 |
|
---|
765 | /**
|
---|
766 | * Allocating string printf.
|
---|
767 | *
|
---|
768 | * @returns The length of the string in the returned *ppszBuffer.
|
---|
769 | * @returns -1 on failure.
|
---|
770 | * @param ppszBuffer Where to store the pointer to the allocated output buffer.
|
---|
771 | * The buffer should be freed using RTStrFree().
|
---|
772 | * On failure *ppszBuffer will be set to NULL.
|
---|
773 | * @param pszFormat The format string.
|
---|
774 | * @param args The format argument.
|
---|
775 | */
|
---|
776 | RTDECL(int) RTStrAPrintfV(char **ppszBuffer, const char *pszFormat, va_list args);
|
---|
777 |
|
---|
778 | /**
|
---|
779 | * Allocating string printf.
|
---|
780 | *
|
---|
781 | * @returns The length of the string in the returned *ppszBuffer.
|
---|
782 | * @returns -1 on failure.
|
---|
783 | * @param ppszBuffer Where to store the pointer to the allocated output buffer.
|
---|
784 | * The buffer should be freed using RTStrFree().
|
---|
785 | * On failure *ppszBuffer will be set to NULL.
|
---|
786 | * @param pszFormat The format string.
|
---|
787 | * @param ... The format argument.
|
---|
788 | */
|
---|
789 | RTDECL(int) RTStrAPrintf(char **ppszBuffer, const char *pszFormat, ...);
|
---|
790 |
|
---|
791 |
|
---|
792 | /**
|
---|
793 | * Strips blankspaces from both ends of the string.
|
---|
794 | *
|
---|
795 | * @returns Pointer to first non-blank char in the string.
|
---|
796 | * @param psz The string to strip.
|
---|
797 | */
|
---|
798 | RTDECL(char *) RTStrStrip(char *psz);
|
---|
799 |
|
---|
800 | /**
|
---|
801 | * Strips blankspaces from the start of the string.
|
---|
802 | *
|
---|
803 | * @returns Pointer to first non-blank char in the string.
|
---|
804 | * @param psz The string to strip.
|
---|
805 | */
|
---|
806 | RTDECL(char *) RTStrStripL(const char *psz);
|
---|
807 |
|
---|
808 | /**
|
---|
809 | * Strips blankspaces from the end of the string.
|
---|
810 | *
|
---|
811 | * @returns psz.
|
---|
812 | * @param psz The string to strip.
|
---|
813 | */
|
---|
814 | RTDECL(char *) RTStrStripR(char *psz);
|
---|
815 |
|
---|
816 | /**
|
---|
817 | * Performs a case sensitive string compare between two UTF-8 strings.
|
---|
818 | *
|
---|
819 | * Encoding errors are ignored by the current implementation. So, the only
|
---|
820 | * difference between this and the CRT strcmp function is the handling of
|
---|
821 | * NULL arguments.
|
---|
822 | *
|
---|
823 | * @returns < 0 if the first string less than the second string.
|
---|
824 | * @returns 0 if the first string identical to the second string.
|
---|
825 | * @returns > 0 if the first string greater than the second string.
|
---|
826 | * @param psz1 First UTF-8 string. Null is allowed.
|
---|
827 | * @param psz2 Second UTF-8 string. Null is allowed.
|
---|
828 | */
|
---|
829 | RTDECL(int) RTStrCmp(const char *psz1, const char *psz2);
|
---|
830 |
|
---|
831 | /**
|
---|
832 | * Performs a case sensitive string compare between two UTF-8 strings, given
|
---|
833 | * a maximum string length.
|
---|
834 | *
|
---|
835 | * Encoding errors are ignored by the current implementation. So, the only
|
---|
836 | * difference between this and the CRT strncmp function is the handling of
|
---|
837 | * NULL arguments.
|
---|
838 | *
|
---|
839 | * @returns < 0 if the first string less than the second string.
|
---|
840 | * @returns 0 if the first string identical to the second string.
|
---|
841 | * @returns > 0 if the first string greater than the second string.
|
---|
842 | * @param psz1 First UTF-8 string. Null is allowed.
|
---|
843 | * @param psz2 Second UTF-8 string. Null is allowed.
|
---|
844 | * @param cchMax The maximum string length
|
---|
845 | */
|
---|
846 | RTDECL(int) RTStrNCmp(const char *psz1, const char *psz2, size_t cchMax);
|
---|
847 |
|
---|
848 | /**
|
---|
849 | * Performs a case insensitive string compare between two UTF-8 strings.
|
---|
850 | *
|
---|
851 | * This is a simplified compare, as only the simplified lower/upper case folding
|
---|
852 | * specified by the unicode specs are used. It does not consider character pairs
|
---|
853 | * as they are used in some languages, just simple upper & lower case compares.
|
---|
854 | *
|
---|
855 | * The result is the difference between the mismatching codepoints after they
|
---|
856 | * both have been lower cased.
|
---|
857 | *
|
---|
858 | * If the string encoding is invalid the function will assert (strict builds)
|
---|
859 | * and use RTStrCmp for the remainder of the string.
|
---|
860 | *
|
---|
861 | * @returns < 0 if the first string less than the second string.
|
---|
862 | * @returns 0 if the first string identical to the second string.
|
---|
863 | * @returns > 0 if the first string greater than the second string.
|
---|
864 | * @param psz1 First UTF-8 string. Null is allowed.
|
---|
865 | * @param psz2 Second UTF-8 string. Null is allowed.
|
---|
866 | */
|
---|
867 | RTDECL(int) RTStrICmp(const char *psz1, const char *psz2);
|
---|
868 |
|
---|
869 | /**
|
---|
870 | * Performs a case insensitive string compare between two UTF-8 strings, given a
|
---|
871 | * maximum string length.
|
---|
872 | *
|
---|
873 | * This is a simplified compare, as only the simplified lower/upper case folding
|
---|
874 | * specified by the unicode specs are used. It does not consider character pairs
|
---|
875 | * as they are used in some languages, just simple upper & lower case compares.
|
---|
876 | *
|
---|
877 | * The result is the difference between the mismatching codepoints after they
|
---|
878 | * both have been lower cased.
|
---|
879 | *
|
---|
880 | * If the string encoding is invalid the function will assert (strict builds)
|
---|
881 | * and use RTStrCmp for the remainder of the string.
|
---|
882 | *
|
---|
883 | * @returns < 0 if the first string less than the second string.
|
---|
884 | * @returns 0 if the first string identical to the second string.
|
---|
885 | * @returns > 0 if the first string greater than the second string.
|
---|
886 | * @param psz1 First UTF-8 string. Null is allowed.
|
---|
887 | * @param psz2 Second UTF-8 string. Null is allowed.
|
---|
888 | * @param cchMax Maximum string length
|
---|
889 | */
|
---|
890 | RTDECL(int) RTStrNICmp(const char *psz1, const char *psz2, size_t cchMax);
|
---|
891 |
|
---|
892 | /**
|
---|
893 | * Locates a case sensitive substring.
|
---|
894 | *
|
---|
895 | * If any of the two strings are NULL, then NULL is returned. If the needle is
|
---|
896 | * an empty string, then the haystack is returned (i.e. matches anything).
|
---|
897 | *
|
---|
898 | * @returns Pointer to the first occurrence of the substring if found, NULL if
|
---|
899 | * not.
|
---|
900 | *
|
---|
901 | * @param pszHaystack The string to search.
|
---|
902 | * @param pszNeedle The substring to search for.
|
---|
903 | *
|
---|
904 | * @remarks The difference between this and strstr is the handling of NULL
|
---|
905 | * pointers.
|
---|
906 | */
|
---|
907 | RTDECL(char *) RTStrStr(const char *pszHaystack, const char *pszNeedle);
|
---|
908 |
|
---|
909 | /**
|
---|
910 | * Locates a case insensitive substring.
|
---|
911 | *
|
---|
912 | * If any of the two strings are NULL, then NULL is returned. If the needle is
|
---|
913 | * an empty string, then the haystack is returned (i.e. matches anything).
|
---|
914 | *
|
---|
915 | * @returns Pointer to the first occurrence of the substring if found, NULL if
|
---|
916 | * not.
|
---|
917 | *
|
---|
918 | * @param pszHaystack The string to search.
|
---|
919 | * @param pszNeedle The substring to search for.
|
---|
920 | *
|
---|
921 | */
|
---|
922 | RTDECL(char *) RTStrIStr(const char *pszHaystack, const char *pszNeedle);
|
---|
923 |
|
---|
924 | /**
|
---|
925 | * Converts the string to lower case.
|
---|
926 | *
|
---|
927 | * @returns Pointer to the converted string.
|
---|
928 | * @param psz The string to convert.
|
---|
929 | */
|
---|
930 | RTDECL(char *) RTStrToLower(char *psz);
|
---|
931 |
|
---|
932 | /**
|
---|
933 | * Converts the string to upper case.
|
---|
934 | *
|
---|
935 | * @returns Pointer to the converted string.
|
---|
936 | * @param psz The string to convert.
|
---|
937 | */
|
---|
938 | RTDECL(char *) RTStrToUpper(char *psz);
|
---|
939 |
|
---|
940 | /**
|
---|
941 | * Find the length of a zero-terminated byte string, given
|
---|
942 | * a max string length.
|
---|
943 | *
|
---|
944 | * See also RTStrNLenEx.
|
---|
945 | *
|
---|
946 | * @returns The string length or cbMax. The returned length does not include
|
---|
947 | * the zero terminator if it was found.
|
---|
948 | *
|
---|
949 | * @param pszString The string.
|
---|
950 | * @param cchMax The max string length.
|
---|
951 | */
|
---|
952 | RTDECL(size_t) RTStrNLen(const char *pszString, size_t cchMax);
|
---|
953 |
|
---|
954 | /**
|
---|
955 | * Find the length of a zero-terminated byte string, given
|
---|
956 | * a max string length.
|
---|
957 | *
|
---|
958 | * See also RTStrNLen.
|
---|
959 | *
|
---|
960 | * @returns IPRT status code.
|
---|
961 | * @retval VINF_SUCCESS if the string has a length less than cchMax.
|
---|
962 | * @retval VERR_BUFFER_OVERFLOW if the end of the string wasn't found
|
---|
963 | * before cchMax was reached.
|
---|
964 | *
|
---|
965 | * @param pszString The string.
|
---|
966 | * @param cchMax The max string length.
|
---|
967 | * @param pcch Where to store the string length excluding the
|
---|
968 | * terminator. This is set to cchMax if the terminator
|
---|
969 | * isn't found.
|
---|
970 | */
|
---|
971 | RTDECL(int) RTStrNLenEx(const char *pszString, size_t cchMax, size_t *pcch);
|
---|
972 |
|
---|
973 | /**
|
---|
974 | * Matches a simple string pattern.
|
---|
975 | *
|
---|
976 | * @returns true if the string matches the pattern, otherwise false.
|
---|
977 | *
|
---|
978 | * @param pszPattern The pattern. Special chars are '*' and '?', where the
|
---|
979 | * asterisk matches zero or more characters and question
|
---|
980 | * mark matches exactly one character.
|
---|
981 | * @param pszString The string to match against the pattern.
|
---|
982 | */
|
---|
983 | RTDECL(bool) RTStrSimplePatternMatch(const char *pszPattern, const char *pszString);
|
---|
984 |
|
---|
985 | /**
|
---|
986 | * Matches a simple string pattern, neither which needs to be zero terminated.
|
---|
987 | *
|
---|
988 | * This is identical to RTStrSimplePatternMatch except that you can optionally
|
---|
989 | * specify the length of both the pattern and the string. The function will
|
---|
990 | * stop when it hits a string terminator or either of the lengths.
|
---|
991 | *
|
---|
992 | * @returns true if the string matches the pattern, otherwise false.
|
---|
993 | *
|
---|
994 | * @param pszPattern The pattern. Special chars are '*' and '?', where the
|
---|
995 | * asterisk matches zero or more characters and question
|
---|
996 | * mark matches exactly one character.
|
---|
997 | * @param cchPattern The pattern length. Pass RTSTR_MAX if you don't know the
|
---|
998 | * length and wish to stop at the string terminator.
|
---|
999 | * @param pszString The string to match against the pattern.
|
---|
1000 | * @param cchString The string length. Pass RTSTR_MAX if you don't know the
|
---|
1001 | * length and wish to match up to the string terminator.
|
---|
1002 | */
|
---|
1003 | RTDECL(bool) RTStrSimplePatternNMatch(const char *pszPattern, size_t cchPattern,
|
---|
1004 | const char *pszString, size_t cchString);
|
---|
1005 |
|
---|
1006 | /**
|
---|
1007 | * Matches multiple patterns against a string.
|
---|
1008 | *
|
---|
1009 | * The patterns are separated by the pipe character (|).
|
---|
1010 | *
|
---|
1011 | * @returns true if the string matches the pattern, otherwise false.
|
---|
1012 | *
|
---|
1013 | * @param pszPatterns The patterns.
|
---|
1014 | * @param cchPatterns The lengths of the patterns to use. Pass RTSTR_MAX to
|
---|
1015 | * stop at the terminator.
|
---|
1016 | * @param pszString The string to match against the pattern.
|
---|
1017 | * @param cchString The string length. Pass RTSTR_MAX stop stop at the
|
---|
1018 | * terminator.
|
---|
1019 | * @param poffPattern Offset into the patterns string of the patttern that
|
---|
1020 | * matched. If no match, this will be set to RTSTR_MAX.
|
---|
1021 | * This is optional, NULL is fine.
|
---|
1022 | */
|
---|
1023 | RTDECL(bool) RTStrSimplePatternMultiMatch(const char *pszPatterns, size_t cchPatterns,
|
---|
1024 | const char *pszString, size_t cchString,
|
---|
1025 | size_t *poffPattern);
|
---|
1026 |
|
---|
1027 |
|
---|
1028 | /** @defgroup rt_str_conv String To/From Number Conversions
|
---|
1029 | * @ingroup grp_rt_str
|
---|
1030 | * @{ */
|
---|
1031 |
|
---|
1032 | /**
|
---|
1033 | * Converts a string representation of a number to a 64-bit unsigned number.
|
---|
1034 | *
|
---|
1035 | * @returns iprt status code.
|
---|
1036 | * Warnings are used to indicate conversion problems.
|
---|
1037 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1038 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
1039 | * @retval VWRN_TRAILING_CHARS
|
---|
1040 | * @retval VWRN_TRAILING_SPACES
|
---|
1041 | * @retval VINF_SUCCESS
|
---|
1042 | * @retval VERR_NO_DIGITS
|
---|
1043 | *
|
---|
1044 | * @param pszValue Pointer to the string value.
|
---|
1045 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
1046 | * @param uBase The base of the representation used.
|
---|
1047 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1048 | * @param pu64 Where to store the converted number. (optional)
|
---|
1049 | */
|
---|
1050 | RTDECL(int) RTStrToUInt64Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint64_t *pu64);
|
---|
1051 |
|
---|
1052 | /**
|
---|
1053 | * Converts a string representation of a number to a 64-bit unsigned number,
|
---|
1054 | * making sure the full string is converted.
|
---|
1055 | *
|
---|
1056 | * @returns iprt status code.
|
---|
1057 | * Warnings are used to indicate conversion problems.
|
---|
1058 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1059 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
1060 | * @retval VINF_SUCCESS
|
---|
1061 | * @retval VERR_NO_DIGITS
|
---|
1062 | * @retval VERR_TRAILING_SPACES
|
---|
1063 | * @retval VERR_TRAILING_CHARS
|
---|
1064 | *
|
---|
1065 | * @param pszValue Pointer to the string value.
|
---|
1066 | * @param uBase The base of the representation used.
|
---|
1067 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1068 | * @param pu64 Where to store the converted number. (optional)
|
---|
1069 | */
|
---|
1070 | RTDECL(int) RTStrToUInt64Full(const char *pszValue, unsigned uBase, uint64_t *pu64);
|
---|
1071 |
|
---|
1072 | /**
|
---|
1073 | * Converts a string representation of a number to a 64-bit unsigned number.
|
---|
1074 | * The base is guessed.
|
---|
1075 | *
|
---|
1076 | * @returns 64-bit unsigned number on success.
|
---|
1077 | * @returns 0 on failure.
|
---|
1078 | * @param pszValue Pointer to the string value.
|
---|
1079 | */
|
---|
1080 | RTDECL(uint64_t) RTStrToUInt64(const char *pszValue);
|
---|
1081 |
|
---|
1082 | /**
|
---|
1083 | * Converts a string representation of a number to a 32-bit unsigned number.
|
---|
1084 | *
|
---|
1085 | * @returns iprt status code.
|
---|
1086 | * Warnings are used to indicate conversion problems.
|
---|
1087 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1088 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
1089 | * @retval VWRN_TRAILING_CHARS
|
---|
1090 | * @retval VWRN_TRAILING_SPACES
|
---|
1091 | * @retval VINF_SUCCESS
|
---|
1092 | * @retval VERR_NO_DIGITS
|
---|
1093 | *
|
---|
1094 | * @param pszValue Pointer to the string value.
|
---|
1095 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
1096 | * @param uBase The base of the representation used.
|
---|
1097 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1098 | * @param pu32 Where to store the converted number. (optional)
|
---|
1099 | */
|
---|
1100 | RTDECL(int) RTStrToUInt32Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint32_t *pu32);
|
---|
1101 |
|
---|
1102 | /**
|
---|
1103 | * Converts a string representation of a number to a 32-bit unsigned number,
|
---|
1104 | * making sure the full string is converted.
|
---|
1105 | *
|
---|
1106 | * @returns iprt status code.
|
---|
1107 | * Warnings are used to indicate conversion problems.
|
---|
1108 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1109 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
1110 | * @retval VINF_SUCCESS
|
---|
1111 | * @retval VERR_NO_DIGITS
|
---|
1112 | * @retval VERR_TRAILING_SPACES
|
---|
1113 | * @retval VERR_TRAILING_CHARS
|
---|
1114 | *
|
---|
1115 | * @param pszValue Pointer to the string value.
|
---|
1116 | * @param uBase The base of the representation used.
|
---|
1117 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1118 | * @param pu32 Where to store the converted number. (optional)
|
---|
1119 | */
|
---|
1120 | RTDECL(int) RTStrToUInt32Full(const char *pszValue, unsigned uBase, uint32_t *pu32);
|
---|
1121 |
|
---|
1122 | /**
|
---|
1123 | * Converts a string representation of a number to a 64-bit unsigned number.
|
---|
1124 | * The base is guessed.
|
---|
1125 | *
|
---|
1126 | * @returns 32-bit unsigned number on success.
|
---|
1127 | * @returns 0 on failure.
|
---|
1128 | * @param pszValue Pointer to the string value.
|
---|
1129 | */
|
---|
1130 | RTDECL(uint32_t) RTStrToUInt32(const char *pszValue);
|
---|
1131 |
|
---|
1132 | /**
|
---|
1133 | * Converts a string representation of a number to a 16-bit unsigned number.
|
---|
1134 | *
|
---|
1135 | * @returns iprt status code.
|
---|
1136 | * Warnings are used to indicate conversion problems.
|
---|
1137 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1138 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
1139 | * @retval VWRN_TRAILING_CHARS
|
---|
1140 | * @retval VWRN_TRAILING_SPACES
|
---|
1141 | * @retval VINF_SUCCESS
|
---|
1142 | * @retval VERR_NO_DIGITS
|
---|
1143 | *
|
---|
1144 | * @param pszValue Pointer to the string value.
|
---|
1145 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
1146 | * @param uBase The base of the representation used.
|
---|
1147 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1148 | * @param pu16 Where to store the converted number. (optional)
|
---|
1149 | */
|
---|
1150 | RTDECL(int) RTStrToUInt16Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint16_t *pu16);
|
---|
1151 |
|
---|
1152 | /**
|
---|
1153 | * Converts a string representation of a number to a 16-bit unsigned number,
|
---|
1154 | * making sure the full string is converted.
|
---|
1155 | *
|
---|
1156 | * @returns iprt status code.
|
---|
1157 | * Warnings are used to indicate conversion problems.
|
---|
1158 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1159 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
1160 | * @retval VINF_SUCCESS
|
---|
1161 | * @retval VERR_NO_DIGITS
|
---|
1162 | * @retval VERR_TRAILING_SPACES
|
---|
1163 | * @retval VERR_TRAILING_CHARS
|
---|
1164 | *
|
---|
1165 | * @param pszValue Pointer to the string value.
|
---|
1166 | * @param uBase The base of the representation used.
|
---|
1167 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1168 | * @param pu16 Where to store the converted number. (optional)
|
---|
1169 | */
|
---|
1170 | RTDECL(int) RTStrToUInt16Full(const char *pszValue, unsigned uBase, uint16_t *pu16);
|
---|
1171 |
|
---|
1172 | /**
|
---|
1173 | * Converts a string representation of a number to a 16-bit unsigned number.
|
---|
1174 | * The base is guessed.
|
---|
1175 | *
|
---|
1176 | * @returns 16-bit unsigned number on success.
|
---|
1177 | * @returns 0 on failure.
|
---|
1178 | * @param pszValue Pointer to the string value.
|
---|
1179 | */
|
---|
1180 | RTDECL(uint16_t) RTStrToUInt16(const char *pszValue);
|
---|
1181 |
|
---|
1182 | /**
|
---|
1183 | * Converts a string representation of a number to a 8-bit unsigned number.
|
---|
1184 | *
|
---|
1185 | * @returns iprt status code.
|
---|
1186 | * Warnings are used to indicate conversion problems.
|
---|
1187 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1188 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
1189 | * @retval VWRN_TRAILING_CHARS
|
---|
1190 | * @retval VWRN_TRAILING_SPACES
|
---|
1191 | * @retval VINF_SUCCESS
|
---|
1192 | * @retval VERR_NO_DIGITS
|
---|
1193 | *
|
---|
1194 | * @param pszValue Pointer to the string value.
|
---|
1195 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
1196 | * @param uBase The base of the representation used.
|
---|
1197 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1198 | * @param pu8 Where to store the converted number. (optional)
|
---|
1199 | */
|
---|
1200 | RTDECL(int) RTStrToUInt8Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint8_t *pu8);
|
---|
1201 |
|
---|
1202 | /**
|
---|
1203 | * Converts a string representation of a number to a 8-bit unsigned number,
|
---|
1204 | * making sure the full string is converted.
|
---|
1205 | *
|
---|
1206 | * @returns iprt status code.
|
---|
1207 | * Warnings are used to indicate conversion problems.
|
---|
1208 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1209 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
1210 | * @retval VINF_SUCCESS
|
---|
1211 | * @retval VERR_NO_DIGITS
|
---|
1212 | * @retval VERR_TRAILING_SPACES
|
---|
1213 | * @retval VERR_TRAILING_CHARS
|
---|
1214 | *
|
---|
1215 | * @param pszValue Pointer to the string value.
|
---|
1216 | * @param uBase The base of the representation used.
|
---|
1217 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1218 | * @param pu8 Where to store the converted number. (optional)
|
---|
1219 | */
|
---|
1220 | RTDECL(int) RTStrToUInt8Full(const char *pszValue, unsigned uBase, uint8_t *pu8);
|
---|
1221 |
|
---|
1222 | /**
|
---|
1223 | * Converts a string representation of a number to a 8-bit unsigned number.
|
---|
1224 | * The base is guessed.
|
---|
1225 | *
|
---|
1226 | * @returns 8-bit unsigned number on success.
|
---|
1227 | * @returns 0 on failure.
|
---|
1228 | * @param pszValue Pointer to the string value.
|
---|
1229 | */
|
---|
1230 | RTDECL(uint8_t) RTStrToUInt8(const char *pszValue);
|
---|
1231 |
|
---|
1232 | /**
|
---|
1233 | * Converts a string representation of a number to a 64-bit signed number.
|
---|
1234 | *
|
---|
1235 | * @returns iprt status code.
|
---|
1236 | * Warnings are used to indicate conversion problems.
|
---|
1237 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1238 | * @retval VWRN_TRAILING_CHARS
|
---|
1239 | * @retval VWRN_TRAILING_SPACES
|
---|
1240 | * @retval VINF_SUCCESS
|
---|
1241 | * @retval VERR_NO_DIGITS
|
---|
1242 | *
|
---|
1243 | * @param pszValue Pointer to the string value.
|
---|
1244 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
1245 | * @param uBase The base of the representation used.
|
---|
1246 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1247 | * @param pi64 Where to store the converted number. (optional)
|
---|
1248 | */
|
---|
1249 | RTDECL(int) RTStrToInt64Ex(const char *pszValue, char **ppszNext, unsigned uBase, int64_t *pi64);
|
---|
1250 |
|
---|
1251 | /**
|
---|
1252 | * Converts a string representation of a number to a 64-bit signed number,
|
---|
1253 | * making sure the full string is converted.
|
---|
1254 | *
|
---|
1255 | * @returns iprt status code.
|
---|
1256 | * Warnings are used to indicate conversion problems.
|
---|
1257 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1258 | * @retval VINF_SUCCESS
|
---|
1259 | * @retval VERR_TRAILING_CHARS
|
---|
1260 | * @retval VERR_TRAILING_SPACES
|
---|
1261 | * @retval VERR_NO_DIGITS
|
---|
1262 | *
|
---|
1263 | * @param pszValue Pointer to the string value.
|
---|
1264 | * @param uBase The base of the representation used.
|
---|
1265 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1266 | * @param pi64 Where to store the converted number. (optional)
|
---|
1267 | */
|
---|
1268 | RTDECL(int) RTStrToInt64Full(const char *pszValue, unsigned uBase, int64_t *pi64);
|
---|
1269 |
|
---|
1270 | /**
|
---|
1271 | * Converts a string representation of a number to a 64-bit signed number.
|
---|
1272 | * The base is guessed.
|
---|
1273 | *
|
---|
1274 | * @returns 64-bit signed number on success.
|
---|
1275 | * @returns 0 on failure.
|
---|
1276 | * @param pszValue Pointer to the string value.
|
---|
1277 | */
|
---|
1278 | RTDECL(int64_t) RTStrToInt64(const char *pszValue);
|
---|
1279 |
|
---|
1280 | /**
|
---|
1281 | * Converts a string representation of a number to a 32-bit signed number.
|
---|
1282 | *
|
---|
1283 | * @returns iprt status code.
|
---|
1284 | * Warnings are used to indicate conversion problems.
|
---|
1285 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1286 | * @retval VWRN_TRAILING_CHARS
|
---|
1287 | * @retval VWRN_TRAILING_SPACES
|
---|
1288 | * @retval VINF_SUCCESS
|
---|
1289 | * @retval VERR_NO_DIGITS
|
---|
1290 | *
|
---|
1291 | * @param pszValue Pointer to the string value.
|
---|
1292 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
1293 | * @param uBase The base of the representation used.
|
---|
1294 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1295 | * @param pi32 Where to store the converted number. (optional)
|
---|
1296 | */
|
---|
1297 | RTDECL(int) RTStrToInt32Ex(const char *pszValue, char **ppszNext, unsigned uBase, int32_t *pi32);
|
---|
1298 |
|
---|
1299 | /**
|
---|
1300 | * Converts a string representation of a number to a 32-bit signed number,
|
---|
1301 | * making sure the full string is converted.
|
---|
1302 | *
|
---|
1303 | * @returns iprt status code.
|
---|
1304 | * Warnings are used to indicate conversion problems.
|
---|
1305 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1306 | * @retval VINF_SUCCESS
|
---|
1307 | * @retval VERR_TRAILING_CHARS
|
---|
1308 | * @retval VERR_TRAILING_SPACES
|
---|
1309 | * @retval VERR_NO_DIGITS
|
---|
1310 | *
|
---|
1311 | * @param pszValue Pointer to the string value.
|
---|
1312 | * @param uBase The base of the representation used.
|
---|
1313 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1314 | * @param pi32 Where to store the converted number. (optional)
|
---|
1315 | */
|
---|
1316 | RTDECL(int) RTStrToInt32Full(const char *pszValue, unsigned uBase, int32_t *pi32);
|
---|
1317 |
|
---|
1318 | /**
|
---|
1319 | * Converts a string representation of a number to a 32-bit signed number.
|
---|
1320 | * The base is guessed.
|
---|
1321 | *
|
---|
1322 | * @returns 32-bit signed number on success.
|
---|
1323 | * @returns 0 on failure.
|
---|
1324 | * @param pszValue Pointer to the string value.
|
---|
1325 | */
|
---|
1326 | RTDECL(int32_t) RTStrToInt32(const char *pszValue);
|
---|
1327 |
|
---|
1328 | /**
|
---|
1329 | * Converts a string representation of a number to a 16-bit signed number.
|
---|
1330 | *
|
---|
1331 | * @returns iprt status code.
|
---|
1332 | * Warnings are used to indicate conversion problems.
|
---|
1333 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1334 | * @retval VWRN_TRAILING_CHARS
|
---|
1335 | * @retval VWRN_TRAILING_SPACES
|
---|
1336 | * @retval VINF_SUCCESS
|
---|
1337 | * @retval VERR_NO_DIGITS
|
---|
1338 | *
|
---|
1339 | * @param pszValue Pointer to the string value.
|
---|
1340 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
1341 | * @param uBase The base of the representation used.
|
---|
1342 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1343 | * @param pi16 Where to store the converted number. (optional)
|
---|
1344 | */
|
---|
1345 | RTDECL(int) RTStrToInt16Ex(const char *pszValue, char **ppszNext, unsigned uBase, int16_t *pi16);
|
---|
1346 |
|
---|
1347 | /**
|
---|
1348 | * Converts a string representation of a number to a 16-bit signed number,
|
---|
1349 | * making sure the full string is converted.
|
---|
1350 | *
|
---|
1351 | * @returns iprt status code.
|
---|
1352 | * Warnings are used to indicate conversion problems.
|
---|
1353 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1354 | * @retval VINF_SUCCESS
|
---|
1355 | * @retval VERR_TRAILING_CHARS
|
---|
1356 | * @retval VERR_TRAILING_SPACES
|
---|
1357 | * @retval VERR_NO_DIGITS
|
---|
1358 | *
|
---|
1359 | * @param pszValue Pointer to the string value.
|
---|
1360 | * @param uBase The base of the representation used.
|
---|
1361 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1362 | * @param pi16 Where to store the converted number. (optional)
|
---|
1363 | */
|
---|
1364 | RTDECL(int) RTStrToInt16Full(const char *pszValue, unsigned uBase, int16_t *pi16);
|
---|
1365 |
|
---|
1366 | /**
|
---|
1367 | * Converts a string representation of a number to a 16-bit signed number.
|
---|
1368 | * The base is guessed.
|
---|
1369 | *
|
---|
1370 | * @returns 16-bit signed number on success.
|
---|
1371 | * @returns 0 on failure.
|
---|
1372 | * @param pszValue Pointer to the string value.
|
---|
1373 | */
|
---|
1374 | RTDECL(int16_t) RTStrToInt16(const char *pszValue);
|
---|
1375 |
|
---|
1376 | /**
|
---|
1377 | * Converts a string representation of a number to a 8-bit signed number.
|
---|
1378 | *
|
---|
1379 | * @returns iprt status code.
|
---|
1380 | * Warnings are used to indicate conversion problems.
|
---|
1381 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1382 | * @retval VWRN_TRAILING_CHARS
|
---|
1383 | * @retval VWRN_TRAILING_SPACES
|
---|
1384 | * @retval VINF_SUCCESS
|
---|
1385 | * @retval VERR_NO_DIGITS
|
---|
1386 | *
|
---|
1387 | * @param pszValue Pointer to the string value.
|
---|
1388 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
1389 | * @param uBase The base of the representation used.
|
---|
1390 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1391 | * @param pi8 Where to store the converted number. (optional)
|
---|
1392 | */
|
---|
1393 | RTDECL(int) RTStrToInt8Ex(const char *pszValue, char **ppszNext, unsigned uBase, int8_t *pi8);
|
---|
1394 |
|
---|
1395 | /**
|
---|
1396 | * Converts a string representation of a number to a 8-bit signed number,
|
---|
1397 | * making sure the full string is converted.
|
---|
1398 | *
|
---|
1399 | * @returns iprt status code.
|
---|
1400 | * Warnings are used to indicate conversion problems.
|
---|
1401 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
1402 | * @retval VINF_SUCCESS
|
---|
1403 | * @retval VERR_TRAILING_CHARS
|
---|
1404 | * @retval VERR_TRAILING_SPACES
|
---|
1405 | * @retval VERR_NO_DIGITS
|
---|
1406 | *
|
---|
1407 | * @param pszValue Pointer to the string value.
|
---|
1408 | * @param uBase The base of the representation used.
|
---|
1409 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
1410 | * @param pi8 Where to store the converted number. (optional)
|
---|
1411 | */
|
---|
1412 | RTDECL(int) RTStrToInt8Full(const char *pszValue, unsigned uBase, int8_t *pi8);
|
---|
1413 |
|
---|
1414 | /**
|
---|
1415 | * Converts a string representation of a number to a 8-bit signed number.
|
---|
1416 | * The base is guessed.
|
---|
1417 | *
|
---|
1418 | * @returns 8-bit signed number on success.
|
---|
1419 | * @returns 0 on failure.
|
---|
1420 | * @param pszValue Pointer to the string value.
|
---|
1421 | */
|
---|
1422 | RTDECL(int8_t) RTStrToInt8(const char *pszValue);
|
---|
1423 |
|
---|
1424 | /** @} */
|
---|
1425 |
|
---|
1426 |
|
---|
1427 | /** @defgroup rt_str_space Unique String Space
|
---|
1428 | * @ingroup grp_rt_str
|
---|
1429 | * @{
|
---|
1430 | */
|
---|
1431 |
|
---|
1432 | /** Pointer to a string name space container node core. */
|
---|
1433 | typedef struct RTSTRSPACECORE *PRTSTRSPACECORE;
|
---|
1434 | /** Pointer to a pointer to a string name space container node core. */
|
---|
1435 | typedef PRTSTRSPACECORE *PPRTSTRSPACECORE;
|
---|
1436 |
|
---|
1437 | /**
|
---|
1438 | * String name space container node core.
|
---|
1439 | */
|
---|
1440 | typedef struct RTSTRSPACECORE
|
---|
1441 | {
|
---|
1442 | /** Hash key. Don't touch. */
|
---|
1443 | uint32_t Key;
|
---|
1444 | /** Pointer to the left leaf node. Don't touch. */
|
---|
1445 | PRTSTRSPACECORE pLeft;
|
---|
1446 | /** Pointer to the left rigth node. Don't touch. */
|
---|
1447 | PRTSTRSPACECORE pRight;
|
---|
1448 | /** Pointer to the list of string with the same key. Don't touch. */
|
---|
1449 | PRTSTRSPACECORE pList;
|
---|
1450 | /** Height of this tree: max(heigth(left), heigth(right)) + 1. Don't touch */
|
---|
1451 | unsigned char uchHeight;
|
---|
1452 | /** The string length. Read only! */
|
---|
1453 | size_t cchString;
|
---|
1454 | /** Pointer to the string. Read only! */
|
---|
1455 | const char *pszString;
|
---|
1456 | } RTSTRSPACECORE;
|
---|
1457 |
|
---|
1458 | /** String space. (Initialize with NULL.) */
|
---|
1459 | typedef PRTSTRSPACECORE RTSTRSPACE;
|
---|
1460 | /** Pointer to a string space. */
|
---|
1461 | typedef PPRTSTRSPACECORE PRTSTRSPACE;
|
---|
1462 |
|
---|
1463 |
|
---|
1464 | /**
|
---|
1465 | * Inserts a string into a unique string space.
|
---|
1466 | *
|
---|
1467 | * @returns true on success.
|
---|
1468 | * @returns false if the string collided with an existing string.
|
---|
1469 | * @param pStrSpace The space to insert it into.
|
---|
1470 | * @param pStr The string node.
|
---|
1471 | */
|
---|
1472 | RTDECL(bool) RTStrSpaceInsert(PRTSTRSPACE pStrSpace, PRTSTRSPACECORE pStr);
|
---|
1473 |
|
---|
1474 | /**
|
---|
1475 | * Removes a string from a unique string space.
|
---|
1476 | *
|
---|
1477 | * @returns Pointer to the removed string node.
|
---|
1478 | * @returns NULL if the string was not found in the string space.
|
---|
1479 | * @param pStrSpace The space to insert it into.
|
---|
1480 | * @param pszString The string to remove.
|
---|
1481 | */
|
---|
1482 | RTDECL(PRTSTRSPACECORE) RTStrSpaceRemove(PRTSTRSPACE pStrSpace, const char *pszString);
|
---|
1483 |
|
---|
1484 | /**
|
---|
1485 | * Gets a string from a unique string space.
|
---|
1486 | *
|
---|
1487 | * @returns Pointer to the string node.
|
---|
1488 | * @returns NULL if the string was not found in the string space.
|
---|
1489 | * @param pStrSpace The space to insert it into.
|
---|
1490 | * @param pszString The string to get.
|
---|
1491 | */
|
---|
1492 | RTDECL(PRTSTRSPACECORE) RTStrSpaceGet(PRTSTRSPACE pStrSpace, const char *pszString);
|
---|
1493 |
|
---|
1494 | /**
|
---|
1495 | * Callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy().
|
---|
1496 | *
|
---|
1497 | * @returns 0 on continue.
|
---|
1498 | * @returns Non-zero to aborts the operation.
|
---|
1499 | * @param pStr The string node
|
---|
1500 | * @param pvUser The user specified argument.
|
---|
1501 | */
|
---|
1502 | typedef DECLCALLBACK(int) FNRTSTRSPACECALLBACK(PRTSTRSPACECORE pStr, void *pvUser);
|
---|
1503 | /** Pointer to callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy(). */
|
---|
1504 | typedef FNRTSTRSPACECALLBACK *PFNRTSTRSPACECALLBACK;
|
---|
1505 |
|
---|
1506 | /**
|
---|
1507 | * Destroys the string space.
|
---|
1508 | * The caller supplies a callback which will be called for each of
|
---|
1509 | * the string nodes in for freeing their memory and other resources.
|
---|
1510 | *
|
---|
1511 | * @returns 0 or what ever non-zero return value pfnCallback returned
|
---|
1512 | * when aborting the destruction.
|
---|
1513 | * @param pStrSpace The space to insert it into.
|
---|
1514 | * @param pfnCallback The callback.
|
---|
1515 | * @param pvUser The user argument.
|
---|
1516 | */
|
---|
1517 | RTDECL(int) RTStrSpaceDestroy(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser);
|
---|
1518 |
|
---|
1519 | /**
|
---|
1520 | * Enumerates the string space.
|
---|
1521 | * The caller supplies a callback which will be called for each of
|
---|
1522 | * the string nodes.
|
---|
1523 | *
|
---|
1524 | * @returns 0 or what ever non-zero return value pfnCallback returned
|
---|
1525 | * when aborting the destruction.
|
---|
1526 | * @param pStrSpace The space to insert it into.
|
---|
1527 | * @param pfnCallback The callback.
|
---|
1528 | * @param pvUser The user argument.
|
---|
1529 | */
|
---|
1530 | RTDECL(int) RTStrSpaceEnumerate(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser);
|
---|
1531 |
|
---|
1532 | /** @} */
|
---|
1533 |
|
---|
1534 |
|
---|
1535 | /** @defgroup rt_str_utf16 UTF-16 String Manipulation
|
---|
1536 | * @ingroup grp_rt_str
|
---|
1537 | * @{
|
---|
1538 | */
|
---|
1539 |
|
---|
1540 | /**
|
---|
1541 | * Free a UTF-16 string allocated by RTStrToUtf16(), RTStrToUtf16Ex(),
|
---|
1542 | * RTLatin1ToUtf16(), RTLatin1ToUtf16Ex(), RTUtf16Dup() or RTUtf16DupEx().
|
---|
1543 | *
|
---|
1544 | * @returns iprt status code.
|
---|
1545 | * @param pwszString The UTF-16 string to free. NULL is accepted.
|
---|
1546 | */
|
---|
1547 | RTDECL(void) RTUtf16Free(PRTUTF16 pwszString);
|
---|
1548 |
|
---|
1549 | /**
|
---|
1550 | * Allocates a new copy of the specified UTF-16 string.
|
---|
1551 | *
|
---|
1552 | * @returns Pointer to the allocated string copy. Use RTUtf16Free() to free it.
|
---|
1553 | * @returns NULL when out of memory.
|
---|
1554 | * @param pwszString UTF-16 string to duplicate.
|
---|
1555 | * @remark This function will not make any attempt to validate the encoding.
|
---|
1556 | */
|
---|
1557 | RTDECL(PRTUTF16) RTUtf16Dup(PCRTUTF16 pwszString);
|
---|
1558 |
|
---|
1559 | /**
|
---|
1560 | * Allocates a new copy of the specified UTF-16 string.
|
---|
1561 | *
|
---|
1562 | * @returns iprt status code.
|
---|
1563 | * @param ppwszString Receives pointer of the allocated UTF-16 string.
|
---|
1564 | * The returned pointer must be freed using RTUtf16Free().
|
---|
1565 | * @param pwszString UTF-16 string to duplicate.
|
---|
1566 | * @param cwcExtra Number of extra RTUTF16 items to allocate.
|
---|
1567 | * @remark This function will not make any attempt to validate the encoding.
|
---|
1568 | */
|
---|
1569 | RTDECL(int) RTUtf16DupEx(PRTUTF16 *ppwszString, PCRTUTF16 pwszString, size_t cwcExtra);
|
---|
1570 |
|
---|
1571 | /**
|
---|
1572 | * Returns the length of a UTF-16 string in UTF-16 characters
|
---|
1573 | * without trailing '\\0'.
|
---|
1574 | *
|
---|
1575 | * Surrogate pairs counts as two UTF-16 characters here. Use RTUtf16CpCnt()
|
---|
1576 | * to get the exact number of code points in the string.
|
---|
1577 | *
|
---|
1578 | * @returns The number of RTUTF16 items in the string.
|
---|
1579 | * @param pwszString Pointer the UTF-16 string.
|
---|
1580 | * @remark This function will not make any attempt to validate the encoding.
|
---|
1581 | */
|
---|
1582 | RTDECL(size_t) RTUtf16Len(PCRTUTF16 pwszString);
|
---|
1583 |
|
---|
1584 | /**
|
---|
1585 | * Performs a case sensitive string compare between two UTF-16 strings.
|
---|
1586 | *
|
---|
1587 | * @returns < 0 if the first string less than the second string.s
|
---|
1588 | * @returns 0 if the first string identical to the second string.
|
---|
1589 | * @returns > 0 if the first string greater than the second string.
|
---|
1590 | * @param pwsz1 First UTF-16 string. Null is allowed.
|
---|
1591 | * @param pwsz2 Second UTF-16 string. Null is allowed.
|
---|
1592 | * @remark This function will not make any attempt to validate the encoding.
|
---|
1593 | */
|
---|
1594 | RTDECL(int) RTUtf16Cmp(register PCRTUTF16 pwsz1, register PCRTUTF16 pwsz2);
|
---|
1595 |
|
---|
1596 | /**
|
---|
1597 | * Performs a case insensitive string compare between two UTF-16 strings.
|
---|
1598 | *
|
---|
1599 | * This is a simplified compare, as only the simplified lower/upper case folding
|
---|
1600 | * specified by the unicode specs are used. It does not consider character pairs
|
---|
1601 | * as they are used in some languages, just simple upper & lower case compares.
|
---|
1602 | *
|
---|
1603 | * @returns < 0 if the first string less than the second string.
|
---|
1604 | * @returns 0 if the first string identical to the second string.
|
---|
1605 | * @returns > 0 if the first string greater than the second string.
|
---|
1606 | * @param pwsz1 First UTF-16 string. Null is allowed.
|
---|
1607 | * @param pwsz2 Second UTF-16 string. Null is allowed.
|
---|
1608 | */
|
---|
1609 | RTDECL(int) RTUtf16ICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
|
---|
1610 |
|
---|
1611 | /**
|
---|
1612 | * Performs a case insensitive string compare between two UTF-16 strings
|
---|
1613 | * using the current locale of the process (if applicable).
|
---|
1614 | *
|
---|
1615 | * This differs from RTUtf16ICmp() in that it will try, if a locale with the
|
---|
1616 | * required data is available, to do a correct case-insensitive compare. It
|
---|
1617 | * follows that it is more complex and thereby likely to be more expensive.
|
---|
1618 | *
|
---|
1619 | * @returns < 0 if the first string less than the second string.
|
---|
1620 | * @returns 0 if the first string identical to the second string.
|
---|
1621 | * @returns > 0 if the first string greater than the second string.
|
---|
1622 | * @param pwsz1 First UTF-16 string. Null is allowed.
|
---|
1623 | * @param pwsz2 Second UTF-16 string. Null is allowed.
|
---|
1624 | */
|
---|
1625 | RTDECL(int) RTUtf16LocaleICmp(PCRTUTF16 pwsz1, PCRTUTF16 pwsz2);
|
---|
1626 |
|
---|
1627 | /**
|
---|
1628 | * Folds a UTF-16 string to lowercase.
|
---|
1629 | *
|
---|
1630 | * This is a very simple folding; is uses the simple lowercase
|
---|
1631 | * code point, it is not related to any locale just the most common
|
---|
1632 | * lowercase codepoint setup by the unicode specs, and it will not
|
---|
1633 | * create new surrogate pairs or remove existing ones.
|
---|
1634 | *
|
---|
1635 | * @returns Pointer to the passed in string.
|
---|
1636 | * @param pwsz The string to fold.
|
---|
1637 | */
|
---|
1638 | RTDECL(PRTUTF16) RTUtf16ToLower(PRTUTF16 pwsz);
|
---|
1639 |
|
---|
1640 | /**
|
---|
1641 | * Folds a UTF-16 string to uppercase.
|
---|
1642 | *
|
---|
1643 | * This is a very simple folding; is uses the simple uppercase
|
---|
1644 | * code point, it is not related to any locale just the most common
|
---|
1645 | * uppercase codepoint setup by the unicode specs, and it will not
|
---|
1646 | * create new surrogate pairs or remove existing ones.
|
---|
1647 | *
|
---|
1648 | * @returns Pointer to the passed in string.
|
---|
1649 | * @param pwsz The string to fold.
|
---|
1650 | */
|
---|
1651 | RTDECL(PRTUTF16) RTUtf16ToUpper(PRTUTF16 pwsz);
|
---|
1652 |
|
---|
1653 | /**
|
---|
1654 | * Translate a UTF-16 string into a UTF-8 allocating the result buffer.
|
---|
1655 | *
|
---|
1656 | * @returns iprt status code.
|
---|
1657 | * @param pwszString UTF-16 string to convert.
|
---|
1658 | * @param ppszString Receives pointer of allocated UTF-8 string on
|
---|
1659 | * success, and is always set to NULL on failure.
|
---|
1660 | * The returned pointer must be freed using RTStrFree().
|
---|
1661 | */
|
---|
1662 | RTDECL(int) RTUtf16ToUtf8(PCRTUTF16 pwszString, char **ppszString);
|
---|
1663 |
|
---|
1664 | /**
|
---|
1665 | * Translates UTF-16 to UTF-8 using buffer provided by the caller or
|
---|
1666 | * a fittingly sized buffer allocated by the function.
|
---|
1667 | *
|
---|
1668 | * @returns iprt status code.
|
---|
1669 | * @param pwszString The UTF-16 string to convert.
|
---|
1670 | * @param cwcString The number of RTUTF16 items to translate from pwszString.
|
---|
1671 | * The translation will stop when reaching cwcString or the terminator ('\\0').
|
---|
1672 | * Use RTSTR_MAX to translate the entire string.
|
---|
1673 | * @param ppsz If cch is non-zero, this must either be pointing to a pointer to
|
---|
1674 | * a buffer of the specified size, or pointer to a NULL pointer.
|
---|
1675 | * If *ppsz is NULL or cch is zero a buffer of at least cch chars
|
---|
1676 | * will be allocated to hold the translated string.
|
---|
1677 | * If a buffer was requested it must be freed using RTUtf16Free().
|
---|
1678 | * @param cch The buffer size in chars (the type). This includes the terminator.
|
---|
1679 | * @param pcch Where to store the length of the translated string,
|
---|
1680 | * excluding the terminator. (Optional)
|
---|
1681 | *
|
---|
1682 | * This may be set under some error conditions,
|
---|
1683 | * however, only for VERR_BUFFER_OVERFLOW and
|
---|
1684 | * VERR_NO_STR_MEMORY will it contain a valid string
|
---|
1685 | * length that can be used to resize the buffer.
|
---|
1686 | */
|
---|
1687 | RTDECL(int) RTUtf16ToUtf8Ex(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch);
|
---|
1688 |
|
---|
1689 | /**
|
---|
1690 | * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
|
---|
1691 | *
|
---|
1692 | * This function will validate the string, and incorrectly encoded UTF-16
|
---|
1693 | * strings will be rejected. The primary purpose of this function is to
|
---|
1694 | * help allocate buffers for RTUtf16ToUtf8() of the correct size. For most
|
---|
1695 | * other purposes RTUtf16ToUtf8Ex() should be used.
|
---|
1696 | *
|
---|
1697 | * @returns Number of char (bytes).
|
---|
1698 | * @returns 0 if the string was incorrectly encoded.
|
---|
1699 | * @param pwsz The UTF-16 string.
|
---|
1700 | */
|
---|
1701 | RTDECL(size_t) RTUtf16CalcUtf8Len(PCRTUTF16 pwsz);
|
---|
1702 |
|
---|
1703 | /**
|
---|
1704 | * Calculates the length of the UTF-16 string in UTF-8 chars (bytes).
|
---|
1705 | *
|
---|
1706 | * This function will validate the string, and incorrectly encoded UTF-16
|
---|
1707 | * strings will be rejected.
|
---|
1708 | *
|
---|
1709 | * @returns iprt status code.
|
---|
1710 | * @param pwsz The string.
|
---|
1711 | * @param cwc The max string length. Use RTSTR_MAX to process the entire string.
|
---|
1712 | * @param pcch Where to store the string length (in bytes). Optional.
|
---|
1713 | * This is undefined on failure.
|
---|
1714 | */
|
---|
1715 | RTDECL(int) RTUtf16CalcUtf8LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
|
---|
1716 |
|
---|
1717 | /**
|
---|
1718 | * Translate a UTF-16 string into a Latin-1 (ISO-8859-1) allocating the result
|
---|
1719 | * buffer.
|
---|
1720 | *
|
---|
1721 | * @returns iprt status code.
|
---|
1722 | * @param pwszString UTF-16 string to convert.
|
---|
1723 | * @param ppszString Receives pointer of allocated Latin1 string on
|
---|
1724 | * success, and is always set to NULL on failure.
|
---|
1725 | * The returned pointer must be freed using RTStrFree().
|
---|
1726 | */
|
---|
1727 | RTDECL(int) RTUtf16ToLatin1(PCRTUTF16 pwszString, char **ppszString);
|
---|
1728 |
|
---|
1729 | /**
|
---|
1730 | * Translates UTF-16 to Latin-1 (ISO-8859-1) using buffer provided by the caller
|
---|
1731 | * or a fittingly sized buffer allocated by the function.
|
---|
1732 | *
|
---|
1733 | * @returns iprt status code.
|
---|
1734 | * @param pwszString The UTF-16 string to convert.
|
---|
1735 | * @param cwcString The number of RTUTF16 items to translate from
|
---|
1736 | * pwszString. The translation will stop when reaching
|
---|
1737 | * cwcString or the terminator ('\\0'). Use RTSTR_MAX
|
---|
1738 | * to translate the entire string.
|
---|
1739 | * @param ppsz Pointer to the pointer to the Latin-1 string. The
|
---|
1740 | * buffer can optionally be preallocated by the caller.
|
---|
1741 | *
|
---|
1742 | * If cch is zero, *ppsz is undefined.
|
---|
1743 | *
|
---|
1744 | * If cch is non-zero and *ppsz is not NULL, then this
|
---|
1745 | * will be used as the output buffer.
|
---|
1746 | * VERR_BUFFER_OVERFLOW will be returned if this is
|
---|
1747 | * insufficient.
|
---|
1748 | *
|
---|
1749 | * If cch is zero or *ppsz is NULL, then a buffer of
|
---|
1750 | * sufficent size is allocated. cch can be used to
|
---|
1751 | * specify a minimum size of this buffer. Use
|
---|
1752 | * RTUtf16Free() to free the result.
|
---|
1753 | *
|
---|
1754 | * @param cch The buffer size in chars (the type). This includes
|
---|
1755 | * the terminator.
|
---|
1756 | * @param pcch Where to store the length of the translated string,
|
---|
1757 | * excluding the terminator. (Optional)
|
---|
1758 | *
|
---|
1759 | * This may be set under some error conditions,
|
---|
1760 | * however, only for VERR_BUFFER_OVERFLOW and
|
---|
1761 | * VERR_NO_STR_MEMORY will it contain a valid string
|
---|
1762 | * length that can be used to resize the buffer.
|
---|
1763 | */
|
---|
1764 | RTDECL(int) RTUtf16ToLatin1Ex(PCRTUTF16 pwszString, size_t cwcString, char **ppsz, size_t cch, size_t *pcch);
|
---|
1765 |
|
---|
1766 | /**
|
---|
1767 | * Calculates the length of the UTF-16 string in Latin-1 (ISO-8859-1) chars.
|
---|
1768 | *
|
---|
1769 | * This function will validate the string, and incorrectly encoded UTF-16
|
---|
1770 | * strings will be rejected. The primary purpose of this function is to
|
---|
1771 | * help allocate buffers for RTUtf16ToLatin1() of the correct size. For most
|
---|
1772 | * other purposes RTUtf16ToLatin1Ex() should be used.
|
---|
1773 | *
|
---|
1774 | * @returns Number of char (bytes).
|
---|
1775 | * @returns 0 if the string was incorrectly encoded.
|
---|
1776 | * @param pwsz The UTF-16 string.
|
---|
1777 | */
|
---|
1778 | RTDECL(size_t) RTUtf16CalcLatin1Len(PCRTUTF16 pwsz);
|
---|
1779 |
|
---|
1780 | /**
|
---|
1781 | * Calculates the length of the UTF-16 string in Latin-1 (ISO-8859-1) chars.
|
---|
1782 | *
|
---|
1783 | * This function will validate the string, and incorrectly encoded UTF-16
|
---|
1784 | * strings will be rejected.
|
---|
1785 | *
|
---|
1786 | * @returns iprt status code.
|
---|
1787 | * @param pwsz The string.
|
---|
1788 | * @param cwc The max string length. Use RTSTR_MAX to process the
|
---|
1789 | * entire string.
|
---|
1790 | * @param pcch Where to store the string length (in bytes). Optional.
|
---|
1791 | * This is undefined on failure.
|
---|
1792 | */
|
---|
1793 | RTDECL(int) RTUtf16CalcLatin1LenEx(PCRTUTF16 pwsz, size_t cwc, size_t *pcch);
|
---|
1794 |
|
---|
1795 | /**
|
---|
1796 | * Get the unicode code point at the given string position.
|
---|
1797 | *
|
---|
1798 | * @returns unicode code point.
|
---|
1799 | * @returns RTUNICP_INVALID if the encoding is invalid.
|
---|
1800 | * @param pwsz The string.
|
---|
1801 | *
|
---|
1802 | * @remark This is an internal worker for RTUtf16GetCp().
|
---|
1803 | */
|
---|
1804 | RTDECL(RTUNICP) RTUtf16GetCpInternal(PCRTUTF16 pwsz);
|
---|
1805 |
|
---|
1806 | /**
|
---|
1807 | * Get the unicode code point at the given string position.
|
---|
1808 | *
|
---|
1809 | * @returns iprt status code.
|
---|
1810 | * @param ppwsz Pointer to the string pointer. This will be updated to
|
---|
1811 | * point to the char following the current code point.
|
---|
1812 | * @param pCp Where to store the code point.
|
---|
1813 | * RTUNICP_INVALID is stored here on failure.
|
---|
1814 | *
|
---|
1815 | * @remark This is an internal worker for RTUtf16GetCpEx().
|
---|
1816 | */
|
---|
1817 | RTDECL(int) RTUtf16GetCpExInternal(PCRTUTF16 *ppwsz, PRTUNICP pCp);
|
---|
1818 |
|
---|
1819 | /**
|
---|
1820 | * Put the unicode code point at the given string position
|
---|
1821 | * and return the pointer to the char following it.
|
---|
1822 | *
|
---|
1823 | * This function will not consider anything at or following the
|
---|
1824 | * buffer area pointed to by pwsz. It is therefore not suitable for
|
---|
1825 | * inserting code points into a string, only appending/overwriting.
|
---|
1826 | *
|
---|
1827 | * @returns pointer to the char following the written code point.
|
---|
1828 | * @param pwsz The string.
|
---|
1829 | * @param CodePoint The code point to write.
|
---|
1830 | * This should not be RTUNICP_INVALID or any other
|
---|
1831 | * character out of the UTF-16 range.
|
---|
1832 | *
|
---|
1833 | * @remark This is an internal worker for RTUtf16GetCpEx().
|
---|
1834 | */
|
---|
1835 | RTDECL(PRTUTF16) RTUtf16PutCpInternal(PRTUTF16 pwsz, RTUNICP CodePoint);
|
---|
1836 |
|
---|
1837 | /**
|
---|
1838 | * Get the unicode code point at the given string position.
|
---|
1839 | *
|
---|
1840 | * @returns unicode code point.
|
---|
1841 | * @returns RTUNICP_INVALID if the encoding is invalid.
|
---|
1842 | * @param pwsz The string.
|
---|
1843 | *
|
---|
1844 | * @remark We optimize this operation by using an inline function for
|
---|
1845 | * everything which isn't a surrogate pair or an endian indicator.
|
---|
1846 | */
|
---|
1847 | DECLINLINE(RTUNICP) RTUtf16GetCp(PCRTUTF16 pwsz)
|
---|
1848 | {
|
---|
1849 | const RTUTF16 wc = *pwsz;
|
---|
1850 | if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
|
---|
1851 | return wc;
|
---|
1852 | return RTUtf16GetCpInternal(pwsz);
|
---|
1853 | }
|
---|
1854 |
|
---|
1855 | /**
|
---|
1856 | * Get the unicode code point at the given string position.
|
---|
1857 | *
|
---|
1858 | * @returns iprt status code.
|
---|
1859 | * @param ppwsz Pointer to the string pointer. This will be updated to
|
---|
1860 | * point to the char following the current code point.
|
---|
1861 | * @param pCp Where to store the code point.
|
---|
1862 | * RTUNICP_INVALID is stored here on failure.
|
---|
1863 | *
|
---|
1864 | * @remark We optimize this operation by using an inline function for
|
---|
1865 | * everything which isn't a surrogate pair or and endian indicator.
|
---|
1866 | */
|
---|
1867 | DECLINLINE(int) RTUtf16GetCpEx(PCRTUTF16 *ppwsz, PRTUNICP pCp)
|
---|
1868 | {
|
---|
1869 | const RTUTF16 wc = **ppwsz;
|
---|
1870 | if (wc < 0xd800 || (wc > 0xdfff && wc < 0xfffe))
|
---|
1871 | {
|
---|
1872 | (*ppwsz)++;
|
---|
1873 | *pCp = wc;
|
---|
1874 | return VINF_SUCCESS;
|
---|
1875 | }
|
---|
1876 | return RTUtf16GetCpExInternal(ppwsz, pCp);
|
---|
1877 | }
|
---|
1878 |
|
---|
1879 | /**
|
---|
1880 | * Put the unicode code point at the given string position
|
---|
1881 | * and return the pointer to the char following it.
|
---|
1882 | *
|
---|
1883 | * This function will not consider anything at or following the
|
---|
1884 | * buffer area pointed to by pwsz. It is therefore not suitable for
|
---|
1885 | * inserting code points into a string, only appending/overwriting.
|
---|
1886 | *
|
---|
1887 | * @returns pointer to the char following the written code point.
|
---|
1888 | * @param pwsz The string.
|
---|
1889 | * @param CodePoint The code point to write.
|
---|
1890 | * This should not be RTUNICP_INVALID or any other
|
---|
1891 | * character out of the UTF-16 range.
|
---|
1892 | *
|
---|
1893 | * @remark We optimize this operation by using an inline function for
|
---|
1894 | * everything which isn't a surrogate pair or and endian indicator.
|
---|
1895 | */
|
---|
1896 | DECLINLINE(PRTUTF16) RTUtf16PutCp(PRTUTF16 pwsz, RTUNICP CodePoint)
|
---|
1897 | {
|
---|
1898 | if (CodePoint < 0xd800 || (CodePoint > 0xd800 && CodePoint < 0xfffe))
|
---|
1899 | {
|
---|
1900 | *pwsz++ = (RTUTF16)CodePoint;
|
---|
1901 | return pwsz;
|
---|
1902 | }
|
---|
1903 | return RTUtf16PutCpInternal(pwsz, CodePoint);
|
---|
1904 | }
|
---|
1905 |
|
---|
1906 | /**
|
---|
1907 | * Skips ahead, past the current code point.
|
---|
1908 | *
|
---|
1909 | * @returns Pointer to the char after the current code point.
|
---|
1910 | * @param pwsz Pointer to the current code point.
|
---|
1911 | * @remark This will not move the next valid code point, only past the current one.
|
---|
1912 | */
|
---|
1913 | DECLINLINE(PRTUTF16) RTUtf16NextCp(PCRTUTF16 pwsz)
|
---|
1914 | {
|
---|
1915 | RTUNICP Cp;
|
---|
1916 | RTUtf16GetCpEx(&pwsz, &Cp);
|
---|
1917 | return (PRTUTF16)pwsz;
|
---|
1918 | }
|
---|
1919 |
|
---|
1920 | /**
|
---|
1921 | * Skips backwards, to the previous code point.
|
---|
1922 | *
|
---|
1923 | * @returns Pointer to the char after the current code point.
|
---|
1924 | * @param pwszStart Pointer to the start of the string.
|
---|
1925 | * @param pwsz Pointer to the current code point.
|
---|
1926 | */
|
---|
1927 | RTDECL(PRTUTF16) RTUtf16PrevCp(PCRTUTF16 pwszStart, PCRTUTF16 pwsz);
|
---|
1928 |
|
---|
1929 |
|
---|
1930 | /**
|
---|
1931 | * Checks if the UTF-16 char is the high surrogate char (i.e.
|
---|
1932 | * the 1st char in the pair).
|
---|
1933 | *
|
---|
1934 | * @returns true if it is.
|
---|
1935 | * @returns false if it isn't.
|
---|
1936 | * @param wc The character to investigate.
|
---|
1937 | */
|
---|
1938 | DECLINLINE(bool) RTUtf16IsHighSurrogate(RTUTF16 wc)
|
---|
1939 | {
|
---|
1940 | return wc >= 0xd800 && wc <= 0xdbff;
|
---|
1941 | }
|
---|
1942 |
|
---|
1943 | /**
|
---|
1944 | * Checks if the UTF-16 char is the low surrogate char (i.e.
|
---|
1945 | * the 2nd char in the pair).
|
---|
1946 | *
|
---|
1947 | * @returns true if it is.
|
---|
1948 | * @returns false if it isn't.
|
---|
1949 | * @param wc The character to investigate.
|
---|
1950 | */
|
---|
1951 | DECLINLINE(bool) RTUtf16IsLowSurrogate(RTUTF16 wc)
|
---|
1952 | {
|
---|
1953 | return wc >= 0xdc00 && wc <= 0xdfff;
|
---|
1954 | }
|
---|
1955 |
|
---|
1956 |
|
---|
1957 | /**
|
---|
1958 | * Checks if the two UTF-16 chars form a valid surrogate pair.
|
---|
1959 | *
|
---|
1960 | * @returns true if they do.
|
---|
1961 | * @returns false if they doesn't.
|
---|
1962 | * @param wcHigh The high (1st) character.
|
---|
1963 | * @param wcLow The low (2nd) character.
|
---|
1964 | */
|
---|
1965 | DECLINLINE(bool) RTUtf16IsSurrogatePair(RTUTF16 wcHigh, RTUTF16 wcLow)
|
---|
1966 | {
|
---|
1967 | return RTUtf16IsHighSurrogate(wcHigh)
|
---|
1968 | && RTUtf16IsLowSurrogate(wcLow);
|
---|
1969 | }
|
---|
1970 |
|
---|
1971 | /** @} */
|
---|
1972 |
|
---|
1973 |
|
---|
1974 | /** @defgroup rt_str_latin1 Latin-1 (ISO-8859-1) String Manipulation
|
---|
1975 | * @ingroup grp_rt_str
|
---|
1976 | * @{
|
---|
1977 | */
|
---|
1978 |
|
---|
1979 | /**
|
---|
1980 | * Calculates the length of the Latin-1 (ISO-8859-1) string in RTUTF16 items.
|
---|
1981 | *
|
---|
1982 | * @returns Number of RTUTF16 items.
|
---|
1983 | * @param psz The Latin-1 string.
|
---|
1984 | */
|
---|
1985 | RTDECL(size_t) RTLatin1CalcUtf16Len(const char *psz);
|
---|
1986 |
|
---|
1987 | /**
|
---|
1988 | * Calculates the length of the Latin-1 (ISO-8859-1) string in RTUTF16 items.
|
---|
1989 | *
|
---|
1990 | * @returns iprt status code.
|
---|
1991 | * @param psz The Latin-1 string.
|
---|
1992 | * @param cch The max string length. Use RTSTR_MAX to process the
|
---|
1993 | * entire string.
|
---|
1994 | * @param pcwc Where to store the string length. Optional.
|
---|
1995 | * This is undefined on failure.
|
---|
1996 | */
|
---|
1997 | RTDECL(int) RTLatin1CalcUtf16LenEx(const char *psz, size_t cch, size_t *pcwc);
|
---|
1998 |
|
---|
1999 | /**
|
---|
2000 | * Translate a Latin-1 (ISO-8859-1) string into a UTF-16 allocating the result
|
---|
2001 | * buffer.
|
---|
2002 | *
|
---|
2003 | * @returns iprt status code.
|
---|
2004 | * @param pszString The Latin-1 string to convert.
|
---|
2005 | * @param ppwszString Receives pointer to the allocated UTF-16 string. The
|
---|
2006 | * returned string must be freed using RTUtf16Free().
|
---|
2007 | */
|
---|
2008 | RTDECL(int) RTLatin1ToUtf16(const char *pszString, PRTUTF16 *ppwszString);
|
---|
2009 |
|
---|
2010 | /**
|
---|
2011 | * Translates pszString from Latin-1 (ISO-8859-1) to UTF-16, allocating the
|
---|
2012 | * result buffer if requested.
|
---|
2013 | *
|
---|
2014 | * @returns iprt status code.
|
---|
2015 | * @param pszString The Latin-1 string to convert.
|
---|
2016 | * @param cchString The maximum size in chars (the type) to convert.
|
---|
2017 | * The conversion stops when it reaches cchString or
|
---|
2018 | * the string terminator ('\\0').
|
---|
2019 | * Use RTSTR_MAX to translate the entire string.
|
---|
2020 | * @param ppwsz If cwc is non-zero, this must either be pointing
|
---|
2021 | * to pointer to a buffer of the specified size, or
|
---|
2022 | * pointer to a NULL pointer.
|
---|
2023 | * If *ppwsz is NULL or cwc is zero a buffer of at
|
---|
2024 | * least cwc items will be allocated to hold the
|
---|
2025 | * translated string. If a buffer was requested it
|
---|
2026 | * must be freed using RTUtf16Free().
|
---|
2027 | * @param cwc The buffer size in RTUTF16s. This includes the
|
---|
2028 | * terminator.
|
---|
2029 | * @param pcwc Where to store the length of the translated string,
|
---|
2030 | * excluding the terminator. (Optional)
|
---|
2031 | *
|
---|
2032 | * This may be set under some error conditions,
|
---|
2033 | * however, only for VERR_BUFFER_OVERFLOW and
|
---|
2034 | * VERR_NO_STR_MEMORY will it contain a valid string
|
---|
2035 | * length that can be used to resize the buffer.
|
---|
2036 | */
|
---|
2037 | RTDECL(int) RTLatin1ToUtf16Ex(const char *pszString, size_t cchString, PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc);
|
---|
2038 |
|
---|
2039 | /** @} */
|
---|
2040 |
|
---|
2041 |
|
---|
2042 | RT_C_DECLS_END
|
---|
2043 |
|
---|
2044 | /** @} */
|
---|
2045 |
|
---|
2046 | #endif
|
---|
2047 |
|
---|