[1] | 1 | /** @file
|
---|
[33540] | 2 | * IPRT - String Manipulation.
|
---|
[1] | 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[76553] | 6 | * Copyright (C) 2006-2019 Oracle Corporation
|
---|
[1] | 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
|
---|
[5999] | 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.
|
---|
[1] | 24 | */
|
---|
| 25 |
|
---|
[76557] | 26 | #ifndef IPRT_INCLUDED_string_h
|
---|
| 27 | #define IPRT_INCLUDED_string_h
|
---|
[76507] | 28 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 29 | # pragma once
|
---|
| 30 | #endif
|
---|
[1] | 31 |
|
---|
| 32 | #include <iprt/cdefs.h>
|
---|
| 33 | #include <iprt/types.h>
|
---|
[31246] | 34 | #include <iprt/assert.h>
|
---|
[1] | 35 | #include <iprt/stdarg.h>
|
---|
[76349] | 36 | #include <iprt/errcore.h> /* for VINF_SUCCESS */
|
---|
[3637] | 37 | #if defined(RT_OS_LINUX) && defined(__KERNEL__)
|
---|
[67769] | 38 | /* no C++ hacks ('new' etc) here anymore! */
|
---|
[331] | 39 | # include <linux/string.h>
|
---|
[36555] | 40 |
|
---|
[35398] | 41 | #elif defined(IN_XF86_MODULE) && !defined(NO_ANSIC)
|
---|
[40507] | 42 | RT_C_DECLS_BEGIN
|
---|
[35398] | 43 | # include "xf86_ansic.h"
|
---|
[40507] | 44 | RT_C_DECLS_END
|
---|
[36555] | 45 |
|
---|
[3636] | 46 | #elif defined(RT_OS_FREEBSD) && defined(_KERNEL)
|
---|
[40507] | 47 | RT_C_DECLS_BEGIN
|
---|
[23525] | 48 | # include <sys/libkern.h>
|
---|
[40507] | 49 | RT_C_DECLS_END
|
---|
[36555] | 50 |
|
---|
[63313] | 51 | #elif defined(RT_OS_NETBSD) && defined(_KERNEL)
|
---|
| 52 | RT_C_DECLS_BEGIN
|
---|
| 53 | # include <lib/libkern/libkern.h>
|
---|
| 54 | RT_C_DECLS_END
|
---|
| 55 |
|
---|
[3888] | 56 | #elif defined(RT_OS_SOLARIS) && defined(_KERNEL)
|
---|
| 57 | /*
|
---|
| 58 | * Same case as with FreeBSD kernel:
|
---|
[18523] | 59 | * The string.h stuff clashes with sys/system.h
|
---|
[3888] | 60 | * ffs = find first set bit.
|
---|
| 61 | */
|
---|
| 62 | # define ffs ffs_string_h
|
---|
| 63 | # include <string.h>
|
---|
| 64 | # undef ffs
|
---|
[4287] | 65 | # undef strpbrk
|
---|
[36555] | 66 |
|
---|
[1] | 67 | #else
|
---|
| 68 | # include <string.h>
|
---|
| 69 | #endif
|
---|
| 70 |
|
---|
| 71 | /*
|
---|
| 72 | * Supply prototypes for standard string functions provided by
|
---|
| 73 | * IPRT instead of the operating environment.
|
---|
| 74 | */
|
---|
[31843] | 75 | #if defined(RT_OS_DARWIN) && defined(KERNEL)
|
---|
[20374] | 76 | RT_C_DECLS_BEGIN
|
---|
[1] | 77 | void *memchr(const void *pv, int ch, size_t cb);
|
---|
| 78 | char *strpbrk(const char *pszStr, const char *pszChars);
|
---|
[20374] | 79 | RT_C_DECLS_END
|
---|
[1] | 80 | #endif
|
---|
| 81 |
|
---|
[31843] | 82 | #if defined(RT_OS_FREEBSD) && defined(_KERNEL)
|
---|
| 83 | RT_C_DECLS_BEGIN
|
---|
| 84 | char *strpbrk(const char *pszStr, const char *pszChars);
|
---|
| 85 | RT_C_DECLS_END
|
---|
| 86 | #endif
|
---|
[31418] | 87 |
|
---|
[63313] | 88 | #if defined(RT_OS_NETBSD) && defined(_KERNEL)
|
---|
| 89 | RT_C_DECLS_BEGIN
|
---|
| 90 | char *strpbrk(const char *pszStr, const char *pszChars);
|
---|
| 91 | RT_C_DECLS_END
|
---|
| 92 | #endif
|
---|
| 93 |
|
---|
[63188] | 94 | #if (!defined(RT_OS_LINUX) || !defined(_GNU_SOURCE)) && !defined(RT_OS_FREEBSD) && !defined(RT_OS_NETBSD)
|
---|
[57722] | 95 | RT_C_DECLS_BEGIN
|
---|
| 96 | void *memrchr(const char *pv, int ch, size_t cb);
|
---|
| 97 | RT_C_DECLS_END
|
---|
| 98 | #endif
|
---|
| 99 |
|
---|
| 100 |
|
---|
[31418] | 101 | /** @def RT_USE_RTC_3629
|
---|
| 102 | * When defined the UTF-8 range will stop at 0x10ffff. If not defined, the
|
---|
| 103 | * range stops at 0x7fffffff.
|
---|
| 104 | * @remarks Must be defined both when building and using the IPRT. */
|
---|
| 105 | #ifdef DOXYGEN_RUNNING
|
---|
| 106 | # define RT_USE_RTC_3629
|
---|
| 107 | #endif
|
---|
| 108 |
|
---|
| 109 |
|
---|
[18424] | 110 | /**
|
---|
| 111 | * Byte zero the specified object.
|
---|
| 112 | *
|
---|
| 113 | * This will use sizeof(Obj) to figure the size and will call memset, bzero
|
---|
| 114 | * or some compiler intrinsic to perform the actual zeroing.
|
---|
| 115 | *
|
---|
| 116 | * @param Obj The object to zero. Make sure to dereference pointers.
|
---|
| 117 | *
|
---|
| 118 | * @remarks Because the macro may use memset it has been placed in string.h
|
---|
| 119 | * instead of cdefs.h to avoid build issues because someone forgot
|
---|
| 120 | * to include this header.
|
---|
| 121 | *
|
---|
| 122 | * @ingroup grp_rt_cdefs
|
---|
| 123 | */
|
---|
| 124 | #define RT_ZERO(Obj) RT_BZERO(&(Obj), sizeof(Obj))
|
---|
[1] | 125 |
|
---|
[18424] | 126 | /**
|
---|
| 127 | * Byte zero the specified memory area.
|
---|
| 128 | *
|
---|
| 129 | * This will call memset, bzero or some compiler intrinsic to clear the
|
---|
| 130 | * specified bytes of memory.
|
---|
| 131 | *
|
---|
| 132 | * @param pv Pointer to the memory.
|
---|
| 133 | * @param cb The number of bytes to clear. Please, don't pass 0.
|
---|
| 134 | *
|
---|
| 135 | * @remarks Because the macro may use memset it has been placed in string.h
|
---|
| 136 | * instead of cdefs.h to avoid build issues because someone forgot
|
---|
| 137 | * to include this header.
|
---|
| 138 | *
|
---|
| 139 | * @ingroup grp_rt_cdefs
|
---|
| 140 | */
|
---|
| 141 | #define RT_BZERO(pv, cb) do { memset((pv), 0, cb); } while (0)
|
---|
| 142 |
|
---|
| 143 |
|
---|
[71605] | 144 | /**
|
---|
| 145 | * For copying a volatile variable to a non-volatile one.
|
---|
| 146 | * @param a_Dst The non-volatile destination variable.
|
---|
| 147 | * @param a_VolatileSrc The volatile source variable / dereferenced pointer.
|
---|
| 148 | */
|
---|
| 149 | #define RT_COPY_VOLATILE(a_Dst, a_VolatileSrc) \
|
---|
| 150 | do { \
|
---|
| 151 | void const volatile *a_pvVolatileSrc_BCopy_Volatile = &(a_VolatileSrc); \
|
---|
| 152 | AssertCompile(sizeof(a_Dst) == sizeof(a_VolatileSrc)); \
|
---|
| 153 | memcpy(&(a_Dst), (void const *)a_pvVolatileSrc_BCopy_Volatile, sizeof(a_Dst)); \
|
---|
| 154 | } while (0)
|
---|
[31418] | 155 |
|
---|
[71605] | 156 | /**
|
---|
| 157 | * For copy a number of bytes from a volatile buffer to a non-volatile one.
|
---|
| 158 | *
|
---|
| 159 | * @param a_pDst Pointer to the destination buffer.
|
---|
| 160 | * @param a_pVolatileSrc Pointer to the volatile source buffer.
|
---|
| 161 | * @param a_cbToCopy Number of bytes to copy.
|
---|
| 162 | */
|
---|
| 163 | #define RT_BCOPY_VOLATILE(a_pDst, a_pVolatileSrc, a_cbToCopy) \
|
---|
| 164 | do { \
|
---|
| 165 | void const volatile *a_pvVolatileSrc_BCopy_Volatile = (a_pVolatileSrc); \
|
---|
| 166 | memcpy((a_pDst), (void const *)a_pvVolatileSrc_BCopy_Volatile, (a_cbToCopy)); \
|
---|
| 167 | } while (0)
|
---|
| 168 |
|
---|
| 169 |
|
---|
[1] | 170 | /** @defgroup grp_rt_str RTStr - String Manipulation
|
---|
| 171 | * Mostly UTF-8 related helpers where the standard string functions won't do.
|
---|
| 172 | * @ingroup grp_rt
|
---|
| 173 | * @{
|
---|
| 174 | */
|
---|
| 175 |
|
---|
[20374] | 176 | RT_C_DECLS_BEGIN
|
---|
[1] | 177 |
|
---|
| 178 |
|
---|
| 179 | /**
|
---|
| 180 | * The maximum string length.
|
---|
| 181 | */
|
---|
| 182 | #define RTSTR_MAX (~(size_t)0)
|
---|
| 183 |
|
---|
| 184 |
|
---|
[45392] | 185 | /** @def RTSTR_TAG
|
---|
[31157] | 186 | * The default allocation tag used by the RTStr allocation APIs.
|
---|
| 187 | *
|
---|
| 188 | * When not defined before the inclusion of iprt/string.h, this will default to
|
---|
| 189 | * the pointer to the current file name. The string API will make of use of
|
---|
| 190 | * this as pointer to a volatile but read-only string.
|
---|
| 191 | */
|
---|
[57926] | 192 | #if !defined(RTSTR_TAG) || defined(DOXYGEN_RUNNING)
|
---|
[31157] | 193 | # define RTSTR_TAG (__FILE__)
|
---|
| 194 | #endif
|
---|
| 195 |
|
---|
| 196 |
|
---|
[1] | 197 | #ifdef IN_RING3
|
---|
| 198 |
|
---|
| 199 | /**
|
---|
[31157] | 200 | * Allocates tmp buffer with default tag, translates pszString from UTF8 to
|
---|
| 201 | * current codepage.
|
---|
[1] | 202 | *
|
---|
| 203 | * @returns iprt status code.
|
---|
| 204 | * @param ppszString Receives pointer of allocated native CP string.
|
---|
| 205 | * The returned pointer must be freed using RTStrFree().
|
---|
| 206 | * @param pszString UTF-8 string to convert.
|
---|
| 207 | */
|
---|
[31157] | 208 | #define RTStrUtf8ToCurrentCP(ppszString, pszString) RTStrUtf8ToCurrentCPTag((ppszString), (pszString), RTSTR_TAG)
|
---|
[1] | 209 |
|
---|
| 210 | /**
|
---|
[31157] | 211 | * Allocates tmp buffer with custom tag, translates pszString from UTF8 to
|
---|
| 212 | * current codepage.
|
---|
| 213 | *
|
---|
| 214 | * @returns iprt status code.
|
---|
| 215 | * @param ppszString Receives pointer of allocated native CP string.
|
---|
| 216 | * The returned pointer must be freed using
|
---|
| 217 | * RTStrFree()., const char *pszTag
|
---|
| 218 | * @param pszString UTF-8 string to convert.
|
---|
| 219 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 220 | */
|
---|
| 221 | RTR3DECL(int) RTStrUtf8ToCurrentCPTag(char **ppszString, const char *pszString, const char *pszTag);
|
---|
| 222 |
|
---|
| 223 | /**
|
---|
[1] | 224 | * Allocates tmp buffer, translates pszString from current codepage to UTF-8.
|
---|
| 225 | *
|
---|
| 226 | * @returns iprt status code.
|
---|
| 227 | * @param ppszString Receives pointer of allocated UTF-8 string.
|
---|
| 228 | * The returned pointer must be freed using RTStrFree().
|
---|
| 229 | * @param pszString Native string to convert.
|
---|
| 230 | */
|
---|
[31157] | 231 | #define RTStrCurrentCPToUtf8(ppszString, pszString) RTStrCurrentCPToUtf8Tag((ppszString), (pszString), RTSTR_TAG)
|
---|
[1] | 232 |
|
---|
[31157] | 233 | /**
|
---|
| 234 | * Allocates tmp buffer, translates pszString from current codepage to UTF-8.
|
---|
| 235 | *
|
---|
| 236 | * @returns iprt status code.
|
---|
| 237 | * @param ppszString Receives pointer of allocated UTF-8 string.
|
---|
| 238 | * The returned pointer must be freed using RTStrFree().
|
---|
| 239 | * @param pszString Native string to convert.
|
---|
| 240 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 241 | */
|
---|
| 242 | RTR3DECL(int) RTStrCurrentCPToUtf8Tag(char **ppszString, const char *pszString, const char *pszTag);
|
---|
[1] | 243 |
|
---|
[31157] | 244 | #endif /* IN_RING3 */
|
---|
| 245 |
|
---|
[1] | 246 | /**
|
---|
| 247 | * Free string allocated by any of the non-UCS-2 string functions.
|
---|
| 248 | *
|
---|
| 249 | * @returns iprt status code.
|
---|
| 250 | * @param pszString Pointer to buffer with string to free.
|
---|
| 251 | * NULL is accepted.
|
---|
| 252 | */
|
---|
| 253 | RTDECL(void) RTStrFree(char *pszString);
|
---|
| 254 |
|
---|
| 255 | /**
|
---|
[31157] | 256 | * Allocates a new copy of the given UTF-8 string (default tag).
|
---|
[1] | 257 | *
|
---|
| 258 | * @returns Pointer to the allocated UTF-8 string.
|
---|
| 259 | * @param pszString UTF-8 string to duplicate.
|
---|
| 260 | */
|
---|
[31157] | 261 | #define RTStrDup(pszString) RTStrDupTag((pszString), RTSTR_TAG)
|
---|
[1] | 262 |
|
---|
| 263 | /**
|
---|
[31157] | 264 | * Allocates a new copy of the given UTF-8 string (custom tag).
|
---|
[1] | 265 | *
|
---|
[31157] | 266 | * @returns Pointer to the allocated UTF-8 string.
|
---|
| 267 | * @param pszString UTF-8 string to duplicate.
|
---|
| 268 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 269 | */
|
---|
| 270 | RTDECL(char *) RTStrDupTag(const char *pszString, const char *pszTag);
|
---|
| 271 |
|
---|
| 272 | /**
|
---|
| 273 | * Allocates a new copy of the given UTF-8 string (default tag).
|
---|
| 274 | *
|
---|
[1] | 275 | * @returns iprt status code.
|
---|
| 276 | * @param ppszString Receives pointer of the allocated UTF-8 string.
|
---|
| 277 | * The returned pointer must be freed using RTStrFree().
|
---|
| 278 | * @param pszString UTF-8 string to duplicate.
|
---|
| 279 | */
|
---|
[31157] | 280 | #define RTStrDupEx(ppszString, pszString) RTStrDupExTag((ppszString), (pszString), RTSTR_TAG)
|
---|
[1] | 281 |
|
---|
| 282 | /**
|
---|
[31157] | 283 | * Allocates a new copy of the given UTF-8 string (custom tag).
|
---|
[22736] | 284 | *
|
---|
[31157] | 285 | * @returns iprt status code.
|
---|
| 286 | * @param ppszString Receives pointer of the allocated UTF-8 string.
|
---|
| 287 | * The returned pointer must be freed using RTStrFree().
|
---|
| 288 | * @param pszString UTF-8 string to duplicate.
|
---|
| 289 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 290 | */
|
---|
| 291 | RTDECL(int) RTStrDupExTag(char **ppszString, const char *pszString, const char *pszTag);
|
---|
| 292 |
|
---|
| 293 | /**
|
---|
| 294 | * Allocates a new copy of the given UTF-8 substring (default tag).
|
---|
| 295 | *
|
---|
[22736] | 296 | * @returns Pointer to the allocated UTF-8 substring.
|
---|
| 297 | * @param pszString UTF-8 string to duplicate.
|
---|
| 298 | * @param cchMax The max number of chars to duplicate, not counting
|
---|
| 299 | * the terminator.
|
---|
| 300 | */
|
---|
[31157] | 301 | #define RTStrDupN(pszString, cchMax) RTStrDupNTag((pszString), (cchMax), RTSTR_TAG)
|
---|
[22736] | 302 |
|
---|
| 303 | /**
|
---|
[31157] | 304 | * Allocates a new copy of the given UTF-8 substring (custom tag).
|
---|
[26481] | 305 | *
|
---|
[31157] | 306 | * @returns Pointer to the allocated UTF-8 substring.
|
---|
| 307 | * @param pszString UTF-8 string to duplicate.
|
---|
| 308 | * @param cchMax The max number of chars to duplicate, not counting
|
---|
| 309 | * the terminator.
|
---|
| 310 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 311 | */
|
---|
| 312 | RTDECL(char *) RTStrDupNTag(const char *pszString, size_t cchMax, const char *pszTag);
|
---|
| 313 |
|
---|
| 314 | /**
|
---|
[33540] | 315 | * Appends a string onto an existing IPRT allocated string (default tag).
|
---|
[31157] | 316 | *
|
---|
[26481] | 317 | * @retval VINF_SUCCESS
|
---|
| 318 | * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
|
---|
| 319 | * remains unchanged.
|
---|
| 320 | *
|
---|
| 321 | * @param ppsz Pointer to the string pointer. The string
|
---|
| 322 | * pointer must either be NULL or point to a string
|
---|
| 323 | * returned by an IPRT string API. (In/Out)
|
---|
| 324 | * @param pszAppend The string to append. NULL and empty strings
|
---|
| 325 | * are quietly ignored.
|
---|
| 326 | */
|
---|
[31157] | 327 | #define RTStrAAppend(ppsz, pszAppend) RTStrAAppendTag((ppsz), (pszAppend), RTSTR_TAG)
|
---|
[26481] | 328 |
|
---|
| 329 | /**
|
---|
[31157] | 330 | * Appends a string onto an existing IPRT allocated string (custom tag).
|
---|
[26481] | 331 | *
|
---|
| 332 | * @retval VINF_SUCCESS
|
---|
| 333 | * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
|
---|
| 334 | * remains unchanged.
|
---|
| 335 | *
|
---|
| 336 | * @param ppsz Pointer to the string pointer. The string
|
---|
| 337 | * pointer must either be NULL or point to a string
|
---|
| 338 | * returned by an IPRT string API. (In/Out)
|
---|
[31157] | 339 | * @param pszAppend The string to append. NULL and empty strings
|
---|
| 340 | * are quietly ignored.
|
---|
| 341 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 342 | */
|
---|
| 343 | RTDECL(int) RTStrAAppendTag(char **ppsz, const char *pszAppend, const char *pszTag);
|
---|
| 344 |
|
---|
| 345 | /**
|
---|
| 346 | * Appends N bytes from a strings onto an existing IPRT allocated string
|
---|
| 347 | * (default tag).
|
---|
| 348 | *
|
---|
| 349 | * @retval VINF_SUCCESS
|
---|
| 350 | * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
|
---|
| 351 | * remains unchanged.
|
---|
| 352 | *
|
---|
| 353 | * @param ppsz Pointer to the string pointer. The string
|
---|
| 354 | * pointer must either be NULL or point to a string
|
---|
| 355 | * returned by an IPRT string API. (In/Out)
|
---|
[26481] | 356 | * @param pszAppend The string to append. Can be NULL if cchAppend
|
---|
| 357 | * is NULL.
|
---|
| 358 | * @param cchAppend The number of chars (not code points) to append
|
---|
| 359 | * from pszAppend. Must not be more than
|
---|
| 360 | * @a pszAppend contains, except for the special
|
---|
| 361 | * value RTSTR_MAX that can be used to indicate all
|
---|
| 362 | * of @a pszAppend without having to strlen it.
|
---|
| 363 | */
|
---|
[31157] | 364 | #define RTStrAAppendN(ppsz, pszAppend, cchAppend) RTStrAAppendNTag((ppsz), (pszAppend), (cchAppend), RTSTR_TAG)
|
---|
[26481] | 365 |
|
---|
| 366 | /**
|
---|
[31157] | 367 | * Appends N bytes from a strings onto an existing IPRT allocated string (custom
|
---|
| 368 | * tag).
|
---|
| 369 | *
|
---|
| 370 | * @retval VINF_SUCCESS
|
---|
| 371 | * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
|
---|
| 372 | * remains unchanged.
|
---|
| 373 | *
|
---|
| 374 | * @param ppsz Pointer to the string pointer. The string
|
---|
| 375 | * pointer must either be NULL or point to a string
|
---|
| 376 | * returned by an IPRT string API. (In/Out)
|
---|
| 377 | * @param pszAppend The string to append. Can be NULL if cchAppend
|
---|
| 378 | * is NULL.
|
---|
| 379 | * @param cchAppend The number of chars (not code points) to append
|
---|
| 380 | * from pszAppend. Must not be more than
|
---|
| 381 | * @a pszAppend contains, except for the special
|
---|
| 382 | * value RTSTR_MAX that can be used to indicate all
|
---|
| 383 | * of @a pszAppend without having to strlen it.
|
---|
| 384 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 385 | */
|
---|
| 386 | RTDECL(int) RTStrAAppendNTag(char **ppsz, const char *pszAppend, size_t cchAppend, const char *pszTag);
|
---|
| 387 |
|
---|
| 388 | /**
|
---|
[26481] | 389 | * Appends one or more strings onto an existing IPRT allocated string.
|
---|
| 390 | *
|
---|
| 391 | * This is a very flexible and efficient alternative to using RTStrAPrintf to
|
---|
| 392 | * combine several strings together.
|
---|
| 393 | *
|
---|
| 394 | * @retval VINF_SUCCESS
|
---|
| 395 | * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
|
---|
| 396 | * remains unchanged.
|
---|
| 397 | *
|
---|
| 398 | * @param ppsz Pointer to the string pointer. The string
|
---|
| 399 | * pointer must either be NULL or point to a string
|
---|
| 400 | * returned by an IPRT string API. (In/Out)
|
---|
| 401 | * @param cPairs The number of string / length pairs in the
|
---|
| 402 | * @a va.
|
---|
| 403 | * @param va List of string (const char *) and length
|
---|
| 404 | * (size_t) pairs. The strings will be appended to
|
---|
| 405 | * the string in the first argument.
|
---|
| 406 | */
|
---|
[31157] | 407 | #define RTStrAAppendExNV(ppsz, cPairs, va) RTStrAAppendExNVTag((ppsz), (cPairs), (va), RTSTR_TAG)
|
---|
[26481] | 408 |
|
---|
| 409 | /**
|
---|
| 410 | * Appends one or more strings onto an existing IPRT allocated string.
|
---|
| 411 | *
|
---|
| 412 | * This is a very flexible and efficient alternative to using RTStrAPrintf to
|
---|
| 413 | * combine several strings together.
|
---|
| 414 | *
|
---|
| 415 | * @retval VINF_SUCCESS
|
---|
| 416 | * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
|
---|
| 417 | * remains unchanged.
|
---|
| 418 | *
|
---|
| 419 | * @param ppsz Pointer to the string pointer. The string
|
---|
| 420 | * pointer must either be NULL or point to a string
|
---|
| 421 | * returned by an IPRT string API. (In/Out)
|
---|
| 422 | * @param cPairs The number of string / length pairs in the
|
---|
[31157] | 423 | * @a va.
|
---|
| 424 | * @param va List of string (const char *) and length
|
---|
| 425 | * (size_t) pairs. The strings will be appended to
|
---|
| 426 | * the string in the first argument.
|
---|
| 427 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 428 | */
|
---|
| 429 | RTDECL(int) RTStrAAppendExNVTag(char **ppsz, size_t cPairs, va_list va, const char *pszTag);
|
---|
| 430 |
|
---|
| 431 | /**
|
---|
| 432 | * Appends one or more strings onto an existing IPRT allocated string
|
---|
| 433 | * (untagged).
|
---|
| 434 | *
|
---|
| 435 | * This is a very flexible and efficient alternative to using RTStrAPrintf to
|
---|
| 436 | * combine several strings together.
|
---|
| 437 | *
|
---|
| 438 | * @retval VINF_SUCCESS
|
---|
| 439 | * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
|
---|
| 440 | * remains unchanged.
|
---|
| 441 | *
|
---|
| 442 | * @param ppsz Pointer to the string pointer. The string
|
---|
| 443 | * pointer must either be NULL or point to a string
|
---|
| 444 | * returned by an IPRT string API. (In/Out)
|
---|
| 445 | * @param cPairs The number of string / length pairs in the
|
---|
[26481] | 446 | * ellipsis.
|
---|
| 447 | * @param ... List of string (const char *) and length
|
---|
| 448 | * (size_t) pairs. The strings will be appended to
|
---|
| 449 | * the string in the first argument.
|
---|
| 450 | */
|
---|
[31157] | 451 | DECLINLINE(int) RTStrAAppendExN(char **ppsz, size_t cPairs, ...)
|
---|
| 452 | {
|
---|
| 453 | int rc;
|
---|
| 454 | va_list va;
|
---|
| 455 | va_start(va, cPairs);
|
---|
| 456 | rc = RTStrAAppendExNVTag(ppsz, cPairs, va, RTSTR_TAG);
|
---|
| 457 | va_end(va);
|
---|
| 458 | return rc;
|
---|
| 459 | }
|
---|
[26481] | 460 |
|
---|
| 461 | /**
|
---|
[31157] | 462 | * Appends one or more strings onto an existing IPRT allocated string (custom
|
---|
| 463 | * tag).
|
---|
| 464 | *
|
---|
| 465 | * This is a very flexible and efficient alternative to using RTStrAPrintf to
|
---|
| 466 | * combine several strings together.
|
---|
| 467 | *
|
---|
| 468 | * @retval VINF_SUCCESS
|
---|
| 469 | * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
|
---|
| 470 | * remains unchanged.
|
---|
| 471 | *
|
---|
| 472 | * @param ppsz Pointer to the string pointer. The string
|
---|
| 473 | * pointer must either be NULL or point to a string
|
---|
| 474 | * returned by an IPRT string API. (In/Out)
|
---|
| 475 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 476 | * @param cPairs The number of string / length pairs in the
|
---|
| 477 | * ellipsis.
|
---|
| 478 | * @param ... List of string (const char *) and length
|
---|
| 479 | * (size_t) pairs. The strings will be appended to
|
---|
| 480 | * the string in the first argument.
|
---|
| 481 | */
|
---|
| 482 | DECLINLINE(int) RTStrAAppendExNTag(char **ppsz, const char *pszTag, size_t cPairs, ...)
|
---|
| 483 | {
|
---|
| 484 | int rc;
|
---|
| 485 | va_list va;
|
---|
| 486 | va_start(va, cPairs);
|
---|
| 487 | rc = RTStrAAppendExNVTag(ppsz, cPairs, va, pszTag);
|
---|
| 488 | va_end(va);
|
---|
| 489 | return rc;
|
---|
| 490 | }
|
---|
| 491 |
|
---|
| 492 | /**
|
---|
| 493 | * Truncates an IPRT allocated string (default tag).
|
---|
| 494 | *
|
---|
| 495 | * @retval VINF_SUCCESS.
|
---|
| 496 | * @retval VERR_OUT_OF_RANGE if cchNew is too long. Nothing is done.
|
---|
| 497 | *
|
---|
| 498 | * @param ppsz Pointer to the string pointer. The string
|
---|
| 499 | * pointer can be NULL if @a cchNew is 0, no change
|
---|
| 500 | * is made then. If we actually reallocate the
|
---|
| 501 | * string, the string pointer might be changed by
|
---|
| 502 | * this call. (In/Out)
|
---|
| 503 | * @param cchNew The new string length (excluding the
|
---|
| 504 | * terminator). The string must be at least this
|
---|
| 505 | * long or we'll return VERR_OUT_OF_RANGE and
|
---|
| 506 | * assert on you.
|
---|
| 507 | */
|
---|
| 508 | #define RTStrATruncate(ppsz, cchNew) RTStrATruncateTag((ppsz), (cchNew), RTSTR_TAG)
|
---|
| 509 |
|
---|
| 510 | /**
|
---|
[26482] | 511 | * Truncates an IPRT allocated string.
|
---|
| 512 | *
|
---|
| 513 | * @retval VINF_SUCCESS.
|
---|
| 514 | * @retval VERR_OUT_OF_RANGE if cchNew is too long. Nothing is done.
|
---|
| 515 | *
|
---|
| 516 | * @param ppsz Pointer to the string pointer. The string
|
---|
| 517 | * pointer can be NULL if @a cchNew is 0, no change
|
---|
| 518 | * is made then. If we actually reallocate the
|
---|
| 519 | * string, the string pointer might be changed by
|
---|
| 520 | * this call. (In/Out)
|
---|
| 521 | * @param cchNew The new string length (excluding the
|
---|
| 522 | * terminator). The string must be at least this
|
---|
| 523 | * long or we'll return VERR_OUT_OF_RANGE and
|
---|
| 524 | * assert on you.
|
---|
[31157] | 525 | * @param pszTag Allocation tag used for statistics and such.
|
---|
[26482] | 526 | */
|
---|
[31157] | 527 | RTDECL(int) RTStrATruncateTag(char **ppsz, size_t cchNew, const char *pszTag);
|
---|
[26482] | 528 |
|
---|
| 529 | /**
|
---|
[31157] | 530 | * Allocates memory for string storage (default tag).
|
---|
[26481] | 531 | *
|
---|
| 532 | * You should normally not use this function, except if there is some very
|
---|
| 533 | * custom string handling you need doing that isn't covered by any of the other
|
---|
| 534 | * APIs.
|
---|
| 535 | *
|
---|
| 536 | * @returns Pointer to the allocated string. The first byte is always set
|
---|
| 537 | * to the string terminator char, the contents of the remainder of the
|
---|
| 538 | * memory is undefined. The string must be freed by calling RTStrFree.
|
---|
| 539 | *
|
---|
| 540 | * NULL is returned if the allocation failed. Please translate this to
|
---|
| 541 | * VERR_NO_STR_MEMORY and not VERR_NO_MEMORY. Also consider
|
---|
| 542 | * RTStrAllocEx if an IPRT status code is required.
|
---|
| 543 | *
|
---|
| 544 | * @param cb How many bytes to allocate. If this is zero, we
|
---|
| 545 | * will allocate a terminator byte anyway.
|
---|
| 546 | */
|
---|
[31157] | 547 | #define RTStrAlloc(cb) RTStrAllocTag((cb), RTSTR_TAG)
|
---|
[26481] | 548 |
|
---|
| 549 | /**
|
---|
[31157] | 550 | * Allocates memory for string storage (custom tag).
|
---|
[26481] | 551 | *
|
---|
| 552 | * You should normally not use this function, except if there is some very
|
---|
| 553 | * custom string handling you need doing that isn't covered by any of the other
|
---|
| 554 | * APIs.
|
---|
| 555 | *
|
---|
[31157] | 556 | * @returns Pointer to the allocated string. The first byte is always set
|
---|
| 557 | * to the string terminator char, the contents of the remainder of the
|
---|
| 558 | * memory is undefined. The string must be freed by calling RTStrFree.
|
---|
| 559 | *
|
---|
| 560 | * NULL is returned if the allocation failed. Please translate this to
|
---|
| 561 | * VERR_NO_STR_MEMORY and not VERR_NO_MEMORY. Also consider
|
---|
| 562 | * RTStrAllocEx if an IPRT status code is required.
|
---|
| 563 | *
|
---|
| 564 | * @param cb How many bytes to allocate. If this is zero, we
|
---|
| 565 | * will allocate a terminator byte anyway.
|
---|
| 566 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 567 | */
|
---|
| 568 | RTDECL(char *) RTStrAllocTag(size_t cb, const char *pszTag);
|
---|
| 569 |
|
---|
| 570 | /**
|
---|
| 571 | * Allocates memory for string storage, with status code (default tag).
|
---|
| 572 | *
|
---|
| 573 | * You should normally not use this function, except if there is some very
|
---|
| 574 | * custom string handling you need doing that isn't covered by any of the other
|
---|
| 575 | * APIs.
|
---|
| 576 | *
|
---|
[26481] | 577 | * @retval VINF_SUCCESS
|
---|
| 578 | * @retval VERR_NO_STR_MEMORY
|
---|
| 579 | *
|
---|
| 580 | * @param ppsz Where to return the allocated string. This will
|
---|
| 581 | * be set to NULL on failure. On success, the
|
---|
| 582 | * returned memory will always start with a
|
---|
| 583 | * terminator char so that it is considered a valid
|
---|
| 584 | * C string, the contents of rest of the memory is
|
---|
| 585 | * undefined.
|
---|
| 586 | * @param cb How many bytes to allocate. If this is zero, we
|
---|
| 587 | * will allocate a terminator byte anyway.
|
---|
| 588 | */
|
---|
[31157] | 589 | #define RTStrAllocEx(ppsz, cb) RTStrAllocExTag((ppsz), (cb), RTSTR_TAG)
|
---|
[26481] | 590 |
|
---|
| 591 | /**
|
---|
[31157] | 592 | * Allocates memory for string storage, with status code (custom tag).
|
---|
[26481] | 593 | *
|
---|
[31157] | 594 | * You should normally not use this function, except if there is some very
|
---|
| 595 | * custom string handling you need doing that isn't covered by any of the other
|
---|
| 596 | * APIs.
|
---|
| 597 | *
|
---|
| 598 | * @retval VINF_SUCCESS
|
---|
| 599 | * @retval VERR_NO_STR_MEMORY
|
---|
| 600 | *
|
---|
| 601 | * @param ppsz Where to return the allocated string. This will
|
---|
| 602 | * be set to NULL on failure. On success, the
|
---|
| 603 | * returned memory will always start with a
|
---|
| 604 | * terminator char so that it is considered a valid
|
---|
| 605 | * C string, the contents of rest of the memory is
|
---|
| 606 | * undefined.
|
---|
| 607 | * @param cb How many bytes to allocate. If this is zero, we
|
---|
| 608 | * will allocate a terminator byte anyway.
|
---|
| 609 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 610 | */
|
---|
| 611 | RTDECL(int) RTStrAllocExTag(char **ppsz, size_t cb, const char *pszTag);
|
---|
| 612 |
|
---|
| 613 | /**
|
---|
| 614 | * Reallocates the specified string (default tag).
|
---|
| 615 | *
|
---|
[26481] | 616 | * You should normally not have use this function, except perhaps to truncate a
|
---|
[26482] | 617 | * really long string you've got from some IPRT string API, but then you should
|
---|
| 618 | * use RTStrATruncate.
|
---|
[26481] | 619 | *
|
---|
| 620 | * @returns VINF_SUCCESS.
|
---|
| 621 | * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
|
---|
| 622 | * remains unchanged.
|
---|
| 623 | *
|
---|
| 624 | * @param ppsz Pointer to the string variable containing the
|
---|
| 625 | * input and output string.
|
---|
| 626 | *
|
---|
| 627 | * When not freeing the string, the result will
|
---|
| 628 | * always have the last byte set to the terminator
|
---|
| 629 | * character so that when used for string
|
---|
| 630 | * truncation the result will be a valid C string
|
---|
| 631 | * (your job to keep it a valid UTF-8 string).
|
---|
| 632 | *
|
---|
| 633 | * When the input string is NULL and we're supposed
|
---|
| 634 | * to reallocate, the returned string will also
|
---|
| 635 | * have the first byte set to the terminator char
|
---|
| 636 | * so it will be a valid C string.
|
---|
| 637 | *
|
---|
| 638 | * @param cbNew When @a cbNew is zero, we'll behave like
|
---|
| 639 | * RTStrFree and @a *ppsz will be set to NULL.
|
---|
| 640 | *
|
---|
| 641 | * When not zero, this will be the new size of the
|
---|
| 642 | * memory backing the string, i.e. it includes the
|
---|
| 643 | * terminator char.
|
---|
| 644 | */
|
---|
[31157] | 645 | #define RTStrRealloc(ppsz, cbNew) RTStrReallocTag((ppsz), (cbNew), RTSTR_TAG)
|
---|
[26481] | 646 |
|
---|
| 647 | /**
|
---|
[31157] | 648 | * Reallocates the specified string (custom tag).
|
---|
| 649 | *
|
---|
| 650 | * You should normally not have use this function, except perhaps to truncate a
|
---|
| 651 | * really long string you've got from some IPRT string API, but then you should
|
---|
| 652 | * use RTStrATruncate.
|
---|
| 653 | *
|
---|
| 654 | * @returns VINF_SUCCESS.
|
---|
| 655 | * @retval VERR_NO_STR_MEMORY if we failed to reallocate the string, @a *ppsz
|
---|
| 656 | * remains unchanged.
|
---|
| 657 | *
|
---|
| 658 | * @param ppsz Pointer to the string variable containing the
|
---|
| 659 | * input and output string.
|
---|
| 660 | *
|
---|
| 661 | * When not freeing the string, the result will
|
---|
| 662 | * always have the last byte set to the terminator
|
---|
| 663 | * character so that when used for string
|
---|
| 664 | * truncation the result will be a valid C string
|
---|
| 665 | * (your job to keep it a valid UTF-8 string).
|
---|
| 666 | *
|
---|
| 667 | * When the input string is NULL and we're supposed
|
---|
| 668 | * to reallocate, the returned string will also
|
---|
| 669 | * have the first byte set to the terminator char
|
---|
| 670 | * so it will be a valid C string.
|
---|
| 671 | *
|
---|
| 672 | * @param cbNew When @a cbNew is zero, we'll behave like
|
---|
| 673 | * RTStrFree and @a *ppsz will be set to NULL.
|
---|
| 674 | *
|
---|
| 675 | * When not zero, this will be the new size of the
|
---|
| 676 | * memory backing the string, i.e. it includes the
|
---|
| 677 | * terminator char.
|
---|
| 678 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 679 | */
|
---|
| 680 | RTDECL(int) RTStrReallocTag(char **ppsz, size_t cbNew, const char *pszTag);
|
---|
| 681 |
|
---|
| 682 | /**
|
---|
[10106] | 683 | * Validates the UTF-8 encoding of the string.
|
---|
| 684 | *
|
---|
| 685 | * @returns iprt status code.
|
---|
| 686 | * @param psz The string.
|
---|
| 687 | */
|
---|
| 688 | RTDECL(int) RTStrValidateEncoding(const char *psz);
|
---|
| 689 |
|
---|
[50792] | 690 | /** @name Flags for RTStrValidateEncodingEx and RTUtf16ValidateEncodingEx
|
---|
[57941] | 691 | * @{
|
---|
[10951] | 692 | */
|
---|
| 693 | /** Check that the string is zero terminated within the given size.
|
---|
| 694 | * VERR_BUFFER_OVERFLOW will be returned if the check fails. */
|
---|
[21642] | 695 | #define RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED RT_BIT_32(0)
|
---|
[50793] | 696 | /** Check that the string is exactly the given length.
|
---|
| 697 | * If it terminates early, VERR_BUFFER_UNDERFLOW will be returned. When used
|
---|
| 698 | * together with RTSTR_VALIDATE_ENCODING_ZERO_TERMINATED, the given length must
|
---|
| 699 | * include the terminator or VERR_BUFFER_OVERFLOW will be returned. */
|
---|
| 700 | #define RTSTR_VALIDATE_ENCODING_EXACT_LENGTH RT_BIT_32(1)
|
---|
[10951] | 701 | /** @} */
|
---|
| 702 |
|
---|
[10106] | 703 | /**
|
---|
| 704 | * Validates the UTF-8 encoding of the string.
|
---|
| 705 | *
|
---|
| 706 | * @returns iprt status code.
|
---|
| 707 | * @param psz The string.
|
---|
[50793] | 708 | * @param cch The max string length (/ size). Use RTSTR_MAX to
|
---|
| 709 | * process the entire string.
|
---|
[50792] | 710 | * @param fFlags Combination of RTSTR_VALIDATE_ENCODING_XXX flags.
|
---|
[10106] | 711 | */
|
---|
[10951] | 712 | RTDECL(int) RTStrValidateEncodingEx(const char *psz, size_t cch, uint32_t fFlags);
|
---|
[10106] | 713 |
|
---|
| 714 | /**
|
---|
| 715 | * Checks if the UTF-8 encoding is valid.
|
---|
| 716 | *
|
---|
| 717 | * @returns true / false.
|
---|
| 718 | * @param psz The string.
|
---|
| 719 | */
|
---|
| 720 | RTDECL(bool) RTStrIsValidEncoding(const char *psz);
|
---|
| 721 |
|
---|
| 722 | /**
|
---|
[30859] | 723 | * Purge all bad UTF-8 encoding in the string, replacing it with '?'.
|
---|
| 724 | *
|
---|
| 725 | * @returns The number of bad characters (0 if nothing was done).
|
---|
| 726 | * @param psz The string to purge.
|
---|
| 727 | */
|
---|
| 728 | RTDECL(size_t) RTStrPurgeEncoding(char *psz);
|
---|
| 729 |
|
---|
| 730 | /**
|
---|
[62916] | 731 | * Sanitizes a (valid) UTF-8 string by replacing all characters outside a white
|
---|
[62930] | 732 | * list in-place by an ASCII replacement character.
|
---|
[40071] | 733 | *
|
---|
[62930] | 734 | * Multi-byte characters will be replaced byte by byte.
|
---|
| 735 | *
|
---|
[62916] | 736 | * @returns The number of code points replaced. In the case of an incorrectly
|
---|
| 737 | * encoded string -1 will be returned, and the string is not completely
|
---|
| 738 | * processed. In the case of puszValidPairs having an odd number of
|
---|
| 739 | * code points, -1 will be also return but without any modification to
|
---|
| 740 | * the string.
|
---|
[40071] | 741 | * @param psz The string to sanitise.
|
---|
[62916] | 742 | * @param puszValidPairs A zero-terminated array of pairs of Unicode points.
|
---|
[40123] | 743 | * Each pair is the start and end point of a range,
|
---|
| 744 | * and the union of these ranges forms the white list.
|
---|
[40071] | 745 | * @param chReplacement The ASCII replacement character.
|
---|
| 746 | */
|
---|
[62916] | 747 | RTDECL(ssize_t) RTStrPurgeComplementSet(char *psz, PCRTUNICP puszValidPairs, char chReplacement);
|
---|
[40071] | 748 |
|
---|
| 749 | /**
|
---|
[1] | 750 | * Gets the number of code points the string is made up of, excluding
|
---|
| 751 | * the terminator.
|
---|
| 752 | *
|
---|
| 753 | *
|
---|
| 754 | * @returns Number of code points (RTUNICP).
|
---|
| 755 | * @returns 0 if the string was incorrectly encoded.
|
---|
| 756 | * @param psz The string.
|
---|
| 757 | */
|
---|
| 758 | RTDECL(size_t) RTStrUniLen(const char *psz);
|
---|
| 759 |
|
---|
| 760 | /**
|
---|
| 761 | * Gets the number of code points the string is made up of, excluding
|
---|
| 762 | * the terminator.
|
---|
| 763 | *
|
---|
| 764 | * This function will validate the string, and incorrectly encoded UTF-8
|
---|
| 765 | * strings will be rejected.
|
---|
| 766 | *
|
---|
| 767 | * @returns iprt status code.
|
---|
| 768 | * @param psz The string.
|
---|
| 769 | * @param cch The max string length. Use RTSTR_MAX to process the entire string.
|
---|
| 770 | * @param pcuc Where to store the code point count.
|
---|
| 771 | * This is undefined on failure.
|
---|
| 772 | */
|
---|
| 773 | RTDECL(int) RTStrUniLenEx(const char *psz, size_t cch, size_t *pcuc);
|
---|
| 774 |
|
---|
| 775 | /**
|
---|
| 776 | * Translate a UTF-8 string into an unicode string (i.e. RTUNICPs), allocating the string buffer.
|
---|
| 777 | *
|
---|
| 778 | * @returns iprt status code.
|
---|
| 779 | * @param pszString UTF-8 string to convert.
|
---|
| 780 | * @param ppUniString Receives pointer to the allocated unicode string.
|
---|
| 781 | * The returned string must be freed using RTUniFree().
|
---|
| 782 | */
|
---|
| 783 | RTDECL(int) RTStrToUni(const char *pszString, PRTUNICP *ppUniString);
|
---|
| 784 |
|
---|
| 785 | /**
|
---|
| 786 | * Translates pszString from UTF-8 to an array of code points, allocating the result
|
---|
| 787 | * array if requested.
|
---|
| 788 | *
|
---|
| 789 | * @returns iprt status code.
|
---|
| 790 | * @param pszString UTF-8 string to convert.
|
---|
| 791 | * @param cchString The maximum size in chars (the type) to convert. The conversion stop
|
---|
| 792 | * when it reaches cchString or the string terminator ('\\0').
|
---|
| 793 | * Use RTSTR_MAX to translate the entire string.
|
---|
| 794 | * @param ppaCps If cCps is non-zero, this must either be pointing to pointer to
|
---|
| 795 | * a buffer of the specified size, or pointer to a NULL pointer.
|
---|
| 796 | * If *ppusz is NULL or cCps is zero a buffer of at least cCps items
|
---|
| 797 | * will be allocated to hold the translated string.
|
---|
[18523] | 798 | * If a buffer was requested it must be freed using RTUtf16Free().
|
---|
[1] | 799 | * @param cCps The number of code points in the unicode string. This includes the terminator.
|
---|
[21741] | 800 | * @param pcCps Where to store the length of the translated string,
|
---|
| 801 | * excluding the terminator. (Optional)
|
---|
| 802 | *
|
---|
| 803 | * This may be set under some error conditions,
|
---|
| 804 | * however, only for VERR_BUFFER_OVERFLOW and
|
---|
| 805 | * VERR_NO_STR_MEMORY will it contain a valid string
|
---|
| 806 | * length that can be used to resize the buffer.
|
---|
[1] | 807 | */
|
---|
| 808 | RTDECL(int) RTStrToUniEx(const char *pszString, size_t cchString, PRTUNICP *ppaCps, size_t cCps, size_t *pcCps);
|
---|
| 809 |
|
---|
| 810 | /**
|
---|
| 811 | * Calculates the length of the string in RTUTF16 items.
|
---|
| 812 | *
|
---|
| 813 | * This function will validate the string, and incorrectly encoded UTF-8
|
---|
| 814 | * strings will be rejected. The primary purpose of this function is to
|
---|
| 815 | * help allocate buffers for RTStrToUtf16Ex of the correct size. For most
|
---|
[18523] | 816 | * other purposes RTStrCalcUtf16LenEx() should be used.
|
---|
[1] | 817 | *
|
---|
| 818 | * @returns Number of RTUTF16 items.
|
---|
| 819 | * @returns 0 if the string was incorrectly encoded.
|
---|
| 820 | * @param psz The string.
|
---|
| 821 | */
|
---|
| 822 | RTDECL(size_t) RTStrCalcUtf16Len(const char *psz);
|
---|
| 823 |
|
---|
| 824 | /**
|
---|
| 825 | * Calculates the length of the string in RTUTF16 items.
|
---|
| 826 | *
|
---|
| 827 | * This function will validate the string, and incorrectly encoded UTF-8
|
---|
| 828 | * strings will be rejected.
|
---|
| 829 | *
|
---|
| 830 | * @returns iprt status code.
|
---|
| 831 | * @param psz The string.
|
---|
| 832 | * @param cch The max string length. Use RTSTR_MAX to process the entire string.
|
---|
| 833 | * @param pcwc Where to store the string length. Optional.
|
---|
| 834 | * This is undefined on failure.
|
---|
| 835 | */
|
---|
| 836 | RTDECL(int) RTStrCalcUtf16LenEx(const char *psz, size_t cch, size_t *pcwc);
|
---|
| 837 |
|
---|
| 838 | /**
|
---|
[31157] | 839 | * Translate a UTF-8 string into a UTF-16 allocating the result buffer (default
|
---|
| 840 | * tag).
|
---|
[1] | 841 | *
|
---|
| 842 | * @returns iprt status code.
|
---|
| 843 | * @param pszString UTF-8 string to convert.
|
---|
| 844 | * @param ppwszString Receives pointer to the allocated UTF-16 string.
|
---|
| 845 | * The returned string must be freed using RTUtf16Free().
|
---|
| 846 | */
|
---|
[31157] | 847 | #define RTStrToUtf16(pszString, ppwszString) RTStrToUtf16Tag((pszString), (ppwszString), RTSTR_TAG)
|
---|
[1] | 848 |
|
---|
| 849 | /**
|
---|
[31157] | 850 | * Translate a UTF-8 string into a UTF-16 allocating the result buffer (custom
|
---|
| 851 | * tag).
|
---|
| 852 | *
|
---|
[67334] | 853 | * This differs from RTStrToUtf16 in that it always produces a
|
---|
| 854 | * big-endian string.
|
---|
| 855 | *
|
---|
[31157] | 856 | * @returns iprt status code.
|
---|
| 857 | * @param pszString UTF-8 string to convert.
|
---|
| 858 | * @param ppwszString Receives pointer to the allocated UTF-16 string.
|
---|
| 859 | * The returned string must be freed using RTUtf16Free().
|
---|
| 860 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 861 | */
|
---|
| 862 | RTDECL(int) RTStrToUtf16Tag(const char *pszString, PRTUTF16 *ppwszString, const char *pszTag);
|
---|
| 863 |
|
---|
| 864 | /**
|
---|
[67334] | 865 | * Translate a UTF-8 string into a UTF-16BE allocating the result buffer
|
---|
| 866 | * (default tag).
|
---|
| 867 | *
|
---|
| 868 | * This differs from RTStrToUtf16Tag in that it always produces a
|
---|
| 869 | * big-endian string.
|
---|
| 870 | *
|
---|
| 871 | * @returns iprt status code.
|
---|
| 872 | * @param pszString UTF-8 string to convert.
|
---|
| 873 | * @param ppwszString Receives pointer to the allocated UTF-16BE string.
|
---|
| 874 | * The returned string must be freed using RTUtf16Free().
|
---|
| 875 | */
|
---|
| 876 | #define RTStrToUtf16Big(pszString, ppwszString) RTStrToUtf16BigTag((pszString), (ppwszString), RTSTR_TAG)
|
---|
| 877 |
|
---|
| 878 | /**
|
---|
| 879 | * Translate a UTF-8 string into a UTF-16BE allocating the result buffer (custom
|
---|
| 880 | * tag).
|
---|
| 881 | *
|
---|
| 882 | * @returns iprt status code.
|
---|
| 883 | * @param pszString UTF-8 string to convert.
|
---|
| 884 | * @param ppwszString Receives pointer to the allocated UTF-16BE string.
|
---|
| 885 | * The returned string must be freed using RTUtf16Free().
|
---|
| 886 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 887 | */
|
---|
| 888 | RTDECL(int) RTStrToUtf16BigTag(const char *pszString, PRTUTF16 *ppwszString, const char *pszTag);
|
---|
| 889 |
|
---|
| 890 | /**
|
---|
[1] | 891 | * Translates pszString from UTF-8 to UTF-16, allocating the result buffer if requested.
|
---|
| 892 | *
|
---|
| 893 | * @returns iprt status code.
|
---|
| 894 | * @param pszString UTF-8 string to convert.
|
---|
| 895 | * @param cchString The maximum size in chars (the type) to convert. The conversion stop
|
---|
| 896 | * when it reaches cchString or the string terminator ('\\0').
|
---|
| 897 | * Use RTSTR_MAX to translate the entire string.
|
---|
| 898 | * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
|
---|
| 899 | * a buffer of the specified size, or pointer to a NULL pointer.
|
---|
| 900 | * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
|
---|
| 901 | * will be allocated to hold the translated string.
|
---|
[18523] | 902 | * If a buffer was requested it must be freed using RTUtf16Free().
|
---|
[1] | 903 | * @param cwc The buffer size in RTUTF16s. This includes the terminator.
|
---|
[21741] | 904 | * @param pcwc Where to store the length of the translated string,
|
---|
| 905 | * excluding the terminator. (Optional)
|
---|
| 906 | *
|
---|
| 907 | * This may be set under some error conditions,
|
---|
| 908 | * however, only for VERR_BUFFER_OVERFLOW and
|
---|
| 909 | * VERR_NO_STR_MEMORY will it contain a valid string
|
---|
| 910 | * length that can be used to resize the buffer.
|
---|
[1] | 911 | */
|
---|
[31157] | 912 | #define RTStrToUtf16Ex(pszString, cchString, ppwsz, cwc, pcwc) \
|
---|
| 913 | RTStrToUtf16ExTag((pszString), (cchString), (ppwsz), (cwc), (pcwc), RTSTR_TAG)
|
---|
[1] | 914 |
|
---|
[31157] | 915 | /**
|
---|
| 916 | * Translates pszString from UTF-8 to UTF-16, allocating the result buffer if
|
---|
| 917 | * requested (custom tag).
|
---|
| 918 | *
|
---|
| 919 | * @returns iprt status code.
|
---|
| 920 | * @param pszString UTF-8 string to convert.
|
---|
| 921 | * @param cchString The maximum size in chars (the type) to convert. The conversion stop
|
---|
| 922 | * when it reaches cchString or the string terminator ('\\0').
|
---|
| 923 | * Use RTSTR_MAX to translate the entire string.
|
---|
| 924 | * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
|
---|
| 925 | * a buffer of the specified size, or pointer to a NULL pointer.
|
---|
| 926 | * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
|
---|
| 927 | * will be allocated to hold the translated string.
|
---|
| 928 | * If a buffer was requested it must be freed using RTUtf16Free().
|
---|
| 929 | * @param cwc The buffer size in RTUTF16s. This includes the terminator.
|
---|
| 930 | * @param pcwc Where to store the length of the translated string,
|
---|
| 931 | * excluding the terminator. (Optional)
|
---|
| 932 | *
|
---|
| 933 | * This may be set under some error conditions,
|
---|
| 934 | * however, only for VERR_BUFFER_OVERFLOW and
|
---|
| 935 | * VERR_NO_STR_MEMORY will it contain a valid string
|
---|
| 936 | * length that can be used to resize the buffer.
|
---|
| 937 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 938 | */
|
---|
[67334] | 939 | RTDECL(int) RTStrToUtf16ExTag(const char *pszString, size_t cchString,
|
---|
| 940 | PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc, const char *pszTag);
|
---|
[1] | 941 |
|
---|
[31157] | 942 |
|
---|
[1] | 943 | /**
|
---|
[67334] | 944 | * Translates pszString from UTF-8 to UTF-16BE, allocating the result buffer if requested.
|
---|
| 945 | *
|
---|
| 946 | * This differs from RTStrToUtf16Ex in that it always produces a
|
---|
| 947 | * big-endian string.
|
---|
| 948 | *
|
---|
| 949 | * @returns iprt status code.
|
---|
| 950 | * @param pszString UTF-8 string to convert.
|
---|
| 951 | * @param cchString The maximum size in chars (the type) to convert. The conversion stop
|
---|
| 952 | * when it reaches cchString or the string terminator ('\\0').
|
---|
| 953 | * Use RTSTR_MAX to translate the entire string.
|
---|
| 954 | * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
|
---|
| 955 | * a buffer of the specified size, or pointer to a NULL pointer.
|
---|
| 956 | * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
|
---|
| 957 | * will be allocated to hold the translated string.
|
---|
| 958 | * If a buffer was requested it must be freed using RTUtf16Free().
|
---|
| 959 | * @param cwc The buffer size in RTUTF16s. This includes the terminator.
|
---|
| 960 | * @param pcwc Where to store the length of the translated string,
|
---|
| 961 | * excluding the terminator. (Optional)
|
---|
| 962 | *
|
---|
| 963 | * This may be set under some error conditions,
|
---|
| 964 | * however, only for VERR_BUFFER_OVERFLOW and
|
---|
| 965 | * VERR_NO_STR_MEMORY will it contain a valid string
|
---|
| 966 | * length that can be used to resize the buffer.
|
---|
| 967 | */
|
---|
| 968 | #define RTStrToUtf16BigEx(pszString, cchString, ppwsz, cwc, pcwc) \
|
---|
| 969 | RTStrToUtf16BigExTag((pszString), (cchString), (ppwsz), (cwc), (pcwc), RTSTR_TAG)
|
---|
| 970 |
|
---|
| 971 | /**
|
---|
| 972 | * Translates pszString from UTF-8 to UTF-16BE, allocating the result buffer if
|
---|
| 973 | * requested (custom tag).
|
---|
| 974 | *
|
---|
| 975 | * This differs from RTStrToUtf16ExTag in that it always produces a
|
---|
| 976 | * big-endian string.
|
---|
| 977 | *
|
---|
| 978 | * @returns iprt status code.
|
---|
| 979 | * @param pszString UTF-8 string to convert.
|
---|
| 980 | * @param cchString The maximum size in chars (the type) to convert. The conversion stop
|
---|
| 981 | * when it reaches cchString or the string terminator ('\\0').
|
---|
| 982 | * Use RTSTR_MAX to translate the entire string.
|
---|
| 983 | * @param ppwsz If cwc is non-zero, this must either be pointing to pointer to
|
---|
| 984 | * a buffer of the specified size, or pointer to a NULL pointer.
|
---|
| 985 | * If *ppwsz is NULL or cwc is zero a buffer of at least cwc items
|
---|
| 986 | * will be allocated to hold the translated string.
|
---|
| 987 | * If a buffer was requested it must be freed using RTUtf16Free().
|
---|
| 988 | * @param cwc The buffer size in RTUTF16s. This includes the terminator.
|
---|
| 989 | * @param pcwc Where to store the length of the translated string,
|
---|
| 990 | * excluding the terminator. (Optional)
|
---|
| 991 | *
|
---|
| 992 | * This may be set under some error conditions,
|
---|
| 993 | * however, only for VERR_BUFFER_OVERFLOW and
|
---|
| 994 | * VERR_NO_STR_MEMORY will it contain a valid string
|
---|
| 995 | * length that can be used to resize the buffer.
|
---|
| 996 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 997 | */
|
---|
| 998 | RTDECL(int) RTStrToUtf16BigExTag(const char *pszString, size_t cchString,
|
---|
| 999 | PRTUTF16 *ppwsz, size_t cwc, size_t *pcwc, const char *pszTag);
|
---|
| 1000 |
|
---|
| 1001 |
|
---|
| 1002 | /**
|
---|
[31199] | 1003 | * Calculates the length of the string in Latin-1 characters.
|
---|
| 1004 | *
|
---|
| 1005 | * This function will validate the string, and incorrectly encoded UTF-8
|
---|
[31418] | 1006 | * strings as well as string with codepoints outside the latin-1 range will be
|
---|
| 1007 | * rejected. The primary purpose of this function is to help allocate buffers
|
---|
| 1008 | * for RTStrToLatin1Ex of the correct size. For most other purposes
|
---|
| 1009 | * RTStrCalcLatin1LenEx() should be used.
|
---|
[31199] | 1010 | *
|
---|
| 1011 | * @returns Number of Latin-1 characters.
|
---|
| 1012 | * @returns 0 if the string was incorrectly encoded.
|
---|
| 1013 | * @param psz The string.
|
---|
| 1014 | */
|
---|
[31221] | 1015 | RTDECL(size_t) RTStrCalcLatin1Len(const char *psz);
|
---|
[31199] | 1016 |
|
---|
| 1017 | /**
|
---|
| 1018 | * Calculates the length of the string in Latin-1 characters.
|
---|
| 1019 | *
|
---|
| 1020 | * This function will validate the string, and incorrectly encoded UTF-8
|
---|
[31418] | 1021 | * strings as well as string with codepoints outside the latin-1 range will be
|
---|
| 1022 | * rejected.
|
---|
[31199] | 1023 | *
|
---|
| 1024 | * @returns iprt status code.
|
---|
| 1025 | * @param psz The string.
|
---|
[31418] | 1026 | * @param cch The max string length. Use RTSTR_MAX to process the
|
---|
| 1027 | * entire string.
|
---|
[31199] | 1028 | * @param pcch Where to store the string length. Optional.
|
---|
| 1029 | * This is undefined on failure.
|
---|
| 1030 | */
|
---|
[57926] | 1031 | RTDECL(int) RTStrCalcLatin1LenEx(const char *psz, size_t cch, size_t *pcch);
|
---|
[31199] | 1032 |
|
---|
| 1033 | /**
|
---|
| 1034 | * Translate a UTF-8 string into a Latin-1 allocating the result buffer (default
|
---|
| 1035 | * tag).
|
---|
| 1036 | *
|
---|
| 1037 | * @returns iprt status code.
|
---|
| 1038 | * @param pszString UTF-8 string to convert.
|
---|
| 1039 | * @param ppszString Receives pointer to the allocated Latin-1 string.
|
---|
| 1040 | * The returned string must be freed using RTStrFree().
|
---|
| 1041 | */
|
---|
| 1042 | #define RTStrToLatin1(pszString, ppszString) RTStrToLatin1Tag((pszString), (ppszString), RTSTR_TAG)
|
---|
| 1043 |
|
---|
| 1044 | /**
|
---|
| 1045 | * Translate a UTF-8 string into a Latin-1 allocating the result buffer (custom
|
---|
| 1046 | * tag).
|
---|
| 1047 | *
|
---|
| 1048 | * @returns iprt status code.
|
---|
| 1049 | * @param pszString UTF-8 string to convert.
|
---|
| 1050 | * @param ppszString Receives pointer to the allocated Latin-1 string.
|
---|
| 1051 | * The returned string must be freed using RTStrFree().
|
---|
| 1052 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 1053 | */
|
---|
| 1054 | RTDECL(int) RTStrToLatin1Tag(const char *pszString, char **ppszString, const char *pszTag);
|
---|
| 1055 |
|
---|
| 1056 | /**
|
---|
| 1057 | * Translates pszString from UTF-8 to Latin-1, allocating the result buffer if requested.
|
---|
| 1058 | *
|
---|
| 1059 | * @returns iprt status code.
|
---|
| 1060 | * @param pszString UTF-8 string to convert.
|
---|
[31418] | 1061 | * @param cchString The maximum size in chars (the type) to convert.
|
---|
| 1062 | * The conversion stop when it reaches cchString or
|
---|
| 1063 | * the string terminator ('\\0'). Use RTSTR_MAX to
|
---|
| 1064 | * translate the entire string.
|
---|
| 1065 | * @param ppsz If cch is non-zero, this must either be pointing to
|
---|
| 1066 | * pointer to a buffer of the specified size, or
|
---|
| 1067 | * pointer to a NULL pointer. If *ppsz is NULL or cch
|
---|
| 1068 | * is zero a buffer of at least cch items will be
|
---|
| 1069 | * allocated to hold the translated string. If a
|
---|
| 1070 | * buffer was requested it must be freed using
|
---|
| 1071 | * RTStrFree().
|
---|
| 1072 | * @param cch The buffer size in bytes. This includes the
|
---|
| 1073 | * terminator.
|
---|
[31199] | 1074 | * @param pcch Where to store the length of the translated string,
|
---|
| 1075 | * excluding the terminator. (Optional)
|
---|
| 1076 | *
|
---|
| 1077 | * This may be set under some error conditions,
|
---|
| 1078 | * however, only for VERR_BUFFER_OVERFLOW and
|
---|
| 1079 | * VERR_NO_STR_MEMORY will it contain a valid string
|
---|
| 1080 | * length that can be used to resize the buffer.
|
---|
| 1081 | */
|
---|
| 1082 | #define RTStrToLatin1Ex(pszString, cchString, ppsz, cch, pcch) \
|
---|
| 1083 | RTStrToLatin1ExTag((pszString), (cchString), (ppsz), (cch), (pcch), RTSTR_TAG)
|
---|
| 1084 |
|
---|
| 1085 | /**
|
---|
| 1086 | * Translates pszString from UTF-8 to Latin1, allocating the result buffer if
|
---|
| 1087 | * requested (custom tag).
|
---|
| 1088 | *
|
---|
| 1089 | * @returns iprt status code.
|
---|
| 1090 | * @param pszString UTF-8 string to convert.
|
---|
[31418] | 1091 | * @param cchString The maximum size in chars (the type) to convert.
|
---|
| 1092 | * The conversion stop when it reaches cchString or
|
---|
| 1093 | * the string terminator ('\\0'). Use RTSTR_MAX to
|
---|
| 1094 | * translate the entire string.
|
---|
| 1095 | * @param ppsz If cch is non-zero, this must either be pointing to
|
---|
| 1096 | * pointer to a buffer of the specified size, or
|
---|
| 1097 | * pointer to a NULL pointer. If *ppsz is NULL or cch
|
---|
| 1098 | * is zero a buffer of at least cch items will be
|
---|
| 1099 | * allocated to hold the translated string. If a
|
---|
| 1100 | * buffer was requested it must be freed using
|
---|
| 1101 | * RTStrFree().
|
---|
| 1102 | * @param cch The buffer size in bytes. This includes the
|
---|
| 1103 | * terminator.
|
---|
[31199] | 1104 | * @param pcch Where to store the length of the translated string,
|
---|
| 1105 | * excluding the terminator. (Optional)
|
---|
| 1106 | *
|
---|
| 1107 | * This may be set under some error conditions,
|
---|
| 1108 | * however, only for VERR_BUFFER_OVERFLOW and
|
---|
| 1109 | * VERR_NO_STR_MEMORY will it contain a valid string
|
---|
| 1110 | * length that can be used to resize the buffer.
|
---|
| 1111 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 1112 | */
|
---|
| 1113 | RTDECL(int) RTStrToLatin1ExTag(const char *pszString, size_t cchString, char **ppsz, size_t cch, size_t *pcch, const char *pszTag);
|
---|
| 1114 |
|
---|
| 1115 | /**
|
---|
[1] | 1116 | * Get the unicode code point at the given string position.
|
---|
| 1117 | *
|
---|
| 1118 | * @returns unicode code point.
|
---|
| 1119 | * @returns RTUNICP_INVALID if the encoding is invalid.
|
---|
| 1120 | * @param psz The string.
|
---|
| 1121 | */
|
---|
| 1122 | RTDECL(RTUNICP) RTStrGetCpInternal(const char *psz);
|
---|
| 1123 |
|
---|
| 1124 | /**
|
---|
| 1125 | * Get the unicode code point at the given string position.
|
---|
| 1126 | *
|
---|
[13927] | 1127 | * @returns iprt status code
|
---|
| 1128 | * @returns VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
|
---|
[30859] | 1129 | * @param ppsz The string cursor.
|
---|
| 1130 | * This is advanced one character forward on failure.
|
---|
[1] | 1131 | * @param pCp Where to store the unicode code point.
|
---|
[13927] | 1132 | * Stores RTUNICP_INVALID if the encoding is invalid.
|
---|
[1] | 1133 | */
|
---|
| 1134 | RTDECL(int) RTStrGetCpExInternal(const char **ppsz, PRTUNICP pCp);
|
---|
| 1135 |
|
---|
| 1136 | /**
|
---|
[13927] | 1137 | * Get the unicode code point at the given string position for a string of a
|
---|
| 1138 | * given length.
|
---|
| 1139 | *
|
---|
| 1140 | * @returns iprt status code
|
---|
[14007] | 1141 | * @retval VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
|
---|
| 1142 | * @retval VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
|
---|
| 1143 | *
|
---|
[13927] | 1144 | * @param ppsz The string.
|
---|
[14007] | 1145 | * @param pcch Pointer to the length of the string. This will be
|
---|
| 1146 | * decremented by the size of the code point.
|
---|
[13927] | 1147 | * @param pCp Where to store the unicode code point.
|
---|
| 1148 | * Stores RTUNICP_INVALID if the encoding is invalid.
|
---|
| 1149 | */
|
---|
[14007] | 1150 | RTDECL(int) RTStrGetCpNExInternal(const char **ppsz, size_t *pcch, PRTUNICP pCp);
|
---|
[13927] | 1151 |
|
---|
| 1152 | /**
|
---|
[1] | 1153 | * Put the unicode code point at the given string position
|
---|
| 1154 | * and return the pointer to the char following it.
|
---|
| 1155 | *
|
---|
[18523] | 1156 | * This function will not consider anything at or following the
|
---|
[1] | 1157 | * buffer area pointed to by psz. It is therefore not suitable for
|
---|
| 1158 | * inserting code points into a string, only appending/overwriting.
|
---|
| 1159 | *
|
---|
| 1160 | * @returns pointer to the char following the written code point.
|
---|
| 1161 | * @param psz The string.
|
---|
| 1162 | * @param CodePoint The code point to write.
|
---|
[18523] | 1163 | * This should not be RTUNICP_INVALID or any other
|
---|
| 1164 | * character out of the UTF-8 range.
|
---|
[1] | 1165 | *
|
---|
| 1166 | * @remark This is a worker function for RTStrPutCp().
|
---|
| 1167 | *
|
---|
| 1168 | */
|
---|
| 1169 | RTDECL(char *) RTStrPutCpInternal(char *psz, RTUNICP CodePoint);
|
---|
| 1170 |
|
---|
| 1171 | /**
|
---|
| 1172 | * Get the unicode code point at the given string position.
|
---|
| 1173 | *
|
---|
| 1174 | * @returns unicode code point.
|
---|
| 1175 | * @returns RTUNICP_INVALID if the encoding is invalid.
|
---|
| 1176 | * @param psz The string.
|
---|
| 1177 | *
|
---|
| 1178 | * @remark We optimize this operation by using an inline function for
|
---|
| 1179 | * the most frequent and simplest sequence, the rest is
|
---|
| 1180 | * handled by RTStrGetCpInternal().
|
---|
| 1181 | */
|
---|
| 1182 | DECLINLINE(RTUNICP) RTStrGetCp(const char *psz)
|
---|
| 1183 | {
|
---|
| 1184 | const unsigned char uch = *(const unsigned char *)psz;
|
---|
[5605] | 1185 | if (!(uch & RT_BIT(7)))
|
---|
[1] | 1186 | return uch;
|
---|
| 1187 | return RTStrGetCpInternal(psz);
|
---|
| 1188 | }
|
---|
| 1189 |
|
---|
| 1190 | /**
|
---|
| 1191 | * Get the unicode code point at the given string position.
|
---|
| 1192 | *
|
---|
| 1193 | * @returns iprt status code.
|
---|
| 1194 | * @param ppsz Pointer to the string pointer. This will be updated to
|
---|
| 1195 | * point to the char following the current code point.
|
---|
[30859] | 1196 | * This is advanced one character forward on failure.
|
---|
[1] | 1197 | * @param pCp Where to store the code point.
|
---|
| 1198 | * RTUNICP_INVALID is stored here on failure.
|
---|
| 1199 | *
|
---|
| 1200 | * @remark We optimize this operation by using an inline function for
|
---|
| 1201 | * the most frequent and simplest sequence, the rest is
|
---|
| 1202 | * handled by RTStrGetCpExInternal().
|
---|
| 1203 | */
|
---|
| 1204 | DECLINLINE(int) RTStrGetCpEx(const char **ppsz, PRTUNICP pCp)
|
---|
| 1205 | {
|
---|
| 1206 | const unsigned char uch = **(const unsigned char **)ppsz;
|
---|
[5605] | 1207 | if (!(uch & RT_BIT(7)))
|
---|
[1] | 1208 | {
|
---|
| 1209 | (*ppsz)++;
|
---|
| 1210 | *pCp = uch;
|
---|
| 1211 | return VINF_SUCCESS;
|
---|
| 1212 | }
|
---|
| 1213 | return RTStrGetCpExInternal(ppsz, pCp);
|
---|
| 1214 | }
|
---|
| 1215 |
|
---|
| 1216 | /**
|
---|
[13927] | 1217 | * Get the unicode code point at the given string position for a string of a
|
---|
| 1218 | * given maximum length.
|
---|
| 1219 | *
|
---|
| 1220 | * @returns iprt status code.
|
---|
[14007] | 1221 | * @retval VERR_INVALID_UTF8_ENCODING if the encoding is invalid.
|
---|
| 1222 | * @retval VERR_END_OF_STRING if *pcch is 0. *pCp is set to RTUNICP_INVALID.
|
---|
| 1223 | *
|
---|
[13927] | 1224 | * @param ppsz Pointer to the string pointer. This will be updated to
|
---|
| 1225 | * point to the char following the current code point.
|
---|
[14007] | 1226 | * @param pcch Pointer to the maximum string length. This will be
|
---|
| 1227 | * decremented by the size of the code point found.
|
---|
[13927] | 1228 | * @param pCp Where to store the code point.
|
---|
| 1229 | * RTUNICP_INVALID is stored here on failure.
|
---|
| 1230 | *
|
---|
| 1231 | * @remark We optimize this operation by using an inline function for
|
---|
| 1232 | * the most frequent and simplest sequence, the rest is
|
---|
| 1233 | * handled by RTStrGetCpNExInternal().
|
---|
| 1234 | */
|
---|
[14007] | 1235 | DECLINLINE(int) RTStrGetCpNEx(const char **ppsz, size_t *pcch, PRTUNICP pCp)
|
---|
[13927] | 1236 | {
|
---|
[14007] | 1237 | if (RT_LIKELY(*pcch != 0))
|
---|
[13927] | 1238 | {
|
---|
[14007] | 1239 | const unsigned char uch = **(const unsigned char **)ppsz;
|
---|
| 1240 | if (!(uch & RT_BIT(7)))
|
---|
| 1241 | {
|
---|
| 1242 | (*ppsz)++;
|
---|
| 1243 | (*pcch)--;
|
---|
| 1244 | *pCp = uch;
|
---|
| 1245 | return VINF_SUCCESS;
|
---|
| 1246 | }
|
---|
[13927] | 1247 | }
|
---|
[14007] | 1248 | return RTStrGetCpNExInternal(ppsz, pcch, pCp);
|
---|
[13927] | 1249 | }
|
---|
| 1250 |
|
---|
| 1251 | /**
|
---|
[31418] | 1252 | * Get the UTF-8 size in characters of a given Unicode code point.
|
---|
[31246] | 1253 | *
|
---|
[31418] | 1254 | * The code point is expected to be a valid Unicode one, but not necessarily in
|
---|
| 1255 | * the range supported by UTF-8.
|
---|
| 1256 | *
|
---|
| 1257 | * @returns The number of chars (bytes) required to encode the code point, or
|
---|
| 1258 | * zero if there is no UTF-8 encoding.
|
---|
| 1259 | * @param CodePoint The unicode code point.
|
---|
[31246] | 1260 | */
|
---|
| 1261 | DECLINLINE(size_t) RTStrCpSize(RTUNICP CodePoint)
|
---|
| 1262 | {
|
---|
[31418] | 1263 | if (CodePoint < 0x00000080)
|
---|
[31246] | 1264 | return 1;
|
---|
[31418] | 1265 | if (CodePoint < 0x00000800)
|
---|
[31246] | 1266 | return 2;
|
---|
[31418] | 1267 | if (CodePoint < 0x00010000)
|
---|
[31246] | 1268 | return 3;
|
---|
[31418] | 1269 | #ifdef RT_USE_RTC_3629
|
---|
| 1270 | if (CodePoint < 0x00011000)
|
---|
[31246] | 1271 | return 4;
|
---|
[31418] | 1272 | #else
|
---|
| 1273 | if (CodePoint < 0x00200000)
|
---|
| 1274 | return 4;
|
---|
| 1275 | if (CodePoint < 0x04000000)
|
---|
| 1276 | return 5;
|
---|
| 1277 | if (CodePoint < 0x7fffffff)
|
---|
| 1278 | return 6;
|
---|
| 1279 | #endif
|
---|
[31246] | 1280 | return 0;
|
---|
| 1281 | }
|
---|
| 1282 |
|
---|
| 1283 | /**
|
---|
[1] | 1284 | * Put the unicode code point at the given string position
|
---|
| 1285 | * and return the pointer to the char following it.
|
---|
| 1286 | *
|
---|
[18523] | 1287 | * This function will not consider anything at or following the
|
---|
[1] | 1288 | * buffer area pointed to by psz. It is therefore not suitable for
|
---|
| 1289 | * inserting code points into a string, only appending/overwriting.
|
---|
| 1290 | *
|
---|
| 1291 | * @returns pointer to the char following the written code point.
|
---|
| 1292 | * @param psz The string.
|
---|
| 1293 | * @param CodePoint The code point to write.
|
---|
[18523] | 1294 | * This should not be RTUNICP_INVALID or any other
|
---|
| 1295 | * character out of the UTF-8 range.
|
---|
[1] | 1296 | *
|
---|
| 1297 | * @remark We optimize this operation by using an inline function for
|
---|
| 1298 | * the most frequent and simplest sequence, the rest is
|
---|
| 1299 | * handled by RTStrPutCpInternal().
|
---|
| 1300 | */
|
---|
| 1301 | DECLINLINE(char *) RTStrPutCp(char *psz, RTUNICP CodePoint)
|
---|
| 1302 | {
|
---|
| 1303 | if (CodePoint < 0x80)
|
---|
| 1304 | {
|
---|
| 1305 | *psz++ = (unsigned char)CodePoint;
|
---|
| 1306 | return psz;
|
---|
| 1307 | }
|
---|
| 1308 | return RTStrPutCpInternal(psz, CodePoint);
|
---|
| 1309 | }
|
---|
| 1310 |
|
---|
| 1311 | /**
|
---|
| 1312 | * Skips ahead, past the current code point.
|
---|
| 1313 | *
|
---|
| 1314 | * @returns Pointer to the char after the current code point.
|
---|
| 1315 | * @param psz Pointer to the current code point.
|
---|
| 1316 | * @remark This will not move the next valid code point, only past the current one.
|
---|
| 1317 | */
|
---|
| 1318 | DECLINLINE(char *) RTStrNextCp(const char *psz)
|
---|
| 1319 | {
|
---|
| 1320 | RTUNICP Cp;
|
---|
| 1321 | RTStrGetCpEx(&psz, &Cp);
|
---|
| 1322 | return (char *)psz;
|
---|
| 1323 | }
|
---|
| 1324 |
|
---|
| 1325 | /**
|
---|
| 1326 | * Skips back to the previous code point.
|
---|
| 1327 | *
|
---|
| 1328 | * @returns Pointer to the char before the current code point.
|
---|
| 1329 | * @returns pszStart on failure.
|
---|
| 1330 | * @param pszStart Pointer to the start of the string.
|
---|
| 1331 | * @param psz Pointer to the current code point.
|
---|
| 1332 | */
|
---|
| 1333 | RTDECL(char *) RTStrPrevCp(const char *pszStart, const char *psz);
|
---|
| 1334 |
|
---|
| 1335 |
|
---|
[33496] | 1336 | /** @page pg_rt_str_format The IPRT Format Strings
|
---|
| 1337 | *
|
---|
| 1338 | * IPRT implements most of the commonly used format types and flags with the
|
---|
| 1339 | * exception of floating point which is completely missing. In addition IPRT
|
---|
| 1340 | * provides a number of IPRT specific format types for the IPRT typedefs and
|
---|
| 1341 | * other useful things. Note that several of these extensions are similar to
|
---|
| 1342 | * \%p and doesn't care much if you try add formating flags/width/precision.
|
---|
| 1343 | *
|
---|
| 1344 | *
|
---|
| 1345 | * Group 0a, The commonly used format types:
|
---|
| 1346 | * - \%s - Takes a pointer to a zero terminated string (UTF-8) and
|
---|
| 1347 | * prints it with the optionally adjustment (width, -) and
|
---|
| 1348 | * length restriction (precision).
|
---|
| 1349 | * - \%ls - Same as \%s except that the input is UTF-16 (output UTF-8).
|
---|
| 1350 | * - \%Ls - Same as \%s except that the input is UCS-32 (output UTF-8).
|
---|
[38658] | 1351 | * - \%S - Same as \%s, used to convert to current codeset but this is
|
---|
| 1352 | * now done by the streams code. Deprecated, use \%s.
|
---|
| 1353 | * - \%lS - Ditto. Deprecated, use \%ls.
|
---|
| 1354 | * - \%LS - Ditto. Deprecated, use \%Ls.
|
---|
[33496] | 1355 | * - \%c - Takes a char and prints it.
|
---|
| 1356 | * - \%d - Takes a signed integer and prints it as decimal. Thousand
|
---|
| 1357 | * separator (\'), zero padding (0), adjustment (-+), width,
|
---|
| 1358 | * precision
|
---|
| 1359 | * - \%i - Same as \%d.
|
---|
| 1360 | * - \%u - Takes an unsigned integer and prints it as decimal. Thousand
|
---|
| 1361 | * separator (\'), zero padding (0), adjustment (-+), width,
|
---|
| 1362 | * precision
|
---|
| 1363 | * - \%x - Takes an unsigned integer and prints it as lowercased
|
---|
| 1364 | * hexadecimal. The special hash (\#) flag causes a '0x'
|
---|
| 1365 | * prefixed to be printed. Zero padding (0), adjustment (-+),
|
---|
| 1366 | * width, precision.
|
---|
| 1367 | * - \%X - Same as \%x except that it is uppercased.
|
---|
| 1368 | * - \%o - Takes an unsigned (?) integer and prints it as octal. Zero
|
---|
| 1369 | * padding (0), adjustment (-+), width, precision.
|
---|
| 1370 | * - \%p - Takes a pointer (void technically) and prints it. Zero
|
---|
| 1371 | * padding (0), adjustment (-+), width, precision.
|
---|
| 1372 | *
|
---|
| 1373 | * The \%d, \%i, \%u, \%x, \%X and \%o format types support the following
|
---|
| 1374 | * argument type specifiers:
|
---|
| 1375 | * - \%ll - long long (uint64_t).
|
---|
| 1376 | * - \%L - long long (uint64_t).
|
---|
| 1377 | * - \%l - long (uint32_t, uint64_t)
|
---|
| 1378 | * - \%h - short (int16_t).
|
---|
| 1379 | * - \%hh - char (int8_t).
|
---|
| 1380 | * - \%H - char (int8_t).
|
---|
| 1381 | * - \%z - size_t.
|
---|
| 1382 | * - \%j - intmax_t (int64_t).
|
---|
| 1383 | * - \%t - ptrdiff_t.
|
---|
| 1384 | * The type in parentheses is typical sizes, however when printing those types
|
---|
| 1385 | * you are better off using the special group 2 format types below (\%RX32 and
|
---|
| 1386 | * such).
|
---|
| 1387 | *
|
---|
| 1388 | *
|
---|
| 1389 | * Group 0b, IPRT format tricks:
|
---|
| 1390 | * - %M - Replaces the format string, takes a string pointer.
|
---|
| 1391 | * - %N - Nested formatting, takes a pointer to a format string
|
---|
| 1392 | * followed by the pointer to a va_list variable. The va_list
|
---|
| 1393 | * variable will not be modified and the caller must do va_end()
|
---|
| 1394 | * on it. Make sure the va_list variable is NOT in a parameter
|
---|
| 1395 | * list or some gcc versions/targets may get it all wrong.
|
---|
| 1396 | *
|
---|
| 1397 | *
|
---|
| 1398 | * Group 1, the basic runtime typedefs (excluding those which obviously are
|
---|
| 1399 | * pointer):
|
---|
| 1400 | * - \%RTbool - Takes a bool value and prints 'true', 'false', or '!%d!'.
|
---|
| 1401 | * - \%RTfile - Takes a #RTFILE value.
|
---|
| 1402 | * - \%RTfmode - Takes a #RTFMODE value.
|
---|
| 1403 | * - \%RTfoff - Takes a #RTFOFF value.
|
---|
| 1404 | * - \%RTfp16 - Takes a #RTFAR16 value.
|
---|
| 1405 | * - \%RTfp32 - Takes a #RTFAR32 value.
|
---|
| 1406 | * - \%RTfp64 - Takes a #RTFAR64 value.
|
---|
| 1407 | * - \%RTgid - Takes a #RTGID value.
|
---|
| 1408 | * - \%RTino - Takes a #RTINODE value.
|
---|
| 1409 | * - \%RTint - Takes a #RTINT value.
|
---|
| 1410 | * - \%RTiop - Takes a #RTIOPORT value.
|
---|
| 1411 | * - \%RTldrm - Takes a #RTLDRMOD value.
|
---|
| 1412 | * - \%RTmac - Takes a #PCRTMAC pointer.
|
---|
| 1413 | * - \%RTnaddr - Takes a #PCRTNETADDR value.
|
---|
| 1414 | * - \%RTnaipv4 - Takes a #RTNETADDRIPV4 value.
|
---|
| 1415 | * - \%RTnaipv6 - Takes a #PCRTNETADDRIPV6 value.
|
---|
| 1416 | * - \%RTnthrd - Takes a #RTNATIVETHREAD value.
|
---|
| 1417 | * - \%RTnthrd - Takes a #RTNATIVETHREAD value.
|
---|
| 1418 | * - \%RTproc - Takes a #RTPROCESS value.
|
---|
| 1419 | * - \%RTptr - Takes a #RTINTPTR or #RTUINTPTR value (but not void *).
|
---|
| 1420 | * - \%RTreg - Takes a #RTCCUINTREG value.
|
---|
| 1421 | * - \%RTsel - Takes a #RTSEL value.
|
---|
| 1422 | * - \%RTsem - Takes a #RTSEMEVENT, #RTSEMEVENTMULTI, #RTSEMMUTEX, #RTSEMFASTMUTEX, or #RTSEMRW value.
|
---|
| 1423 | * - \%RTsock - Takes a #RTSOCKET value.
|
---|
| 1424 | * - \%RTthrd - Takes a #RTTHREAD value.
|
---|
| 1425 | * - \%RTuid - Takes a #RTUID value.
|
---|
| 1426 | * - \%RTuint - Takes a #RTUINT value.
|
---|
| 1427 | * - \%RTunicp - Takes a #RTUNICP value.
|
---|
| 1428 | * - \%RTutf16 - Takes a #RTUTF16 value.
|
---|
| 1429 | * - \%RTuuid - Takes a #PCRTUUID and will print the UUID as a string.
|
---|
| 1430 | * - \%RTxuint - Takes a #RTUINT or #RTINT value, formatting it as hex.
|
---|
| 1431 | * - \%RGi - Takes a #RTGCINT value.
|
---|
| 1432 | * - \%RGp - Takes a #RTGCPHYS value.
|
---|
| 1433 | * - \%RGr - Takes a #RTGCUINTREG value.
|
---|
| 1434 | * - \%RGu - Takes a #RTGCUINT value.
|
---|
| 1435 | * - \%RGv - Takes a #RTGCPTR, #RTGCINTPTR or #RTGCUINTPTR value.
|
---|
| 1436 | * - \%RGx - Takes a #RTGCUINT or #RTGCINT value, formatting it as hex.
|
---|
| 1437 | * - \%RHi - Takes a #RTHCINT value.
|
---|
| 1438 | * - \%RHp - Takes a #RTHCPHYS value.
|
---|
| 1439 | * - \%RHr - Takes a #RTHCUINTREG value.
|
---|
| 1440 | * - \%RHu - Takes a #RTHCUINT value.
|
---|
| 1441 | * - \%RHv - Takes a #RTHCPTR, #RTHCINTPTR or #RTHCUINTPTR value.
|
---|
| 1442 | * - \%RHx - Takes a #RTHCUINT or #RTHCINT value, formatting it as hex.
|
---|
| 1443 | * - \%RRv - Takes a #RTRCPTR, #RTRCINTPTR or #RTRCUINTPTR value.
|
---|
| 1444 | * - \%RCi - Takes a #RTINT value.
|
---|
| 1445 | * - \%RCp - Takes a #RTCCPHYS value.
|
---|
| 1446 | * - \%RCr - Takes a #RTCCUINTREG value.
|
---|
| 1447 | * - \%RCu - Takes a #RTUINT value.
|
---|
| 1448 | * - \%RCv - Takes a #uintptr_t, #intptr_t, void * value.
|
---|
| 1449 | * - \%RCx - Takes a #RTUINT or #RTINT value, formatting it as hex.
|
---|
| 1450 | *
|
---|
| 1451 | *
|
---|
| 1452 | * Group 2, the generic integer types which are prefered over relying on what
|
---|
| 1453 | * bit-count a 'long', 'short', or 'long long' has on a platform. This are
|
---|
| 1454 | * highly prefered for the [u]intXX_t kind of types:
|
---|
| 1455 | * - \%RI[8|16|32|64] - Signed integer value of the specifed bit count.
|
---|
| 1456 | * - \%RU[8|16|32|64] - Unsigned integer value of the specifed bit count.
|
---|
| 1457 | * - \%RX[8|16|32|64] - Hexadecimal integer value of the specifed bit count.
|
---|
| 1458 | *
|
---|
| 1459 | *
|
---|
| 1460 | * Group 3, hex dumpers and other complex stuff which requires more than simple
|
---|
| 1461 | * formatting:
|
---|
| 1462 | * - \%Rhxd - Takes a pointer to the memory which is to be dumped in typical
|
---|
| 1463 | * hex format. Use the precision to specify the length, and the width to
|
---|
| 1464 | * set the number of bytes per line. Default width and precision is 16.
|
---|
[69016] | 1465 | * - \%RhxD - Same as \%Rhxd, except that it skips duplicate lines.
|
---|
[33496] | 1466 | * - \%Rhxs - Takes a pointer to the memory to be displayed as a hex string,
|
---|
| 1467 | * i.e. a series of space separated bytes formatted as two digit hex value.
|
---|
| 1468 | * Use the precision to specify the length. Default length is 16 bytes.
|
---|
| 1469 | * The width, if specified, is ignored.
|
---|
[69833] | 1470 | *
|
---|
| 1471 | * - \%Rhcb - Human readable byte size formatting, using
|
---|
| 1472 | * binary unit prefixes (GiB, MiB and such). Takes a
|
---|
| 1473 | * 64-bit unsigned integer as input. Does one
|
---|
| 1474 | * decimal point by default, can do 0-3 via precision
|
---|
| 1475 | * field. No rounding when calculating fraction.
|
---|
| 1476 | * - \%Rhci - SI variant of \%Rhcb, fraction is rounded.
|
---|
| 1477 | * - \%Rhub - Human readable number formatting, using
|
---|
| 1478 | * binary unit prefixes. Takes a 64-bit unsigned
|
---|
| 1479 | * integer as input. Does one decimal point by
|
---|
| 1480 | * default, can do 0-3 via precision field. No
|
---|
| 1481 | * rounding when calculating fraction.
|
---|
| 1482 | * - \%Rhui - SI variant of \%Rhub, fraction is rounded.
|
---|
| 1483 | *
|
---|
[33496] | 1484 | * - \%Rrc - Takes an integer iprt status code as argument. Will insert the
|
---|
| 1485 | * status code define corresponding to the iprt status code.
|
---|
| 1486 | * - \%Rrs - Takes an integer iprt status code as argument. Will insert the
|
---|
| 1487 | * short description of the specified status code.
|
---|
| 1488 | * - \%Rrf - Takes an integer iprt status code as argument. Will insert the
|
---|
| 1489 | * full description of the specified status code.
|
---|
| 1490 | * - \%Rra - Takes an integer iprt status code as argument. Will insert the
|
---|
| 1491 | * status code define + full description.
|
---|
| 1492 | * - \%Rwc - Takes a long Windows error code as argument. Will insert the status
|
---|
| 1493 | * code define corresponding to the Windows error code.
|
---|
| 1494 | * - \%Rwf - Takes a long Windows error code as argument. Will insert the
|
---|
| 1495 | * full description of the specified status code.
|
---|
| 1496 | * - \%Rwa - Takes a long Windows error code as argument. Will insert the
|
---|
| 1497 | * error code define + full description.
|
---|
| 1498 | *
|
---|
| 1499 | * - \%Rhrc - Takes a COM/XPCOM status code as argument. Will insert the status
|
---|
| 1500 | * code define corresponding to the Windows error code.
|
---|
| 1501 | * - \%Rhrf - Takes a COM/XPCOM status code as argument. Will insert the
|
---|
| 1502 | * full description of the specified status code.
|
---|
| 1503 | * - \%Rhra - Takes a COM/XPCOM error code as argument. Will insert the
|
---|
| 1504 | * error code define + full description.
|
---|
| 1505 | *
|
---|
| 1506 | * - \%Rfn - Pretty printing of a function or method. It drops the
|
---|
| 1507 | * return code and parameter list.
|
---|
| 1508 | * - \%Rbn - Prints the base name. For dropping the path in
|
---|
| 1509 | * order to save space when printing a path name.
|
---|
| 1510 | *
|
---|
[66732] | 1511 | * - \%lRbs - Same as \%ls except inlut is big endian UTF-16.
|
---|
| 1512 | *
|
---|
[33496] | 1513 | * On other platforms, \%Rw? simply prints the argument in a form of 0xXXXXXXXX.
|
---|
| 1514 | *
|
---|
| 1515 | *
|
---|
| 1516 | * Group 4, structure dumpers:
|
---|
| 1517 | * - \%RDtimespec - Takes a PCRTTIMESPEC.
|
---|
| 1518 | *
|
---|
| 1519 | *
|
---|
[73914] | 1520 | * Group 5, XML / HTML, JSON and URI escapers:
|
---|
[33496] | 1521 | * - \%RMas - Takes a string pointer (const char *) and outputs
|
---|
| 1522 | * it as an attribute value with the proper escaping.
|
---|
| 1523 | * This typically ends up in double quotes.
|
---|
| 1524 | *
|
---|
| 1525 | * - \%RMes - Takes a string pointer (const char *) and outputs
|
---|
| 1526 | * it as an element with the necessary escaping.
|
---|
| 1527 | *
|
---|
[73914] | 1528 | * - \%RMjs - Takes a string pointer (const char *) and outputs
|
---|
| 1529 | * it in quotes with proper JSON escaping.
|
---|
| 1530 | *
|
---|
[74708] | 1531 | * - \%RMpa - Takes a string pointer (const char *) and outputs
|
---|
| 1532 | * it percent-encoded (RFC-3986). All reserved characters
|
---|
| 1533 | * are encoded.
|
---|
| 1534 | *
|
---|
[73909] | 1535 | * - \%RMpf - Takes a string pointer (const char *) and outputs
|
---|
| 1536 | * it percent-encoded (RFC-3986), form style. This
|
---|
| 1537 | * means '+' is used to escape space (' ') and '%2B'
|
---|
| 1538 | * is used to escape '+'.
|
---|
[73801] | 1539 | *
|
---|
[73909] | 1540 | * - \%RMpp - Takes a string pointer (const char *) and outputs
|
---|
| 1541 | * it percent-encoded (RFC-3986), path style. This
|
---|
| 1542 | * means '/' will not be escaped.
|
---|
| 1543 | *
|
---|
| 1544 | * - \%RMpq - Takes a string pointer (const char *) and outputs
|
---|
| 1545 | * it percent-encoded (RFC-3986), query style. This
|
---|
| 1546 | * means '+' will not be escaped.
|
---|
| 1547 | *
|
---|
| 1548 | *
|
---|
[73914] | 1549 | * Group 6, CPU Architecture Register dumpers:
|
---|
[37964] | 1550 | * - \%RAx86[reg] - Takes a 64-bit register value if the register is
|
---|
| 1551 | * 64-bit or smaller. Check the code wrt which
|
---|
| 1552 | * registers are implemented.
|
---|
[33496] | 1553 | *
|
---|
| 1554 | */
|
---|
[31246] | 1555 |
|
---|
[1] | 1556 | #ifndef DECLARED_FNRTSTROUTPUT /* duplicated in iprt/log.h */
|
---|
[33496] | 1557 | # define DECLARED_FNRTSTROUTPUT
|
---|
[1] | 1558 | /**
|
---|
| 1559 | * Output callback.
|
---|
| 1560 | *
|
---|
| 1561 | * @returns number of bytes written.
|
---|
| 1562 | * @param pvArg User argument.
|
---|
| 1563 | * @param pachChars Pointer to an array of utf-8 characters.
|
---|
| 1564 | * @param cbChars Number of bytes in the character array pointed to by pachChars.
|
---|
| 1565 | */
|
---|
| 1566 | typedef DECLCALLBACK(size_t) FNRTSTROUTPUT(void *pvArg, const char *pachChars, size_t cbChars);
|
---|
| 1567 | /** Pointer to callback function. */
|
---|
| 1568 | typedef FNRTSTROUTPUT *PFNRTSTROUTPUT;
|
---|
| 1569 | #endif
|
---|
| 1570 |
|
---|
[57941] | 1571 | /** @name Format flag.
|
---|
[1] | 1572 | * These are used by RTStrFormat extensions and RTStrFormatNumber, mind
|
---|
| 1573 | * that not all flags makes sense to both of the functions.
|
---|
| 1574 | * @{ */
|
---|
[19942] | 1575 | #define RTSTR_F_CAPITAL 0x0001
|
---|
| 1576 | #define RTSTR_F_LEFT 0x0002
|
---|
| 1577 | #define RTSTR_F_ZEROPAD 0x0004
|
---|
| 1578 | #define RTSTR_F_SPECIAL 0x0008
|
---|
| 1579 | #define RTSTR_F_VALSIGNED 0x0010
|
---|
| 1580 | #define RTSTR_F_PLUS 0x0020
|
---|
| 1581 | #define RTSTR_F_BLANK 0x0040
|
---|
| 1582 | #define RTSTR_F_WIDTH 0x0080
|
---|
| 1583 | #define RTSTR_F_PRECISION 0x0100
|
---|
| 1584 | #define RTSTR_F_THOUSAND_SEP 0x0200
|
---|
[66284] | 1585 | #define RTSTR_F_OBFUSCATE_PTR 0x0400
|
---|
[1] | 1586 |
|
---|
[19942] | 1587 | #define RTSTR_F_BIT_MASK 0xf800
|
---|
| 1588 | #define RTSTR_F_8BIT 0x0800
|
---|
| 1589 | #define RTSTR_F_16BIT 0x1000
|
---|
| 1590 | #define RTSTR_F_32BIT 0x2000
|
---|
| 1591 | #define RTSTR_F_64BIT 0x4000
|
---|
| 1592 | #define RTSTR_F_128BIT 0x8000
|
---|
[1] | 1593 | /** @} */
|
---|
| 1594 |
|
---|
| 1595 | /** @def RTSTR_GET_BIT_FLAG
|
---|
| 1596 | * Gets the bit flag for the specified type.
|
---|
| 1597 | */
|
---|
| 1598 | #define RTSTR_GET_BIT_FLAG(type) \
|
---|
[31419] | 1599 | ( sizeof(type) * 8 == 32 ? RTSTR_F_32BIT \
|
---|
| 1600 | : sizeof(type) * 8 == 64 ? RTSTR_F_64BIT \
|
---|
| 1601 | : sizeof(type) * 8 == 16 ? RTSTR_F_16BIT \
|
---|
| 1602 | : sizeof(type) * 8 == 8 ? RTSTR_F_8BIT \
|
---|
| 1603 | : sizeof(type) * 8 == 128 ? RTSTR_F_128BIT \
|
---|
[1] | 1604 | : 0)
|
---|
| 1605 |
|
---|
| 1606 |
|
---|
| 1607 | /**
|
---|
| 1608 | * Callback to format non-standard format specifiers.
|
---|
| 1609 | *
|
---|
| 1610 | * @returns The number of bytes formatted.
|
---|
| 1611 | * @param pvArg Formatter argument.
|
---|
| 1612 | * @param pfnOutput Pointer to output function.
|
---|
| 1613 | * @param pvArgOutput Argument for the output function.
|
---|
| 1614 | * @param ppszFormat Pointer to the format string pointer. Advance this till the char
|
---|
| 1615 | * after the format specifier.
|
---|
| 1616 | * @param pArgs Pointer to the argument list. Use this to fetch the arguments.
|
---|
| 1617 | * @param cchWidth Format Width. -1 if not specified.
|
---|
| 1618 | * @param cchPrecision Format Precision. -1 if not specified.
|
---|
| 1619 | * @param fFlags Flags (RTSTR_NTFS_*).
|
---|
| 1620 | * @param chArgSize The argument size specifier, 'l' or 'L'.
|
---|
| 1621 | */
|
---|
[5666] | 1622 | typedef DECLCALLBACK(size_t) FNSTRFORMAT(void *pvArg, PFNRTSTROUTPUT pfnOutput, void *pvArgOutput,
|
---|
| 1623 | const char **ppszFormat, va_list *pArgs, int cchWidth,
|
---|
| 1624 | int cchPrecision, unsigned fFlags, char chArgSize);
|
---|
[1] | 1625 | /** Pointer to a FNSTRFORMAT() function. */
|
---|
| 1626 | typedef FNSTRFORMAT *PFNSTRFORMAT;
|
---|
| 1627 |
|
---|
| 1628 |
|
---|
| 1629 | /**
|
---|
| 1630 | * Partial implementation of a printf like formatter.
|
---|
| 1631 | * It doesn't do everything correct, and there is no floating point support.
|
---|
| 1632 | * However, it supports custom formats by the means of a format callback.
|
---|
| 1633 | *
|
---|
| 1634 | * @returns number of bytes formatted.
|
---|
| 1635 | * @param pfnOutput Output worker.
|
---|
| 1636 | * Called in two ways. Normally with a string and its length.
|
---|
| 1637 | * For termination, it's called with NULL for string, 0 for length.
|
---|
| 1638 | * @param pvArgOutput Argument to the output worker.
|
---|
| 1639 | * @param pfnFormat Custom format worker.
|
---|
| 1640 | * @param pvArgFormat Argument to the format worker.
|
---|
[33496] | 1641 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
[7170] | 1642 | * @param InArgs Argument list.
|
---|
[1] | 1643 | */
|
---|
[56919] | 1644 | RTDECL(size_t) RTStrFormatV(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat,
|
---|
| 1645 | const char *pszFormat, va_list InArgs) RT_IPRT_FORMAT_ATTR(5, 0);
|
---|
[1] | 1646 |
|
---|
| 1647 | /**
|
---|
| 1648 | * Partial implementation of a printf like formatter.
|
---|
[64340] | 1649 | *
|
---|
[1] | 1650 | * It doesn't do everything correct, and there is no floating point support.
|
---|
| 1651 | * However, it supports custom formats by the means of a format callback.
|
---|
| 1652 | *
|
---|
| 1653 | * @returns number of bytes formatted.
|
---|
| 1654 | * @param pfnOutput Output worker.
|
---|
| 1655 | * Called in two ways. Normally with a string and its length.
|
---|
| 1656 | * For termination, it's called with NULL for string, 0 for length.
|
---|
| 1657 | * @param pvArgOutput Argument to the output worker.
|
---|
| 1658 | * @param pfnFormat Custom format worker.
|
---|
| 1659 | * @param pvArgFormat Argument to the format worker.
|
---|
[33496] | 1660 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
[1] | 1661 | * @param ... Argument list.
|
---|
| 1662 | */
|
---|
[56919] | 1663 | RTDECL(size_t) RTStrFormat(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat,
|
---|
| 1664 | const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(5, 6);
|
---|
[1] | 1665 |
|
---|
| 1666 | /**
|
---|
| 1667 | * Formats an integer number according to the parameters.
|
---|
| 1668 | *
|
---|
| 1669 | * @returns Length of the formatted number.
|
---|
[35585] | 1670 | * @param psz Pointer to output string buffer of sufficient size.
|
---|
| 1671 | * @param u64Value Value to format.
|
---|
| 1672 | * @param uiBase Number representation base.
|
---|
| 1673 | * @param cchWidth Width.
|
---|
| 1674 | * @param cchPrecision Precision.
|
---|
| 1675 | * @param fFlags Flags, RTSTR_F_XXX.
|
---|
[1] | 1676 | */
|
---|
[56919] | 1677 | RTDECL(int) RTStrFormatNumber(char *psz, uint64_t u64Value, unsigned int uiBase, signed int cchWidth, signed int cchPrecision,
|
---|
| 1678 | unsigned int fFlags);
|
---|
[1] | 1679 |
|
---|
[35585] | 1680 | /**
|
---|
| 1681 | * Formats an unsigned 8-bit number.
|
---|
| 1682 | *
|
---|
| 1683 | * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
|
---|
| 1684 | * @param pszBuf The output buffer.
|
---|
| 1685 | * @param cbBuf The size of the output buffer.
|
---|
| 1686 | * @param u8Value The value to format.
|
---|
| 1687 | * @param uiBase Number representation base.
|
---|
| 1688 | * @param cchWidth Width.
|
---|
| 1689 | * @param cchPrecision Precision.
|
---|
| 1690 | * @param fFlags Flags, RTSTR_F_XXX.
|
---|
| 1691 | */
|
---|
| 1692 | RTDECL(ssize_t) RTStrFormatU8(char *pszBuf, size_t cbBuf, uint8_t u8Value, unsigned int uiBase,
|
---|
| 1693 | signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
|
---|
[7183] | 1694 |
|
---|
[1] | 1695 | /**
|
---|
[35585] | 1696 | * Formats an unsigned 16-bit number.
|
---|
| 1697 | *
|
---|
| 1698 | * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
|
---|
| 1699 | * @param pszBuf The output buffer.
|
---|
| 1700 | * @param cbBuf The size of the output buffer.
|
---|
| 1701 | * @param u16Value The value to format.
|
---|
| 1702 | * @param uiBase Number representation base.
|
---|
| 1703 | * @param cchWidth Width.
|
---|
| 1704 | * @param cchPrecision Precision.
|
---|
| 1705 | * @param fFlags Flags, RTSTR_F_XXX.
|
---|
| 1706 | */
|
---|
| 1707 | RTDECL(ssize_t) RTStrFormatU16(char *pszBuf, size_t cbBuf, uint16_t u16Value, unsigned int uiBase,
|
---|
| 1708 | signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
|
---|
| 1709 |
|
---|
| 1710 | /**
|
---|
| 1711 | * Formats an unsigned 32-bit number.
|
---|
| 1712 | *
|
---|
| 1713 | * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
|
---|
| 1714 | * @param pszBuf The output buffer.
|
---|
| 1715 | * @param cbBuf The size of the output buffer.
|
---|
| 1716 | * @param u32Value The value to format.
|
---|
| 1717 | * @param uiBase Number representation base.
|
---|
| 1718 | * @param cchWidth Width.
|
---|
| 1719 | * @param cchPrecision Precision.
|
---|
| 1720 | * @param fFlags Flags, RTSTR_F_XXX.
|
---|
| 1721 | */
|
---|
| 1722 | RTDECL(ssize_t) RTStrFormatU32(char *pszBuf, size_t cbBuf, uint32_t u32Value, unsigned int uiBase,
|
---|
| 1723 | signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
|
---|
| 1724 |
|
---|
| 1725 | /**
|
---|
| 1726 | * Formats an unsigned 64-bit number.
|
---|
| 1727 | *
|
---|
| 1728 | * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
|
---|
| 1729 | * @param pszBuf The output buffer.
|
---|
| 1730 | * @param cbBuf The size of the output buffer.
|
---|
| 1731 | * @param u64Value The value to format.
|
---|
| 1732 | * @param uiBase Number representation base.
|
---|
| 1733 | * @param cchWidth Width.
|
---|
| 1734 | * @param cchPrecision Precision.
|
---|
| 1735 | * @param fFlags Flags, RTSTR_F_XXX.
|
---|
| 1736 | */
|
---|
| 1737 | RTDECL(ssize_t) RTStrFormatU64(char *pszBuf, size_t cbBuf, uint64_t u64Value, unsigned int uiBase,
|
---|
| 1738 | signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
|
---|
| 1739 |
|
---|
| 1740 | /**
|
---|
| 1741 | * Formats an unsigned 128-bit number.
|
---|
| 1742 | *
|
---|
| 1743 | * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
|
---|
| 1744 | * @param pszBuf The output buffer.
|
---|
| 1745 | * @param cbBuf The size of the output buffer.
|
---|
| 1746 | * @param pu128Value The value to format.
|
---|
| 1747 | * @param uiBase Number representation base.
|
---|
| 1748 | * @param cchWidth Width.
|
---|
| 1749 | * @param cchPrecision Precision.
|
---|
| 1750 | * @param fFlags Flags, RTSTR_F_XXX.
|
---|
[66882] | 1751 | * @remarks The current implementation is limited to base 16 and doesn't do
|
---|
| 1752 | * width or precision and probably ignores few flags too.
|
---|
[35585] | 1753 | */
|
---|
| 1754 | RTDECL(ssize_t) RTStrFormatU128(char *pszBuf, size_t cbBuf, PCRTUINT128U pu128Value, unsigned int uiBase,
|
---|
| 1755 | signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
|
---|
| 1756 |
|
---|
| 1757 | /**
|
---|
[66882] | 1758 | * Formats an unsigned 256-bit number.
|
---|
| 1759 | *
|
---|
| 1760 | * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
|
---|
| 1761 | * @param pszBuf The output buffer.
|
---|
| 1762 | * @param cbBuf The size of the output buffer.
|
---|
| 1763 | * @param pu256Value The value to format.
|
---|
| 1764 | * @param uiBase Number representation base.
|
---|
| 1765 | * @param cchWidth Width.
|
---|
| 1766 | * @param cchPrecision Precision.
|
---|
| 1767 | * @param fFlags Flags, RTSTR_F_XXX.
|
---|
| 1768 | * @remarks The current implementation is limited to base 16 and doesn't do
|
---|
| 1769 | * width or precision and probably ignores few flags too.
|
---|
| 1770 | */
|
---|
| 1771 | RTDECL(ssize_t) RTStrFormatU256(char *pszBuf, size_t cbBuf, PCRTUINT256U pu256Value, unsigned int uiBase,
|
---|
| 1772 | signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
|
---|
| 1773 |
|
---|
| 1774 | /**
|
---|
| 1775 | * Formats an unsigned 512-bit number.
|
---|
| 1776 | *
|
---|
| 1777 | * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
|
---|
| 1778 | * @param pszBuf The output buffer.
|
---|
| 1779 | * @param cbBuf The size of the output buffer.
|
---|
| 1780 | * @param pu512Value The value to format.
|
---|
| 1781 | * @param uiBase Number representation base.
|
---|
| 1782 | * @param cchWidth Width.
|
---|
| 1783 | * @param cchPrecision Precision.
|
---|
| 1784 | * @param fFlags Flags, RTSTR_F_XXX.
|
---|
| 1785 | * @remarks The current implementation is limited to base 16 and doesn't do
|
---|
| 1786 | * width or precision and probably ignores few flags too.
|
---|
| 1787 | */
|
---|
| 1788 | RTDECL(ssize_t) RTStrFormatU512(char *pszBuf, size_t cbBuf, PCRTUINT512U pu512Value, unsigned int uiBase,
|
---|
| 1789 | signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
|
---|
| 1790 |
|
---|
| 1791 |
|
---|
| 1792 | /**
|
---|
[35585] | 1793 | * Formats an 80-bit extended floating point number.
|
---|
| 1794 | *
|
---|
| 1795 | * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
|
---|
| 1796 | * @param pszBuf The output buffer.
|
---|
| 1797 | * @param cbBuf The size of the output buffer.
|
---|
| 1798 | * @param pr80Value The value to format.
|
---|
| 1799 | * @param cchWidth Width.
|
---|
| 1800 | * @param cchPrecision Precision.
|
---|
| 1801 | * @param fFlags Flags, RTSTR_F_XXX.
|
---|
| 1802 | */
|
---|
| 1803 | RTDECL(ssize_t) RTStrFormatR80(char *pszBuf, size_t cbBuf, PCRTFLOAT80U pr80Value, signed int cchWidth,
|
---|
| 1804 | signed int cchPrecision, uint32_t fFlags);
|
---|
| 1805 |
|
---|
| 1806 | /**
|
---|
| 1807 | * Formats an 80-bit extended floating point number, version 2.
|
---|
| 1808 | *
|
---|
| 1809 | * @returns The length of the formatted number or VERR_BUFFER_OVERFLOW.
|
---|
| 1810 | * @param pszBuf The output buffer.
|
---|
| 1811 | * @param cbBuf The size of the output buffer.
|
---|
| 1812 | * @param pr80Value The value to format.
|
---|
| 1813 | * @param cchWidth Width.
|
---|
| 1814 | * @param cchPrecision Precision.
|
---|
| 1815 | * @param fFlags Flags, RTSTR_F_XXX.
|
---|
| 1816 | */
|
---|
| 1817 | RTDECL(ssize_t) RTStrFormatR80u2(char *pszBuf, size_t cbBuf, PCRTFLOAT80U2 pr80Value, signed int cchWidth,
|
---|
| 1818 | signed int cchPrecision, uint32_t fFlags);
|
---|
| 1819 |
|
---|
| 1820 |
|
---|
| 1821 |
|
---|
| 1822 | /**
|
---|
[7183] | 1823 | * Callback for formatting a type.
|
---|
| 1824 | *
|
---|
| 1825 | * This is registered using the RTStrFormatTypeRegister function and will
|
---|
| 1826 | * be called during string formatting to handle the specified %R[type].
|
---|
| 1827 | * The argument for this format type is assumed to be a pointer and it's
|
---|
| 1828 | * passed in the @a pvValue argument.
|
---|
| 1829 | *
|
---|
| 1830 | * @returns Length of the formatted output.
|
---|
| 1831 | * @param pfnOutput Output worker.
|
---|
| 1832 | * @param pvArgOutput Argument to the output worker.
|
---|
| 1833 | * @param pszType The type name.
|
---|
| 1834 | * @param pvValue The argument value.
|
---|
| 1835 | * @param cchWidth Width.
|
---|
| 1836 | * @param cchPrecision Precision.
|
---|
| 1837 | * @param fFlags Flags (NTFS_*).
|
---|
| 1838 | * @param pvUser The user argument.
|
---|
| 1839 | */
|
---|
| 1840 | typedef DECLCALLBACK(size_t) FNRTSTRFORMATTYPE(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput,
|
---|
| 1841 | const char *pszType, void const *pvValue,
|
---|
| 1842 | int cchWidth, int cchPrecision, unsigned fFlags,
|
---|
| 1843 | void *pvUser);
|
---|
| 1844 | /** Pointer to a FNRTSTRFORMATTYPE. */
|
---|
| 1845 | typedef FNRTSTRFORMATTYPE *PFNRTSTRFORMATTYPE;
|
---|
| 1846 |
|
---|
| 1847 |
|
---|
| 1848 | /**
|
---|
| 1849 | * Register a format handler for a type.
|
---|
| 1850 | *
|
---|
| 1851 | * The format handler is used to handle '%R[type]' format types, where the argument
|
---|
| 1852 | * in the vector is a pointer value (a bit restrictive, but keeps it simple).
|
---|
| 1853 | *
|
---|
| 1854 | * The caller must ensure that no other thread will be making use of any of
|
---|
| 1855 | * the dynamic formatting type facilities simultaneously with this call.
|
---|
| 1856 | *
|
---|
| 1857 | * @returns IPRT status code.
|
---|
| 1858 | * @retval VINF_SUCCESS on success.
|
---|
| 1859 | * @retval VERR_ALREADY_EXISTS if the type has already been registered.
|
---|
| 1860 | * @retval VERR_TOO_MANY_OPEN_FILES if all the type slots has been allocated already.
|
---|
| 1861 | *
|
---|
| 1862 | * @param pszType The type name.
|
---|
| 1863 | * @param pfnHandler The handler address. See FNRTSTRFORMATTYPE for details.
|
---|
| 1864 | * @param pvUser The user argument to pass to the handler. See RTStrFormatTypeSetUser
|
---|
| 1865 | * for how to update this later.
|
---|
| 1866 | */
|
---|
| 1867 | RTDECL(int) RTStrFormatTypeRegister(const char *pszType, PFNRTSTRFORMATTYPE pfnHandler, void *pvUser);
|
---|
| 1868 |
|
---|
| 1869 | /**
|
---|
| 1870 | * Deregisters a format type.
|
---|
| 1871 | *
|
---|
| 1872 | * The caller must ensure that no other thread will be making use of any of
|
---|
| 1873 | * the dynamic formatting type facilities simultaneously with this call.
|
---|
| 1874 | *
|
---|
| 1875 | * @returns IPRT status code.
|
---|
| 1876 | * @retval VINF_SUCCESS on success.
|
---|
| 1877 | * @retval VERR_FILE_NOT_FOUND if not found.
|
---|
| 1878 | *
|
---|
| 1879 | * @param pszType The type to deregister.
|
---|
| 1880 | */
|
---|
| 1881 | RTDECL(int) RTStrFormatTypeDeregister(const char *pszType);
|
---|
| 1882 |
|
---|
| 1883 | /**
|
---|
| 1884 | * Sets the user argument for a type.
|
---|
| 1885 | *
|
---|
| 1886 | * This can be used if a user argument needs relocating in GC.
|
---|
| 1887 | *
|
---|
| 1888 | * @returns IPRT status code.
|
---|
| 1889 | * @retval VINF_SUCCESS on success.
|
---|
| 1890 | * @retval VERR_FILE_NOT_FOUND if not found.
|
---|
| 1891 | *
|
---|
| 1892 | * @param pszType The type to update.
|
---|
| 1893 | * @param pvUser The new user argument value.
|
---|
| 1894 | */
|
---|
| 1895 | RTDECL(int) RTStrFormatTypeSetUser(const char *pszType, void *pvUser);
|
---|
| 1896 |
|
---|
| 1897 |
|
---|
| 1898 | /**
|
---|
[1] | 1899 | * String printf.
|
---|
| 1900 | *
|
---|
[31950] | 1901 | * @returns The length of the returned string (in pszBuffer) excluding the
|
---|
| 1902 | * terminator.
|
---|
[1] | 1903 | * @param pszBuffer Output buffer.
|
---|
| 1904 | * @param cchBuffer Size of the output buffer.
|
---|
[33496] | 1905 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
[1] | 1906 | * @param args The format argument.
|
---|
[64340] | 1907 | *
|
---|
| 1908 | * @deprecated Use RTStrPrintf2V! Problematic return value on overflow.
|
---|
[1] | 1909 | */
|
---|
[57004] | 1910 | RTDECL(size_t) RTStrPrintfV(char *pszBuffer, size_t cchBuffer, const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
|
---|
[1] | 1911 |
|
---|
| 1912 | /**
|
---|
| 1913 | * String printf.
|
---|
| 1914 | *
|
---|
[31950] | 1915 | * @returns The length of the returned string (in pszBuffer) excluding the
|
---|
| 1916 | * terminator.
|
---|
[1] | 1917 | * @param pszBuffer Output buffer.
|
---|
| 1918 | * @param cchBuffer Size of the output buffer.
|
---|
[33496] | 1919 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
[1] | 1920 | * @param ... The format argument.
|
---|
[64340] | 1921 | *
|
---|
| 1922 | * @deprecated Use RTStrPrintf2! Problematic return value on overflow.
|
---|
[1] | 1923 | */
|
---|
[56919] | 1924 | RTDECL(size_t) RTStrPrintf(char *pszBuffer, size_t cchBuffer, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
|
---|
[1] | 1925 |
|
---|
| 1926 | /**
|
---|
| 1927 | * String printf with custom formatting.
|
---|
| 1928 | *
|
---|
[31950] | 1929 | * @returns The length of the returned string (in pszBuffer) excluding the
|
---|
| 1930 | * terminator.
|
---|
[1] | 1931 | * @param pfnFormat Pointer to handler function for the custom formats.
|
---|
| 1932 | * @param pvArg Argument to the pfnFormat function.
|
---|
| 1933 | * @param pszBuffer Output buffer.
|
---|
| 1934 | * @param cchBuffer Size of the output buffer.
|
---|
[33496] | 1935 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
[1] | 1936 | * @param args The format argument.
|
---|
[64340] | 1937 | *
|
---|
| 1938 | * @deprecated Use RTStrPrintf2ExV! Problematic return value on overflow.
|
---|
[1] | 1939 | */
|
---|
[56919] | 1940 | RTDECL(size_t) RTStrPrintfExV(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cchBuffer,
|
---|
| 1941 | const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(5, 0);
|
---|
[1] | 1942 |
|
---|
| 1943 | /**
|
---|
| 1944 | * String printf with custom formatting.
|
---|
| 1945 | *
|
---|
[31950] | 1946 | * @returns The length of the returned string (in pszBuffer) excluding the
|
---|
| 1947 | * terminator.
|
---|
[1] | 1948 | * @param pfnFormat Pointer to handler function for the custom formats.
|
---|
| 1949 | * @param pvArg Argument to the pfnFormat function.
|
---|
| 1950 | * @param pszBuffer Output buffer.
|
---|
| 1951 | * @param cchBuffer Size of the output buffer.
|
---|
[33496] | 1952 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
[1] | 1953 | * @param ... The format argument.
|
---|
[64340] | 1954 | *
|
---|
| 1955 | * @deprecated Use RTStrPrintf2Ex! Problematic return value on overflow.
|
---|
[1] | 1956 | */
|
---|
[56919] | 1957 | RTDECL(size_t) RTStrPrintfEx(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cchBuffer,
|
---|
| 1958 | const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(5, 6);
|
---|
[1] | 1959 |
|
---|
[64340] | 1960 | /**
|
---|
| 1961 | * String printf, version 2.
|
---|
| 1962 | *
|
---|
| 1963 | * @returns On success, positive count of formatted character excluding the
|
---|
| 1964 | * terminator. On buffer overflow, negative number giving the required
|
---|
| 1965 | * buffer size (including terminator char).
|
---|
| 1966 | *
|
---|
| 1967 | * @param pszBuffer Output buffer.
|
---|
| 1968 | * @param cbBuffer Size of the output buffer.
|
---|
| 1969 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
| 1970 | * @param args The format argument.
|
---|
| 1971 | */
|
---|
| 1972 | RTDECL(ssize_t) RTStrPrintf2V(char *pszBuffer, size_t cbBuffer, const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
|
---|
[1] | 1973 |
|
---|
| 1974 | /**
|
---|
[64340] | 1975 | * String printf, version 2.
|
---|
| 1976 | *
|
---|
| 1977 | * @returns On success, positive count of formatted character excluding the
|
---|
| 1978 | * terminator. On buffer overflow, negative number giving the required
|
---|
| 1979 | * buffer size (including terminator char).
|
---|
| 1980 | *
|
---|
| 1981 | * @param pszBuffer Output buffer.
|
---|
| 1982 | * @param cbBuffer Size of the output buffer.
|
---|
| 1983 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
| 1984 | * @param ... The format argument.
|
---|
| 1985 | */
|
---|
| 1986 | RTDECL(ssize_t) RTStrPrintf2(char *pszBuffer, size_t cbBuffer, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
|
---|
| 1987 |
|
---|
| 1988 | /**
|
---|
| 1989 | * String printf with custom formatting, version 2.
|
---|
| 1990 | *
|
---|
| 1991 | * @returns On success, positive count of formatted character excluding the
|
---|
| 1992 | * terminator. On buffer overflow, negative number giving the required
|
---|
| 1993 | * buffer size (including terminator char).
|
---|
| 1994 | *
|
---|
| 1995 | * @param pfnFormat Pointer to handler function for the custom formats.
|
---|
| 1996 | * @param pvArg Argument to the pfnFormat function.
|
---|
| 1997 | * @param pszBuffer Output buffer.
|
---|
| 1998 | * @param cbBuffer Size of the output buffer.
|
---|
| 1999 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
| 2000 | * @param args The format argument.
|
---|
| 2001 | */
|
---|
| 2002 | RTDECL(ssize_t) RTStrPrintf2ExV(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cbBuffer,
|
---|
| 2003 | const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(5, 0);
|
---|
| 2004 |
|
---|
| 2005 | /**
|
---|
| 2006 | * String printf with custom formatting, version 2.
|
---|
| 2007 | *
|
---|
| 2008 | * @returns On success, positive count of formatted character excluding the
|
---|
| 2009 | * terminator. On buffer overflow, negative number giving the required
|
---|
| 2010 | * buffer size (including terminator char).
|
---|
| 2011 | *
|
---|
| 2012 | * @param pfnFormat Pointer to handler function for the custom formats.
|
---|
| 2013 | * @param pvArg Argument to the pfnFormat function.
|
---|
| 2014 | * @param pszBuffer Output buffer.
|
---|
| 2015 | * @param cbBuffer Size of the output buffer.
|
---|
| 2016 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
| 2017 | * @param ... The format argument.
|
---|
| 2018 | */
|
---|
| 2019 | RTDECL(ssize_t) RTStrPrintf2Ex(PFNSTRFORMAT pfnFormat, void *pvArg, char *pszBuffer, size_t cbBuffer,
|
---|
| 2020 | const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(5, 6);
|
---|
| 2021 |
|
---|
| 2022 | /**
|
---|
[31157] | 2023 | * Allocating string printf (default tag).
|
---|
[1] | 2024 | *
|
---|
[31950] | 2025 | * @returns The length of the string in the returned *ppszBuffer excluding the
|
---|
| 2026 | * terminator.
|
---|
[1] | 2027 | * @returns -1 on failure.
|
---|
| 2028 | * @param ppszBuffer Where to store the pointer to the allocated output buffer.
|
---|
| 2029 | * The buffer should be freed using RTStrFree().
|
---|
| 2030 | * On failure *ppszBuffer will be set to NULL.
|
---|
[33496] | 2031 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
[1] | 2032 | * @param args The format argument.
|
---|
| 2033 | */
|
---|
[31157] | 2034 | #define RTStrAPrintfV(ppszBuffer, pszFormat, args) RTStrAPrintfVTag((ppszBuffer), (pszFormat), (args), RTSTR_TAG)
|
---|
[1] | 2035 |
|
---|
| 2036 | /**
|
---|
[31157] | 2037 | * Allocating string printf (custom tag).
|
---|
| 2038 | *
|
---|
[31950] | 2039 | * @returns The length of the string in the returned *ppszBuffer excluding the
|
---|
| 2040 | * terminator.
|
---|
[31157] | 2041 | * @returns -1 on failure.
|
---|
| 2042 | * @param ppszBuffer Where to store the pointer to the allocated output buffer.
|
---|
| 2043 | * The buffer should be freed using RTStrFree().
|
---|
| 2044 | * On failure *ppszBuffer will be set to NULL.
|
---|
[33496] | 2045 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
[31157] | 2046 | * @param args The format argument.
|
---|
| 2047 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 2048 | */
|
---|
[56919] | 2049 | RTDECL(int) RTStrAPrintfVTag(char **ppszBuffer, const char *pszFormat, va_list args, const char *pszTag) RT_IPRT_FORMAT_ATTR(2, 0);
|
---|
[31157] | 2050 |
|
---|
| 2051 | /**
|
---|
[1] | 2052 | * Allocating string printf.
|
---|
| 2053 | *
|
---|
[31950] | 2054 | * @returns The length of the string in the returned *ppszBuffer excluding the
|
---|
| 2055 | * terminator.
|
---|
[1] | 2056 | * @returns -1 on failure.
|
---|
| 2057 | * @param ppszBuffer Where to store the pointer to the allocated output buffer.
|
---|
| 2058 | * The buffer should be freed using RTStrFree().
|
---|
| 2059 | * On failure *ppszBuffer will be set to NULL.
|
---|
[33496] | 2060 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
[1] | 2061 | * @param ... The format argument.
|
---|
| 2062 | */
|
---|
[57004] | 2063 | DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 3) RTStrAPrintf(char **ppszBuffer, const char *pszFormat, ...)
|
---|
[31157] | 2064 | {
|
---|
| 2065 | int cbRet;
|
---|
| 2066 | va_list va;
|
---|
| 2067 | va_start(va, pszFormat);
|
---|
| 2068 | cbRet = RTStrAPrintfVTag(ppszBuffer, pszFormat, va, RTSTR_TAG);
|
---|
| 2069 | va_end(va);
|
---|
| 2070 | return cbRet;
|
---|
| 2071 | }
|
---|
[1] | 2072 |
|
---|
[24427] | 2073 | /**
|
---|
[31157] | 2074 | * Allocating string printf (custom tag).
|
---|
| 2075 | *
|
---|
[31950] | 2076 | * @returns The length of the string in the returned *ppszBuffer excluding the
|
---|
| 2077 | * terminator.
|
---|
[31157] | 2078 | * @returns -1 on failure.
|
---|
| 2079 | * @param ppszBuffer Where to store the pointer to the allocated output buffer.
|
---|
| 2080 | * The buffer should be freed using RTStrFree().
|
---|
| 2081 | * On failure *ppszBuffer will be set to NULL.
|
---|
| 2082 | * @param pszTag Allocation tag used for statistics and such.
|
---|
[33496] | 2083 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
[31157] | 2084 | * @param ... The format argument.
|
---|
| 2085 | */
|
---|
[57004] | 2086 | DECLINLINE(int) RT_IPRT_FORMAT_ATTR(3, 4) RTStrAPrintfTag(char **ppszBuffer, const char *pszTag, const char *pszFormat, ...)
|
---|
[31157] | 2087 | {
|
---|
| 2088 | int cbRet;
|
---|
| 2089 | va_list va;
|
---|
| 2090 | va_start(va, pszFormat);
|
---|
| 2091 | cbRet = RTStrAPrintfVTag(ppszBuffer, pszFormat, va, pszTag);
|
---|
| 2092 | va_end(va);
|
---|
| 2093 | return cbRet;
|
---|
| 2094 | }
|
---|
| 2095 |
|
---|
| 2096 | /**
|
---|
[24427] | 2097 | * Allocating string printf, version 2.
|
---|
| 2098 | *
|
---|
| 2099 | * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
|
---|
| 2100 | * memory.
|
---|
[33496] | 2101 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
[24427] | 2102 | * @param args The format argument.
|
---|
| 2103 | */
|
---|
[31157] | 2104 | #define RTStrAPrintf2V(pszFormat, args) RTStrAPrintf2VTag((pszFormat), (args), RTSTR_TAG)
|
---|
[1] | 2105 |
|
---|
| 2106 | /**
|
---|
[31157] | 2107 | * Allocating string printf, version 2.
|
---|
[24427] | 2108 | *
|
---|
| 2109 | * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
|
---|
| 2110 | * memory.
|
---|
[33496] | 2111 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
[31157] | 2112 | * @param args The format argument.
|
---|
| 2113 | * @param pszTag Allocation tag used for statistics and such.
|
---|
| 2114 | */
|
---|
[56919] | 2115 | RTDECL(char *) RTStrAPrintf2VTag(const char *pszFormat, va_list args, const char *pszTag) RT_IPRT_FORMAT_ATTR(1, 0);
|
---|
[31157] | 2116 |
|
---|
| 2117 | /**
|
---|
| 2118 | * Allocating string printf, version 2 (default tag).
|
---|
| 2119 | *
|
---|
| 2120 | * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
|
---|
| 2121 | * memory.
|
---|
[33496] | 2122 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
[24427] | 2123 | * @param ... The format argument.
|
---|
| 2124 | */
|
---|
[57004] | 2125 | DECLINLINE(char *) RT_IPRT_FORMAT_ATTR(1, 2) RTStrAPrintf2(const char *pszFormat, ...)
|
---|
[31157] | 2126 | {
|
---|
| 2127 | char *pszRet;
|
---|
| 2128 | va_list va;
|
---|
| 2129 | va_start(va, pszFormat);
|
---|
| 2130 | pszRet = RTStrAPrintf2VTag(pszFormat, va, RTSTR_TAG);
|
---|
| 2131 | va_end(va);
|
---|
| 2132 | return pszRet;
|
---|
| 2133 | }
|
---|
[24427] | 2134 |
|
---|
| 2135 | /**
|
---|
[31157] | 2136 | * Allocating string printf, version 2 (custom tag).
|
---|
| 2137 | *
|
---|
| 2138 | * @returns Formatted string. Use RTStrFree() to free it. NULL when out of
|
---|
| 2139 | * memory.
|
---|
| 2140 | * @param pszTag Allocation tag used for statistics and such.
|
---|
[33496] | 2141 | * @param pszFormat Pointer to the format string, @see pg_rt_str_format.
|
---|
[31157] | 2142 | * @param ... The format argument.
|
---|
| 2143 | */
|
---|
[57004] | 2144 | DECLINLINE(char *) RT_IPRT_FORMAT_ATTR(2, 3) RTStrAPrintf2Tag(const char *pszTag, const char *pszFormat, ...)
|
---|
[31157] | 2145 | {
|
---|
| 2146 | char *pszRet;
|
---|
| 2147 | va_list va;
|
---|
| 2148 | va_start(va, pszFormat);
|
---|
| 2149 | pszRet = RTStrAPrintf2VTag(pszFormat, va, pszTag);
|
---|
| 2150 | va_end(va);
|
---|
| 2151 | return pszRet;
|
---|
| 2152 | }
|
---|
| 2153 |
|
---|
| 2154 | /**
|
---|
[1] | 2155 | * Strips blankspaces from both ends of the string.
|
---|
| 2156 | *
|
---|
| 2157 | * @returns Pointer to first non-blank char in the string.
|
---|
| 2158 | * @param psz The string to strip.
|
---|
| 2159 | */
|
---|
| 2160 | RTDECL(char *) RTStrStrip(char *psz);
|
---|
| 2161 |
|
---|
| 2162 | /**
|
---|
| 2163 | * Strips blankspaces from the start of the string.
|
---|
| 2164 | *
|
---|
| 2165 | * @returns Pointer to first non-blank char in the string.
|
---|
| 2166 | * @param psz The string to strip.
|
---|
| 2167 | */
|
---|
| 2168 | RTDECL(char *) RTStrStripL(const char *psz);
|
---|
| 2169 |
|
---|
| 2170 | /**
|
---|
| 2171 | * Strips blankspaces from the end of the string.
|
---|
| 2172 | *
|
---|
| 2173 | * @returns psz.
|
---|
| 2174 | * @param psz The string to strip.
|
---|
| 2175 | */
|
---|
| 2176 | RTDECL(char *) RTStrStripR(char *psz);
|
---|
| 2177 |
|
---|
[13472] | 2178 | /**
|
---|
[26659] | 2179 | * String copy with overflow handling.
|
---|
| 2180 | *
|
---|
| 2181 | * @retval VINF_SUCCESS on success.
|
---|
| 2182 | * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
|
---|
| 2183 | * buffer will contain as much of the string as it can hold, fully
|
---|
| 2184 | * terminated.
|
---|
| 2185 | *
|
---|
| 2186 | * @param pszDst The destination buffer.
|
---|
| 2187 | * @param cbDst The size of the destination buffer (in bytes).
|
---|
| 2188 | * @param pszSrc The source string. NULL is not OK.
|
---|
| 2189 | */
|
---|
| 2190 | RTDECL(int) RTStrCopy(char *pszDst, size_t cbDst, const char *pszSrc);
|
---|
| 2191 |
|
---|
| 2192 | /**
|
---|
| 2193 | * String copy with overflow handling.
|
---|
| 2194 | *
|
---|
| 2195 | * @retval VINF_SUCCESS on success.
|
---|
| 2196 | * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
|
---|
| 2197 | * buffer will contain as much of the string as it can hold, fully
|
---|
| 2198 | * terminated.
|
---|
| 2199 | *
|
---|
| 2200 | * @param pszDst The destination buffer.
|
---|
| 2201 | * @param cbDst The size of the destination buffer (in bytes).
|
---|
| 2202 | * @param pszSrc The source string. NULL is not OK.
|
---|
| 2203 | * @param cchSrcMax The maximum number of chars (not code points) to
|
---|
| 2204 | * copy from the source string, not counting the
|
---|
| 2205 | * terminator as usual.
|
---|
| 2206 | */
|
---|
| 2207 | RTDECL(int) RTStrCopyEx(char *pszDst, size_t cbDst, const char *pszSrc, size_t cchSrcMax);
|
---|
| 2208 |
|
---|
| 2209 | /**
|
---|
[36407] | 2210 | * String copy with overflow handling and buffer advancing.
|
---|
| 2211 | *
|
---|
| 2212 | * @retval VINF_SUCCESS on success.
|
---|
| 2213 | * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
|
---|
| 2214 | * buffer will contain as much of the string as it can hold, fully
|
---|
| 2215 | * terminated.
|
---|
| 2216 | *
|
---|
| 2217 | * @param ppszDst Pointer to the destination buffer pointer.
|
---|
| 2218 | * This will be advanced to the end of the copied
|
---|
| 2219 | * bytes (points at the terminator). This is also
|
---|
| 2220 | * updated on overflow.
|
---|
| 2221 | * @param pcbDst Pointer to the destination buffer size
|
---|
| 2222 | * variable. This will be updated in accord with
|
---|
| 2223 | * the buffer pointer.
|
---|
| 2224 | * @param pszSrc The source string. NULL is not OK.
|
---|
| 2225 | */
|
---|
| 2226 | RTDECL(int) RTStrCopyP(char **ppszDst, size_t *pcbDst, const char *pszSrc);
|
---|
| 2227 |
|
---|
| 2228 | /**
|
---|
| 2229 | * String copy with overflow handling.
|
---|
| 2230 | *
|
---|
| 2231 | * @retval VINF_SUCCESS on success.
|
---|
| 2232 | * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
|
---|
| 2233 | * buffer will contain as much of the string as it can hold, fully
|
---|
| 2234 | * terminated.
|
---|
| 2235 | *
|
---|
| 2236 | * @param ppszDst Pointer to the destination buffer pointer.
|
---|
| 2237 | * This will be advanced to the end of the copied
|
---|
| 2238 | * bytes (points at the terminator). This is also
|
---|
| 2239 | * updated on overflow.
|
---|
| 2240 | * @param pcbDst Pointer to the destination buffer size
|
---|
| 2241 | * variable. This will be updated in accord with
|
---|
| 2242 | * the buffer pointer.
|
---|
| 2243 | * @param pszSrc The source string. NULL is not OK.
|
---|
| 2244 | * @param cchSrcMax The maximum number of chars (not code points) to
|
---|
| 2245 | * copy from the source string, not counting the
|
---|
| 2246 | * terminator as usual.
|
---|
| 2247 | */
|
---|
| 2248 | RTDECL(int) RTStrCopyPEx(char **ppszDst, size_t *pcbDst, const char *pszSrc, size_t cchSrcMax);
|
---|
| 2249 |
|
---|
| 2250 | /**
|
---|
[33678] | 2251 | * String concatenation with overflow handling.
|
---|
| 2252 | *
|
---|
| 2253 | * @retval VINF_SUCCESS on success.
|
---|
| 2254 | * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
|
---|
| 2255 | * buffer will contain as much of the string as it can hold, fully
|
---|
| 2256 | * terminated.
|
---|
| 2257 | *
|
---|
| 2258 | * @param pszDst The destination buffer.
|
---|
| 2259 | * @param cbDst The size of the destination buffer (in bytes).
|
---|
| 2260 | * @param pszSrc The source string. NULL is not OK.
|
---|
| 2261 | */
|
---|
| 2262 | RTDECL(int) RTStrCat(char *pszDst, size_t cbDst, const char *pszSrc);
|
---|
| 2263 |
|
---|
| 2264 | /**
|
---|
| 2265 | * String concatenation with overflow handling.
|
---|
| 2266 | *
|
---|
| 2267 | * @retval VINF_SUCCESS on success.
|
---|
| 2268 | * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
|
---|
| 2269 | * buffer will contain as much of the string as it can hold, fully
|
---|
| 2270 | * terminated.
|
---|
| 2271 | *
|
---|
| 2272 | * @param pszDst The destination buffer.
|
---|
| 2273 | * @param cbDst The size of the destination buffer (in bytes).
|
---|
| 2274 | * @param pszSrc The source string. NULL is not OK.
|
---|
| 2275 | * @param cchSrcMax The maximum number of chars (not code points) to
|
---|
| 2276 | * copy from the source string, not counting the
|
---|
| 2277 | * terminator as usual.
|
---|
| 2278 | */
|
---|
| 2279 | RTDECL(int) RTStrCatEx(char *pszDst, size_t cbDst, const char *pszSrc, size_t cchSrcMax);
|
---|
| 2280 |
|
---|
| 2281 | /**
|
---|
[36407] | 2282 | * String concatenation with overflow handling.
|
---|
| 2283 | *
|
---|
| 2284 | * @retval VINF_SUCCESS on success.
|
---|
| 2285 | * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
|
---|
| 2286 | * buffer will contain as much of the string as it can hold, fully
|
---|
| 2287 | * terminated.
|
---|
| 2288 | *
|
---|
| 2289 | * @param ppszDst Pointer to the destination buffer pointer.
|
---|
| 2290 | * This will be advanced to the end of the copied
|
---|
| 2291 | * bytes (points at the terminator). This is also
|
---|
| 2292 | * updated on overflow.
|
---|
| 2293 | * @param pcbDst Pointer to the destination buffer size
|
---|
| 2294 | * variable. This will be updated in accord with
|
---|
| 2295 | * the buffer pointer.
|
---|
| 2296 | * @param pszSrc The source string. NULL is not OK.
|
---|
| 2297 | */
|
---|
| 2298 | RTDECL(int) RTStrCatP(char **ppszDst, size_t *pcbDst, const char *pszSrc);
|
---|
| 2299 |
|
---|
| 2300 | /**
|
---|
| 2301 | * String concatenation with overflow handling and buffer advancing.
|
---|
| 2302 | *
|
---|
| 2303 | * @retval VINF_SUCCESS on success.
|
---|
| 2304 | * @retval VERR_BUFFER_OVERFLOW if the destination buffer is too small. The
|
---|
| 2305 | * buffer will contain as much of the string as it can hold, fully
|
---|
| 2306 | * terminated.
|
---|
| 2307 | *
|
---|
| 2308 | * @param ppszDst Pointer to the destination buffer pointer.
|
---|
| 2309 | * This will be advanced to the end of the copied
|
---|
| 2310 | * bytes (points at the terminator). This is also
|
---|
| 2311 | * updated on overflow.
|
---|
| 2312 | * @param pcbDst Pointer to the destination buffer size
|
---|
| 2313 | * variable. This will be updated in accord with
|
---|
| 2314 | * the buffer pointer.
|
---|
| 2315 | * @param pszSrc The source string. NULL is not OK.
|
---|
| 2316 | * @param cchSrcMax The maximum number of chars (not code points) to
|
---|
| 2317 | * copy from the source string, not counting the
|
---|
| 2318 | * terminator as usual.
|
---|
| 2319 | */
|
---|
| 2320 | RTDECL(int) RTStrCatPEx(char **ppszDst, size_t *pcbDst, const char *pszSrc, size_t cchSrcMax);
|
---|
| 2321 |
|
---|
| 2322 | /**
|
---|
[13472] | 2323 | * Performs a case sensitive string compare between two UTF-8 strings.
|
---|
| 2324 | *
|
---|
| 2325 | * Encoding errors are ignored by the current implementation. So, the only
|
---|
| 2326 | * difference between this and the CRT strcmp function is the handling of
|
---|
| 2327 | * NULL arguments.
|
---|
| 2328 | *
|
---|
| 2329 | * @returns < 0 if the first string less than the second string.
|
---|
| 2330 | * @returns 0 if the first string identical to the second string.
|
---|
| 2331 | * @returns > 0 if the first string greater than the second string.
|
---|
| 2332 | * @param psz1 First UTF-8 string. Null is allowed.
|
---|
| 2333 | * @param psz2 Second UTF-8 string. Null is allowed.
|
---|
| 2334 | */
|
---|
| 2335 | RTDECL(int) RTStrCmp(const char *psz1, const char *psz2);
|
---|
[1] | 2336 |
|
---|
[13472] | 2337 | /**
|
---|
[13927] | 2338 | * Performs a case sensitive string compare between two UTF-8 strings, given
|
---|
| 2339 | * a maximum string length.
|
---|
| 2340 | *
|
---|
| 2341 | * Encoding errors are ignored by the current implementation. So, the only
|
---|
| 2342 | * difference between this and the CRT strncmp function is the handling of
|
---|
| 2343 | * NULL arguments.
|
---|
| 2344 | *
|
---|
| 2345 | * @returns < 0 if the first string less than the second string.
|
---|
| 2346 | * @returns 0 if the first string identical to the second string.
|
---|
| 2347 | * @returns > 0 if the first string greater than the second string.
|
---|
| 2348 | * @param psz1 First UTF-8 string. Null is allowed.
|
---|
| 2349 | * @param psz2 Second UTF-8 string. Null is allowed.
|
---|
| 2350 | * @param cchMax The maximum string length
|
---|
| 2351 | */
|
---|
| 2352 | RTDECL(int) RTStrNCmp(const char *psz1, const char *psz2, size_t cchMax);
|
---|
| 2353 |
|
---|
| 2354 | /**
|
---|
[13472] | 2355 | * Performs a case insensitive string compare between two UTF-8 strings.
|
---|
| 2356 | *
|
---|
| 2357 | * This is a simplified compare, as only the simplified lower/upper case folding
|
---|
| 2358 | * specified by the unicode specs are used. It does not consider character pairs
|
---|
| 2359 | * as they are used in some languages, just simple upper & lower case compares.
|
---|
| 2360 | *
|
---|
| 2361 | * The result is the difference between the mismatching codepoints after they
|
---|
| 2362 | * both have been lower cased.
|
---|
| 2363 | *
|
---|
| 2364 | * If the string encoding is invalid the function will assert (strict builds)
|
---|
| 2365 | * and use RTStrCmp for the remainder of the string.
|
---|
| 2366 | *
|
---|
| 2367 | * @returns < 0 if the first string less than the second string.
|
---|
| 2368 | * @returns 0 if the first string identical to the second string.
|
---|
| 2369 | * @returns > 0 if the first string greater than the second string.
|
---|
| 2370 | * @param psz1 First UTF-8 string. Null is allowed.
|
---|
| 2371 | * @param psz2 Second UTF-8 string. Null is allowed.
|
---|
| 2372 | */
|
---|
| 2373 | RTDECL(int) RTStrICmp(const char *psz1, const char *psz2);
|
---|
| 2374 |
|
---|
| 2375 | /**
|
---|
[13927] | 2376 | * Performs a case insensitive string compare between two UTF-8 strings, given a
|
---|
| 2377 | * maximum string length.
|
---|
| 2378 | *
|
---|
| 2379 | * This is a simplified compare, as only the simplified lower/upper case folding
|
---|
| 2380 | * specified by the unicode specs are used. It does not consider character pairs
|
---|
| 2381 | * as they are used in some languages, just simple upper & lower case compares.
|
---|
| 2382 | *
|
---|
| 2383 | * The result is the difference between the mismatching codepoints after they
|
---|
| 2384 | * both have been lower cased.
|
---|
| 2385 | *
|
---|
| 2386 | * If the string encoding is invalid the function will assert (strict builds)
|
---|
[70092] | 2387 | * and use RTStrNCmp for the remainder of the string.
|
---|
[13927] | 2388 | *
|
---|
| 2389 | * @returns < 0 if the first string less than the second string.
|
---|
| 2390 | * @returns 0 if the first string identical to the second string.
|
---|
| 2391 | * @returns > 0 if the first string greater than the second string.
|
---|
| 2392 | * @param psz1 First UTF-8 string. Null is allowed.
|
---|
| 2393 | * @param psz2 Second UTF-8 string. Null is allowed.
|
---|
| 2394 | * @param cchMax Maximum string length
|
---|
| 2395 | */
|
---|
| 2396 | RTDECL(int) RTStrNICmp(const char *psz1, const char *psz2, size_t cchMax);
|
---|
| 2397 |
|
---|
| 2398 | /**
|
---|
[66361] | 2399 | * Performs a case insensitive string compare between a UTF-8 string and a 7-bit
|
---|
| 2400 | * ASCII string.
|
---|
| 2401 | *
|
---|
| 2402 | * This is potentially faster than RTStrICmp and drags in less dependencies. It
|
---|
| 2403 | * is really handy for hardcoded inputs.
|
---|
| 2404 | *
|
---|
| 2405 | * If the string encoding is invalid the function will assert (strict builds)
|
---|
| 2406 | * and use RTStrCmp for the remainder of the string.
|
---|
| 2407 | *
|
---|
| 2408 | * @returns < 0 if the first string less than the second string.
|
---|
| 2409 | * @returns 0 if the first string identical to the second string.
|
---|
| 2410 | * @returns > 0 if the first string greater than the second string.
|
---|
| 2411 | * @param psz1 First UTF-8 string. Null is allowed.
|
---|
| 2412 | * @param psz2 Second string, 7-bit ASCII. Null is allowed.
|
---|
[70092] | 2413 | * @sa RTStrICmp, RTUtf16ICmpAscii
|
---|
[66361] | 2414 | */
|
---|
| 2415 | RTDECL(int) RTStrICmpAscii(const char *psz1, const char *psz2);
|
---|
| 2416 |
|
---|
| 2417 | /**
|
---|
[70092] | 2418 | * Performs a case insensitive string compare between a UTF-8 string and a 7-bit
|
---|
| 2419 | * ASCII string, given a maximum string length.
|
---|
| 2420 | *
|
---|
| 2421 | * This is potentially faster than RTStrNICmp and drags in less dependencies.
|
---|
| 2422 | * It is really handy for hardcoded inputs.
|
---|
| 2423 | *
|
---|
| 2424 | * If the string encoding is invalid the function will assert (strict builds)
|
---|
| 2425 | * and use RTStrNCmp for the remainder of the string.
|
---|
| 2426 | *
|
---|
| 2427 | * @returns < 0 if the first string less than the second string.
|
---|
| 2428 | * @returns 0 if the first string identical to the second string.
|
---|
| 2429 | * @returns > 0 if the first string greater than the second string.
|
---|
| 2430 | * @param psz1 First UTF-8 string. Null is allowed.
|
---|
| 2431 | * @param psz2 Second string, 7-bit ASCII. Null is allowed.
|
---|
| 2432 | * @param cchMax Maximum string length
|
---|
| 2433 | * @sa RTStrNICmp, RTUtf16NICmpAscii
|
---|
| 2434 | */
|
---|
| 2435 | RTDECL(int) RTStrNICmpAscii(const char *psz1, const char *psz2, size_t cchMax);
|
---|
| 2436 |
|
---|
| 2437 | /**
|
---|
[59067] | 2438 | * Checks whether @a pszString starts with @a pszStart.
|
---|
| 2439 | *
|
---|
| 2440 | * @returns true / false.
|
---|
| 2441 | * @param pszString The string to check.
|
---|
| 2442 | * @param pszStart The start string to check for.
|
---|
| 2443 | */
|
---|
| 2444 | RTDECL(int) RTStrStartsWith(const char *pszString, const char *pszStart);
|
---|
| 2445 |
|
---|
| 2446 | /**
|
---|
| 2447 | * Checks whether @a pszString starts with @a pszStart, case insensitive.
|
---|
| 2448 | *
|
---|
| 2449 | * @returns true / false.
|
---|
| 2450 | * @param pszString The string to check.
|
---|
| 2451 | * @param pszStart The start string to check for.
|
---|
| 2452 | */
|
---|
| 2453 | RTDECL(int) RTStrIStartsWith(const char *pszString, const char *pszStart);
|
---|
| 2454 |
|
---|
| 2455 | /**
|
---|
[18555] | 2456 | * Locates a case sensitive substring.
|
---|
[18552] | 2457 | *
|
---|
| 2458 | * If any of the two strings are NULL, then NULL is returned. If the needle is
|
---|
| 2459 | * an empty string, then the haystack is returned (i.e. matches anything).
|
---|
| 2460 | *
|
---|
[18555] | 2461 | * @returns Pointer to the first occurrence of the substring if found, NULL if
|
---|
[18552] | 2462 | * not.
|
---|
| 2463 | *
|
---|
| 2464 | * @param pszHaystack The string to search.
|
---|
| 2465 | * @param pszNeedle The substring to search for.
|
---|
| 2466 | *
|
---|
| 2467 | * @remarks The difference between this and strstr is the handling of NULL
|
---|
[18555] | 2468 | * pointers.
|
---|
[18552] | 2469 | */
|
---|
| 2470 | RTDECL(char *) RTStrStr(const char *pszHaystack, const char *pszNeedle);
|
---|
| 2471 |
|
---|
| 2472 | /**
|
---|
| 2473 | * Locates a case insensitive substring.
|
---|
| 2474 | *
|
---|
| 2475 | * If any of the two strings are NULL, then NULL is returned. If the needle is
|
---|
| 2476 | * an empty string, then the haystack is returned (i.e. matches anything).
|
---|
| 2477 | *
|
---|
[18556] | 2478 | * @returns Pointer to the first occurrence of the substring if found, NULL if
|
---|
[18552] | 2479 | * not.
|
---|
| 2480 | *
|
---|
| 2481 | * @param pszHaystack The string to search.
|
---|
| 2482 | * @param pszNeedle The substring to search for.
|
---|
| 2483 | *
|
---|
| 2484 | */
|
---|
| 2485 | RTDECL(char *) RTStrIStr(const char *pszHaystack, const char *pszNeedle);
|
---|
| 2486 |
|
---|
| 2487 | /**
|
---|
| 2488 | * Converts the string to lower case.
|
---|
| 2489 | *
|
---|
| 2490 | * @returns Pointer to the converted string.
|
---|
| 2491 | * @param psz The string to convert.
|
---|
| 2492 | */
|
---|
| 2493 | RTDECL(char *) RTStrToLower(char *psz);
|
---|
| 2494 |
|
---|
| 2495 | /**
|
---|
| 2496 | * Converts the string to upper case.
|
---|
| 2497 | *
|
---|
| 2498 | * @returns Pointer to the converted string.
|
---|
| 2499 | * @param psz The string to convert.
|
---|
| 2500 | */
|
---|
| 2501 | RTDECL(char *) RTStrToUpper(char *psz);
|
---|
| 2502 |
|
---|
| 2503 | /**
|
---|
[46010] | 2504 | * Checks if the string is case foldable, i.e. whether it would change if
|
---|
| 2505 | * subject to RTStrToLower or RTStrToUpper.
|
---|
| 2506 | *
|
---|
| 2507 | * @returns true / false
|
---|
| 2508 | * @param psz The string in question.
|
---|
| 2509 | */
|
---|
| 2510 | RTDECL(bool) RTStrIsCaseFoldable(const char *psz);
|
---|
| 2511 |
|
---|
| 2512 | /**
|
---|
| 2513 | * Checks if the string is upper cased (no lower case chars in it).
|
---|
| 2514 | *
|
---|
| 2515 | * @returns true / false
|
---|
| 2516 | * @param psz The string in question.
|
---|
| 2517 | */
|
---|
| 2518 | RTDECL(bool) RTStrIsUpperCased(const char *psz);
|
---|
| 2519 |
|
---|
| 2520 | /**
|
---|
| 2521 | * Checks if the string is lower cased (no upper case chars in it).
|
---|
| 2522 | *
|
---|
| 2523 | * @returns true / false
|
---|
| 2524 | * @param psz The string in question.
|
---|
| 2525 | */
|
---|
| 2526 | RTDECL(bool) RTStrIsLowerCased(const char *psz);
|
---|
| 2527 |
|
---|
| 2528 | /**
|
---|
[13472] | 2529 | * Find the length of a zero-terminated byte string, given
|
---|
| 2530 | * a max string length.
|
---|
| 2531 | *
|
---|
| 2532 | * See also RTStrNLenEx.
|
---|
| 2533 | *
|
---|
| 2534 | * @returns The string length or cbMax. The returned length does not include
|
---|
| 2535 | * the zero terminator if it was found.
|
---|
| 2536 | *
|
---|
| 2537 | * @param pszString The string.
|
---|
| 2538 | * @param cchMax The max string length.
|
---|
| 2539 | */
|
---|
| 2540 | RTDECL(size_t) RTStrNLen(const char *pszString, size_t cchMax);
|
---|
| 2541 |
|
---|
| 2542 | /**
|
---|
| 2543 | * Find the length of a zero-terminated byte string, given
|
---|
| 2544 | * a max string length.
|
---|
| 2545 | *
|
---|
| 2546 | * See also RTStrNLen.
|
---|
| 2547 | *
|
---|
| 2548 | * @returns IPRT status code.
|
---|
| 2549 | * @retval VINF_SUCCESS if the string has a length less than cchMax.
|
---|
| 2550 | * @retval VERR_BUFFER_OVERFLOW if the end of the string wasn't found
|
---|
| 2551 | * before cchMax was reached.
|
---|
| 2552 | *
|
---|
| 2553 | * @param pszString The string.
|
---|
| 2554 | * @param cchMax The max string length.
|
---|
| 2555 | * @param pcch Where to store the string length excluding the
|
---|
| 2556 | * terminator. This is set to cchMax if the terminator
|
---|
| 2557 | * isn't found.
|
---|
| 2558 | */
|
---|
| 2559 | RTDECL(int) RTStrNLenEx(const char *pszString, size_t cchMax, size_t *pcch);
|
---|
| 2560 |
|
---|
[30320] | 2561 | RT_C_DECLS_END
|
---|
| 2562 |
|
---|
| 2563 | /** The maximum size argument of a memchr call. */
|
---|
[36638] | 2564 | #define RTSTR_MEMCHR_MAX ((~(size_t)0 >> 1) - 15)
|
---|
[30320] | 2565 |
|
---|
[13472] | 2566 | /**
|
---|
[30320] | 2567 | * Find the zero terminator in a string with a limited length.
|
---|
| 2568 | *
|
---|
| 2569 | * @returns Pointer to the zero terminator.
|
---|
| 2570 | * @returns NULL if the zero terminator was not found.
|
---|
| 2571 | *
|
---|
| 2572 | * @param pszString The string.
|
---|
| 2573 | * @param cchMax The max string length. RTSTR_MAX is fine.
|
---|
| 2574 | */
|
---|
| 2575 | #if defined(__cplusplus) && !defined(DOXYGEN_RUNNING)
|
---|
| 2576 | DECLINLINE(char const *) RTStrEnd(char const *pszString, size_t cchMax)
|
---|
| 2577 | {
|
---|
[36638] | 2578 | /* Avoid potential issues with memchr seen in glibc.
|
---|
| 2579 | * See sysdeps/x86_64/memchr.S in glibc versions older than 2.11 */
|
---|
| 2580 | while (cchMax > RTSTR_MEMCHR_MAX)
|
---|
[30320] | 2581 | {
|
---|
| 2582 | char const *pszRet = (char const *)memchr(pszString, '\0', RTSTR_MEMCHR_MAX);
|
---|
| 2583 | if (RT_LIKELY(pszRet))
|
---|
| 2584 | return pszRet;
|
---|
| 2585 | pszString += RTSTR_MEMCHR_MAX;
|
---|
| 2586 | cchMax -= RTSTR_MEMCHR_MAX;
|
---|
| 2587 | }
|
---|
| 2588 | return (char const *)memchr(pszString, '\0', cchMax);
|
---|
| 2589 | }
|
---|
| 2590 |
|
---|
| 2591 | DECLINLINE(char *) RTStrEnd(char *pszString, size_t cchMax)
|
---|
| 2592 | #else
|
---|
| 2593 | DECLINLINE(char *) RTStrEnd(const char *pszString, size_t cchMax)
|
---|
| 2594 | #endif
|
---|
| 2595 | {
|
---|
[36638] | 2596 | /* Avoid potential issues with memchr seen in glibc.
|
---|
| 2597 | * See sysdeps/x86_64/memchr.S in glibc versions older than 2.11 */
|
---|
| 2598 | while (cchMax > RTSTR_MEMCHR_MAX)
|
---|
[30320] | 2599 | {
|
---|
| 2600 | char *pszRet = (char *)memchr(pszString, '\0', RTSTR_MEMCHR_MAX);
|
---|
| 2601 | if (RT_LIKELY(pszRet))
|
---|
| 2602 | return pszRet;
|
---|
| 2603 | pszString += RTSTR_MEMCHR_MAX;
|
---|
| 2604 | cchMax -= RTSTR_MEMCHR_MAX;
|
---|
| 2605 | }
|
---|
| 2606 | return (char *)memchr(pszString, '\0', cchMax);
|
---|
| 2607 | }
|
---|
| 2608 |
|
---|
| 2609 | RT_C_DECLS_BEGIN
|
---|
| 2610 |
|
---|
| 2611 | /**
|
---|
[57719] | 2612 | * Finds the offset at which a simple character first occurs in a string.
|
---|
| 2613 | *
|
---|
| 2614 | * @returns The offset of the first occurence or the terminator offset.
|
---|
| 2615 | * @param pszHaystack The string to search.
|
---|
| 2616 | * @param chNeedle The character to search for.
|
---|
| 2617 | */
|
---|
| 2618 | DECLINLINE(size_t) RTStrOffCharOrTerm(const char *pszHaystack, char chNeedle)
|
---|
| 2619 | {
|
---|
| 2620 | const char *psz = pszHaystack;
|
---|
| 2621 | char ch;
|
---|
| 2622 | while ( (ch = *psz) != chNeedle
|
---|
| 2623 | && ch != '\0')
|
---|
| 2624 | psz++;
|
---|
| 2625 | return psz - pszHaystack;
|
---|
| 2626 | }
|
---|
| 2627 |
|
---|
| 2628 |
|
---|
| 2629 | /**
|
---|
[13472] | 2630 | * Matches a simple string pattern.
|
---|
| 2631 | *
|
---|
| 2632 | * @returns true if the string matches the pattern, otherwise false.
|
---|
| 2633 | *
|
---|
| 2634 | * @param pszPattern The pattern. Special chars are '*' and '?', where the
|
---|
| 2635 | * asterisk matches zero or more characters and question
|
---|
| 2636 | * mark matches exactly one character.
|
---|
| 2637 | * @param pszString The string to match against the pattern.
|
---|
| 2638 | */
|
---|
| 2639 | RTDECL(bool) RTStrSimplePatternMatch(const char *pszPattern, const char *pszString);
|
---|
| 2640 |
|
---|
| 2641 | /**
|
---|
| 2642 | * Matches a simple string pattern, neither which needs to be zero terminated.
|
---|
| 2643 | *
|
---|
| 2644 | * This is identical to RTStrSimplePatternMatch except that you can optionally
|
---|
| 2645 | * specify the length of both the pattern and the string. The function will
|
---|
| 2646 | * stop when it hits a string terminator or either of the lengths.
|
---|
| 2647 | *
|
---|
| 2648 | * @returns true if the string matches the pattern, otherwise false.
|
---|
| 2649 | *
|
---|
| 2650 | * @param pszPattern The pattern. Special chars are '*' and '?', where the
|
---|
| 2651 | * asterisk matches zero or more characters and question
|
---|
| 2652 | * mark matches exactly one character.
|
---|
[13549] | 2653 | * @param cchPattern The pattern length. Pass RTSTR_MAX if you don't know the
|
---|
| 2654 | * length and wish to stop at the string terminator.
|
---|
[13472] | 2655 | * @param pszString The string to match against the pattern.
|
---|
[13549] | 2656 | * @param cchString The string length. Pass RTSTR_MAX if you don't know the
|
---|
| 2657 | * length and wish to match up to the string terminator.
|
---|
[13472] | 2658 | */
|
---|
| 2659 | RTDECL(bool) RTStrSimplePatternNMatch(const char *pszPattern, size_t cchPattern,
|
---|
| 2660 | const char *pszString, size_t cchString);
|
---|
| 2661 |
|
---|
| 2662 | /**
|
---|
| 2663 | * Matches multiple patterns against a string.
|
---|
| 2664 | *
|
---|
| 2665 | * The patterns are separated by the pipe character (|).
|
---|
| 2666 | *
|
---|
| 2667 | * @returns true if the string matches the pattern, otherwise false.
|
---|
| 2668 | *
|
---|
| 2669 | * @param pszPatterns The patterns.
|
---|
[13549] | 2670 | * @param cchPatterns The lengths of the patterns to use. Pass RTSTR_MAX to
|
---|
| 2671 | * stop at the terminator.
|
---|
[13472] | 2672 | * @param pszString The string to match against the pattern.
|
---|
[13549] | 2673 | * @param cchString The string length. Pass RTSTR_MAX stop stop at the
|
---|
| 2674 | * terminator.
|
---|
[13472] | 2675 | * @param poffPattern Offset into the patterns string of the patttern that
|
---|
[13546] | 2676 | * matched. If no match, this will be set to RTSTR_MAX.
|
---|
[13472] | 2677 | * This is optional, NULL is fine.
|
---|
| 2678 | */
|
---|
| 2679 | RTDECL(bool) RTStrSimplePatternMultiMatch(const char *pszPatterns, size_t cchPatterns,
|
---|
| 2680 | const char *pszString, size_t cchString,
|
---|
| 2681 | size_t *poffPattern);
|
---|
| 2682 |
|
---|
[1] | 2683 | /**
|
---|
[25014] | 2684 | * Compares two version strings RTStrICmp fashion.
|
---|
[24639] | 2685 | *
|
---|
[25011] | 2686 | * The version string is split up into sections at punctuation, spaces,
|
---|
[33540] | 2687 | * underscores, dashes and plus signs. The sections are then split up into
|
---|
[25011] | 2688 | * numeric and string sub-sections. Finally, the sub-sections are compared
|
---|
| 2689 | * in a numeric or case insesntivie fashion depending on what they are.
|
---|
| 2690 | *
|
---|
[25014] | 2691 | * The following strings are considered to be equal: "1.0.0", "1.00.0", "1.0",
|
---|
| 2692 | * "1". These aren't: "1.0.0r993", "1.0", "1.0r993", "1.0_Beta3", "1.1"
|
---|
[25011] | 2693 | *
|
---|
[25014] | 2694 | * @returns < 0 if the first string less than the second string.
|
---|
| 2695 | * @returns 0 if the first string identical to the second string.
|
---|
| 2696 | * @returns > 0 if the first string greater than the second string.
|
---|
[24639] | 2697 | *
|
---|
[24893] | 2698 | * @param pszVer1 First version string to compare.
|
---|
[25005] | 2699 | * @param pszVer2 Second version string to compare first version with.
|
---|
[24639] | 2700 | */
|
---|
[25005] | 2701 | RTDECL(int) RTStrVersionCompare(const char *pszVer1, const char *pszVer2);
|
---|
[24639] | 2702 |
|
---|
[25011] | 2703 |
|
---|
| 2704 | /** @defgroup rt_str_conv String To/From Number Conversions
|
---|
| 2705 | * @{ */
|
---|
| 2706 |
|
---|
[24639] | 2707 | /**
|
---|
[1] | 2708 | * Converts a string representation of a number to a 64-bit unsigned number.
|
---|
| 2709 | *
|
---|
| 2710 | * @returns iprt status code.
|
---|
[18523] | 2711 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 2712 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 2713 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
| 2714 | * @retval VWRN_TRAILING_CHARS
|
---|
| 2715 | * @retval VWRN_TRAILING_SPACES
|
---|
| 2716 | * @retval VINF_SUCCESS
|
---|
| 2717 | * @retval VERR_NO_DIGITS
|
---|
| 2718 | *
|
---|
[1] | 2719 | * @param pszValue Pointer to the string value.
|
---|
| 2720 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
| 2721 | * @param uBase The base of the representation used.
|
---|
[14774] | 2722 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[1] | 2723 | * @param pu64 Where to store the converted number. (optional)
|
---|
| 2724 | */
|
---|
| 2725 | RTDECL(int) RTStrToUInt64Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint64_t *pu64);
|
---|
| 2726 |
|
---|
| 2727 | /**
|
---|
[5712] | 2728 | * Converts a string representation of a number to a 64-bit unsigned number,
|
---|
| 2729 | * making sure the full string is converted.
|
---|
| 2730 | *
|
---|
| 2731 | * @returns iprt status code.
|
---|
[18523] | 2732 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 2733 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 2734 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
| 2735 | * @retval VINF_SUCCESS
|
---|
| 2736 | * @retval VERR_NO_DIGITS
|
---|
| 2737 | * @retval VERR_TRAILING_SPACES
|
---|
| 2738 | * @retval VERR_TRAILING_CHARS
|
---|
| 2739 | *
|
---|
| 2740 | * @param pszValue Pointer to the string value.
|
---|
| 2741 | * @param uBase The base of the representation used.
|
---|
[14774] | 2742 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[5712] | 2743 | * @param pu64 Where to store the converted number. (optional)
|
---|
| 2744 | */
|
---|
| 2745 | RTDECL(int) RTStrToUInt64Full(const char *pszValue, unsigned uBase, uint64_t *pu64);
|
---|
| 2746 |
|
---|
| 2747 | /**
|
---|
[1] | 2748 | * Converts a string representation of a number to a 64-bit unsigned number.
|
---|
| 2749 | * The base is guessed.
|
---|
| 2750 | *
|
---|
| 2751 | * @returns 64-bit unsigned number on success.
|
---|
| 2752 | * @returns 0 on failure.
|
---|
| 2753 | * @param pszValue Pointer to the string value.
|
---|
| 2754 | */
|
---|
| 2755 | RTDECL(uint64_t) RTStrToUInt64(const char *pszValue);
|
---|
| 2756 |
|
---|
| 2757 | /**
|
---|
| 2758 | * Converts a string representation of a number to a 32-bit unsigned number.
|
---|
| 2759 | *
|
---|
| 2760 | * @returns iprt status code.
|
---|
[460] | 2761 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 2762 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 2763 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
| 2764 | * @retval VWRN_TRAILING_CHARS
|
---|
| 2765 | * @retval VWRN_TRAILING_SPACES
|
---|
| 2766 | * @retval VINF_SUCCESS
|
---|
| 2767 | * @retval VERR_NO_DIGITS
|
---|
| 2768 | *
|
---|
[1] | 2769 | * @param pszValue Pointer to the string value.
|
---|
| 2770 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
| 2771 | * @param uBase The base of the representation used.
|
---|
[460] | 2772 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[1] | 2773 | * @param pu32 Where to store the converted number. (optional)
|
---|
| 2774 | */
|
---|
| 2775 | RTDECL(int) RTStrToUInt32Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint32_t *pu32);
|
---|
| 2776 |
|
---|
| 2777 | /**
|
---|
[5712] | 2778 | * Converts a string representation of a number to a 32-bit unsigned number,
|
---|
| 2779 | * making sure the full string is converted.
|
---|
| 2780 | *
|
---|
| 2781 | * @returns iprt status code.
|
---|
[18523] | 2782 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 2783 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 2784 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
| 2785 | * @retval VINF_SUCCESS
|
---|
| 2786 | * @retval VERR_NO_DIGITS
|
---|
| 2787 | * @retval VERR_TRAILING_SPACES
|
---|
| 2788 | * @retval VERR_TRAILING_CHARS
|
---|
| 2789 | *
|
---|
| 2790 | * @param pszValue Pointer to the string value.
|
---|
| 2791 | * @param uBase The base of the representation used.
|
---|
[14774] | 2792 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[5712] | 2793 | * @param pu32 Where to store the converted number. (optional)
|
---|
| 2794 | */
|
---|
| 2795 | RTDECL(int) RTStrToUInt32Full(const char *pszValue, unsigned uBase, uint32_t *pu32);
|
---|
| 2796 |
|
---|
| 2797 | /**
|
---|
[74594] | 2798 | * Converts a string representation of a number to a 32-bit unsigned number.
|
---|
[1] | 2799 | * The base is guessed.
|
---|
| 2800 | *
|
---|
| 2801 | * @returns 32-bit unsigned number on success.
|
---|
| 2802 | * @returns 0 on failure.
|
---|
| 2803 | * @param pszValue Pointer to the string value.
|
---|
| 2804 | */
|
---|
| 2805 | RTDECL(uint32_t) RTStrToUInt32(const char *pszValue);
|
---|
| 2806 |
|
---|
| 2807 | /**
|
---|
| 2808 | * Converts a string representation of a number to a 16-bit unsigned number.
|
---|
| 2809 | *
|
---|
| 2810 | * @returns iprt status code.
|
---|
[460] | 2811 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 2812 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 2813 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
| 2814 | * @retval VWRN_TRAILING_CHARS
|
---|
| 2815 | * @retval VWRN_TRAILING_SPACES
|
---|
| 2816 | * @retval VINF_SUCCESS
|
---|
| 2817 | * @retval VERR_NO_DIGITS
|
---|
| 2818 | *
|
---|
[1] | 2819 | * @param pszValue Pointer to the string value.
|
---|
| 2820 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
| 2821 | * @param uBase The base of the representation used.
|
---|
[460] | 2822 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[1] | 2823 | * @param pu16 Where to store the converted number. (optional)
|
---|
| 2824 | */
|
---|
| 2825 | RTDECL(int) RTStrToUInt16Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint16_t *pu16);
|
---|
| 2826 |
|
---|
| 2827 | /**
|
---|
[5712] | 2828 | * Converts a string representation of a number to a 16-bit unsigned number,
|
---|
| 2829 | * making sure the full string is converted.
|
---|
| 2830 | *
|
---|
| 2831 | * @returns iprt status code.
|
---|
[18523] | 2832 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 2833 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 2834 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
| 2835 | * @retval VINF_SUCCESS
|
---|
| 2836 | * @retval VERR_NO_DIGITS
|
---|
| 2837 | * @retval VERR_TRAILING_SPACES
|
---|
| 2838 | * @retval VERR_TRAILING_CHARS
|
---|
| 2839 | *
|
---|
| 2840 | * @param pszValue Pointer to the string value.
|
---|
| 2841 | * @param uBase The base of the representation used.
|
---|
[14774] | 2842 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[5712] | 2843 | * @param pu16 Where to store the converted number. (optional)
|
---|
| 2844 | */
|
---|
| 2845 | RTDECL(int) RTStrToUInt16Full(const char *pszValue, unsigned uBase, uint16_t *pu16);
|
---|
| 2846 |
|
---|
| 2847 | /**
|
---|
[1] | 2848 | * Converts a string representation of a number to a 16-bit unsigned number.
|
---|
| 2849 | * The base is guessed.
|
---|
| 2850 | *
|
---|
| 2851 | * @returns 16-bit unsigned number on success.
|
---|
| 2852 | * @returns 0 on failure.
|
---|
| 2853 | * @param pszValue Pointer to the string value.
|
---|
| 2854 | */
|
---|
| 2855 | RTDECL(uint16_t) RTStrToUInt16(const char *pszValue);
|
---|
| 2856 |
|
---|
| 2857 | /**
|
---|
| 2858 | * Converts a string representation of a number to a 8-bit unsigned number.
|
---|
| 2859 | *
|
---|
| 2860 | * @returns iprt status code.
|
---|
[460] | 2861 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 2862 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 2863 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
| 2864 | * @retval VWRN_TRAILING_CHARS
|
---|
| 2865 | * @retval VWRN_TRAILING_SPACES
|
---|
| 2866 | * @retval VINF_SUCCESS
|
---|
| 2867 | * @retval VERR_NO_DIGITS
|
---|
| 2868 | *
|
---|
[1] | 2869 | * @param pszValue Pointer to the string value.
|
---|
| 2870 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
| 2871 | * @param uBase The base of the representation used.
|
---|
[460] | 2872 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[1] | 2873 | * @param pu8 Where to store the converted number. (optional)
|
---|
| 2874 | */
|
---|
| 2875 | RTDECL(int) RTStrToUInt8Ex(const char *pszValue, char **ppszNext, unsigned uBase, uint8_t *pu8);
|
---|
| 2876 |
|
---|
| 2877 | /**
|
---|
[5712] | 2878 | * Converts a string representation of a number to a 8-bit unsigned number,
|
---|
| 2879 | * making sure the full string is converted.
|
---|
| 2880 | *
|
---|
| 2881 | * @returns iprt status code.
|
---|
[18523] | 2882 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 2883 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 2884 | * @retval VWRN_NEGATIVE_UNSIGNED
|
---|
| 2885 | * @retval VINF_SUCCESS
|
---|
| 2886 | * @retval VERR_NO_DIGITS
|
---|
| 2887 | * @retval VERR_TRAILING_SPACES
|
---|
| 2888 | * @retval VERR_TRAILING_CHARS
|
---|
| 2889 | *
|
---|
| 2890 | * @param pszValue Pointer to the string value.
|
---|
| 2891 | * @param uBase The base of the representation used.
|
---|
[14774] | 2892 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[5712] | 2893 | * @param pu8 Where to store the converted number. (optional)
|
---|
| 2894 | */
|
---|
| 2895 | RTDECL(int) RTStrToUInt8Full(const char *pszValue, unsigned uBase, uint8_t *pu8);
|
---|
| 2896 |
|
---|
| 2897 | /**
|
---|
[1] | 2898 | * Converts a string representation of a number to a 8-bit unsigned number.
|
---|
| 2899 | * The base is guessed.
|
---|
| 2900 | *
|
---|
| 2901 | * @returns 8-bit unsigned number on success.
|
---|
| 2902 | * @returns 0 on failure.
|
---|
| 2903 | * @param pszValue Pointer to the string value.
|
---|
| 2904 | */
|
---|
| 2905 | RTDECL(uint8_t) RTStrToUInt8(const char *pszValue);
|
---|
| 2906 |
|
---|
| 2907 | /**
|
---|
| 2908 | * Converts a string representation of a number to a 64-bit signed number.
|
---|
| 2909 | *
|
---|
| 2910 | * @returns iprt status code.
|
---|
[460] | 2911 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 2912 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 2913 | * @retval VWRN_TRAILING_CHARS
|
---|
| 2914 | * @retval VWRN_TRAILING_SPACES
|
---|
| 2915 | * @retval VINF_SUCCESS
|
---|
| 2916 | * @retval VERR_NO_DIGITS
|
---|
| 2917 | *
|
---|
[1] | 2918 | * @param pszValue Pointer to the string value.
|
---|
| 2919 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
| 2920 | * @param uBase The base of the representation used.
|
---|
[460] | 2921 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[1] | 2922 | * @param pi64 Where to store the converted number. (optional)
|
---|
| 2923 | */
|
---|
| 2924 | RTDECL(int) RTStrToInt64Ex(const char *pszValue, char **ppszNext, unsigned uBase, int64_t *pi64);
|
---|
| 2925 |
|
---|
| 2926 | /**
|
---|
[5712] | 2927 | * Converts a string representation of a number to a 64-bit signed number,
|
---|
| 2928 | * making sure the full string is converted.
|
---|
| 2929 | *
|
---|
| 2930 | * @returns iprt status code.
|
---|
[18523] | 2931 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 2932 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 2933 | * @retval VINF_SUCCESS
|
---|
| 2934 | * @retval VERR_TRAILING_CHARS
|
---|
| 2935 | * @retval VERR_TRAILING_SPACES
|
---|
| 2936 | * @retval VERR_NO_DIGITS
|
---|
| 2937 | *
|
---|
| 2938 | * @param pszValue Pointer to the string value.
|
---|
| 2939 | * @param uBase The base of the representation used.
|
---|
[14774] | 2940 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[5712] | 2941 | * @param pi64 Where to store the converted number. (optional)
|
---|
| 2942 | */
|
---|
| 2943 | RTDECL(int) RTStrToInt64Full(const char *pszValue, unsigned uBase, int64_t *pi64);
|
---|
| 2944 |
|
---|
| 2945 | /**
|
---|
[1] | 2946 | * Converts a string representation of a number to a 64-bit signed number.
|
---|
| 2947 | * The base is guessed.
|
---|
| 2948 | *
|
---|
| 2949 | * @returns 64-bit signed number on success.
|
---|
| 2950 | * @returns 0 on failure.
|
---|
| 2951 | * @param pszValue Pointer to the string value.
|
---|
| 2952 | */
|
---|
| 2953 | RTDECL(int64_t) RTStrToInt64(const char *pszValue);
|
---|
| 2954 |
|
---|
| 2955 | /**
|
---|
| 2956 | * Converts a string representation of a number to a 32-bit signed number.
|
---|
| 2957 | *
|
---|
| 2958 | * @returns iprt status code.
|
---|
[460] | 2959 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 2960 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 2961 | * @retval VWRN_TRAILING_CHARS
|
---|
| 2962 | * @retval VWRN_TRAILING_SPACES
|
---|
| 2963 | * @retval VINF_SUCCESS
|
---|
| 2964 | * @retval VERR_NO_DIGITS
|
---|
| 2965 | *
|
---|
[1] | 2966 | * @param pszValue Pointer to the string value.
|
---|
| 2967 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
| 2968 | * @param uBase The base of the representation used.
|
---|
[460] | 2969 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[1] | 2970 | * @param pi32 Where to store the converted number. (optional)
|
---|
| 2971 | */
|
---|
| 2972 | RTDECL(int) RTStrToInt32Ex(const char *pszValue, char **ppszNext, unsigned uBase, int32_t *pi32);
|
---|
| 2973 |
|
---|
| 2974 | /**
|
---|
[5712] | 2975 | * Converts a string representation of a number to a 32-bit signed number,
|
---|
| 2976 | * making sure the full string is converted.
|
---|
| 2977 | *
|
---|
| 2978 | * @returns iprt status code.
|
---|
[18523] | 2979 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 2980 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 2981 | * @retval VINF_SUCCESS
|
---|
| 2982 | * @retval VERR_TRAILING_CHARS
|
---|
| 2983 | * @retval VERR_TRAILING_SPACES
|
---|
| 2984 | * @retval VERR_NO_DIGITS
|
---|
| 2985 | *
|
---|
| 2986 | * @param pszValue Pointer to the string value.
|
---|
| 2987 | * @param uBase The base of the representation used.
|
---|
[14774] | 2988 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[5712] | 2989 | * @param pi32 Where to store the converted number. (optional)
|
---|
| 2990 | */
|
---|
| 2991 | RTDECL(int) RTStrToInt32Full(const char *pszValue, unsigned uBase, int32_t *pi32);
|
---|
| 2992 |
|
---|
| 2993 | /**
|
---|
[1] | 2994 | * Converts a string representation of a number to a 32-bit signed number.
|
---|
| 2995 | * The base is guessed.
|
---|
| 2996 | *
|
---|
| 2997 | * @returns 32-bit signed number on success.
|
---|
| 2998 | * @returns 0 on failure.
|
---|
| 2999 | * @param pszValue Pointer to the string value.
|
---|
| 3000 | */
|
---|
| 3001 | RTDECL(int32_t) RTStrToInt32(const char *pszValue);
|
---|
| 3002 |
|
---|
| 3003 | /**
|
---|
| 3004 | * Converts a string representation of a number to a 16-bit signed number.
|
---|
| 3005 | *
|
---|
| 3006 | * @returns iprt status code.
|
---|
[460] | 3007 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 3008 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 3009 | * @retval VWRN_TRAILING_CHARS
|
---|
| 3010 | * @retval VWRN_TRAILING_SPACES
|
---|
| 3011 | * @retval VINF_SUCCESS
|
---|
| 3012 | * @retval VERR_NO_DIGITS
|
---|
| 3013 | *
|
---|
[1] | 3014 | * @param pszValue Pointer to the string value.
|
---|
| 3015 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
| 3016 | * @param uBase The base of the representation used.
|
---|
[460] | 3017 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[1] | 3018 | * @param pi16 Where to store the converted number. (optional)
|
---|
| 3019 | */
|
---|
| 3020 | RTDECL(int) RTStrToInt16Ex(const char *pszValue, char **ppszNext, unsigned uBase, int16_t *pi16);
|
---|
| 3021 |
|
---|
| 3022 | /**
|
---|
[5712] | 3023 | * Converts a string representation of a number to a 16-bit signed number,
|
---|
| 3024 | * making sure the full string is converted.
|
---|
| 3025 | *
|
---|
| 3026 | * @returns iprt status code.
|
---|
[18523] | 3027 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 3028 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 3029 | * @retval VINF_SUCCESS
|
---|
| 3030 | * @retval VERR_TRAILING_CHARS
|
---|
| 3031 | * @retval VERR_TRAILING_SPACES
|
---|
| 3032 | * @retval VERR_NO_DIGITS
|
---|
| 3033 | *
|
---|
| 3034 | * @param pszValue Pointer to the string value.
|
---|
| 3035 | * @param uBase The base of the representation used.
|
---|
[14774] | 3036 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[5712] | 3037 | * @param pi16 Where to store the converted number. (optional)
|
---|
| 3038 | */
|
---|
| 3039 | RTDECL(int) RTStrToInt16Full(const char *pszValue, unsigned uBase, int16_t *pi16);
|
---|
| 3040 |
|
---|
| 3041 | /**
|
---|
[1] | 3042 | * Converts a string representation of a number to a 16-bit signed number.
|
---|
| 3043 | * The base is guessed.
|
---|
| 3044 | *
|
---|
| 3045 | * @returns 16-bit signed number on success.
|
---|
| 3046 | * @returns 0 on failure.
|
---|
| 3047 | * @param pszValue Pointer to the string value.
|
---|
| 3048 | */
|
---|
| 3049 | RTDECL(int16_t) RTStrToInt16(const char *pszValue);
|
---|
| 3050 |
|
---|
| 3051 | /**
|
---|
| 3052 | * Converts a string representation of a number to a 8-bit signed number.
|
---|
| 3053 | *
|
---|
| 3054 | * @returns iprt status code.
|
---|
[460] | 3055 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 3056 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 3057 | * @retval VWRN_TRAILING_CHARS
|
---|
| 3058 | * @retval VWRN_TRAILING_SPACES
|
---|
| 3059 | * @retval VINF_SUCCESS
|
---|
| 3060 | * @retval VERR_NO_DIGITS
|
---|
| 3061 | *
|
---|
[1] | 3062 | * @param pszValue Pointer to the string value.
|
---|
| 3063 | * @param ppszNext Where to store the pointer to the first char following the number. (Optional)
|
---|
| 3064 | * @param uBase The base of the representation used.
|
---|
[460] | 3065 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[21741] | 3066 | * @param pi8 Where to store the converted number. (optional)
|
---|
[1] | 3067 | */
|
---|
| 3068 | RTDECL(int) RTStrToInt8Ex(const char *pszValue, char **ppszNext, unsigned uBase, int8_t *pi8);
|
---|
| 3069 |
|
---|
| 3070 | /**
|
---|
[5712] | 3071 | * Converts a string representation of a number to a 8-bit signed number,
|
---|
| 3072 | * making sure the full string is converted.
|
---|
| 3073 | *
|
---|
| 3074 | * @returns iprt status code.
|
---|
[18523] | 3075 | * Warnings are used to indicate conversion problems.
|
---|
[5712] | 3076 | * @retval VWRN_NUMBER_TOO_BIG
|
---|
| 3077 | * @retval VINF_SUCCESS
|
---|
| 3078 | * @retval VERR_TRAILING_CHARS
|
---|
| 3079 | * @retval VERR_TRAILING_SPACES
|
---|
| 3080 | * @retval VERR_NO_DIGITS
|
---|
| 3081 | *
|
---|
| 3082 | * @param pszValue Pointer to the string value.
|
---|
| 3083 | * @param uBase The base of the representation used.
|
---|
[14774] | 3084 | * If 0 the function will look for known prefixes before defaulting to 10.
|
---|
[7170] | 3085 | * @param pi8 Where to store the converted number. (optional)
|
---|
[5712] | 3086 | */
|
---|
| 3087 | RTDECL(int) RTStrToInt8Full(const char *pszValue, unsigned uBase, int8_t *pi8);
|
---|
| 3088 |
|
---|
| 3089 | /**
|
---|
[1] | 3090 | * Converts a string representation of a number to a 8-bit signed number.
|
---|
| 3091 | * The base is guessed.
|
---|
| 3092 | *
|
---|
| 3093 | * @returns 8-bit signed number on success.
|
---|
| 3094 | * @returns 0 on failure.
|
---|
| 3095 | * @param pszValue Pointer to the string value.
|
---|
| 3096 | */
|
---|
| 3097 | RTDECL(int8_t) RTStrToInt8(const char *pszValue);
|
---|
| 3098 |
|
---|
[23507] | 3099 | /**
|
---|
| 3100 | * Formats a buffer stream as hex bytes.
|
---|
| 3101 | *
|
---|
| 3102 | * The default is no separating spaces or line breaks or anything.
|
---|
| 3103 | *
|
---|
| 3104 | * @returns IPRT status code.
|
---|
| 3105 | * @retval VERR_INVALID_POINTER if any of the pointers are wrong.
|
---|
| 3106 | * @retval VERR_BUFFER_OVERFLOW if the buffer is insufficent to hold the bytes.
|
---|
| 3107 | *
|
---|
| 3108 | * @param pszBuf Output string buffer.
|
---|
[60028] | 3109 | * @param cbBuf The size of the output buffer.
|
---|
[23507] | 3110 | * @param pv Pointer to the bytes to stringify.
|
---|
| 3111 | * @param cb The number of bytes to stringify.
|
---|
[51770] | 3112 | * @param fFlags Combination of RTSTRPRINTHEXBYTES_F_XXX values.
|
---|
| 3113 | * @sa RTUtf16PrintHexBytes.
|
---|
[23507] | 3114 | */
|
---|
[60028] | 3115 | RTDECL(int) RTStrPrintHexBytes(char *pszBuf, size_t cbBuf, void const *pv, size_t cb, uint32_t fFlags);
|
---|
[51770] | 3116 | /** @name RTSTRPRINTHEXBYTES_F_XXX - flags for RTStrPrintHexBytes and RTUtf16PritnHexBytes.
|
---|
| 3117 | * @{ */
|
---|
| 3118 | /** Upper case hex digits, the default is lower case. */
|
---|
| 3119 | #define RTSTRPRINTHEXBYTES_F_UPPER RT_BIT(0)
|
---|
[60028] | 3120 | /** Add a space between each group. */
|
---|
| 3121 | #define RTSTRPRINTHEXBYTES_F_SEP_SPACE RT_BIT(1)
|
---|
| 3122 | /** Add a colon between each group. */
|
---|
| 3123 | #define RTSTRPRINTHEXBYTES_F_SEP_COLON RT_BIT(2)
|
---|
[51770] | 3124 | /** @} */
|
---|
[23507] | 3125 |
|
---|
| 3126 | /**
|
---|
| 3127 | * Converts a string of hex bytes back into binary data.
|
---|
| 3128 | *
|
---|
| 3129 | * @returns IPRT status code.
|
---|
| 3130 | * @retval VERR_INVALID_POINTER if any of the pointers are wrong.
|
---|
| 3131 | * @retval VERR_BUFFER_OVERFLOW if the string contains too many hex bytes.
|
---|
| 3132 | * @retval VERR_BUFFER_UNDERFLOW if there aren't enough hex bytes to fill up
|
---|
| 3133 | * the output buffer.
|
---|
| 3134 | * @retval VERR_UNEVEN_INPUT if the input contains a half byte.
|
---|
| 3135 | * @retval VERR_NO_DIGITS
|
---|
| 3136 | * @retval VWRN_TRAILING_CHARS
|
---|
| 3137 | * @retval VWRN_TRAILING_SPACES
|
---|
| 3138 | *
|
---|
| 3139 | * @param pszHex The string containing the hex bytes.
|
---|
| 3140 | * @param pv Output buffer.
|
---|
| 3141 | * @param cb The size of the output buffer.
|
---|
| 3142 | * @param fFlags Must be zero, reserved for future use.
|
---|
| 3143 | */
|
---|
| 3144 | RTDECL(int) RTStrConvertHexBytes(char const *pszHex, void *pv, size_t cb, uint32_t fFlags);
|
---|
| 3145 |
|
---|
[1] | 3146 | /** @} */
|
---|
| 3147 |
|
---|
| 3148 |
|
---|
| 3149 | /** @defgroup rt_str_space Unique String Space
|
---|
| 3150 | * @{
|
---|
| 3151 | */
|
---|
| 3152 |
|
---|
| 3153 | /** Pointer to a string name space container node core. */
|
---|
| 3154 | typedef struct RTSTRSPACECORE *PRTSTRSPACECORE;
|
---|
| 3155 | /** Pointer to a pointer to a string name space container node core. */
|
---|
| 3156 | typedef PRTSTRSPACECORE *PPRTSTRSPACECORE;
|
---|
| 3157 |
|
---|
| 3158 | /**
|
---|
| 3159 | * String name space container node core.
|
---|
| 3160 | */
|
---|
| 3161 | typedef struct RTSTRSPACECORE
|
---|
| 3162 | {
|
---|
| 3163 | /** Pointer to the left leaf node. Don't touch. */
|
---|
| 3164 | PRTSTRSPACECORE pLeft;
|
---|
[33540] | 3165 | /** Pointer to the left right node. Don't touch. */
|
---|
[1] | 3166 | PRTSTRSPACECORE pRight;
|
---|
[73935] | 3167 | /** Pointer to the list of string with the same hash key value. Don't touch. */
|
---|
[1] | 3168 | PRTSTRSPACECORE pList;
|
---|
[73935] | 3169 | /** Hash key. Don't touch. */
|
---|
| 3170 | uint32_t Key;
|
---|
[1] | 3171 | /** Height of this tree: max(heigth(left), heigth(right)) + 1. Don't touch */
|
---|
| 3172 | unsigned char uchHeight;
|
---|
| 3173 | /** The string length. Read only! */
|
---|
| 3174 | size_t cchString;
|
---|
| 3175 | /** Pointer to the string. Read only! */
|
---|
[20739] | 3176 | const char *pszString;
|
---|
[1] | 3177 | } RTSTRSPACECORE;
|
---|
| 3178 |
|
---|
| 3179 | /** String space. (Initialize with NULL.) */
|
---|
| 3180 | typedef PRTSTRSPACECORE RTSTRSPACE;
|
---|
| 3181 | /** Pointer to a string space. */
|
---|
| 3182 | typedef PPRTSTRSPACECORE PRTSTRSPACE;
|
---|
| 3183 |
|
---|
| 3184 |
|
---|
| 3185 | /**
|
---|
| 3186 | * Inserts a string into a unique string space.
|
---|
| 3187 | *
|
---|
| 3188 | * @returns true on success.
|
---|
[18523] | 3189 | * @returns false if the string collided with an existing string.
|
---|
[1] | 3190 | * @param pStrSpace The space to insert it into.
|
---|
| 3191 | * @param pStr The string node.
|
---|
| 3192 | */
|
---|
| 3193 | RTDECL(bool) RTStrSpaceInsert(PRTSTRSPACE pStrSpace, PRTSTRSPACECORE pStr);
|
---|
| 3194 |
|
---|
| 3195 | /**
|
---|
| 3196 | * Removes a string from a unique string space.
|
---|
| 3197 | *
|
---|
| 3198 | * @returns Pointer to the removed string node.
|
---|
| 3199 | * @returns NULL if the string was not found in the string space.
|
---|
[40771] | 3200 | * @param pStrSpace The space to remove it from.
|
---|
[1] | 3201 | * @param pszString The string to remove.
|
---|
| 3202 | */
|
---|
| 3203 | RTDECL(PRTSTRSPACECORE) RTStrSpaceRemove(PRTSTRSPACE pStrSpace, const char *pszString);
|
---|
| 3204 |
|
---|
| 3205 | /**
|
---|
| 3206 | * Gets a string from a unique string space.
|
---|
| 3207 | *
|
---|
| 3208 | * @returns Pointer to the string node.
|
---|
| 3209 | * @returns NULL if the string was not found in the string space.
|
---|
[40771] | 3210 | * @param pStrSpace The space to get it from.
|
---|
[1] | 3211 | * @param pszString The string to get.
|
---|
| 3212 | */
|
---|
| 3213 | RTDECL(PRTSTRSPACECORE) RTStrSpaceGet(PRTSTRSPACE pStrSpace, const char *pszString);
|
---|
| 3214 |
|
---|
| 3215 | /**
|
---|
[35464] | 3216 | * Gets a string from a unique string space.
|
---|
| 3217 | *
|
---|
| 3218 | * @returns Pointer to the string node.
|
---|
| 3219 | * @returns NULL if the string was not found in the string space.
|
---|
[40771] | 3220 | * @param pStrSpace The space to get it from.
|
---|
[35464] | 3221 | * @param pszString The string to get.
|
---|
| 3222 | * @param cchMax The max string length to evaluate. Passing
|
---|
| 3223 | * RTSTR_MAX is ok and makes it behave just like
|
---|
| 3224 | * RTStrSpaceGet.
|
---|
| 3225 | */
|
---|
| 3226 | RTDECL(PRTSTRSPACECORE) RTStrSpaceGetN(PRTSTRSPACE pStrSpace, const char *pszString, size_t cchMax);
|
---|
| 3227 |
|
---|
| 3228 | /**
|
---|
[1] | 3229 | * Callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy().
|
---|
| 3230 | *
|
---|
| 3231 | * @returns 0 on continue.
|
---|
| 3232 | * @returns Non-zero to aborts the operation.
|
---|
| 3233 | * @param pStr The string node
|
---|
| 3234 | * @param pvUser The user specified argument.
|
---|
| 3235 | */
|
---|
| 3236 | typedef DECLCALLBACK(int) FNRTSTRSPACECALLBACK(PRTSTRSPACECORE pStr, void *pvUser);
|
---|
| 3237 | /** Pointer to callback function for RTStrSpaceEnumerate() and RTStrSpaceDestroy(). */
|
---|
| 3238 | typedef FNRTSTRSPACECALLBACK *PFNRTSTRSPACECALLBACK;
|
---|
| 3239 |
|
---|
| 3240 | /**
|
---|
| 3241 | * Destroys the string space.
|
---|
| 3242 | *
|
---|
[34379] | 3243 | * The caller supplies a callback which will be called for each of the string
|
---|
| 3244 | * nodes in for freeing their memory and other resources.
|
---|
| 3245 | *
|
---|
[1] | 3246 | * @returns 0 or what ever non-zero return value pfnCallback returned
|
---|
| 3247 | * when aborting the destruction.
|
---|
[40771] | 3248 | * @param pStrSpace The space to destroy.
|
---|
[1] | 3249 | * @param pfnCallback The callback.
|
---|
| 3250 | * @param pvUser The user argument.
|
---|
| 3251 | */
|
---|
| 3252 | RTDECL(int) RTStrSpaceDestroy(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser);
|
---|
| 3253 |
|
---|
| 3254 | /**
|
---|
| 3255 | * Enumerates the string space.
|
---|
| 3256 | * The caller supplies a callback which will be called for each of
|
---|
| 3257 | * the string nodes.
|
---|
| 3258 | *
|
---|
| 3259 | * @returns 0 or what ever non-zero return value pfnCallback returned
|
---|
| 3260 | * when aborting the destruction.
|
---|
[40771] | 3261 | * @param pStrSpace The space to enumerate.
|
---|
[1] | 3262 | * @param pfnCallback The callback.
|
---|
| 3263 | * @param pvUser The user argument.
|
---|
| 3264 | */
|
---|
| 3265 | RTDECL(int) RTStrSpaceEnumerate(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser);
|
---|
| 3266 |
|
---|
| 3267 | /** @} */
|
---|
| 3268 |
|
---|
| 3269 |
|
---|
[40052] | 3270 | /** @defgroup rt_str_hash Sting hashing
|
---|
| 3271 | * @{ */
|
---|
| 3272 |
|
---|
| 3273 | /**
|
---|
| 3274 | * Hashes the given string using algorithm \#1.
|
---|
| 3275 | *
|
---|
| 3276 | * @returns String hash.
|
---|
| 3277 | * @param pszString The string to hash.
|
---|
| 3278 | */
|
---|
| 3279 | RTDECL(uint32_t) RTStrHash1(const char *pszString);
|
---|
| 3280 |
|
---|
| 3281 | /**
|
---|
| 3282 | * Hashes the given string using algorithm \#1.
|
---|
| 3283 | *
|
---|
| 3284 | * @returns String hash.
|
---|
| 3285 | * @param pszString The string to hash.
|
---|
| 3286 | * @param cchString The max length to hash. Hashing will stop if the
|
---|
| 3287 | * terminator character is encountered first. Passing
|
---|
| 3288 | * RTSTR_MAX is fine.
|
---|
| 3289 | */
|
---|
| 3290 | RTDECL(uint32_t) RTStrHash1N(const char *pszString, size_t cchString);
|
---|
| 3291 |
|
---|
| 3292 | /**
|
---|
| 3293 | * Hashes the given strings as if they were concatenated using algorithm \#1.
|
---|
| 3294 | *
|
---|
| 3295 | * @returns String hash.
|
---|
| 3296 | * @param cPairs The number of string / length pairs in the
|
---|
| 3297 | * ellipsis.
|
---|
| 3298 | * @param ... List of string (const char *) and length
|
---|
| 3299 | * (size_t) pairs. Passing RTSTR_MAX as the size is
|
---|
| 3300 | * fine.
|
---|
| 3301 | */
|
---|
| 3302 | RTDECL(uint32_t) RTStrHash1ExN(size_t cPairs, ...);
|
---|
| 3303 |
|
---|
| 3304 | /**
|
---|
| 3305 | * Hashes the given strings as if they were concatenated using algorithm \#1.
|
---|
| 3306 | *
|
---|
| 3307 | * @returns String hash.
|
---|
| 3308 | * @param cPairs The number of string / length pairs in the @a va.
|
---|
| 3309 | * @param va List of string (const char *) and length
|
---|
| 3310 | * (size_t) pairs. Passing RTSTR_MAX as the size is
|
---|
| 3311 | * fine.
|
---|
| 3312 | */
|
---|
| 3313 | RTDECL(uint32_t) RTStrHash1ExNV(size_t cPairs, va_list va);
|
---|
| 3314 |
|
---|
| 3315 | /** @} */
|
---|
| 3316 |
|
---|
[1] | 3317 | /** @} */
|
---|
| 3318 |
|
---|
[20374] | 3319 | RT_C_DECLS_END
|
---|
[1] | 3320 |
|
---|
[76585] | 3321 | #endif /* !IPRT_INCLUDED_string_h */
|
---|
[1] | 3322 |
|
---|