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