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