[6076] | 1 | /* $Id: string.h 93115 2022-01-01 11:31:46Z vboxsync $ */
|
---|
[1] | 2 | /** @file
|
---|
[36429] | 3 | * MS COM / XPCOM Abstraction Layer - Smart string classes declaration.
|
---|
[1] | 4 | */
|
---|
| 5 |
|
---|
| 6 | /*
|
---|
[93115] | 7 | * Copyright (C) 2006-2022 Oracle Corporation
|
---|
[1] | 8 | *
|
---|
| 9 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
| 10 | * available from http://www.virtualbox.org. This file is free software;
|
---|
| 11 | * you can redistribute it and/or modify it under the terms of the GNU
|
---|
[5999] | 12 | * General Public License (GPL) as published by the Free Software
|
---|
| 13 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
| 14 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
| 15 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
| 16 | *
|
---|
| 17 | * The contents of this file may alternatively be used under the terms
|
---|
| 18 | * of the Common Development and Distribution License Version 1.0
|
---|
| 19 | * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
|
---|
| 20 | * VirtualBox OSE distribution, in which case the provisions of the
|
---|
| 21 | * CDDL are applicable instead of those of the GPL.
|
---|
| 22 | *
|
---|
| 23 | * You may elect to license modified versions of this file under the
|
---|
| 24 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
[1] | 25 | */
|
---|
| 26 |
|
---|
[76558] | 27 | #ifndef VBOX_INCLUDED_com_string_h
|
---|
| 28 | #define VBOX_INCLUDED_com_string_h
|
---|
[76507] | 29 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 30 | # pragma once
|
---|
| 31 | #endif
|
---|
[1] | 32 |
|
---|
[9332] | 33 | /* Make sure all the stdint.h macros are included - must come first! */
|
---|
| 34 | #ifndef __STDC_LIMIT_MACROS
|
---|
| 35 | # define __STDC_LIMIT_MACROS
|
---|
| 36 | #endif
|
---|
| 37 | #ifndef __STDC_CONSTANT_MACROS
|
---|
| 38 | # define __STDC_CONSTANT_MACROS
|
---|
| 39 | #endif
|
---|
| 40 |
|
---|
[32727] | 41 | #if defined(VBOX_WITH_XPCOM)
|
---|
[9332] | 42 | # include <nsMemory.h>
|
---|
[1] | 43 | #endif
|
---|
| 44 |
|
---|
| 45 | #include "VBox/com/defs.h"
|
---|
| 46 | #include "VBox/com/assert.h"
|
---|
| 47 |
|
---|
[34785] | 48 | #include <iprt/mem.h>
|
---|
[76408] | 49 | #include <iprt/utf16.h>
|
---|
[25349] | 50 | #include <iprt/cpp/ministring.h>
|
---|
[1] | 51 |
|
---|
[58110] | 52 |
|
---|
| 53 | /** @defgroup grp_com_str Smart String Classes
|
---|
| 54 | * @ingroup grp_com
|
---|
| 55 | * @{
|
---|
| 56 | */
|
---|
| 57 |
|
---|
[1] | 58 | namespace com
|
---|
| 59 | {
|
---|
| 60 |
|
---|
| 61 | class Utf8Str;
|
---|
| 62 |
|
---|
[26753] | 63 | // global constant in glue/string.cpp that represents an empty BSTR
|
---|
| 64 | extern const BSTR g_bstrEmpty;
|
---|
| 65 |
|
---|
[1] | 66 | /**
|
---|
[26753] | 67 | * String class used universally in Main for COM-style Utf-16 strings.
|
---|
[1] | 68 | *
|
---|
[36428] | 69 | * Unfortunately COM on Windows uses UTF-16 everywhere, requiring conversions
|
---|
| 70 | * back and forth since most of VirtualBox and our libraries use UTF-8.
|
---|
[26753] | 71 | *
|
---|
[36428] | 72 | * To make things more obscure, on Windows, a COM-style BSTR is not just a
|
---|
| 73 | * pointer to a null-terminated wide character array, but the four bytes (32
|
---|
| 74 | * bits) BEFORE the memory that the pointer points to are a length DWORD. One
|
---|
| 75 | * must therefore avoid pointer arithmetic and always use SysAllocString and
|
---|
| 76 | * the like to deal with BSTR pointers, which manage that DWORD correctly.
|
---|
[26753] | 77 | *
|
---|
[36428] | 78 | * For platforms other than Windows, we provide our own versions of the Sys*
|
---|
| 79 | * functions in Main/xpcom/helpers.cpp which do NOT use length prefixes though
|
---|
| 80 | * to be compatible with how XPCOM allocates string parameters to public
|
---|
| 81 | * functions.
|
---|
[26753] | 82 | *
|
---|
[36428] | 83 | * The Bstr class hides all this handling behind a std::string-like interface
|
---|
[36527] | 84 | * and also provides automatic conversions to RTCString and Utf8Str instances.
|
---|
[26753] | 85 | *
|
---|
[36428] | 86 | * The one advantage of using the SysString* routines is that this makes it
|
---|
| 87 | * possible to use it as a type of member variables of COM/XPCOM components and
|
---|
| 88 | * pass their values to callers through component methods' output parameters
|
---|
| 89 | * using the #cloneTo() operation. Also, the class can adopt (take ownership
|
---|
| 90 | * of) string buffers returned in output parameters of COM methods using the
|
---|
| 91 | * #asOutParam() operation and correctly free them afterwards.
|
---|
| 92 | *
|
---|
| 93 | * Starting with VirtualBox 3.2, like Utf8Str, Bstr no longer differentiates
|
---|
| 94 | * between NULL strings and empty strings. In other words, Bstr("") and
|
---|
| 95 | * Bstr(NULL) behave the same. In both cases, Bstr allocates no memory,
|
---|
| 96 | * reports a zero length and zero allocated bytes for both, and returns an
|
---|
| 97 | * empty C wide string from raw().
|
---|
| 98 | *
|
---|
| 99 | * @note All Bstr methods ASSUMES valid UTF-16 or UTF-8 input strings.
|
---|
| 100 | * The VirtualBox policy in this regard is to validate strings coming
|
---|
| 101 | * from external sources before passing them to Bstr or Utf8Str.
|
---|
[1] | 102 | */
|
---|
| 103 | class Bstr
|
---|
| 104 | {
|
---|
| 105 | public:
|
---|
| 106 |
|
---|
[26753] | 107 | Bstr()
|
---|
| 108 | : m_bstr(NULL)
|
---|
| 109 | { }
|
---|
[1] | 110 |
|
---|
[26753] | 111 | Bstr(const Bstr &that)
|
---|
| 112 | {
|
---|
| 113 | copyFrom((const OLECHAR *)that.m_bstr);
|
---|
| 114 | }
|
---|
[1] | 115 |
|
---|
[26753] | 116 | Bstr(CBSTR that)
|
---|
| 117 | {
|
---|
| 118 | copyFrom((const OLECHAR *)that);
|
---|
| 119 | }
|
---|
[15051] | 120 |
|
---|
[32727] | 121 | #if defined(VBOX_WITH_XPCOM)
|
---|
[26753] | 122 | Bstr(const wchar_t *that)
|
---|
[1] | 123 | {
|
---|
[26239] | 124 | AssertCompile(sizeof(wchar_t) == sizeof(OLECHAR));
|
---|
[26753] | 125 | copyFrom((const OLECHAR *)that);
|
---|
[1] | 126 | }
|
---|
[15051] | 127 | #endif
|
---|
[1] | 128 |
|
---|
[36527] | 129 | Bstr(const RTCString &that)
|
---|
[26753] | 130 | {
|
---|
[31539] | 131 | copyFrom(that.c_str());
|
---|
[26753] | 132 | }
|
---|
[1] | 133 |
|
---|
[26753] | 134 | Bstr(const char *that)
|
---|
| 135 | {
|
---|
| 136 | copyFrom(that);
|
---|
| 137 | }
|
---|
[26553] | 138 |
|
---|
[34846] | 139 | Bstr(const char *a_pThat, size_t a_cchMax)
|
---|
| 140 | {
|
---|
| 141 | copyFromN(a_pThat, a_cchMax);
|
---|
| 142 | }
|
---|
| 143 |
|
---|
[26753] | 144 | ~Bstr()
|
---|
| 145 | {
|
---|
| 146 | setNull();
|
---|
| 147 | }
|
---|
[26603] | 148 |
|
---|
[80793] | 149 | Bstr &operator=(const Bstr &that)
|
---|
[26753] | 150 | {
|
---|
[80850] | 151 | cleanupAndCopyFrom((const OLECHAR *)that.m_bstr);
|
---|
[26753] | 152 | return *this;
|
---|
| 153 | }
|
---|
[26603] | 154 |
|
---|
[80793] | 155 | Bstr &operator=(CBSTR that)
|
---|
[2012] | 156 | {
|
---|
[80850] | 157 | cleanupAndCopyFrom((const OLECHAR *)that);
|
---|
[26603] | 158 | return *this;
|
---|
[1] | 159 | }
|
---|
| 160 |
|
---|
[32727] | 161 | #if defined(VBOX_WITH_XPCOM)
|
---|
[80793] | 162 | Bstr &operator=(const wchar_t *that)
|
---|
[2012] | 163 | {
|
---|
[80850] | 164 | cleanupAndCopyFrom((const OLECHAR *)that);
|
---|
[26603] | 165 | return *this;
|
---|
[1] | 166 | }
|
---|
[26753] | 167 | #endif
|
---|
[1] | 168 |
|
---|
[80793] | 169 | Bstr &setNull()
|
---|
[2012] | 170 | {
|
---|
[26753] | 171 | cleanup();
|
---|
[26603] | 172 | return *this;
|
---|
[2012] | 173 | }
|
---|
| 174 |
|
---|
[85288] | 175 | /**
|
---|
| 176 | * Extended assignment method that returns a COM status code instead of an
|
---|
| 177 | * exception on failure.
|
---|
| 178 | *
|
---|
| 179 | * @returns S_OK or E_OUTOFMEMORY.
|
---|
| 180 | * @param a_rSrcStr The source string
|
---|
| 181 | */
|
---|
| 182 | HRESULT assignEx(const Bstr &a_rSrcStr) RT_NOEXCEPT
|
---|
| 183 | {
|
---|
| 184 | return cleanupAndCopyFromEx((const OLECHAR *)a_rSrcStr.m_bstr);
|
---|
| 185 | }
|
---|
| 186 |
|
---|
| 187 | /**
|
---|
| 188 | * Extended assignment method that returns a COM status code instead of an
|
---|
| 189 | * exception on failure.
|
---|
| 190 | *
|
---|
| 191 | * @returns S_OK or E_OUTOFMEMORY.
|
---|
| 192 | * @param a_pSrcStr The source string
|
---|
| 193 | */
|
---|
| 194 | HRESULT assignEx(CBSTR a_pSrcStr) RT_NOEXCEPT
|
---|
| 195 | {
|
---|
| 196 | return cleanupAndCopyFromEx((const OLECHAR *)a_pSrcStr);
|
---|
| 197 | }
|
---|
| 198 |
|
---|
[85308] | 199 | /**
|
---|
| 200 | * Assign the value of a RTCString/Utf8Str string, no exceptions.
|
---|
| 201 | *
|
---|
| 202 | * @returns S_OK or E_OUTOFMEMORY.
|
---|
| 203 | * @param a_rSrcStr The source string
|
---|
| 204 | */
|
---|
| 205 | HRESULT assignEx(RTCString const &a_rSrcStr) RT_NOEXCEPT
|
---|
| 206 | {
|
---|
| 207 | return cleanupAndCopyFromNoThrow(a_rSrcStr.c_str(), a_rSrcStr.length());
|
---|
| 208 | }
|
---|
| 209 |
|
---|
| 210 | /**
|
---|
| 211 | * Assign the value of a RTCString/Utf8Str substring, no exceptions.
|
---|
| 212 | *
|
---|
| 213 | * @returns S_OK, E_OUTOFMEMORY or E_INVALIDARG.
|
---|
| 214 | * @param a_rSrcStr The source string
|
---|
| 215 | * @param a_offSrc The character (byte) offset of the substring.
|
---|
| 216 | * @param a_cchSrc The number of characters (bytes) to copy from the source
|
---|
| 217 | * string.
|
---|
| 218 | */
|
---|
| 219 | HRESULT assignEx(RTCString const &a_rSrcStr, size_t a_offSrc, size_t a_cchSrc) RT_NOEXCEPT
|
---|
| 220 | {
|
---|
| 221 | size_t const cchTmp = a_rSrcStr.length();
|
---|
| 222 | if ( a_offSrc + a_cchSrc < cchTmp
|
---|
| 223 | && a_offSrc < cchTmp)
|
---|
| 224 | return cleanupAndCopyFromNoThrow(a_rSrcStr.c_str() + a_offSrc, a_cchSrc);
|
---|
| 225 | return E_INVALIDARG;
|
---|
| 226 | }
|
---|
| 227 |
|
---|
| 228 | /**
|
---|
| 229 | * Assign the value of a zero terminated UTF-8 string, no exceptions.
|
---|
| 230 | *
|
---|
| 231 | * @returns S_OK or E_OUTOFMEMORY.
|
---|
| 232 | * @param a_pszSrcStr The source string.
|
---|
| 233 | */
|
---|
| 234 | HRESULT assignEx(const char *a_pszSrcStr) RT_NOEXCEPT
|
---|
| 235 | {
|
---|
| 236 | return cleanupAndCopyFromNoThrow(a_pszSrcStr, RTSTR_MAX);
|
---|
| 237 | }
|
---|
| 238 |
|
---|
| 239 | /**
|
---|
| 240 | * Assign the value of a UTF-8 substring, no exceptions.
|
---|
| 241 | *
|
---|
| 242 | * @returns S_OK or E_OUTOFMEMORY.
|
---|
| 243 | * @param a_pszSrcStr The source string.
|
---|
| 244 | * @param a_cchSrc The number of characters (bytes) to copy from the source
|
---|
| 245 | * string.
|
---|
| 246 | */
|
---|
| 247 | HRESULT assignEx(const char *a_pszSrcStr, size_t a_cchSrc) RT_NOEXCEPT
|
---|
| 248 | {
|
---|
| 249 | return cleanupAndCopyFromNoThrow(a_pszSrcStr, a_cchSrc);
|
---|
| 250 | }
|
---|
| 251 |
|
---|
[40875] | 252 | #ifdef _MSC_VER
|
---|
| 253 | # if _MSC_VER >= 1400
|
---|
[34785] | 254 | RTMEMEF_NEW_AND_DELETE_OPERATORS();
|
---|
[40875] | 255 | # endif
|
---|
| 256 | #else
|
---|
| 257 | RTMEMEF_NEW_AND_DELETE_OPERATORS();
|
---|
| 258 | #endif
|
---|
[34785] | 259 |
|
---|
[26753] | 260 | /** Case sensitivity selector. */
|
---|
| 261 | enum CaseSensitivity
|
---|
[2012] | 262 | {
|
---|
[26753] | 263 | CaseSensitive,
|
---|
| 264 | CaseInsensitive
|
---|
| 265 | };
|
---|
| 266 |
|
---|
| 267 | /**
|
---|
| 268 | * Compares the member string to str.
|
---|
| 269 | * @param str
|
---|
| 270 | * @param cs Whether comparison should be case-sensitive.
|
---|
| 271 | * @return
|
---|
| 272 | */
|
---|
| 273 | int compare(CBSTR str, CaseSensitivity cs = CaseSensitive) const
|
---|
| 274 | {
|
---|
| 275 | if (cs == CaseSensitive)
|
---|
| 276 | return ::RTUtf16Cmp((PRTUTF16)m_bstr, (PRTUTF16)str);
|
---|
| 277 | return ::RTUtf16LocaleICmp((PRTUTF16)m_bstr, (PRTUTF16)str);
|
---|
[1] | 278 | }
|
---|
| 279 |
|
---|
[32718] | 280 | int compare(BSTR str, CaseSensitivity cs = CaseSensitive) const
|
---|
[15051] | 281 | {
|
---|
[32718] | 282 | return compare((CBSTR)str, cs);
|
---|
[15051] | 283 | }
|
---|
| 284 |
|
---|
[32718] | 285 | int compare(const Bstr &that, CaseSensitivity cs = CaseSensitive) const
|
---|
| 286 | {
|
---|
| 287 | return compare(that.m_bstr, cs);
|
---|
| 288 | }
|
---|
| 289 |
|
---|
[26753] | 290 | bool operator==(const Bstr &that) const { return !compare(that.m_bstr); }
|
---|
[48691] | 291 | bool operator==(CBSTR that) const { return !compare(that); }
|
---|
| 292 | bool operator==(BSTR that) const { return !compare(that); }
|
---|
[26753] | 293 | bool operator!=(const Bstr &that) const { return !!compare(that.m_bstr); }
|
---|
[48691] | 294 | bool operator!=(CBSTR that) const { return !!compare(that); }
|
---|
| 295 | bool operator!=(BSTR that) const { return !!compare(that); }
|
---|
| 296 | bool operator<(const Bstr &that) const { return compare(that.m_bstr) < 0; }
|
---|
| 297 | bool operator<(CBSTR that) const { return compare(that) < 0; }
|
---|
| 298 | bool operator<(BSTR that) const { return compare(that) < 0; }
|
---|
| 299 | bool operator<=(const Bstr &that) const { return compare(that.m_bstr) <= 0; }
|
---|
| 300 | bool operator<=(CBSTR that) const { return compare(that) <= 0; }
|
---|
| 301 | bool operator<=(BSTR that) const { return compare(that) <= 0; }
|
---|
| 302 | bool operator>(const Bstr &that) const { return compare(that.m_bstr) > 0; }
|
---|
| 303 | bool operator>(CBSTR that) const { return compare(that) > 0; }
|
---|
| 304 | bool operator>(BSTR that) const { return compare(that) > 0; }
|
---|
| 305 | bool operator>=(const Bstr &that) const { return compare(that.m_bstr) >= 0; }
|
---|
| 306 | bool operator>=(CBSTR that) const { return compare(that) >= 0; }
|
---|
| 307 | bool operator>=(BSTR that) const { return compare(that) >= 0; }
|
---|
[26603] | 308 |
|
---|
[26753] | 309 | /**
|
---|
[60409] | 310 | * Compares this string to an UTF-8 C style string.
|
---|
| 311 | *
|
---|
| 312 | * @retval 0 if equal
|
---|
| 313 | * @retval -1 if this string is smaller than the UTF-8 one.
|
---|
| 314 | * @retval 1 if the UTF-8 string is smaller than this.
|
---|
| 315 | *
|
---|
| 316 | * @param a_pszRight The string to compare with.
|
---|
| 317 | * @param a_enmCase Whether comparison should be case-sensitive.
|
---|
| 318 | */
|
---|
| 319 | int compareUtf8(const char *a_pszRight, CaseSensitivity a_enmCase = CaseSensitive) const;
|
---|
| 320 |
|
---|
| 321 | /** Java style compare method.
|
---|
| 322 | * @returns true if @a a_pszRight equals this string.
|
---|
| 323 | * @param a_pszRight The (UTF-8) string to compare with. */
|
---|
| 324 | bool equals(const char *a_pszRight) const { return compareUtf8(a_pszRight, CaseSensitive) == 0; }
|
---|
| 325 |
|
---|
| 326 | /** Java style case-insensitive compare method.
|
---|
| 327 | * @returns true if @a a_pszRight equals this string.
|
---|
| 328 | * @param a_pszRight The (UTF-8) string to compare with. */
|
---|
| 329 | bool equalsIgnoreCase(const char *a_pszRight) const { return compareUtf8(a_pszRight, CaseInsensitive) == 0; }
|
---|
| 330 |
|
---|
| 331 | /** Java style compare method.
|
---|
| 332 | * @returns true if @a a_rThat equals this string.
|
---|
| 333 | * @param a_rThat The other Bstr instance to compare with. */
|
---|
| 334 | bool equals(const Bstr &a_rThat) const { return compare(a_rThat.m_bstr, CaseSensitive) == 0; }
|
---|
| 335 | /** Java style case-insensitive compare method.
|
---|
| 336 | * @returns true if @a a_rThat equals this string.
|
---|
| 337 | * @param a_rThat The other Bstr instance to compare with. */
|
---|
| 338 | bool equalsIgnoreCase(const Bstr &a_rThat) const { return compare(a_rThat.m_bstr, CaseInsensitive) == 0; }
|
---|
| 339 |
|
---|
| 340 | /** Java style compare method.
|
---|
| 341 | * @returns true if @a a_pThat equals this string.
|
---|
| 342 | * @param a_pThat The native const BSTR to compare with. */
|
---|
| 343 | bool equals(CBSTR a_pThat) const { return compare(a_pThat, CaseSensitive) == 0; }
|
---|
| 344 | /** Java style case-insensitive compare method.
|
---|
| 345 | * @returns true if @a a_pThat equals this string.
|
---|
| 346 | * @param a_pThat The native const BSTR to compare with. */
|
---|
| 347 | bool equalsIgnoreCase(CBSTR a_pThat) const { return compare(a_pThat, CaseInsensitive) == 0; }
|
---|
| 348 |
|
---|
| 349 | /** Java style compare method.
|
---|
| 350 | * @returns true if @a a_pThat equals this string.
|
---|
| 351 | * @param a_pThat The native BSTR to compare with. */
|
---|
| 352 | bool equals(BSTR a_pThat) const { return compare(a_pThat, CaseSensitive) == 0; }
|
---|
| 353 | /** Java style case-insensitive compare method.
|
---|
| 354 | * @returns true if @a a_pThat equals this string.
|
---|
| 355 | * @param a_pThat The native BSTR to compare with. */
|
---|
| 356 | bool equalsIgnoreCase(BSTR a_pThat) const { return compare(a_pThat, CaseInsensitive) == 0; }
|
---|
| 357 |
|
---|
| 358 | /**
|
---|
[93105] | 359 | * Checks if the string starts with @a a_rStart.
|
---|
| 360 | */
|
---|
| 361 | bool startsWith(Bstr const &a_rStart) const;
|
---|
| 362 | /**
|
---|
| 363 | * Checks if the string starts with @a a_rStart.
|
---|
| 364 | */
|
---|
| 365 | bool startsWith(RTCString const &a_rStart) const;
|
---|
| 366 | /**
|
---|
| 367 | * Checks if the string starts with @a a_pszStart.
|
---|
| 368 | */
|
---|
| 369 | bool startsWith(const char *a_pszStart) const;
|
---|
| 370 |
|
---|
| 371 | /**
|
---|
[26753] | 372 | * Returns true if the member string has no length.
|
---|
| 373 | * This is true for instances created from both NULL and "" input strings.
|
---|
| 374 | *
|
---|
| 375 | * @note Always use this method to check if an instance is empty. Do not
|
---|
| 376 | * use length() because that may need to run through the entire string
|
---|
[32718] | 377 | * (Bstr does not cache string lengths).
|
---|
[26753] | 378 | */
|
---|
| 379 | bool isEmpty() const { return m_bstr == NULL || *m_bstr == 0; }
|
---|
| 380 |
|
---|
[34242] | 381 | /**
|
---|
| 382 | * Returns true if the member string has a length of one or more.
|
---|
| 383 | *
|
---|
| 384 | * @returns true if not empty, false if empty (NULL or "").
|
---|
| 385 | */
|
---|
| 386 | bool isNotEmpty() const { return m_bstr != NULL && *m_bstr != 0; }
|
---|
| 387 |
|
---|
[26753] | 388 | size_t length() const { return isEmpty() ? 0 : ::RTUtf16Len((PRTUTF16)m_bstr); }
|
---|
| 389 |
|
---|
[80793] | 390 | /**
|
---|
| 391 | * Assigns the output of the string format operation (RTStrPrintf).
|
---|
| 392 | *
|
---|
| 393 | * @param pszFormat Pointer to the format string,
|
---|
| 394 | * @see pg_rt_str_format.
|
---|
| 395 | * @param ... Ellipsis containing the arguments specified by
|
---|
| 396 | * the format string.
|
---|
| 397 | *
|
---|
| 398 | * @throws std::bad_alloc On allocation error. Object state is undefined.
|
---|
| 399 | *
|
---|
| 400 | * @returns Reference to the object.
|
---|
| 401 | */
|
---|
| 402 | Bstr &printf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
|
---|
| 403 |
|
---|
| 404 | /**
|
---|
| 405 | * Assigns the output of the string format operation (RTStrPrintf).
|
---|
| 406 | *
|
---|
| 407 | * @param pszFormat Pointer to the format string,
|
---|
| 408 | * @see pg_rt_str_format.
|
---|
| 409 | * @param ... Ellipsis containing the arguments specified by
|
---|
| 410 | * the format string.
|
---|
| 411 | *
|
---|
[80836] | 412 | * @returns S_OK, E_OUTOFMEMORY or E_INVAL (bad encoding).
|
---|
[80793] | 413 | */
|
---|
| 414 | HRESULT printfNoThrow(const char *pszFormat, ...) RT_NOEXCEPT RT_IPRT_FORMAT_ATTR(1, 2);
|
---|
| 415 |
|
---|
| 416 | /**
|
---|
| 417 | * Assigns the output of the string format operation (RTStrPrintfV).
|
---|
| 418 | *
|
---|
| 419 | * @param pszFormat Pointer to the format string,
|
---|
| 420 | * @see pg_rt_str_format.
|
---|
| 421 | * @param va Argument vector containing the arguments
|
---|
| 422 | * specified by the format string.
|
---|
| 423 | *
|
---|
| 424 | * @throws std::bad_alloc On allocation error. Object state is undefined.
|
---|
| 425 | *
|
---|
| 426 | * @returns Reference to the object.
|
---|
| 427 | */
|
---|
| 428 | Bstr &printfV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
|
---|
| 429 |
|
---|
| 430 | /**
|
---|
| 431 | * Assigns the output of the string format operation (RTStrPrintfV).
|
---|
| 432 | *
|
---|
| 433 | * @param pszFormat Pointer to the format string,
|
---|
| 434 | * @see pg_rt_str_format.
|
---|
| 435 | * @param va Argument vector containing the arguments
|
---|
| 436 | * specified by the format string.
|
---|
| 437 | *
|
---|
[80836] | 438 | * @returns S_OK, E_OUTOFMEMORY or E_INVAL (bad encoding).
|
---|
[80793] | 439 | */
|
---|
| 440 | HRESULT printfVNoThrow(const char *pszFormat, va_list va) RT_NOEXCEPT RT_IPRT_FORMAT_ATTR(1, 0);
|
---|
| 441 |
|
---|
[80836] | 442 | /** @name Append methods and operators
|
---|
| 443 | * @{ */
|
---|
| 444 |
|
---|
| 445 | /**
|
---|
| 446 | * Appends the string @a that to @a rThat.
|
---|
| 447 | *
|
---|
| 448 | * @param rThat The string to append.
|
---|
| 449 | * @throws std::bad_alloc On allocation error. The object is left unchanged.
|
---|
| 450 | * @returns Reference to the object.
|
---|
| 451 | */
|
---|
| 452 | Bstr &append(const Bstr &rThat);
|
---|
| 453 |
|
---|
| 454 | /**
|
---|
| 455 | * Appends the string @a that to @a rThat.
|
---|
| 456 | *
|
---|
| 457 | * @param rThat The string to append.
|
---|
| 458 | * @returns S_OK, E_OUTOFMEMORY or E_INVAL (bad encoding).
|
---|
| 459 | */
|
---|
| 460 | HRESULT appendNoThrow(const Bstr &rThat) RT_NOEXCEPT;
|
---|
| 461 |
|
---|
| 462 | /**
|
---|
| 463 | * Appends the UTF-8 string @a that to @a rThat.
|
---|
| 464 | *
|
---|
| 465 | * @param rThat The string to append.
|
---|
| 466 | * @throws std::bad_alloc On allocation error. The object is left unchanged.
|
---|
| 467 | * @returns Reference to the object.
|
---|
| 468 | */
|
---|
| 469 | Bstr &append(const RTCString &rThat);
|
---|
| 470 |
|
---|
| 471 | /**
|
---|
| 472 | * Appends the UTF-8 string @a that to @a rThat.
|
---|
| 473 | *
|
---|
| 474 | * @param rThat The string to append.
|
---|
| 475 | * @returns S_OK, E_OUTOFMEMORY or E_INVAL (bad encoding).
|
---|
| 476 | */
|
---|
| 477 | HRESULT appendNoThrow(const RTCString &rThat) RT_NOEXCEPT;
|
---|
| 478 |
|
---|
| 479 | /**
|
---|
| 480 | * Appends the UTF-16 string @a pszSrc to @a this.
|
---|
| 481 | *
|
---|
| 482 | * @param pwszSrc The C-style UTF-16 string to append.
|
---|
| 483 | * @throws std::bad_alloc On allocation error. The object is left unchanged.
|
---|
| 484 | * @returns Reference to the object.
|
---|
| 485 | */
|
---|
| 486 | Bstr &append(CBSTR pwszSrc);
|
---|
| 487 |
|
---|
| 488 | /**
|
---|
| 489 | * Appends the UTF-16 string @a pszSrc to @a this.
|
---|
| 490 | *
|
---|
| 491 | * @param pwszSrc The C-style UTF-16 string to append.
|
---|
| 492 | * @returns S_OK, E_OUTOFMEMORY or E_INVAL (bad encoding).
|
---|
| 493 | */
|
---|
| 494 | HRESULT appendNoThrow(CBSTR pwszSrc) RT_NOEXCEPT;
|
---|
| 495 |
|
---|
| 496 | /**
|
---|
| 497 | * Appends the UTF-8 string @a pszSrc to @a this.
|
---|
| 498 | *
|
---|
| 499 | * @param pszSrc The C-style string to append.
|
---|
| 500 | * @throws std::bad_alloc On allocation error. The object is left unchanged.
|
---|
| 501 | * @returns Reference to the object.
|
---|
| 502 | */
|
---|
| 503 | Bstr &append(const char *pszSrc);
|
---|
| 504 |
|
---|
| 505 | /**
|
---|
| 506 | * Appends the UTF-8 string @a pszSrc to @a this.
|
---|
| 507 | *
|
---|
| 508 | * @param pszSrc The C-style string to append.
|
---|
| 509 | * @returns S_OK, E_OUTOFMEMORY or E_INVAL (bad encoding).
|
---|
| 510 | */
|
---|
| 511 | HRESULT appendNoThrow(const char *pszSrc) RT_NOEXCEPT;
|
---|
| 512 |
|
---|
| 513 | /**
|
---|
| 514 | * Appends the a substring from @a rThat to @a this.
|
---|
| 515 | *
|
---|
| 516 | * @param rThat The string to append a substring from.
|
---|
| 517 | * @param offStart The start of the substring to append (UTF-16
|
---|
| 518 | * offset, not codepoint).
|
---|
| 519 | * @param cwcMax The maximum number of UTF-16 units to append.
|
---|
| 520 | * @throws std::bad_alloc On allocation error. The object is left unchanged.
|
---|
| 521 | * @returns Reference to the object.
|
---|
| 522 | */
|
---|
| 523 | Bstr &append(const Bstr &rThat, size_t offStart, size_t cwcMax = RTSTR_MAX);
|
---|
| 524 |
|
---|
| 525 | /**
|
---|
| 526 | * Appends the a substring from @a rThat to @a this.
|
---|
| 527 | *
|
---|
| 528 | * @param rThat The string to append a substring from.
|
---|
| 529 | * @param offStart The start of the substring to append (UTF-16
|
---|
| 530 | * offset, not codepoint).
|
---|
| 531 | * @param cwcMax The maximum number of UTF-16 units to append.
|
---|
| 532 | * @returns S_OK, E_OUTOFMEMORY or E_INVAL (bad encoding).
|
---|
| 533 | */
|
---|
| 534 | HRESULT appendNoThrow(const Bstr &rThat, size_t offStart, size_t cwcMax = RTSTR_MAX) RT_NOEXCEPT;
|
---|
| 535 |
|
---|
| 536 | /**
|
---|
| 537 | * Appends the a substring from UTF-8 @a rThat to @a this.
|
---|
| 538 | *
|
---|
| 539 | * @param rThat The string to append a substring from.
|
---|
| 540 | * @param offStart The start of the substring to append (byte offset,
|
---|
| 541 | * not codepoint).
|
---|
| 542 | * @param cchMax The maximum number of bytes to append.
|
---|
| 543 | * @throws std::bad_alloc On allocation error. The object is left unchanged.
|
---|
| 544 | * @returns Reference to the object.
|
---|
| 545 | */
|
---|
| 546 | Bstr &append(const RTCString &rThat, size_t offStart, size_t cchMax = RTSTR_MAX);
|
---|
| 547 |
|
---|
| 548 | /**
|
---|
| 549 | * Appends the a substring from UTF-8 @a rThat to @a this.
|
---|
| 550 | *
|
---|
| 551 | * @param rThat The string to append a substring from.
|
---|
| 552 | * @param offStart The start of the substring to append (byte offset,
|
---|
| 553 | * not codepoint).
|
---|
| 554 | * @param cchMax The maximum number of bytes to append.
|
---|
| 555 | * @returns S_OK, E_OUTOFMEMORY or E_INVAL (bad encoding).
|
---|
| 556 | */
|
---|
| 557 | HRESULT appendNoThrow(const RTCString &rThat, size_t offStart, size_t cchMax = RTSTR_MAX) RT_NOEXCEPT;
|
---|
| 558 |
|
---|
| 559 | /**
|
---|
| 560 | * Appends the first @a cchMax chars from UTF-16 string @a pszThat to @a this.
|
---|
| 561 | *
|
---|
| 562 | * @param pwszThat The C-style UTF-16 string to append.
|
---|
| 563 | * @param cchMax The maximum number of bytes to append.
|
---|
| 564 | * @throws std::bad_alloc On allocation error. The object is left unchanged.
|
---|
| 565 | * @returns Reference to the object.
|
---|
| 566 | */
|
---|
| 567 | Bstr &append(CBSTR pwszThat, size_t cchMax);
|
---|
| 568 |
|
---|
| 569 | /**
|
---|
| 570 | * Appends the first @a cchMax chars from UTF-16 string @a pszThat to @a this.
|
---|
| 571 | *
|
---|
| 572 | * @param pwszThat The C-style UTF-16 string to append.
|
---|
| 573 | * @param cchMax The maximum number of bytes to append.
|
---|
| 574 | * @returns S_OK, E_OUTOFMEMORY or E_INVAL (bad encoding).
|
---|
| 575 | */
|
---|
| 576 | HRESULT appendNoThrow(CBSTR pwszThat, size_t cchMax) RT_NOEXCEPT;
|
---|
| 577 |
|
---|
| 578 | /**
|
---|
| 579 | * Appends the first @a cchMax chars from string @a pszThat to @a this.
|
---|
| 580 | *
|
---|
| 581 | * @param pszThat The C-style string to append.
|
---|
| 582 | * @param cchMax The maximum number of bytes to append.
|
---|
| 583 | * @throws std::bad_alloc On allocation error. The object is left unchanged.
|
---|
| 584 | * @returns Reference to the object.
|
---|
| 585 | */
|
---|
| 586 | Bstr &append(const char *pszThat, size_t cchMax);
|
---|
| 587 |
|
---|
| 588 | /**
|
---|
| 589 | * Appends the first @a cchMax chars from string @a pszThat to @a this.
|
---|
| 590 | *
|
---|
| 591 | * @param pszThat The C-style string to append.
|
---|
| 592 | * @param cchMax The maximum number of bytes to append.
|
---|
| 593 | * @returns S_OK, E_OUTOFMEMORY or E_INVAL (bad encoding).
|
---|
| 594 | */
|
---|
| 595 | HRESULT appendNoThrow(const char *pszThat, size_t cchMax) RT_NOEXCEPT;
|
---|
| 596 |
|
---|
| 597 | /**
|
---|
| 598 | * Appends the given character to @a this.
|
---|
| 599 | *
|
---|
| 600 | * @param ch The character to append.
|
---|
| 601 | * @throws std::bad_alloc On allocation error. The object is left unchanged.
|
---|
| 602 | * @returns Reference to the object.
|
---|
| 603 | */
|
---|
| 604 | Bstr &append(char ch);
|
---|
| 605 |
|
---|
| 606 | /**
|
---|
| 607 | * Appends the given character to @a this.
|
---|
| 608 | *
|
---|
| 609 | * @param ch The character to append.
|
---|
| 610 | * @returns S_OK, E_OUTOFMEMORY or E_INVAL (bad encoding).
|
---|
| 611 | */
|
---|
| 612 | HRESULT appendNoThrow(char ch) RT_NOEXCEPT;
|
---|
| 613 |
|
---|
| 614 | /**
|
---|
| 615 | * Appends the given unicode code point to @a this.
|
---|
| 616 | *
|
---|
| 617 | * @param uc The unicode code point to append.
|
---|
| 618 | * @throws std::bad_alloc On allocation error. The object is left unchanged.
|
---|
| 619 | * @returns Reference to the object.
|
---|
| 620 | */
|
---|
| 621 | Bstr &appendCodePoint(RTUNICP uc);
|
---|
| 622 |
|
---|
| 623 | /**
|
---|
| 624 | * Appends the given unicode code point to @a this.
|
---|
| 625 | *
|
---|
| 626 | * @param uc The unicode code point to append.
|
---|
| 627 | * @returns S_OK, E_OUTOFMEMORY or E_INVAL (bad encoding).
|
---|
| 628 | */
|
---|
| 629 | HRESULT appendCodePointNoThrow(RTUNICP uc) RT_NOEXCEPT;
|
---|
| 630 |
|
---|
| 631 | /**
|
---|
| 632 | * Appends the output of the string format operation (RTStrPrintf).
|
---|
| 633 | *
|
---|
| 634 | * @param pszFormat Pointer to the format string,
|
---|
| 635 | * @see pg_rt_str_format.
|
---|
| 636 | * @param ... Ellipsis containing the arguments specified by
|
---|
| 637 | * the format string.
|
---|
| 638 | *
|
---|
| 639 | * @throws std::bad_alloc On allocation error. Object state is undefined.
|
---|
| 640 | *
|
---|
| 641 | * @returns Reference to the object.
|
---|
| 642 | */
|
---|
| 643 | Bstr &appendPrintf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
|
---|
| 644 |
|
---|
| 645 | /**
|
---|
| 646 | * Appends the output of the string format operation (RTStrPrintf).
|
---|
| 647 | *
|
---|
| 648 | * @param pszFormat Pointer to the format string,
|
---|
| 649 | * @see pg_rt_str_format.
|
---|
| 650 | * @param ... Ellipsis containing the arguments specified by
|
---|
| 651 | * the format string.
|
---|
| 652 | *
|
---|
| 653 | * @returns S_OK, E_OUTOFMEMORY or E_INVAL (bad encoding).
|
---|
| 654 | */
|
---|
| 655 | HRESULT appendPrintfNoThrow(const char *pszFormat, ...) RT_NOEXCEPT RT_IPRT_FORMAT_ATTR(1, 2);
|
---|
| 656 |
|
---|
| 657 | /**
|
---|
| 658 | * Appends the output of the string format operation (RTStrPrintfV).
|
---|
| 659 | *
|
---|
| 660 | * @param pszFormat Pointer to the format string,
|
---|
| 661 | * @see pg_rt_str_format.
|
---|
| 662 | * @param va Argument vector containing the arguments
|
---|
| 663 | * specified by the format string.
|
---|
| 664 | *
|
---|
| 665 | * @throws std::bad_alloc On allocation error. Object state is undefined.
|
---|
| 666 | *
|
---|
| 667 | * @returns Reference to the object.
|
---|
| 668 | */
|
---|
| 669 | Bstr &appendPrintfV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
|
---|
| 670 |
|
---|
| 671 | /**
|
---|
| 672 | * Appends the output of the string format operation (RTStrPrintfV).
|
---|
| 673 | *
|
---|
| 674 | * @param pszFormat Pointer to the format string,
|
---|
| 675 | * @see pg_rt_str_format.
|
---|
| 676 | * @param va Argument vector containing the arguments
|
---|
| 677 | * specified by the format string.
|
---|
| 678 | *
|
---|
| 679 | * @returns S_OK, E_OUTOFMEMORY or E_INVAL (bad encoding).
|
---|
| 680 | */
|
---|
| 681 | HRESULT appendPrintfVNoThrow(const char *pszFormat, va_list va) RT_NOEXCEPT RT_IPRT_FORMAT_ATTR(1, 0);
|
---|
| 682 |
|
---|
| 683 | /**
|
---|
| 684 | * Shortcut to append(), Bstr variant.
|
---|
| 685 | *
|
---|
| 686 | * @param rThat The string to append.
|
---|
| 687 | * @returns Reference to the object.
|
---|
| 688 | */
|
---|
| 689 | Bstr &operator+=(const Bstr &rThat)
|
---|
| 690 | {
|
---|
| 691 | return append(rThat);
|
---|
| 692 | }
|
---|
| 693 |
|
---|
| 694 | /**
|
---|
| 695 | * Shortcut to append(), RTCString variant.
|
---|
| 696 | *
|
---|
| 697 | * @param rThat The string to append.
|
---|
| 698 | * @returns Reference to the object.
|
---|
| 699 | */
|
---|
| 700 | Bstr &operator+=(const RTCString &rThat)
|
---|
| 701 | {
|
---|
| 702 | return append(rThat);
|
---|
| 703 | }
|
---|
| 704 |
|
---|
| 705 | /**
|
---|
| 706 | * Shortcut to append(), CBSTR variant.
|
---|
| 707 | *
|
---|
| 708 | * @param pwszThat The C-style string to append.
|
---|
| 709 | * @returns Reference to the object.
|
---|
| 710 | */
|
---|
| 711 | Bstr &operator+=(CBSTR pwszThat)
|
---|
| 712 | {
|
---|
| 713 | return append(pwszThat);
|
---|
| 714 | }
|
---|
| 715 |
|
---|
| 716 | /**
|
---|
| 717 | * Shortcut to append(), const char * variant.
|
---|
| 718 | *
|
---|
| 719 | * @param pszThat The C-style string to append.
|
---|
| 720 | * @returns Reference to the object.
|
---|
| 721 | */
|
---|
| 722 | Bstr &operator+=(const char *pszThat)
|
---|
| 723 | {
|
---|
| 724 | return append(pszThat);
|
---|
| 725 | }
|
---|
| 726 |
|
---|
| 727 | /**
|
---|
| 728 | * Shortcut to append(), char variant.
|
---|
| 729 | *
|
---|
| 730 | * @param ch The character to append.
|
---|
| 731 | *
|
---|
| 732 | * @returns Reference to the object.
|
---|
| 733 | */
|
---|
| 734 | Bstr &operator+=(char ch)
|
---|
| 735 | {
|
---|
| 736 | return append(ch);
|
---|
| 737 | }
|
---|
| 738 |
|
---|
| 739 | /** @} */
|
---|
| 740 |
|
---|
[80838] | 741 | /**
|
---|
| 742 | * Erases a sequence from the string.
|
---|
| 743 | *
|
---|
| 744 | * @returns Reference to the object.
|
---|
| 745 | * @param offStart Where in @a this string to start erasing (UTF-16
|
---|
| 746 | * units, not codepoints).
|
---|
| 747 | * @param cwcLength How much following @a offStart to erase (UTF-16
|
---|
| 748 | * units, not codepoints).
|
---|
| 749 | */
|
---|
| 750 | Bstr &erase(size_t offStart = 0, size_t cwcLength = RTSTR_MAX) RT_NOEXCEPT;
|
---|
| 751 |
|
---|
| 752 |
|
---|
[84287] | 753 | /** @name BASE64 related methods
|
---|
| 754 | * @{ */
|
---|
| 755 | /**
|
---|
[84339] | 756 | * Encodes the given data as BASE64.
|
---|
[84287] | 757 | *
|
---|
| 758 | * @returns S_OK or E_OUTOFMEMORY.
|
---|
| 759 | * @param pvData Pointer to the data to encode.
|
---|
| 760 | * @param cbData Number of bytes to encode.
|
---|
| 761 | * @param fLineBreaks Whether to add line breaks (true) or just encode it
|
---|
| 762 | * as a continuous string.
|
---|
[84339] | 763 | * @sa RTBase64EncodeUtf16
|
---|
[84287] | 764 | */
|
---|
| 765 | HRESULT base64Encode(const void *pvData, size_t cbData, bool fLineBreaks = false);
|
---|
[84339] | 766 |
|
---|
| 767 | /**
|
---|
| 768 | * Decodes the string as BASE64.
|
---|
| 769 | *
|
---|
| 770 | * @returns IPRT status code, see RTBase64DecodeUtf16Ex.
|
---|
| 771 | * @param pvData Where to return the decoded bytes.
|
---|
| 772 | * @param cbData Size of the @a pvData return buffer.
|
---|
| 773 | * @param pcbActual Where to return number of bytes actually decoded.
|
---|
| 774 | * This is optional and if not specified, the request
|
---|
| 775 | * will fail unless @a cbData matches the data size
|
---|
| 776 | * exactly.
|
---|
| 777 | * @param ppwszEnd Where to return pointer to the first non-base64
|
---|
| 778 | * character following the encoded data. This is
|
---|
| 779 | * optional and if NULL, the request will fail if there
|
---|
| 780 | * are anything trailing the encoded bytes in the
|
---|
| 781 | * string.
|
---|
| 782 | * @sa base64DecodedSize, RTBase64DecodeUtf16
|
---|
| 783 | */
|
---|
| 784 | int base64Decode(void *pvData, size_t cbData, size_t *pcbActual = NULL, PRTUTF16 *ppwszEnd = NULL);
|
---|
| 785 |
|
---|
| 786 | /**
|
---|
| 787 | * Determins the size of the BASE64 encoded data in the string.
|
---|
| 788 | *
|
---|
| 789 | * @returns The length in bytes. -1 if the encoding is bad.
|
---|
| 790 | *
|
---|
| 791 | * @param ppwszEnd If not NULL, this will point to the first char
|
---|
| 792 | * following the Base64 encoded text block. If
|
---|
| 793 | * NULL the entire string is assumed to be Base64.
|
---|
| 794 | * @sa base64Decode, RTBase64DecodedUtf16Size
|
---|
| 795 | */
|
---|
| 796 | ssize_t base64DecodedSize(PRTUTF16 *ppwszEnd = NULL);
|
---|
[84287] | 797 | /** @} */
|
---|
| 798 |
|
---|
[32727] | 799 | #if defined(VBOX_WITH_XPCOM)
|
---|
[26753] | 800 | /**
|
---|
| 801 | * Returns a pointer to the raw member UTF-16 string. If the member string is empty,
|
---|
| 802 | * returns a pointer to a global variable containing an empty BSTR with a proper zero
|
---|
| 803 | * length prefix so that Windows is happy.
|
---|
| 804 | */
|
---|
| 805 | CBSTR raw() const
|
---|
[2012] | 806 | {
|
---|
[26753] | 807 | if (m_bstr)
|
---|
| 808 | return m_bstr;
|
---|
| 809 |
|
---|
| 810 | return g_bstrEmpty;
|
---|
[1] | 811 | }
|
---|
[32727] | 812 | #else
|
---|
| 813 | /**
|
---|
| 814 | * Windows-only hack, as the automatically generated headers use BSTR.
|
---|
| 815 | * So if we don't want to cast like crazy we have to be more loose than
|
---|
| 816 | * on XPCOM.
|
---|
| 817 | *
|
---|
| 818 | * Returns a pointer to the raw member UTF-16 string. If the member string is empty,
|
---|
| 819 | * returns a pointer to a global variable containing an empty BSTR with a proper zero
|
---|
| 820 | * length prefix so that Windows is happy.
|
---|
| 821 | */
|
---|
| 822 | BSTR raw() const
|
---|
| 823 | {
|
---|
| 824 | if (m_bstr)
|
---|
| 825 | return m_bstr;
|
---|
[1] | 826 |
|
---|
[32727] | 827 | return g_bstrEmpty;
|
---|
| 828 | }
|
---|
| 829 | #endif
|
---|
| 830 |
|
---|
[15051] | 831 | /**
|
---|
[80835] | 832 | * Returns a non-const raw pointer that allows modifying the string directly.
|
---|
[26753] | 833 | *
|
---|
[80835] | 834 | * @note As opposed to raw(), this DOES return NULL if the member string is
|
---|
| 835 | * empty because we cannot return a mutable pointer to the global variable
|
---|
| 836 | * with the empty string.
|
---|
| 837 | *
|
---|
| 838 | * @note If modifying the string size (only shrinking it is allows), #jolt() or
|
---|
| 839 | * #joltNoThrow() must be called!
|
---|
| 840 | *
|
---|
| 841 | * @note Do not modify memory beyond the #length() of the string!
|
---|
| 842 | *
|
---|
| 843 | * @sa joltNoThrow(), mutalbleRaw(), reserve(), reserveNoThrow()
|
---|
[26603] | 844 | */
|
---|
[26753] | 845 | BSTR mutableRaw() { return m_bstr; }
|
---|
[26603] | 846 |
|
---|
| 847 | /**
|
---|
[80835] | 848 | * Correct the embedded length after using mutableRaw().
|
---|
| 849 | *
|
---|
| 850 | * This is needed on COM (Windows) to update the embedded string length. It is
|
---|
| 851 | * a stub on hosts using XPCOM.
|
---|
| 852 | *
|
---|
| 853 | * @param cwcNew The new string length, if handy, otherwise a negative
|
---|
| 854 | * number.
|
---|
| 855 | * @sa joltNoThrow(), mutalbleRaw(), reserve(), reserveNoThrow()
|
---|
| 856 | */
|
---|
| 857 | #ifndef VBOX_WITH_XPCOM
|
---|
| 858 | void jolt(ssize_t cwcNew = -1);
|
---|
| 859 | #else
|
---|
| 860 | void jolt(ssize_t cwcNew = -1)
|
---|
| 861 | {
|
---|
| 862 | Assert(cwcNew < 0 || (cwcNew == 0 && !m_bstr) || m_bstr[cwcNew] == '\0'); RT_NOREF(cwcNew);
|
---|
| 863 | }
|
---|
| 864 | #endif
|
---|
| 865 |
|
---|
| 866 | /**
|
---|
| 867 | * Correct the embedded length after using mutableRaw().
|
---|
| 868 | *
|
---|
| 869 | * This is needed on COM (Windows) to update the embedded string length. It is
|
---|
| 870 | * a stub on hosts using XPCOM.
|
---|
| 871 | *
|
---|
| 872 | * @returns S_OK on success, E_OUTOFMEMORY if shrinking the string failed.
|
---|
| 873 | * @param cwcNew The new string length, if handy, otherwise a negative
|
---|
| 874 | * number.
|
---|
| 875 | * @sa jolt(), mutalbleRaw(), reserve(), reserveNoThrow()
|
---|
| 876 | */
|
---|
| 877 | #ifndef VBOX_WITH_XPCOM
|
---|
| 878 | HRESULT joltNoThrow(ssize_t cwcNew = -1) RT_NOEXCEPT;
|
---|
| 879 | #else
|
---|
| 880 | HRESULT joltNoThrow(ssize_t cwcNew = -1) RT_NOEXCEPT
|
---|
| 881 | {
|
---|
| 882 | Assert(cwcNew < 0 || (cwcNew == 0 && !m_bstr) || m_bstr[cwcNew] == '\0'); RT_NOREF(cwcNew);
|
---|
| 883 | return S_OK;
|
---|
| 884 | }
|
---|
| 885 | #endif
|
---|
| 886 |
|
---|
| 887 | /**
|
---|
| 888 | * Make sure at that least @a cwc of buffer space is reserved.
|
---|
| 889 | *
|
---|
| 890 | * Requests that the contained memory buffer have at least cb bytes allocated.
|
---|
| 891 | * This may expand or shrink the string's storage, but will never truncate the
|
---|
| 892 | * contained string. In other words, cb will be ignored if it's smaller than
|
---|
| 893 | * length() + 1.
|
---|
| 894 | *
|
---|
| 895 | * @param cwcMin The new minimum string length that the can be stored. This
|
---|
| 896 | * does not include the terminator.
|
---|
| 897 | * @param fForce Force this size.
|
---|
| 898 | *
|
---|
| 899 | * @throws std::bad_alloc On allocation error. The object is left unchanged.
|
---|
| 900 | */
|
---|
| 901 | void reserve(size_t cwcMin, bool fForce = false);
|
---|
| 902 |
|
---|
| 903 | /**
|
---|
| 904 | * A C like version of the #reserve() method, i.e. return code instead of throw.
|
---|
| 905 | *
|
---|
| 906 | * @returns S_OK or E_OUTOFMEMORY.
|
---|
| 907 | * @param cwcMin The new minimum string length that the can be stored. This
|
---|
| 908 | * does not include the terminator.
|
---|
| 909 | * @param fForce Force this size.
|
---|
| 910 | */
|
---|
| 911 | HRESULT reserveNoThrow(size_t cwcMin, bool fForce = false) RT_NOEXCEPT;
|
---|
| 912 |
|
---|
| 913 | /**
|
---|
[6851] | 914 | * Intended to assign copies of instances to |BSTR| out parameters from
|
---|
| 915 | * within the interface method. Transfers the ownership of the duplicated
|
---|
| 916 | * string to the caller.
|
---|
[26753] | 917 | *
|
---|
| 918 | * If the member string is empty, this allocates an empty BSTR in *pstr
|
---|
| 919 | * (i.e. makes it point to a new buffer with a null byte).
|
---|
[40418] | 920 | *
|
---|
| 921 | * @deprecated Use cloneToEx instead to avoid throwing exceptions.
|
---|
[1] | 922 | */
|
---|
[26753] | 923 | void cloneTo(BSTR *pstr) const
|
---|
[2012] | 924 | {
|
---|
| 925 | if (pstr)
|
---|
[26603] | 926 | {
|
---|
[26753] | 927 | *pstr = ::SysAllocString((const OLECHAR *)raw()); // raw() returns a pointer to "" if empty
|
---|
| 928 | #ifdef RT_EXCEPTIONS_ENABLED
|
---|
| 929 | if (!*pstr)
|
---|
| 930 | throw std::bad_alloc();
|
---|
| 931 | #endif
|
---|
[26603] | 932 | }
|
---|
[1] | 933 | }
|
---|
| 934 |
|
---|
| 935 | /**
|
---|
[40418] | 936 | * A version of cloneTo that does not throw any out of memory exceptions, but
|
---|
| 937 | * returns E_OUTOFMEMORY intead.
|
---|
| 938 | * @returns S_OK or E_OUTOFMEMORY.
|
---|
| 939 | */
|
---|
| 940 | HRESULT cloneToEx(BSTR *pstr) const
|
---|
| 941 | {
|
---|
| 942 | if (!pstr)
|
---|
| 943 | return S_OK;
|
---|
| 944 | *pstr = ::SysAllocString((const OLECHAR *)raw()); // raw() returns a pointer to "" if empty
|
---|
| 945 | return pstr ? S_OK : E_OUTOFMEMORY;
|
---|
| 946 | }
|
---|
| 947 |
|
---|
| 948 | /**
|
---|
[6851] | 949 | * Intended to assign instances to |BSTR| out parameters from within the
|
---|
| 950 | * interface method. Transfers the ownership of the original string to the
|
---|
| 951 | * caller and resets the instance to null.
|
---|
| 952 | *
|
---|
| 953 | * As opposed to cloneTo(), this method doesn't create a copy of the
|
---|
| 954 | * string.
|
---|
[26753] | 955 | *
|
---|
| 956 | * If the member string is empty, this allocates an empty BSTR in *pstr
|
---|
| 957 | * (i.e. makes it point to a new buffer with a null byte).
|
---|
[36428] | 958 | *
|
---|
| 959 | * @param pbstrDst The BSTR variable to detach the string to.
|
---|
| 960 | *
|
---|
| 961 | * @throws std::bad_alloc if we failed to allocate a new empty string.
|
---|
[1] | 962 | */
|
---|
[36428] | 963 | void detachTo(BSTR *pbstrDst)
|
---|
[6851] | 964 | {
|
---|
[26753] | 965 | if (m_bstr)
|
---|
[40418] | 966 | {
|
---|
[36428] | 967 | *pbstrDst = m_bstr;
|
---|
[40418] | 968 | m_bstr = NULL;
|
---|
| 969 | }
|
---|
[26753] | 970 | else
|
---|
| 971 | {
|
---|
| 972 | // allocate null BSTR
|
---|
[36428] | 973 | *pbstrDst = ::SysAllocString((const OLECHAR *)g_bstrEmpty);
|
---|
[26753] | 974 | #ifdef RT_EXCEPTIONS_ENABLED
|
---|
[36428] | 975 | if (!*pbstrDst)
|
---|
[26753] | 976 | throw std::bad_alloc();
|
---|
| 977 | #endif
|
---|
| 978 | }
|
---|
[6851] | 979 | }
|
---|
| 980 |
|
---|
| 981 | /**
|
---|
[40418] | 982 | * A version of detachTo that does not throw exceptions on out-of-memory
|
---|
| 983 | * conditions, but instead returns E_OUTOFMEMORY.
|
---|
| 984 | *
|
---|
| 985 | * @param pbstrDst The BSTR variable to detach the string to.
|
---|
| 986 | * @returns S_OK or E_OUTOFMEMORY.
|
---|
| 987 | */
|
---|
| 988 | HRESULT detachToEx(BSTR *pbstrDst)
|
---|
| 989 | {
|
---|
| 990 | if (m_bstr)
|
---|
| 991 | {
|
---|
| 992 | *pbstrDst = m_bstr;
|
---|
| 993 | m_bstr = NULL;
|
---|
| 994 | }
|
---|
| 995 | else
|
---|
| 996 | {
|
---|
| 997 | // allocate null BSTR
|
---|
| 998 | *pbstrDst = ::SysAllocString((const OLECHAR *)g_bstrEmpty);
|
---|
| 999 | if (!*pbstrDst)
|
---|
| 1000 | return E_OUTOFMEMORY;
|
---|
| 1001 | }
|
---|
| 1002 | return S_OK;
|
---|
| 1003 | }
|
---|
| 1004 |
|
---|
| 1005 | /**
|
---|
[1] | 1006 | * Intended to pass instances as |BSTR| out parameters to methods.
|
---|
| 1007 | * Takes the ownership of the returned data.
|
---|
| 1008 | */
|
---|
[36428] | 1009 | BSTR *asOutParam()
|
---|
[26753] | 1010 | {
|
---|
| 1011 | cleanup();
|
---|
| 1012 | return &m_bstr;
|
---|
| 1013 | }
|
---|
[1] | 1014 |
|
---|
[6851] | 1015 | /**
|
---|
[31281] | 1016 | * Static immutable empty-string object. May be used for comparison purposes.
|
---|
[6076] | 1017 | */
|
---|
[31281] | 1018 | static const Bstr Empty;
|
---|
[6076] | 1019 |
|
---|
[13580] | 1020 | protected:
|
---|
[1] | 1021 |
|
---|
[80850] | 1022 | void cleanup();
|
---|
[1] | 1023 |
|
---|
[26753] | 1024 | /**
|
---|
| 1025 | * Protected internal helper to copy a string. This ignores the previous object
|
---|
| 1026 | * state, so either call this from a constructor or call cleanup() first.
|
---|
| 1027 | *
|
---|
| 1028 | * This variant copies from a zero-terminated UTF-16 string (which need not
|
---|
| 1029 | * be a BSTR, i.e. need not have a length prefix).
|
---|
| 1030 | *
|
---|
| 1031 | * If the source is empty, this sets the member string to NULL.
|
---|
[36428] | 1032 | *
|
---|
| 1033 | * @param a_bstrSrc The source string. The caller guarantees
|
---|
| 1034 | * that this is valid UTF-16.
|
---|
| 1035 | *
|
---|
| 1036 | * @throws std::bad_alloc - the object is representing an empty string.
|
---|
[26753] | 1037 | */
|
---|
[80850] | 1038 | void copyFrom(const OLECHAR *a_bstrSrc);
|
---|
[1] | 1039 |
|
---|
[80850] | 1040 | /** cleanup() + copyFrom() - for assignment operators. */
|
---|
| 1041 | void cleanupAndCopyFrom(const OLECHAR *a_bstrSrc);
|
---|
| 1042 |
|
---|
[26753] | 1043 | /**
|
---|
[85288] | 1044 | * Protected internal helper to copy a string, implying cleanup().
|
---|
| 1045 | *
|
---|
| 1046 | * This variant copies from a zero-terminated UTF-16 string (which need not be a
|
---|
| 1047 | * BSTR, i.e. need not have a length prefix).
|
---|
| 1048 | *
|
---|
| 1049 | * If the source is empty, this sets the member string to NULL.
|
---|
| 1050 | *
|
---|
| 1051 | * @param a_bstrSrc The source string. The caller guarantees
|
---|
| 1052 | * that this is valid UTF-16.
|
---|
| 1053 | * @returns S_OK or E_OUTOFMEMORY
|
---|
| 1054 | */
|
---|
| 1055 | HRESULT cleanupAndCopyFromEx(const OLECHAR *a_bstrSrc) RT_NOEXCEPT;
|
---|
| 1056 |
|
---|
| 1057 | /**
|
---|
[26753] | 1058 | * Protected internal helper to copy a string. This ignores the previous object
|
---|
| 1059 | * state, so either call this from a constructor or call cleanup() first.
|
---|
| 1060 | *
|
---|
| 1061 | * This variant copies and converts from a zero-terminated UTF-8 string.
|
---|
| 1062 | *
|
---|
| 1063 | * If the source is empty, this sets the member string to NULL.
|
---|
[36428] | 1064 | *
|
---|
| 1065 | * @param a_pszSrc The source string. The caller guarantees
|
---|
| 1066 | * that this is valid UTF-8.
|
---|
| 1067 | *
|
---|
| 1068 | * @throws std::bad_alloc - the object is representing an empty string.
|
---|
[26753] | 1069 | */
|
---|
[36428] | 1070 | void copyFrom(const char *a_pszSrc)
|
---|
[2012] | 1071 | {
|
---|
[36428] | 1072 | copyFromN(a_pszSrc, RTSTR_MAX);
|
---|
[1] | 1073 | }
|
---|
| 1074 |
|
---|
[34846] | 1075 | /**
|
---|
| 1076 | * Variant of copyFrom for sub-string constructors.
|
---|
| 1077 | *
|
---|
[36428] | 1078 | * @param a_pszSrc The source string. The caller guarantees
|
---|
| 1079 | * that this is valid UTF-8.
|
---|
[58106] | 1080 | * @param a_cchSrc The maximum number of chars (not codepoints) to
|
---|
| 1081 | * copy. If you pass RTSTR_MAX it'll be exactly
|
---|
| 1082 | * like copyFrom().
|
---|
[36428] | 1083 | *
|
---|
| 1084 | * @throws std::bad_alloc - the object is representing an empty string.
|
---|
[34846] | 1085 | */
|
---|
| 1086 | void copyFromN(const char *a_pszSrc, size_t a_cchSrc);
|
---|
| 1087 |
|
---|
[85308] | 1088 | /** cleanup() + non-throwing copyFromN(). */
|
---|
| 1089 | HRESULT cleanupAndCopyFromNoThrow(const char *a_pszSrc, size_t a_cchMax) RT_NOEXCEPT;
|
---|
| 1090 |
|
---|
[80836] | 1091 | Bstr &appendWorkerUtf16(PCRTUTF16 pwszSrc, size_t cwcSrc);
|
---|
| 1092 | Bstr &appendWorkerUtf8(const char *pszSrc, size_t cchSrc);
|
---|
| 1093 | HRESULT appendWorkerUtf16NoThrow(PCRTUTF16 pwszSrc, size_t cwcSrc) RT_NOEXCEPT;
|
---|
| 1094 | HRESULT appendWorkerUtf8NoThrow(const char *pszSrc, size_t cchSrc) RT_NOEXCEPT;
|
---|
| 1095 |
|
---|
[80793] | 1096 | static DECLCALLBACK(size_t) printfOutputCallbackNoThrow(void *pvArg, const char *pachChars, size_t cbChars) RT_NOEXCEPT;
|
---|
| 1097 |
|
---|
[26753] | 1098 | BSTR m_bstr;
|
---|
[26603] | 1099 |
|
---|
| 1100 | friend class Utf8Str; /* to access our raw_copy() */
|
---|
[1] | 1101 | };
|
---|
| 1102 |
|
---|
[26552] | 1103 | /* symmetric compare operators */
|
---|
[26603] | 1104 | inline bool operator==(CBSTR l, const Bstr &r) { return r.operator==(l); }
|
---|
| 1105 | inline bool operator!=(CBSTR l, const Bstr &r) { return r.operator!=(l); }
|
---|
| 1106 | inline bool operator==(BSTR l, const Bstr &r) { return r.operator==(l); }
|
---|
| 1107 | inline bool operator!=(BSTR l, const Bstr &r) { return r.operator!=(l); }
|
---|
[26552] | 1108 |
|
---|
[26753] | 1109 |
|
---|
[1] | 1110 |
|
---|
[36428] | 1111 |
|
---|
[1] | 1112 | /**
|
---|
[36428] | 1113 | * String class used universally in Main for UTF-8 strings.
|
---|
[3387] | 1114 | *
|
---|
[36527] | 1115 | * This is based on RTCString, to which some functionality has been
|
---|
[36428] | 1116 | * moved. Here we keep things that are specific to Main, such as conversions
|
---|
| 1117 | * with UTF-16 strings (Bstr).
|
---|
[26753] | 1118 | *
|
---|
[36527] | 1119 | * Like RTCString, Utf8Str does not differentiate between NULL strings
|
---|
[36428] | 1120 | * and empty strings. In other words, Utf8Str("") and Utf8Str(NULL) behave the
|
---|
[36527] | 1121 | * same. In both cases, RTCString allocates no memory, reports
|
---|
[36428] | 1122 | * a zero length and zero allocated bytes for both, and returns an empty
|
---|
| 1123 | * C string from c_str().
|
---|
| 1124 | *
|
---|
| 1125 | * @note All Utf8Str methods ASSUMES valid UTF-8 or UTF-16 input strings.
|
---|
| 1126 | * The VirtualBox policy in this regard is to validate strings coming
|
---|
| 1127 | * from external sources before passing them to Utf8Str or Bstr.
|
---|
[1] | 1128 | */
|
---|
[36527] | 1129 | class Utf8Str : public RTCString
|
---|
[1] | 1130 | {
|
---|
| 1131 | public:
|
---|
| 1132 |
|
---|
[21079] | 1133 | Utf8Str() {}
|
---|
[17742] | 1134 |
|
---|
[36527] | 1135 | Utf8Str(const RTCString &that)
|
---|
| 1136 | : RTCString(that)
|
---|
[21079] | 1137 | {}
|
---|
[1] | 1138 |
|
---|
[21079] | 1139 | Utf8Str(const char *that)
|
---|
[36527] | 1140 | : RTCString(that)
|
---|
[21079] | 1141 | {}
|
---|
[1] | 1142 |
|
---|
[21079] | 1143 | Utf8Str(const Bstr &that)
|
---|
[2012] | 1144 | {
|
---|
[32718] | 1145 | copyFrom(that.raw());
|
---|
[1] | 1146 | }
|
---|
| 1147 |
|
---|
[52554] | 1148 | Utf8Str(CBSTR that, size_t a_cwcSize = RTSTR_MAX)
|
---|
[2012] | 1149 | {
|
---|
[52554] | 1150 | copyFrom(that, a_cwcSize);
|
---|
[1] | 1151 | }
|
---|
| 1152 |
|
---|
[42177] | 1153 | Utf8Str(const char *a_pszSrc, size_t a_cchSrc)
|
---|
| 1154 | : RTCString(a_pszSrc, a_cchSrc)
|
---|
| 1155 | {
|
---|
| 1156 | }
|
---|
| 1157 |
|
---|
[33621] | 1158 | /**
|
---|
| 1159 | * Constructs a new string given the format string and the list of the
|
---|
| 1160 | * arguments for the format string.
|
---|
| 1161 | *
|
---|
| 1162 | * @param a_pszFormat Pointer to the format string (UTF-8),
|
---|
| 1163 | * @see pg_rt_str_format.
|
---|
| 1164 | * @param a_va Argument vector containing the arguments
|
---|
| 1165 | * specified by the format string.
|
---|
[36527] | 1166 | * @sa RTCString::printfV
|
---|
[33621] | 1167 | */
|
---|
[57005] | 1168 | Utf8Str(const char *a_pszFormat, va_list a_va) RT_IPRT_FORMAT_ATTR(1, 0)
|
---|
[36527] | 1169 | : RTCString(a_pszFormat, a_va)
|
---|
[33621] | 1170 | {
|
---|
| 1171 | }
|
---|
| 1172 |
|
---|
[36527] | 1173 | Utf8Str& operator=(const RTCString &that)
|
---|
[2012] | 1174 | {
|
---|
[36527] | 1175 | RTCString::operator=(that);
|
---|
[1] | 1176 | return *this;
|
---|
| 1177 | }
|
---|
| 1178 |
|
---|
[21079] | 1179 | Utf8Str& operator=(const char *that)
|
---|
[2012] | 1180 | {
|
---|
[36527] | 1181 | RTCString::operator=(that);
|
---|
[2012] | 1182 | return *this;
|
---|
| 1183 | }
|
---|
| 1184 |
|
---|
[21079] | 1185 | Utf8Str& operator=(const Bstr &that)
|
---|
[17646] | 1186 | {
|
---|
[21079] | 1187 | cleanup();
|
---|
[32718] | 1188 | copyFrom(that.raw());
|
---|
[18529] | 1189 | return *this;
|
---|
| 1190 | }
|
---|
| 1191 |
|
---|
[21079] | 1192 | Utf8Str& operator=(CBSTR that)
|
---|
[18529] | 1193 | {
|
---|
[21079] | 1194 | cleanup();
|
---|
| 1195 | copyFrom(that);
|
---|
[18529] | 1196 | return *this;
|
---|
| 1197 | }
|
---|
| 1198 |
|
---|
[42570] | 1199 | /**
|
---|
| 1200 | * Extended assignment method that returns a COM status code instead of an
|
---|
| 1201 | * exception on failure.
|
---|
| 1202 | *
|
---|
| 1203 | * @returns S_OK or E_OUTOFMEMORY.
|
---|
| 1204 | * @param a_rSrcStr The source string
|
---|
| 1205 | */
|
---|
| 1206 | HRESULT assignEx(Utf8Str const &a_rSrcStr)
|
---|
| 1207 | {
|
---|
[51887] | 1208 | return copyFromExNComRC(a_rSrcStr.m_psz, 0, a_rSrcStr.m_cch);
|
---|
[42570] | 1209 | }
|
---|
| 1210 |
|
---|
| 1211 | /**
|
---|
| 1212 | * Extended assignment method that returns a COM status code instead of an
|
---|
| 1213 | * exception on failure.
|
---|
| 1214 | *
|
---|
| 1215 | * @returns S_OK, E_OUTOFMEMORY or E_INVALIDARG.
|
---|
[58106] | 1216 | * @param a_rSrcStr The source string
|
---|
[42570] | 1217 | * @param a_offSrc The character (byte) offset of the substring.
|
---|
| 1218 | * @param a_cchSrc The number of characters (bytes) to copy from the source
|
---|
| 1219 | * string.
|
---|
| 1220 | */
|
---|
| 1221 | HRESULT assignEx(Utf8Str const &a_rSrcStr, size_t a_offSrc, size_t a_cchSrc)
|
---|
| 1222 | {
|
---|
| 1223 | if ( a_offSrc + a_cchSrc > a_rSrcStr.m_cch
|
---|
| 1224 | || a_offSrc > a_rSrcStr.m_cch)
|
---|
| 1225 | return E_INVALIDARG;
|
---|
[51887] | 1226 | return copyFromExNComRC(a_rSrcStr.m_psz, a_offSrc, a_cchSrc);
|
---|
[42570] | 1227 | }
|
---|
| 1228 |
|
---|
| 1229 | /**
|
---|
| 1230 | * Extended assignment method that returns a COM status code instead of an
|
---|
| 1231 | * exception on failure.
|
---|
| 1232 | *
|
---|
| 1233 | * @returns S_OK or E_OUTOFMEMORY.
|
---|
| 1234 | * @param a_pcszSrc The source string
|
---|
| 1235 | */
|
---|
| 1236 | HRESULT assignEx(const char *a_pcszSrc)
|
---|
| 1237 | {
|
---|
[51887] | 1238 | return copyFromExNComRC(a_pcszSrc, 0, a_pcszSrc ? strlen(a_pcszSrc) : 0);
|
---|
[42570] | 1239 | }
|
---|
| 1240 |
|
---|
| 1241 | /**
|
---|
| 1242 | * Extended assignment method that returns a COM status code instead of an
|
---|
| 1243 | * exception on failure.
|
---|
| 1244 | *
|
---|
| 1245 | * @returns S_OK or E_OUTOFMEMORY.
|
---|
| 1246 | * @param a_pcszSrc The source string
|
---|
| 1247 | * @param a_cchSrc The number of characters (bytes) to copy from the source
|
---|
| 1248 | * string.
|
---|
| 1249 | */
|
---|
| 1250 | HRESULT assignEx(const char *a_pcszSrc, size_t a_cchSrc)
|
---|
| 1251 | {
|
---|
[51887] | 1252 | return copyFromExNComRC(a_pcszSrc, 0, a_cchSrc);
|
---|
[42570] | 1253 | }
|
---|
| 1254 |
|
---|
[34785] | 1255 | RTMEMEF_NEW_AND_DELETE_OPERATORS();
|
---|
| 1256 |
|
---|
[32727] | 1257 | #if defined(VBOX_WITH_XPCOM)
|
---|
[1] | 1258 | /**
|
---|
[24657] | 1259 | * Intended to assign instances to |char *| out parameters from within the
|
---|
| 1260 | * interface method. Transfers the ownership of the duplicated string to the
|
---|
| 1261 | * caller.
|
---|
| 1262 | *
|
---|
[26753] | 1263 | * This allocates a single 0 byte in the target if the member string is empty.
|
---|
[26603] | 1264 | *
|
---|
[26753] | 1265 | * This uses XPCOM memory allocation and thus only works on XPCOM. MSCOM doesn't
|
---|
| 1266 | * like char* strings anyway.
|
---|
[26603] | 1267 | */
|
---|
[26753] | 1268 | void cloneTo(char **pstr) const;
|
---|
[40418] | 1269 |
|
---|
| 1270 | /**
|
---|
| 1271 | * A version of cloneTo that does not throw allocation errors but returns
|
---|
| 1272 | * E_OUTOFMEMORY instead.
|
---|
| 1273 | * @returns S_OK or E_OUTOFMEMORY (COM status codes).
|
---|
| 1274 | */
|
---|
| 1275 | HRESULT cloneToEx(char **pstr) const;
|
---|
[26753] | 1276 | #endif
|
---|
[26603] | 1277 |
|
---|
| 1278 | /**
|
---|
[1] | 1279 | * Intended to assign instances to |BSTR| out parameters from within the
|
---|
| 1280 | * interface method. Transfers the ownership of the duplicated string to the
|
---|
| 1281 | * caller.
|
---|
| 1282 | */
|
---|
[26753] | 1283 | void cloneTo(BSTR *pstr) const
|
---|
[2012] | 1284 | {
|
---|
| 1285 | if (pstr)
|
---|
| 1286 | {
|
---|
[26753] | 1287 | Bstr bstr(*this);
|
---|
| 1288 | bstr.cloneTo(pstr);
|
---|
[1] | 1289 | }
|
---|
| 1290 | }
|
---|
| 1291 |
|
---|
[16326] | 1292 | /**
|
---|
[40418] | 1293 | * A version of cloneTo that does not throw allocation errors but returns
|
---|
| 1294 | * E_OUTOFMEMORY instead.
|
---|
| 1295 | *
|
---|
| 1296 | * @param pbstr Where to store a clone of the string.
|
---|
| 1297 | * @returns S_OK or E_OUTOFMEMORY (COM status codes).
|
---|
| 1298 | */
|
---|
[85314] | 1299 | HRESULT cloneToEx(BSTR *pbstr) const RT_NOEXCEPT;
|
---|
[40418] | 1300 |
|
---|
| 1301 | /**
|
---|
| 1302 | * Safe assignment from BSTR.
|
---|
| 1303 | *
|
---|
| 1304 | * @param pbstrSrc The source string.
|
---|
| 1305 | * @returns S_OK or E_OUTOFMEMORY (COM status codes).
|
---|
| 1306 | */
|
---|
| 1307 | HRESULT cloneEx(CBSTR pbstrSrc)
|
---|
| 1308 | {
|
---|
| 1309 | cleanup();
|
---|
| 1310 | return copyFromEx(pbstrSrc);
|
---|
| 1311 | }
|
---|
| 1312 |
|
---|
| 1313 | /**
|
---|
[21079] | 1314 | * Removes a trailing slash from the member string, if present.
|
---|
| 1315 | * Calls RTPathStripTrailingSlash() without having to mess with mutableRaw().
|
---|
| 1316 | */
|
---|
[33073] | 1317 | Utf8Str& stripTrailingSlash();
|
---|
[21079] | 1318 |
|
---|
| 1319 | /**
|
---|
| 1320 | * Removes a trailing filename from the member string, if present.
|
---|
| 1321 | * Calls RTPathStripFilename() without having to mess with mutableRaw().
|
---|
| 1322 | */
|
---|
[33073] | 1323 | Utf8Str& stripFilename();
|
---|
[21079] | 1324 |
|
---|
| 1325 | /**
|
---|
[33055] | 1326 | * Removes the path component from the member string, if present.
|
---|
| 1327 | * Calls RTPathFilename() without having to mess with mutableRaw().
|
---|
| 1328 | */
|
---|
[33073] | 1329 | Utf8Str& stripPath();
|
---|
[33055] | 1330 |
|
---|
| 1331 | /**
|
---|
[49039] | 1332 | * Removes a trailing file name suffix from the member string, if present.
|
---|
| 1333 | * Calls RTPathStripSuffix() without having to mess with mutableRaw().
|
---|
[21079] | 1334 | */
|
---|
[49039] | 1335 | Utf8Str& stripSuffix();
|
---|
[21079] | 1336 |
|
---|
[67640] | 1337 | /**
|
---|
| 1338 | * Parses key=value pairs.
|
---|
| 1339 | *
|
---|
| 1340 | * @returns offset of the @a a_rPairSeparator following the returned value.
|
---|
[67642] | 1341 | * @retval npos is returned if there are no more key/value pairs.
|
---|
[67640] | 1342 | *
|
---|
| 1343 | * @param a_rKey Reference to variable that should receive
|
---|
| 1344 | * the key substring. This is set to null if
|
---|
| 1345 | * no key/value found. (It's also possible the
|
---|
| 1346 | * key is an empty string, so be careful.)
|
---|
| 1347 | * @param a_rValue Reference to variable that should receive
|
---|
| 1348 | * the value substring. This is set to null if
|
---|
| 1349 | * no key/value found. (It's also possible the
|
---|
| 1350 | * value is an empty string, so be careful.)
|
---|
| 1351 | * @param a_offStart The offset to start searching from. This is
|
---|
| 1352 | * typically 0 for the first call, and the
|
---|
| 1353 | * return value of the previous call for the
|
---|
| 1354 | * subsequent ones.
|
---|
[67752] | 1355 | * @param a_rPairSeparator The pair separator string. If this is an
|
---|
| 1356 | * empty string, the whole string will be
|
---|
| 1357 | * considered as a single key/value pair.
|
---|
[67640] | 1358 | * @param a_rKeyValueSeparator The key/value separator string.
|
---|
| 1359 | */
|
---|
| 1360 | size_t parseKeyValue(Utf8Str &a_rKey, Utf8Str &a_rValue, size_t a_offStart = 0,
|
---|
| 1361 | const Utf8Str &a_rPairSeparator = ",", const Utf8Str &a_rKeyValueSeparator = "=") const;
|
---|
[52312] | 1362 |
|
---|
[21079] | 1363 | /**
|
---|
[31281] | 1364 | * Static immutable empty-string object. May be used for comparison purposes.
|
---|
[6076] | 1365 | */
|
---|
[31281] | 1366 | static const Utf8Str Empty;
|
---|
[13580] | 1367 | protected:
|
---|
[1] | 1368 |
|
---|
[52554] | 1369 | void copyFrom(CBSTR a_pbstr, size_t a_cwcMax = RTSTR_MAX);
|
---|
[40418] | 1370 | HRESULT copyFromEx(CBSTR a_pbstr);
|
---|
[51887] | 1371 | HRESULT copyFromExNComRC(const char *a_pcszSrc, size_t a_offSrc, size_t a_cchSrc);
|
---|
[1] | 1372 |
|
---|
[13580] | 1373 | friend class Bstr; /* to access our raw_copy() */
|
---|
[1] | 1374 | };
|
---|
| 1375 |
|
---|
| 1376 | /**
|
---|
[36527] | 1377 | * Class with RTCString::printf as constructor for your convenience.
|
---|
[1] | 1378 | *
|
---|
[33621] | 1379 | * Constructing a Utf8Str string object from a format string and a variable
|
---|
| 1380 | * number of arguments can easily be confused with the other Utf8Str
|
---|
| 1381 | * constructures, thus this child class.
|
---|
| 1382 | *
|
---|
| 1383 | * The usage of this class is like the following:
|
---|
| 1384 | * @code
|
---|
| 1385 | Utf8StrFmt strName("program name = %s", argv[0]);
|
---|
| 1386 | @endcode
|
---|
[91519] | 1387 | *
|
---|
| 1388 | * @note Do not use in assignments to Utf8Str variables. Instead use
|
---|
| 1389 | * RTCString::printf directly on the variable! This avoid an extra
|
---|
| 1390 | * temporary Utf8Str instance and assignment operation.
|
---|
[1] | 1391 | */
|
---|
| 1392 | class Utf8StrFmt : public Utf8Str
|
---|
| 1393 | {
|
---|
| 1394 | public:
|
---|
| 1395 |
|
---|
| 1396 | /**
|
---|
[33621] | 1397 | * Constructs a new string given the format string and the list of the
|
---|
| 1398 | * arguments for the format string.
|
---|
[1] | 1399 | *
|
---|
[33621] | 1400 | * @param a_pszFormat Pointer to the format string (UTF-8),
|
---|
| 1401 | * @see pg_rt_str_format.
|
---|
| 1402 | * @param ... Ellipsis containing the arguments specified by
|
---|
| 1403 | * the format string.
|
---|
[1] | 1404 | */
|
---|
[57005] | 1405 | explicit Utf8StrFmt(const char *a_pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2)
|
---|
[2012] | 1406 | {
|
---|
[33621] | 1407 | va_list va;
|
---|
| 1408 | va_start(va, a_pszFormat);
|
---|
| 1409 | printfV(a_pszFormat, va);
|
---|
| 1410 | va_end(va);
|
---|
[1] | 1411 | }
|
---|
| 1412 |
|
---|
[34785] | 1413 | RTMEMEF_NEW_AND_DELETE_OPERATORS();
|
---|
| 1414 |
|
---|
[4134] | 1415 | protected:
|
---|
[30750] | 1416 | Utf8StrFmt()
|
---|
| 1417 | { }
|
---|
[1] | 1418 |
|
---|
[4134] | 1419 | private:
|
---|
[1] | 1420 | };
|
---|
| 1421 |
|
---|
[4134] | 1422 | /**
|
---|
[80879] | 1423 | * Class with Bstr::printf as constructor for your convenience.
|
---|
[13580] | 1424 | */
|
---|
| 1425 | class BstrFmt : public Bstr
|
---|
| 1426 | {
|
---|
| 1427 | public:
|
---|
| 1428 |
|
---|
| 1429 | /**
|
---|
| 1430 | * Constructs a new string given the format string and the list of the
|
---|
| 1431 | * arguments for the format string.
|
---|
| 1432 | *
|
---|
[80851] | 1433 | * @param a_pszFormat printf-like format string (in UTF-8 encoding), see
|
---|
| 1434 | * iprt/string.h for details.
|
---|
| 1435 | * @param ... List of the arguments for the format string.
|
---|
[13580] | 1436 | */
|
---|
[80851] | 1437 | explicit BstrFmt(const char *a_pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2)
|
---|
[13580] | 1438 | {
|
---|
[80851] | 1439 | va_list va;
|
---|
| 1440 | va_start(va, a_pszFormat);
|
---|
| 1441 | printfV(a_pszFormat, va);
|
---|
| 1442 | va_end(va);
|
---|
[13580] | 1443 | }
|
---|
[34785] | 1444 |
|
---|
| 1445 | RTMEMEF_NEW_AND_DELETE_OPERATORS();
|
---|
[80879] | 1446 |
|
---|
| 1447 | protected:
|
---|
| 1448 | BstrFmt()
|
---|
| 1449 | { }
|
---|
[13580] | 1450 | };
|
---|
| 1451 |
|
---|
| 1452 | /**
|
---|
[80879] | 1453 | * Class with Bstr::printfV as constructor for your convenience.
|
---|
[13580] | 1454 | */
|
---|
| 1455 | class BstrFmtVA : public Bstr
|
---|
| 1456 | {
|
---|
| 1457 | public:
|
---|
| 1458 |
|
---|
| 1459 | /**
|
---|
| 1460 | * Constructs a new string given the format string and the list of the
|
---|
| 1461 | * arguments for the format string.
|
---|
| 1462 | *
|
---|
[80851] | 1463 | * @param a_pszFormat printf-like format string (in UTF-8 encoding), see
|
---|
| 1464 | * iprt/string.h for details.
|
---|
| 1465 | * @param a_va List of arguments for the format string
|
---|
[13580] | 1466 | */
|
---|
[80851] | 1467 | BstrFmtVA(const char *a_pszFormat, va_list a_va) RT_IPRT_FORMAT_ATTR(1, 0)
|
---|
[13580] | 1468 | {
|
---|
[80851] | 1469 | printfV(a_pszFormat, a_va);
|
---|
[13580] | 1470 | }
|
---|
[34785] | 1471 |
|
---|
| 1472 | RTMEMEF_NEW_AND_DELETE_OPERATORS();
|
---|
[80879] | 1473 |
|
---|
| 1474 | protected:
|
---|
| 1475 | BstrFmtVA()
|
---|
| 1476 | { }
|
---|
[13580] | 1477 | };
|
---|
| 1478 |
|
---|
[5658] | 1479 | } /* namespace com */
|
---|
[1] | 1480 |
|
---|
[58110] | 1481 | /** @} */
|
---|
| 1482 |
|
---|
[76585] | 1483 | #endif /* !VBOX_INCLUDED_com_string_h */
|
---|
[24657] | 1484 |
|
---|