VirtualBox

source: vbox/trunk/include/iprt/string.h@ 21751

Last change on this file since 21751 was 21741, checked in by vboxsync, 15 years ago

iprt/string.h: documentation correction for the extended conversion functions.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 75.9 KB
Line 
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)
68RT_C_DECLS_BEGIN
69void *memchr(const void *pv, int ch, size_t cb);
70char *strpbrk(const char *pszStr, const char *pszChars);
71RT_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
114RT_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 */
133RTR3DECL(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 */
143RTR3DECL(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 */
154RTDECL(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 */
162RTDECL(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 */
172RTDECL(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 */
180RTDECL(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 */
197RTDECL(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 */
205RTDECL(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 */
216RTDECL(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 */
231RTDECL(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 */
241RTDECL(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 */
266RTDECL(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 */
280RTDECL(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 */
294RTDECL(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 */
304RTDECL(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 */
328RTDECL(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 */
338RTDECL(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 */
349RTDECL(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 */
365RTDECL(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 */
384RTDECL(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 */
397DECLINLINE(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 */
418DECLINLINE(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 */
449DECLINLINE(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 */
483DECLINLINE(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 */
500DECLINLINE(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 */
515RTDECL(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 */
529typedef DECLCALLBACK(size_t) FNRTSTROUTPUT(void *pvArg, const char *pachChars, size_t cbChars);
530/** Pointer to callback function. */
531typedef 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 */
584typedef 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. */
588typedef 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 */
606RTDECL(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 */
623RTDECL(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 */
636RTDECL(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 */
657typedef 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. */
662typedef 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 */
684RTDECL(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 */
698RTDECL(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 */
712RTDECL(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 */
724RTDECL(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 */
735RTDECL(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 */
749RTDECL(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 */
762RTDECL(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 */
776RTDECL(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 */
789RTDECL(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 */
798RTDECL(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 */
806RTDECL(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 */
814RTDECL(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 */
829RTDECL(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 */
846RTDECL(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 */
867RTDECL(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 */
890RTDECL(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 */
907RTDECL(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 */
922RTDECL(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 */
930RTDECL(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 */
938RTDECL(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 */
952RTDECL(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 */
971RTDECL(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 */
983RTDECL(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 */
1003RTDECL(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 */
1023RTDECL(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 */
1050RTDECL(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 */
1070RTDECL(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 */
1080RTDECL(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 */
1100RTDECL(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 */
1120RTDECL(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 */
1130RTDECL(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 */
1150RTDECL(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 */
1170RTDECL(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 */
1180RTDECL(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 */
1200RTDECL(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 */
1220RTDECL(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 */
1230RTDECL(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 */
1249RTDECL(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 */
1268RTDECL(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 */
1278RTDECL(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 */
1297RTDECL(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 */
1316RTDECL(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 */
1326RTDECL(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 */
1345RTDECL(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 */
1364RTDECL(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 */
1374RTDECL(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 */
1393RTDECL(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 */
1412RTDECL(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 */
1422RTDECL(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. */
1433typedef struct RTSTRSPACECORE *PRTSTRSPACECORE;
1434/** Pointer to a pointer to a string name space container node core. */
1435typedef PRTSTRSPACECORE *PPRTSTRSPACECORE;
1436
1437/**
1438 * String name space container node core.
1439 */
1440typedef 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.) */
1459typedef PRTSTRSPACECORE RTSTRSPACE;
1460/** Pointer to a string space. */
1461typedef 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 */
1472RTDECL(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 */
1482RTDECL(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 */
1492RTDECL(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 */
1502typedef DECLCALLBACK(int) FNRTSTRSPACECALLBACK(PRTSTRSPACECORE pStr, void *pvUser);
1503/** Pointer to callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy(). */
1504typedef 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 */
1517RTDECL(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 */
1530RTDECL(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 */
1547RTDECL(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 */
1557RTDECL(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 */
1569RTDECL(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 */
1582RTDECL(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 */
1594RTDECL(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 */
1609RTDECL(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 */
1625RTDECL(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 */
1638RTDECL(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 */
1651RTDECL(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 */
1662RTDECL(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 */
1687RTDECL(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 */
1701RTDECL(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 */
1715RTDECL(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 */
1727RTDECL(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 */
1764RTDECL(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 */
1778RTDECL(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 */
1793RTDECL(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 */
1804RTDECL(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 */
1817RTDECL(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 */
1835RTDECL(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 */
1847DECLINLINE(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 */
1867DECLINLINE(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 */
1896DECLINLINE(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 */
1913DECLINLINE(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 */
1927RTDECL(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 */
1938DECLINLINE(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 */
1951DECLINLINE(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 */
1965DECLINLINE(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 */
1985RTDECL(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 */
1997RTDECL(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 */
2008RTDECL(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 */
2037RTDECL(int) RTLatin1ToUtf16Ex(const char *pszString, size_t cchString, PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc);
2038
2039/** @} */
2040
2041
2042RT_C_DECLS_END
2043
2044/** @} */
2045
2046#endif
2047
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette