VirtualBox

source: vbox/trunk/include/iprt/cpp/ministring.h@ 97583

Last change on this file since 97583 was 96407, checked in by vboxsync, 2 years ago

scm copyright and license note update

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 56.2 KB
Line 
1/** @file
2 * IPRT - C++ string class.
3 */
4
5/*
6 * Copyright (C) 2007-2022 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_cpp_ministring_h
37#define IPRT_INCLUDED_cpp_ministring_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/mem.h>
43#include <iprt/string.h>
44#include <iprt/stdarg.h>
45#include <iprt/cpp/list.h>
46
47#include <new>
48
49
50/** @defgroup grp_rt_cpp_string C++ String support
51 * @ingroup grp_rt_cpp
52 * @{
53 */
54
55/** @brief C++ string class.
56 *
57 * This is a C++ string class that does not depend on anything else except IPRT
58 * memory management functions. Semantics are like in std::string, except it
59 * can do a lot less.
60 *
61 * Note that RTCString does not differentiate between NULL strings
62 * and empty strings. In other words, RTCString("") and RTCString(NULL)
63 * behave the same. In both cases, RTCString allocates no memory, reports
64 * a zero length and zero allocated bytes for both, and returns an empty
65 * C-style string from c_str().
66 *
67 * @note RTCString ASSUMES that all strings it deals with are valid UTF-8.
68 * The caller is responsible for not breaking this assumption.
69 */
70#ifdef VBOX
71 /** @remarks Much of the code in here used to be in com::Utf8Str so that
72 * com::Utf8Str can now derive from RTCString and only contain code
73 * that is COM-specific, such as com::Bstr conversions. Compared to
74 * the old Utf8Str though, RTCString always knows the length of its
75 * member string and the size of the buffer so it can use memcpy()
76 * instead of strdup().
77 */
78#endif
79class RT_DECL_CLASS RTCString
80{
81public:
82#if defined(RT_NEED_NEW_AND_DELETE) && ( !defined(RTMEM_WRAP_SOME_NEW_AND_DELETE_TO_EF) \
83 || defined(RTMEM_NO_WRAP_SOME_NEW_AND_DELETE_TO_EF))
84 RTMEM_IMPLEMENT_NEW_AND_DELETE();
85#else
86 RTMEMEF_NEW_AND_DELETE_OPERATORS();
87#endif
88
89 /**
90 * Creates an empty string that has no memory allocated.
91 */
92 RTCString()
93 : m_psz(NULL),
94 m_cch(0),
95 m_cbAllocated(0)
96 {
97 }
98
99 /**
100 * Creates a copy of another RTCString.
101 *
102 * This allocates s.length() + 1 bytes for the new instance, unless s is empty.
103 *
104 * @param a_rSrc The source string.
105 *
106 * @throws std::bad_alloc
107 */
108 RTCString(const RTCString &a_rSrc)
109 {
110 copyFromN(a_rSrc.m_psz, a_rSrc.m_cch);
111 }
112
113 /**
114 * Creates a copy of a C-style string.
115 *
116 * This allocates strlen(pcsz) + 1 bytes for the new instance, unless s is empty.
117 *
118 * @param pcsz The source string.
119 *
120 * @throws std::bad_alloc
121 */
122 RTCString(const char *pcsz)
123 {
124 copyFromN(pcsz, pcsz ? strlen(pcsz) : 0);
125 }
126
127 /**
128 * Create a partial copy of another RTCString.
129 *
130 * @param a_rSrc The source string.
131 * @param a_offSrc The byte offset into the source string.
132 * @param a_cchSrc The max number of chars (encoded UTF-8 bytes)
133 * to copy from the source string.
134 */
135 RTCString(const RTCString &a_rSrc, size_t a_offSrc, size_t a_cchSrc = npos)
136 {
137 if (a_offSrc < a_rSrc.m_cch)
138 copyFromN(&a_rSrc.m_psz[a_offSrc], RT_MIN(a_cchSrc, a_rSrc.m_cch - a_offSrc));
139 else
140 {
141 m_psz = NULL;
142 m_cch = 0;
143 m_cbAllocated = 0;
144 }
145 }
146
147 /**
148 * Create a partial copy of a C-style string.
149 *
150 * @param a_pszSrc The source string (UTF-8).
151 * @param a_cchSrc The max number of chars (encoded UTF-8 bytes)
152 * to copy from the source string. This must not
153 * be '0' as the compiler could easily mistake
154 * that for the va_list constructor.
155 */
156 RTCString(const char *a_pszSrc, size_t a_cchSrc)
157 {
158 size_t cchMax = a_pszSrc ? RTStrNLen(a_pszSrc, a_cchSrc) : 0;
159 copyFromN(a_pszSrc, RT_MIN(a_cchSrc, cchMax));
160 }
161
162 /**
163 * Create a string containing @a a_cTimes repetitions of the character @a
164 * a_ch.
165 *
166 * @param a_cTimes The number of times the character is repeated.
167 * @param a_ch The character to fill the string with.
168 */
169 RTCString(size_t a_cTimes, char a_ch)
170 : m_psz(NULL),
171 m_cch(0),
172 m_cbAllocated(0)
173 {
174 Assert((unsigned)a_ch < 0x80);
175 if (a_cTimes)
176 {
177 reserve(a_cTimes + 1);
178 memset(m_psz, a_ch, a_cTimes);
179 m_psz[a_cTimes] = '\0';
180 m_cch = a_cTimes;
181 }
182 }
183
184 /**
185 * Create a new string given the format string and its arguments.
186 *
187 * @param a_pszFormat Pointer to the format string (UTF-8),
188 * @see pg_rt_str_format.
189 * @param a_va Argument vector containing the arguments
190 * specified by the format string.
191 * @sa printfV
192 * @remarks Not part of std::string.
193 */
194 RTCString(const char *a_pszFormat, va_list a_va) RT_IPRT_FORMAT_ATTR(1, 0)
195 : m_psz(NULL),
196 m_cch(0),
197 m_cbAllocated(0)
198 {
199 printfV(a_pszFormat, a_va);
200 }
201
202 /**
203 * Destructor.
204 */
205 virtual ~RTCString()
206 {
207 cleanup();
208 }
209
210 /**
211 * String length in bytes.
212 *
213 * Returns the length of the member string in bytes, which is equal to strlen(c_str()).
214 * In other words, this does not count unicode codepoints; use utf8length() for that.
215 * The byte length is always cached so calling this is cheap and requires no
216 * strlen() invocation.
217 *
218 * @returns m_cbLength.
219 */
220 size_t length() const
221 {
222 return m_cch;
223 }
224
225 /**
226 * String length in unicode codepoints.
227 *
228 * As opposed to length(), which returns the length in bytes, this counts
229 * the number of unicode codepoints. This is *not* cached so calling this
230 * is expensive.
231 *
232 * @returns Number of codepoints in the member string.
233 */
234 size_t uniLength() const
235 {
236 return m_psz ? RTStrUniLen(m_psz) : 0;
237 }
238
239 /**
240 * The allocated buffer size (in bytes).
241 *
242 * Returns the number of bytes allocated in the internal string buffer, which is
243 * at least length() + 1 if length() > 0; for an empty string, this returns 0.
244 *
245 * @returns m_cbAllocated.
246 */
247 size_t capacity() const
248 {
249 return m_cbAllocated;
250 }
251
252 /**
253 * Make sure at that least cb of buffer space is reserved.
254 *
255 * Requests that the contained memory buffer have at least cb bytes allocated.
256 * This may expand or shrink the string's storage, but will never truncate the
257 * contained string. In other words, cb will be ignored if it's smaller than
258 * length() + 1.
259 *
260 * @param cb New minimum size (in bytes) of member memory buffer.
261 *
262 * @throws std::bad_alloc On allocation error. The object is left unchanged.
263 */
264 void reserve(size_t cb)
265 {
266 if ( ( cb != m_cbAllocated
267 && cb > m_cch + 1)
268 || ( m_psz == NULL
269 && cb > 0))
270 {
271 int rc = RTStrRealloc(&m_psz, cb);
272 if (RT_SUCCESS(rc))
273 m_cbAllocated = cb;
274#ifdef RT_EXCEPTIONS_ENABLED
275 else
276 throw std::bad_alloc();
277#endif
278 }
279 }
280
281 /**
282 * A C like version of the reserve method, i.e. return code instead of throw.
283 *
284 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
285 * @param cb New minimum size (in bytes) of member memory buffer.
286 */
287 int reserveNoThrow(size_t cb) RT_NOEXCEPT
288 {
289 if ( ( cb != m_cbAllocated
290 && cb > m_cch + 1)
291 || ( m_psz == NULL
292 && cb > 0))
293 {
294 int rc = RTStrRealloc(&m_psz, cb);
295 if (RT_SUCCESS(rc))
296 m_cbAllocated = cb;
297 else
298 return rc;
299 }
300 return VINF_SUCCESS;
301 }
302
303 /**
304 * Deallocates all memory.
305 */
306 inline void setNull()
307 {
308 cleanup();
309 }
310
311 /**
312 * Assigns a copy of pcsz to @a this.
313 *
314 * @param pcsz The source string.
315 *
316 * @throws std::bad_alloc On allocation failure. The object is left describing
317 * a NULL string.
318 *
319 * @returns Reference to the object.
320 */
321 RTCString &operator=(const char *pcsz)
322 {
323 if (m_psz != pcsz)
324 {
325 cleanup();
326 copyFromN(pcsz, pcsz ? strlen(pcsz) : 0);
327 }
328 return *this;
329 }
330
331 /**
332 * Assigns a copy of s to @a this.
333 *
334 * @param s The source string.
335 *
336 * @throws std::bad_alloc On allocation failure. The object is left describing
337 * a NULL string.
338 *
339 * @returns Reference to the object.
340 */
341 RTCString &operator=(const RTCString &s)
342 {
343 if (this != &s)
344 {
345 cleanup();
346 copyFromN(s.m_psz, s.m_cch);
347 }
348 return *this;
349 }
350
351 /**
352 * Assigns a copy of another RTCString.
353 *
354 * @param a_rSrc Reference to the source string.
355 * @throws std::bad_alloc On allocation error. The object is left unchanged.
356 */
357 RTCString &assign(const RTCString &a_rSrc);
358
359 /**
360 * Assigns a copy of another RTCString.
361 *
362 * @param a_rSrc Reference to the source string.
363 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
364 */
365 int assignNoThrow(const RTCString &a_rSrc) RT_NOEXCEPT;
366
367 /**
368 * Assigns a copy of a C-style string.
369 *
370 * @param a_pszSrc Pointer to the C-style source string.
371 * @throws std::bad_alloc On allocation error. The object is left unchanged.
372 * @remarks ASSUMES valid
373 */
374 RTCString &assign(const char *a_pszSrc);
375
376 /**
377 * Assigns a copy of a C-style string.
378 *
379 * @param a_pszSrc Pointer to the C-style source string.
380 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
381 * @remarks ASSUMES valid
382 */
383 int assignNoThrow(const char *a_pszSrc) RT_NOEXCEPT;
384
385 /**
386 * Assigns a partial copy of another RTCString.
387 *
388 * @param a_rSrc The source string.
389 * @param a_offSrc The byte offset into the source string.
390 * @param a_cchSrc The max number of chars (encoded UTF-8 bytes)
391 * to copy from the source string.
392 * @throws std::bad_alloc On allocation error. The object is left unchanged.
393 */
394 RTCString &assign(const RTCString &a_rSrc, size_t a_offSrc, size_t a_cchSrc = npos);
395
396 /**
397 * Assigns a partial copy of another RTCString.
398 *
399 * @param a_rSrc The source string.
400 * @param a_offSrc The byte offset into the source string.
401 * @param a_cchSrc The max number of chars (encoded UTF-8 bytes)
402 * to copy from the source string.
403 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
404 */
405 int assignNoThrow(const RTCString &a_rSrc, size_t a_offSrc, size_t a_cchSrc = npos) RT_NOEXCEPT;
406
407 /**
408 * Assigns a partial copy of a C-style string.
409 *
410 * @param a_pszSrc The source string (UTF-8).
411 * @param a_cchSrc The max number of chars (encoded UTF-8 bytes)
412 * to copy from the source string.
413 * @throws std::bad_alloc On allocation error. The object is left unchanged.
414 */
415 RTCString &assign(const char *a_pszSrc, size_t a_cchSrc);
416
417 /**
418 * Assigns a partial copy of a C-style string.
419 *
420 * @param a_pszSrc The source string (UTF-8).
421 * @param a_cchSrc The max number of chars (encoded UTF-8 bytes)
422 * to copy from the source string.
423 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
424 */
425 int assignNoThrow(const char *a_pszSrc, size_t a_cchSrc) RT_NOEXCEPT;
426
427 /**
428 * Assigs a string containing @a a_cTimes repetitions of the character @a a_ch.
429 *
430 * @param a_cTimes The number of times the character is repeated.
431 * @param a_ch The character to fill the string with.
432 * @throws std::bad_alloc On allocation error. The object is left unchanged.
433 */
434 RTCString &assign(size_t a_cTimes, char a_ch);
435
436 /**
437 * Assigs a string containing @a a_cTimes repetitions of the character @a a_ch.
438 *
439 * @param a_cTimes The number of times the character is repeated.
440 * @param a_ch The character to fill the string with.
441 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
442 */
443 int assignNoThrow(size_t a_cTimes, char a_ch) RT_NOEXCEPT;
444
445 /**
446 * Assigns the output of the string format operation (RTStrPrintf).
447 *
448 * @param pszFormat Pointer to the format string,
449 * @see pg_rt_str_format.
450 * @param ... Ellipsis containing the arguments specified by
451 * the format string.
452 *
453 * @throws std::bad_alloc On allocation error. Object state is undefined.
454 *
455 * @returns Reference to the object.
456 */
457 RTCString &printf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
458
459 /**
460 * Assigns the output of the string format operation (RTStrPrintf).
461 *
462 * @param pszFormat Pointer to the format string,
463 * @see pg_rt_str_format.
464 * @param ... Ellipsis containing the arguments specified by
465 * the format string.
466 *
467 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
468 */
469 int printfNoThrow(const char *pszFormat, ...) RT_NOEXCEPT RT_IPRT_FORMAT_ATTR(1, 2);
470
471 /**
472 * Assigns the output of the string format operation (RTStrPrintfV).
473 *
474 * @param pszFormat Pointer to the format string,
475 * @see pg_rt_str_format.
476 * @param va Argument vector containing the arguments
477 * specified by the format string.
478 *
479 * @throws std::bad_alloc On allocation error. Object state is undefined.
480 *
481 * @returns Reference to the object.
482 */
483 RTCString &printfV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
484
485 /**
486 * Assigns the output of the string format operation (RTStrPrintfV).
487 *
488 * @param pszFormat Pointer to the format string,
489 * @see pg_rt_str_format.
490 * @param va Argument vector containing the arguments
491 * specified by the format string.
492 *
493 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
494 */
495 int printfVNoThrow(const char *pszFormat, va_list va) RT_NOEXCEPT RT_IPRT_FORMAT_ATTR(1, 0);
496
497 /**
498 * Appends the string @a that to @a rThat.
499 *
500 * @param rThat The string to append.
501 * @throws std::bad_alloc On allocation error. The object is left unchanged.
502 * @returns Reference to the object.
503 */
504 RTCString &append(const RTCString &rThat);
505
506 /**
507 * Appends the string @a that to @a rThat.
508 *
509 * @param rThat The string to append.
510 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
511 */
512 int appendNoThrow(const RTCString &rThat) RT_NOEXCEPT;
513
514 /**
515 * Appends the string @a pszSrc to @a this.
516 *
517 * @param pszSrc The C-style string to append.
518 * @throws std::bad_alloc On allocation error. The object is left unchanged.
519 * @returns Reference to the object.
520 */
521 RTCString &append(const char *pszSrc);
522
523 /**
524 * Appends the string @a pszSrc to @a this.
525 *
526 * @param pszSrc The C-style string to append.
527 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
528 */
529 int appendNoThrow(const char *pszSrc) RT_NOEXCEPT;
530
531 /**
532 * Appends the a substring from @a rThat to @a this.
533 *
534 * @param rThat The string to append a substring from.
535 * @param offStart The start of the substring to append (byte offset,
536 * not codepoint).
537 * @param cchMax The maximum number of bytes to append.
538 * @throws std::bad_alloc On allocation error. The object is left unchanged.
539 * @returns Reference to the object.
540 */
541 RTCString &append(const RTCString &rThat, size_t offStart, size_t cchMax = RTSTR_MAX);
542
543 /**
544 * Appends the a substring from @a rThat to @a this.
545 *
546 * @param rThat The string to append a substring from.
547 * @param offStart The start of the substring to append (byte offset,
548 * not codepoint).
549 * @param cchMax The maximum number of bytes to append.
550 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
551 */
552 int appendNoThrow(const RTCString &rThat, size_t offStart, size_t cchMax = RTSTR_MAX) RT_NOEXCEPT;
553
554 /**
555 * Appends the first @a cchMax chars from string @a pszThat to @a this.
556 *
557 * @param pszThat The C-style string to append.
558 * @param cchMax The maximum number of bytes to append.
559 * @throws std::bad_alloc On allocation error. The object is left unchanged.
560 * @returns Reference to the object.
561 */
562 RTCString &append(const char *pszThat, size_t cchMax);
563
564 /**
565 * Appends the first @a cchMax chars from string @a pszThat to @a this.
566 *
567 * @param pszThat The C-style string to append.
568 * @param cchMax The maximum number of bytes to append.
569 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
570 */
571 int appendNoThrow(const char *pszThat, size_t cchMax) RT_NOEXCEPT;
572
573 /**
574 * Appends the given character to @a this.
575 *
576 * @param ch The character to append.
577 * @throws std::bad_alloc On allocation error. The object is left unchanged.
578 * @returns Reference to the object.
579 */
580 RTCString &append(char ch);
581
582 /**
583 * Appends the given character to @a this.
584 *
585 * @param ch The character to append.
586 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
587 */
588 int appendNoThrow(char ch) RT_NOEXCEPT;
589
590 /**
591 * Appends the given unicode code point to @a this.
592 *
593 * @param uc The unicode code point to append.
594 * @throws std::bad_alloc On allocation error. The object is left unchanged.
595 * @returns Reference to the object.
596 */
597 RTCString &appendCodePoint(RTUNICP uc);
598
599 /**
600 * Appends the given unicode code point to @a this.
601 *
602 * @param uc The unicode code point to append.
603 * @returns VINF_SUCCESS, VERR_INVALID_UTF8_ENCODING or VERR_NO_STRING_MEMORY.
604 */
605 int appendCodePointNoThrow(RTUNICP uc) RT_NOEXCEPT;
606
607 /**
608 * Appends the output of the string format operation (RTStrPrintf).
609 *
610 * @param pszFormat Pointer to the format string,
611 * @see pg_rt_str_format.
612 * @param ... Ellipsis containing the arguments specified by
613 * the format string.
614 *
615 * @throws std::bad_alloc On allocation error. Object state is undefined.
616 *
617 * @returns Reference to the object.
618 */
619 RTCString &appendPrintf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
620
621 /**
622 * Appends the output of the string format operation (RTStrPrintf).
623 *
624 * @param pszFormat Pointer to the format string,
625 * @see pg_rt_str_format.
626 * @param ... Ellipsis containing the arguments specified by
627 * the format string.
628 *
629 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
630 */
631 int appendPrintfNoThrow(const char *pszFormat, ...) RT_NOEXCEPT RT_IPRT_FORMAT_ATTR(1, 2);
632
633 /**
634 * Appends the output of the string format operation (RTStrPrintfV).
635 *
636 * @param pszFormat Pointer to the format string,
637 * @see pg_rt_str_format.
638 * @param va Argument vector containing the arguments
639 * specified by the format string.
640 *
641 * @throws std::bad_alloc On allocation error. Object state is undefined.
642 *
643 * @returns Reference to the object.
644 */
645 RTCString &appendPrintfV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
646
647 /**
648 * Appends the output of the string format operation (RTStrPrintfV).
649 *
650 * @param pszFormat Pointer to the format string,
651 * @see pg_rt_str_format.
652 * @param va Argument vector containing the arguments
653 * specified by the format string.
654 *
655 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
656 */
657 int appendPrintfVNoThrow(const char *pszFormat, va_list va) RT_NOEXCEPT RT_IPRT_FORMAT_ATTR(1, 0);
658
659 /**
660 * Shortcut to append(), RTCString variant.
661 *
662 * @param rThat The string to append.
663 * @returns Reference to the object.
664 */
665 RTCString &operator+=(const RTCString &rThat)
666 {
667 return append(rThat);
668 }
669
670 /**
671 * Shortcut to append(), const char* variant.
672 *
673 * @param pszThat The C-style string to append.
674 * @returns Reference to the object.
675 */
676 RTCString &operator+=(const char *pszThat)
677 {
678 return append(pszThat);
679 }
680
681 /**
682 * Shortcut to append(), char variant.
683 *
684 * @param ch The character to append.
685 *
686 * @returns Reference to the object.
687 */
688 RTCString &operator+=(char ch)
689 {
690 return append(ch);
691 }
692
693 /**
694 * Converts the member string to upper case.
695 *
696 * @returns Reference to the object.
697 */
698 RTCString &toUpper() RT_NOEXCEPT
699 {
700 if (length())
701 {
702 /* Folding an UTF-8 string may result in a shorter encoding (see
703 testcase), so recalculate the length afterwards. */
704 ::RTStrToUpper(m_psz);
705 size_t cchNew = strlen(m_psz);
706 Assert(cchNew <= m_cch);
707 m_cch = cchNew;
708 }
709 return *this;
710 }
711
712 /**
713 * Converts the member string to lower case.
714 *
715 * @returns Reference to the object.
716 */
717 RTCString &toLower() RT_NOEXCEPT
718 {
719 if (length())
720 {
721 /* Folding an UTF-8 string may result in a shorter encoding (see
722 testcase), so recalculate the length afterwards. */
723 ::RTStrToLower(m_psz);
724 size_t cchNew = strlen(m_psz);
725 Assert(cchNew <= m_cch);
726 m_cch = cchNew;
727 }
728 return *this;
729 }
730
731 /**
732 * Erases a sequence from the string.
733 *
734 * @returns Reference to the object.
735 * @param offStart Where in @a this string to start erasing.
736 * @param cchLength How much following @a offStart to erase.
737 */
738 RTCString &erase(size_t offStart = 0, size_t cchLength = npos) RT_NOEXCEPT;
739
740 /**
741 * Replaces a span of @a this string with a replacement string.
742 *
743 * @returns Reference to the object.
744 * @param offStart Where in @a this string to start replacing.
745 * @param cchLength How much following @a offStart to replace. npos is
746 * accepted.
747 * @param rStrReplacement The replacement string.
748 *
749 * @throws std::bad_alloc On allocation error. The object is left unchanged.
750 *
751 * @note Non-standard behaviour if offStart is beyond the end of the string.
752 * No change will occure and strict builds hits a debug assertion.
753 */
754 RTCString &replace(size_t offStart, size_t cchLength, const RTCString &rStrReplacement);
755
756 /**
757 * Replaces a span of @a this string with a replacement string.
758 *
759 * @returns VINF_SUCCESS, VERR_OUT_OF_RANGE or VERR_NO_STRING_MEMORY.
760 * @param offStart Where in @a this string to start replacing.
761 * @param cchLength How much following @a offStart to replace. npos is
762 * accepted.
763 * @param rStrReplacement The replacement string.
764 */
765 int replaceNoThrow(size_t offStart, size_t cchLength, const RTCString &rStrReplacement) RT_NOEXCEPT;
766
767 /**
768 * Replaces a span of @a this string with a replacement substring.
769 *
770 * @returns Reference to the object.
771 * @param offStart Where in @a this string to start replacing.
772 * @param cchLength How much following @a offStart to replace. npos is
773 * accepted.
774 * @param rStrReplacement The string from which a substring is taken.
775 * @param offReplacement The offset into @a rStrReplacement where the
776 * replacement substring starts.
777 * @param cchReplacement The maximum length of the replacement substring.
778 *
779 * @throws std::bad_alloc On allocation error. The object is left unchanged.
780 *
781 * @note Non-standard behaviour if offStart or offReplacement is beyond the
782 * end of the repective strings. No change is made in the former case,
783 * while we consider it an empty string in the latter. In both
784 * situation a debug assertion is raised in strict builds.
785 */
786 RTCString &replace(size_t offStart, size_t cchLength, const RTCString &rStrReplacement,
787 size_t offReplacement, size_t cchReplacement);
788
789 /**
790 * Replaces a span of @a this string with a replacement substring.
791 *
792 * @returns VINF_SUCCESS, VERR_OUT_OF_RANGE or VERR_NO_STRING_MEMORY.
793 * @param offStart Where in @a this string to start replacing.
794 * @param cchLength How much following @a offStart to replace. npos is
795 * accepted.
796 * @param rStrReplacement The string from which a substring is taken.
797 * @param offReplacement The offset into @a rStrReplacement where the
798 * replacement substring starts.
799 * @param cchReplacement The maximum length of the replacement substring.
800 */
801 int replaceNoThrow(size_t offStart, size_t cchLength, const RTCString &rStrReplacement,
802 size_t offReplacement, size_t cchReplacement) RT_NOEXCEPT;
803
804 /**
805 * Replaces a span of @a this string with the replacement string.
806 *
807 * @returns Reference to the object.
808 * @param offStart Where in @a this string to start replacing.
809 * @param cchLength How much following @a offStart to replace. npos is
810 * accepted.
811 * @param pszReplacement The replacement string.
812 *
813 * @throws std::bad_alloc On allocation error. The object is left unchanged.
814 *
815 * @note Non-standard behaviour if offStart is beyond the end of the string.
816 * No change will occure and strict builds hits a debug assertion.
817 */
818 RTCString &replace(size_t offStart, size_t cchLength, const char *pszReplacement);
819
820 /**
821 * Replaces a span of @a this string with the replacement string.
822 *
823 * @returns VINF_SUCCESS, VERR_OUT_OF_RANGE or VERR_NO_STRING_MEMORY.
824 * @param offStart Where in @a this string to start replacing.
825 * @param cchLength How much following @a offStart to replace. npos is
826 * accepted.
827 * @param pszReplacement The replacement string.
828 */
829 int replaceNoThrow(size_t offStart, size_t cchLength, const char *pszReplacement) RT_NOEXCEPT;
830
831 /**
832 * Replaces a span of @a this string with the replacement string.
833 *
834 * @returns Reference to the object.
835 * @param offStart Where in @a this string to start replacing.
836 * @param cchLength How much following @a offStart to replace. npos is
837 * accepted.
838 * @param pszReplacement The replacement string.
839 * @param cchReplacement How much of @a pszReplacement to use at most. If a
840 * zero terminator is found before reaching this value,
841 * we'll stop there.
842 *
843 * @throws std::bad_alloc On allocation error. The object is left unchanged.
844 *
845 * @note Non-standard behaviour if offStart is beyond the end of the string.
846 * No change will occure and strict builds hits a debug assertion.
847 */
848 RTCString &replace(size_t offStart, size_t cchLength, const char *pszReplacement, size_t cchReplacement);
849
850 /**
851 * Replaces a span of @a this string with the replacement string.
852 *
853 * @returns VINF_SUCCESS, VERR_OUT_OF_RANGE or VERR_NO_STRING_MEMORY.
854 * @param offStart Where in @a this string to start replacing.
855 * @param cchLength How much following @a offStart to replace. npos is
856 * accepted.
857 * @param pszReplacement The replacement string.
858 * @param cchReplacement How much of @a pszReplacement to use at most. If a
859 * zero terminator is found before reaching this value,
860 * we'll stop there.
861 */
862 int replaceNoThrow(size_t offStart, size_t cchLength, const char *pszReplacement, size_t cchReplacement) RT_NOEXCEPT;
863
864 /**
865 * Truncates the string to a max length of @a cchMax.
866 *
867 * If the string is shorter than @a cchMax characters, no change is made.
868 *
869 * If the @a cchMax is not at the start of a UTF-8 sequence, it will be adjusted
870 * down to the start of the UTF-8 sequence. Thus, after a truncation, the
871 * length() may be smaller than @a cchMax.
872 *
873 */
874 RTCString &truncate(size_t cchMax) RT_NOEXCEPT;
875
876 /**
877 * Index operator.
878 *
879 * Returns the byte at the given index, or a null byte if the index is not
880 * smaller than length(). This does _not_ count codepoints but simply points
881 * into the member C-style string.
882 *
883 * @param i The index into the string buffer.
884 * @returns char at the index or null.
885 */
886 inline char operator[](size_t i) const RT_NOEXCEPT
887 {
888 if (i < length())
889 return m_psz[i];
890 return '\0';
891 }
892
893 /**
894 * Returns the contained string as a const C-style string pointer.
895 *
896 * This never returns NULL; if the string is empty, this returns a pointer to
897 * static null byte.
898 *
899 * @returns const pointer to C-style string.
900 */
901 inline const char *c_str() const RT_NOEXCEPT
902 {
903 return (m_psz) ? m_psz : "";
904 }
905
906 /**
907 * Returns a non-const raw pointer that allows to modify the string directly.
908 * As opposed to c_str() and raw(), this DOES return NULL for an empty string
909 * because we cannot return a non-const pointer to a static "" global.
910 *
911 * @warning
912 * -# Be sure not to modify data beyond the allocated memory! Call
913 * capacity() to find out how large that buffer is.
914 * -# After any operation that modifies the length of the string,
915 * you _must_ call RTCString::jolt(), or subsequent copy operations
916 * may go nowhere. Better not use mutableRaw() at all.
917 */
918 char *mutableRaw() RT_NOEXCEPT
919 {
920 return m_psz;
921 }
922
923 /**
924 * Clean up after using mutableRaw.
925 *
926 * Intended to be called after something has messed with the internal string
927 * buffer (e.g. after using mutableRaw() or Utf8Str::asOutParam()). Resets the
928 * internal lengths correctly. Otherwise subsequent copy operations may go
929 * nowhere.
930 */
931 void jolt() RT_NOEXCEPT
932 {
933 if (m_psz)
934 {
935 m_cch = strlen(m_psz);
936 m_cbAllocated = m_cch + 1; /* (Required for the Utf8Str::asOutParam case) */
937 }
938 else
939 {
940 m_cch = 0;
941 m_cbAllocated = 0;
942 }
943 }
944
945 /**
946 * Returns @c true if the member string has no length.
947 *
948 * This is @c true for instances created from both NULL and "" input
949 * strings.
950 *
951 * This states nothing about how much memory might be allocated.
952 *
953 * @returns @c true if empty, @c false if not.
954 */
955 bool isEmpty() const RT_NOEXCEPT
956 {
957 return length() == 0;
958 }
959
960 /**
961 * Returns @c false if the member string has no length.
962 *
963 * This is @c false for instances created from both NULL and "" input
964 * strings.
965 *
966 * This states nothing about how much memory might be allocated.
967 *
968 * @returns @c false if empty, @c true if not.
969 */
970 bool isNotEmpty() const RT_NOEXCEPT
971 {
972 return length() != 0;
973 }
974
975 /** Case sensitivity selector. */
976 enum CaseSensitivity
977 {
978 CaseSensitive,
979 CaseInsensitive
980 };
981
982 /**
983 * Compares the member string to a C-string.
984 *
985 * @param pcszThat The string to compare with.
986 * @param cs Whether comparison should be case-sensitive.
987 * @returns 0 if equal, negative if this is smaller than @a pcsz, positive
988 * if larger.
989 */
990 int compare(const char *pcszThat, CaseSensitivity cs = CaseSensitive) const RT_NOEXCEPT
991 {
992 /* This klugde is for m_cch=0 and m_psz=NULL. pcsz=NULL and psz=""
993 are treated the same way so that str.compare(str2.c_str()) works. */
994 if (length() == 0)
995 return pcszThat == NULL || *pcszThat == '\0' ? 0 : -1;
996
997 if (cs == CaseSensitive)
998 return ::RTStrCmp(m_psz, pcszThat);
999 return ::RTStrICmp(m_psz, pcszThat);
1000 }
1001
1002 /**
1003 * Compares the member string to another RTCString.
1004 *
1005 * @param rThat The string to compare with.
1006 * @param cs Whether comparison should be case-sensitive.
1007 * @returns 0 if equal, negative if this is smaller than @a pcsz, positive
1008 * if larger.
1009 */
1010 int compare(const RTCString &rThat, CaseSensitivity cs = CaseSensitive) const RT_NOEXCEPT
1011 {
1012 if (cs == CaseSensitive)
1013 return ::RTStrCmp(m_psz, rThat.m_psz);
1014 return ::RTStrICmp(m_psz, rThat.m_psz);
1015 }
1016
1017 /**
1018 * Compares the two strings.
1019 *
1020 * @returns true if equal, false if not.
1021 * @param rThat The string to compare with.
1022 */
1023 bool equals(const RTCString &rThat) const RT_NOEXCEPT
1024 {
1025 return rThat.length() == length()
1026 && ( length() == 0
1027 || memcmp(rThat.m_psz, m_psz, length()) == 0);
1028 }
1029
1030 /**
1031 * Compares the two strings.
1032 *
1033 * @returns true if equal, false if not.
1034 * @param pszThat The string to compare with.
1035 */
1036 bool equals(const char *pszThat) const RT_NOEXCEPT
1037 {
1038 /* This klugde is for m_cch=0 and m_psz=NULL. pcsz=NULL and psz=""
1039 are treated the same way so that str.equals(str2.c_str()) works. */
1040 if (length() == 0)
1041 return pszThat == NULL || *pszThat == '\0';
1042 return RTStrCmp(pszThat, m_psz) == 0;
1043 }
1044
1045 /**
1046 * Compares the two strings ignoring differences in case.
1047 *
1048 * @returns true if equal, false if not.
1049 * @param that The string to compare with.
1050 */
1051 bool equalsIgnoreCase(const RTCString &that) const RT_NOEXCEPT
1052 {
1053 /* Unfolded upper and lower case characters may require different
1054 amount of encoding space, so the length optimization doesn't work. */
1055 return RTStrICmp(that.m_psz, m_psz) == 0;
1056 }
1057
1058 /**
1059 * Compares the two strings ignoring differences in case.
1060 *
1061 * @returns true if equal, false if not.
1062 * @param pszThat The string to compare with.
1063 */
1064 bool equalsIgnoreCase(const char *pszThat) const RT_NOEXCEPT
1065 {
1066 /* This klugde is for m_cch=0 and m_psz=NULL. pcsz=NULL and psz=""
1067 are treated the same way so that str.equalsIgnoreCase(str2.c_str()) works. */
1068 if (length() == 0)
1069 return pszThat == NULL || *pszThat == '\0';
1070 return RTStrICmp(pszThat, m_psz) == 0;
1071 }
1072
1073 /** @name Comparison operators.
1074 * @{ */
1075 bool operator==(const RTCString &that) const { return equals(that); }
1076 bool operator!=(const RTCString &that) const { return !equals(that); }
1077 bool operator<( const RTCString &that) const { return compare(that) < 0; }
1078 bool operator>( const RTCString &that) const { return compare(that) > 0; }
1079
1080 bool operator==(const char *pszThat) const { return equals(pszThat); }
1081 bool operator!=(const char *pszThat) const { return !equals(pszThat); }
1082 bool operator<( const char *pszThat) const { return compare(pszThat) < 0; }
1083 bool operator>( const char *pszThat) const { return compare(pszThat) > 0; }
1084 /** @} */
1085
1086 /** Max string offset value.
1087 *
1088 * When returned by a method, this indicates failure. When taken as input,
1089 * typically a default, it means all the way to the string terminator.
1090 */
1091 static const size_t npos;
1092
1093 /**
1094 * Find the given substring.
1095 *
1096 * Looks for @a pszNeedle in @a this starting at @a offStart and returns its
1097 * position as a byte (not codepoint) offset, counting from the beginning of
1098 * @a this as 0.
1099 *
1100 * @param pszNeedle The substring to find.
1101 * @param offStart The (byte) offset into the string buffer to start
1102 * searching.
1103 *
1104 * @returns 0 based position of pszNeedle. npos if not found.
1105 */
1106 size_t find(const char *pszNeedle, size_t offStart = 0) const RT_NOEXCEPT;
1107 size_t find_first_of(const char *pszNeedle, size_t offStart = 0) const RT_NOEXCEPT
1108 { return find(pszNeedle, offStart); }
1109
1110 /**
1111 * Find the given substring.
1112 *
1113 * Looks for @a pStrNeedle in @a this starting at @a offStart and returns its
1114 * position as a byte (not codepoint) offset, counting from the beginning of
1115 * @a this as 0.
1116 *
1117 * @param pStrNeedle The substring to find.
1118 * @param offStart The (byte) offset into the string buffer to start
1119 * searching.
1120 *
1121 * @returns 0 based position of pStrNeedle. npos if not found or pStrNeedle is
1122 * NULL or an empty string.
1123 */
1124 size_t find(const RTCString *pStrNeedle, size_t offStart = 0) const RT_NOEXCEPT;
1125
1126 /**
1127 * Find the given substring.
1128 *
1129 * Looks for @a rStrNeedle in @a this starting at @a offStart and returns its
1130 * position as a byte (not codepoint) offset, counting from the beginning of
1131 * @a this as 0.
1132 *
1133 * @param rStrNeedle The substring to find.
1134 * @param offStart The (byte) offset into the string buffer to start
1135 * searching.
1136 *
1137 * @returns 0 based position of pStrNeedle. npos if not found or pStrNeedle is
1138 * NULL or an empty string.
1139 */
1140 size_t find(const RTCString &rStrNeedle, size_t offStart = 0) const RT_NOEXCEPT;
1141 size_t find_first_of(const RTCString &rStrNeedle, size_t offStart = 0) const RT_NOEXCEPT
1142 { return find(rStrNeedle, offStart); }
1143
1144 /**
1145 * Find the given character (byte).
1146 *
1147 * @returns 0 based position of chNeedle. npos if not found or pStrNeedle is
1148 * NULL or an empty string.
1149 * @param chNeedle The character (byte) to find.
1150 * @param offStart The (byte) offset into the string buffer to start
1151 * searching. Default is start of the string.
1152 *
1153 * @note This searches for a C character value, not a codepoint. Use the
1154 * string version to locate codepoints above U+7F.
1155 */
1156 size_t find(char chNeedle, size_t offStart = 0) const RT_NOEXCEPT;
1157 size_t find_first_of(char chNeedle, size_t offStart = 0) const RT_NOEXCEPT
1158 { return find(chNeedle, offStart); }
1159
1160 /**
1161 * Replaces all occurences of cFind with cReplace in the member string.
1162 * In order not to produce invalid UTF-8, the characters must be ASCII
1163 * values less than 128; this is not verified.
1164 *
1165 * @param chFind Character to replace. Must be ASCII < 128.
1166 * @param chReplace Character to replace cFind with. Must be ASCII < 128.
1167 */
1168 void findReplace(char chFind, char chReplace) RT_NOEXCEPT;
1169
1170 /**
1171 * Count the occurences of the specified character in the string.
1172 *
1173 * @param ch What to search for. Must be ASCII < 128.
1174 * @remarks QString::count
1175 */
1176 size_t count(char ch) const RT_NOEXCEPT;
1177
1178 /**
1179 * Count the occurences of the specified sub-string in the string.
1180 *
1181 * @param psz What to search for.
1182 * @param cs Case sensitivity selector.
1183 * @remarks QString::count
1184 */
1185 size_t count(const char *psz, CaseSensitivity cs = CaseSensitive) const RT_NOEXCEPT;
1186
1187 /**
1188 * Count the occurences of the specified sub-string in the string.
1189 *
1190 * @param pStr What to search for.
1191 * @param cs Case sensitivity selector.
1192 * @remarks QString::count
1193 */
1194 size_t count(const RTCString *pStr, CaseSensitivity cs = CaseSensitive) const RT_NOEXCEPT;
1195
1196 /**
1197 * Strips leading and trailing spaces.
1198 *
1199 * @returns this
1200 */
1201 RTCString &strip() RT_NOEXCEPT;
1202
1203 /**
1204 * Strips leading spaces.
1205 *
1206 * @returns this
1207 */
1208 RTCString &stripLeft() RT_NOEXCEPT;
1209
1210 /**
1211 * Strips trailing spaces.
1212 *
1213 * @returns this
1214 */
1215 RTCString &stripRight() RT_NOEXCEPT;
1216
1217 /**
1218 * Returns a substring of @a this as a new Utf8Str.
1219 *
1220 * Works exactly like its equivalent in std::string. With the default
1221 * parameters "0" and "npos", this always copies the entire string. The
1222 * "pos" and "n" arguments represent bytes; it is the caller's responsibility
1223 * to ensure that the offsets do not copy invalid UTF-8 sequences. When
1224 * used in conjunction with find() and length(), this will work.
1225 *
1226 * @param pos Index of first byte offset to copy from @a this,
1227 * counting from 0.
1228 * @param n Number of bytes to copy, starting with the one at "pos".
1229 * The copying will stop if the null terminator is encountered before
1230 * n bytes have been copied.
1231 */
1232 RTCString substr(size_t pos = 0, size_t n = npos) const
1233 {
1234 return RTCString(*this, pos, n);
1235 }
1236
1237 /**
1238 * Returns a substring of @a this as a new Utf8Str. As opposed to substr(), this
1239 * variant takes codepoint offsets instead of byte offsets.
1240 *
1241 * @param pos Index of first unicode codepoint to copy from
1242 * @a this, counting from 0.
1243 * @param n Number of unicode codepoints to copy, starting with
1244 * the one at "pos". The copying will stop if the null
1245 * terminator is encountered before n codepoints have
1246 * been copied.
1247 */
1248 RTCString substrCP(size_t pos = 0, size_t n = npos) const;
1249
1250 /**
1251 * Returns true if @a this ends with @a that.
1252 *
1253 * @param that Suffix to test for.
1254 * @param cs Case sensitivity selector.
1255 * @returns true if match, false if mismatch.
1256 */
1257 bool endsWith(const RTCString &that, CaseSensitivity cs = CaseSensitive) const RT_NOEXCEPT;
1258
1259 /**
1260 * Returns true if @a this begins with @a that.
1261 * @param that Prefix to test for.
1262 * @param cs Case sensitivity selector.
1263 * @returns true if match, false if mismatch.
1264 */
1265 bool startsWith(const RTCString &that, CaseSensitivity cs = CaseSensitive) const RT_NOEXCEPT;
1266
1267 /**
1268 * Checks if the string starts with the given word, ignoring leading blanks.
1269 *
1270 * @param pszWord The word to test for.
1271 * @param enmCase Case sensitivity selector.
1272 * @returns true if match, false if mismatch.
1273 */
1274 bool startsWithWord(const char *pszWord, CaseSensitivity enmCase = CaseSensitive) const RT_NOEXCEPT;
1275
1276 /**
1277 * Checks if the string starts with the given word, ignoring leading blanks.
1278 *
1279 * @param rThat Prefix to test for.
1280 * @param enmCase Case sensitivity selector.
1281 * @returns true if match, false if mismatch.
1282 */
1283 bool startsWithWord(const RTCString &rThat, CaseSensitivity enmCase = CaseSensitive) const RT_NOEXCEPT;
1284
1285 /**
1286 * Returns true if @a this contains @a that (strstr).
1287 *
1288 * @param that Substring to look for.
1289 * @param cs Case sensitivity selector.
1290 * @returns true if found, false if not found.
1291 */
1292 bool contains(const RTCString &that, CaseSensitivity cs = CaseSensitive) const RT_NOEXCEPT;
1293
1294 /**
1295 * Returns true if @a this contains @a pszNeedle (strstr).
1296 *
1297 * @param pszNeedle Substring to look for.
1298 * @param cs Case sensitivity selector.
1299 * @returns true if found, false if not found.
1300 */
1301 bool contains(const char *pszNeedle, CaseSensitivity cs = CaseSensitive) const RT_NOEXCEPT;
1302
1303 /**
1304 * Attempts to convert the member string into a 32-bit integer.
1305 *
1306 * @returns 32-bit unsigned number on success.
1307 * @returns 0 on failure.
1308 */
1309 int32_t toInt32() const RT_NOEXCEPT
1310 {
1311 return RTStrToInt32(c_str());
1312 }
1313
1314 /**
1315 * Attempts to convert the member string into an unsigned 32-bit integer.
1316 *
1317 * @returns 32-bit unsigned number on success.
1318 * @returns 0 on failure.
1319 */
1320 uint32_t toUInt32() const RT_NOEXCEPT
1321 {
1322 return RTStrToUInt32(c_str());
1323 }
1324
1325 /**
1326 * Attempts to convert the member string into an 64-bit integer.
1327 *
1328 * @returns 64-bit unsigned number on success.
1329 * @returns 0 on failure.
1330 */
1331 int64_t toInt64() const RT_NOEXCEPT
1332 {
1333 return RTStrToInt64(c_str());
1334 }
1335
1336 /**
1337 * Attempts to convert the member string into an unsigned 64-bit integer.
1338 *
1339 * @returns 64-bit unsigned number on success.
1340 * @returns 0 on failure.
1341 */
1342 uint64_t toUInt64() const RT_NOEXCEPT
1343 {
1344 return RTStrToUInt64(c_str());
1345 }
1346
1347 /**
1348 * Attempts to convert the member string into an unsigned 64-bit integer.
1349 *
1350 * @param i Where to return the value on success.
1351 * @returns IPRT error code, see RTStrToInt64.
1352 */
1353 int toInt(uint64_t &i) const RT_NOEXCEPT;
1354
1355 /**
1356 * Attempts to convert the member string into an unsigned 32-bit integer.
1357 *
1358 * @param i Where to return the value on success.
1359 * @returns IPRT error code, see RTStrToInt32.
1360 */
1361 int toInt(uint32_t &i) const RT_NOEXCEPT;
1362
1363 /** Splitting behavior regarding empty sections in the string. */
1364 enum SplitMode
1365 {
1366 KeepEmptyParts, /**< Empty parts are added as empty strings to the result list. */
1367 RemoveEmptyParts /**< Empty parts are skipped. */
1368 };
1369
1370 /**
1371 * Splits a string separated by strSep into its parts.
1372 *
1373 * @param a_rstrSep The separator to search for.
1374 * @param a_enmMode How should empty parts be handled.
1375 * @returns separated strings as string list.
1376 * @throws std::bad_alloc On allocation error.
1377 */
1378 RTCList<RTCString, RTCString *> split(const RTCString &a_rstrSep,
1379 SplitMode a_enmMode = RemoveEmptyParts) const;
1380
1381 /**
1382 * Joins a list of strings together using the provided separator and
1383 * an optional prefix for each item in the list.
1384 *
1385 * @param a_rList The list to join.
1386 * @param a_rstrPrefix The prefix used for appending to each item.
1387 * @param a_rstrSep The separator used for joining.
1388 * @returns joined string.
1389 * @throws std::bad_alloc On allocation error.
1390 */
1391 static RTCString joinEx(const RTCList<RTCString, RTCString *> &a_rList,
1392 const RTCString &a_rstrPrefix /* = "" */,
1393 const RTCString &a_rstrSep /* = "" */);
1394
1395 /**
1396 * Joins a list of strings together using the provided separator.
1397 *
1398 * @param a_rList The list to join.
1399 * @param a_rstrSep The separator used for joining.
1400 * @returns joined string.
1401 * @throws std::bad_alloc On allocation error.
1402 */
1403 static RTCString join(const RTCList<RTCString, RTCString *> &a_rList,
1404 const RTCString &a_rstrSep = "");
1405
1406 /**
1407 * Swaps two strings in a fast way.
1408 *
1409 * Exception safe.
1410 *
1411 * @param a_rThat The string to swap with.
1412 */
1413 inline void swap(RTCString &a_rThat) RT_NOEXCEPT
1414 {
1415 char *pszTmp = m_psz;
1416 size_t cchTmp = m_cch;
1417 size_t cbAllocatedTmp = m_cbAllocated;
1418
1419 m_psz = a_rThat.m_psz;
1420 m_cch = a_rThat.m_cch;
1421 m_cbAllocated = a_rThat.m_cbAllocated;
1422
1423 a_rThat.m_psz = pszTmp;
1424 a_rThat.m_cch = cchTmp;
1425 a_rThat.m_cbAllocated = cbAllocatedTmp;
1426 }
1427
1428protected:
1429
1430 /**
1431 * Hide operator bool() to force people to use isEmpty() explicitly.
1432 */
1433 operator bool() const;
1434
1435 /**
1436 * Destructor implementation, also used to clean up in operator=() before
1437 * assigning a new string.
1438 */
1439 void cleanup() RT_NOEXCEPT
1440 {
1441 if (m_psz)
1442 {
1443 RTStrFree(m_psz);
1444 m_psz = NULL;
1445 m_cch = 0;
1446 m_cbAllocated = 0;
1447 }
1448 }
1449
1450 /**
1451 * Protected internal helper to copy a string.
1452 *
1453 * This ignores the previous object state, so either call this from a
1454 * constructor or call cleanup() first. copyFromN() unconditionally sets
1455 * the members to a copy of the given other strings and makes no
1456 * assumptions about previous contents. Can therefore be used both in copy
1457 * constructors, when member variables have no defined value, and in
1458 * assignments after having called cleanup().
1459 *
1460 * @param pcszSrc The source string.
1461 * @param cchSrc The number of chars (bytes) to copy from the
1462 * source strings. RTSTR_MAX is NOT accepted.
1463 *
1464 * @throws std::bad_alloc On allocation failure. The object is left
1465 * describing a NULL string.
1466 */
1467 void copyFromN(const char *pcszSrc, size_t cchSrc)
1468 {
1469 if (cchSrc)
1470 {
1471 m_psz = RTStrAlloc(cchSrc + 1);
1472 if (RT_LIKELY(m_psz))
1473 {
1474 m_cch = cchSrc;
1475 m_cbAllocated = cchSrc + 1;
1476 memcpy(m_psz, pcszSrc, cchSrc);
1477 m_psz[cchSrc] = '\0';
1478 }
1479 else
1480 {
1481 m_cch = 0;
1482 m_cbAllocated = 0;
1483#ifdef RT_EXCEPTIONS_ENABLED
1484 throw std::bad_alloc();
1485#endif
1486 }
1487 }
1488 else
1489 {
1490 m_cch = 0;
1491 m_cbAllocated = 0;
1492 m_psz = NULL;
1493 }
1494 }
1495
1496 /**
1497 * Appends exactly @a cchSrc chars from @a pszSrc to @a this.
1498 *
1499 * This is an internal worker for the append() methods.
1500 *
1501 * @returns Reference to the object.
1502 * @param pszSrc The source string.
1503 * @param cchSrc The source string length (exact).
1504 * @throws std::bad_alloc On allocation error. The object is left unchanged.
1505 *
1506 */
1507 RTCString &appendWorker(const char *pszSrc, size_t cchSrc);
1508
1509 /**
1510 * Appends exactly @a cchSrc chars from @a pszSrc to @a this.
1511 *
1512 * This is an internal worker for the appendNoThrow() methods.
1513 *
1514 * @returns VINF_SUCCESS or VERR_NO_STRING_MEMORY.
1515 * @param pszSrc The source string.
1516 * @param cchSrc The source string length (exact).
1517 */
1518 int appendWorkerNoThrow(const char *pszSrc, size_t cchSrc) RT_NOEXCEPT;
1519
1520 /**
1521 * Replaces exatly @a cchLength chars at @a offStart with @a cchSrc from @a
1522 * pszSrc.
1523 *
1524 * @returns Reference to the object.
1525 * @param offStart Where in @a this string to start replacing.
1526 * @param cchLength How much following @a offStart to replace. npos is
1527 * accepted.
1528 * @param pszSrc The replacement string.
1529 * @param cchSrc The exactly length of the replacement string.
1530 *
1531 * @throws std::bad_alloc On allocation error. The object is left unchanged.
1532 */
1533 RTCString &replaceWorker(size_t offStart, size_t cchLength, const char *pszSrc, size_t cchSrc);
1534
1535 /**
1536 * Replaces exatly @a cchLength chars at @a offStart with @a cchSrc from @a
1537 * pszSrc.
1538 *
1539 * @returns VINF_SUCCESS, VERR_OUT_OF_RANGE or VERR_NO_STRING_MEMORY.
1540 * @param offStart Where in @a this string to start replacing.
1541 * @param cchLength How much following @a offStart to replace. npos is
1542 * accepted.
1543 * @param pszSrc The replacement string.
1544 * @param cchSrc The exactly length of the replacement string.
1545 */
1546 int replaceWorkerNoThrow(size_t offStart, size_t cchLength, const char *pszSrc, size_t cchSrc) RT_NOEXCEPT;
1547
1548 static DECLCALLBACK(size_t) printfOutputCallback(void *pvArg, const char *pachChars, size_t cbChars);
1549 static DECLCALLBACK(size_t) printfOutputCallbackNoThrow(void *pvArg, const char *pachChars, size_t cbChars) RT_NOEXCEPT;
1550
1551 char *m_psz; /**< The string buffer. */
1552 size_t m_cch; /**< strlen(m_psz) - i.e. no terminator included. */
1553 size_t m_cbAllocated; /**< Size of buffer that m_psz points to; at least m_cbLength + 1. */
1554};
1555
1556/** @} */
1557
1558
1559/** @addtogroup grp_rt_cpp_string
1560 * @{
1561 */
1562
1563/**
1564 * Concatenate two strings.
1565 *
1566 * @param a_rstr1 String one.
1567 * @param a_rstr2 String two.
1568 * @returns the concatenate string.
1569 *
1570 * @relates RTCString
1571 */
1572RTDECL(const RTCString) operator+(const RTCString &a_rstr1, const RTCString &a_rstr2);
1573
1574/**
1575 * Concatenate two strings.
1576 *
1577 * @param a_rstr1 String one.
1578 * @param a_psz2 String two.
1579 * @returns the concatenate string.
1580 *
1581 * @relates RTCString
1582 */
1583RTDECL(const RTCString) operator+(const RTCString &a_rstr1, const char *a_psz2);
1584
1585/**
1586 * Concatenate two strings.
1587 *
1588 * @param a_psz1 String one.
1589 * @param a_rstr2 String two.
1590 * @returns the concatenate string.
1591 *
1592 * @relates RTCString
1593 */
1594RTDECL(const RTCString) operator+(const char *a_psz1, const RTCString &a_rstr2);
1595
1596/**
1597 * Class with RTCString::printf as constructor for your convenience.
1598 *
1599 * Constructing a RTCString string object from a format string and a variable
1600 * number of arguments can easily be confused with the other RTCString
1601 * constructors, thus this child class.
1602 *
1603 * The usage of this class is like the following:
1604 * @code
1605 RTCStringFmt strName("program name = %s", argv[0]);
1606 @endcode
1607 */
1608class RTCStringFmt : public RTCString
1609{
1610public:
1611
1612 /**
1613 * Constructs a new string given the format string and the list of the
1614 * arguments for the format string.
1615 *
1616 * @param a_pszFormat Pointer to the format string (UTF-8),
1617 * @see pg_rt_str_format.
1618 * @param ... Ellipsis containing the arguments specified by
1619 * the format string.
1620 */
1621 explicit RTCStringFmt(const char *a_pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2)
1622 {
1623 va_list va;
1624 va_start(va, a_pszFormat);
1625 printfV(a_pszFormat, va);
1626 va_end(va);
1627 }
1628
1629 RTMEMEF_NEW_AND_DELETE_OPERATORS();
1630
1631protected:
1632 RTCStringFmt() {}
1633};
1634
1635/** @} */
1636
1637#endif /* !IPRT_INCLUDED_cpp_ministring_h */
1638
Note: See TracBrowser for help on using the repository browser.

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