VirtualBox

source: vbox/trunk/include/VBox/com/string.h@ 52312

Last change on this file since 52312 was 52312, checked in by vboxsync, 10 years ago

6219: New parameters related to file size / recording time limitation for VM Video Capture have been added (vcpmaxtime, vcpmaxsize and vcpoptions - special codec options in key=value format). EbmlWriter has been refactored. Removed some redundant code.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 24.4 KB
Line 
1/* $Id: string.h 52312 2014-08-07 12:54:38Z vboxsync $ */
2/** @file
3 * MS COM / XPCOM Abstraction Layer - Smart string classes declaration.
4 */
5
6/*
7 * Copyright (C) 2006-2012 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 *
17 * The contents of this file may alternatively be used under the terms
18 * of the Common Development and Distribution License Version 1.0
19 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20 * VirtualBox OSE distribution, in which case the provisions of the
21 * CDDL are applicable instead of those of the GPL.
22 *
23 * You may elect to license modified versions of this file under the
24 * terms and conditions of either the GPL or the CDDL or both.
25 */
26
27#ifndef ___VBox_com_string_h
28#define ___VBox_com_string_h
29
30/* Make sure all the stdint.h macros are included - must come first! */
31#ifndef __STDC_LIMIT_MACROS
32# define __STDC_LIMIT_MACROS
33#endif
34#ifndef __STDC_CONSTANT_MACROS
35# define __STDC_CONSTANT_MACROS
36#endif
37
38#if defined(VBOX_WITH_XPCOM)
39# include <nsMemory.h>
40#endif
41
42#include "VBox/com/defs.h"
43#include "VBox/com/assert.h"
44
45#include <iprt/mem.h>
46#include <iprt/cpp/ministring.h>
47
48namespace com
49{
50
51class Utf8Str;
52
53// global constant in glue/string.cpp that represents an empty BSTR
54extern const BSTR g_bstrEmpty;
55
56/**
57 * String class used universally in Main for COM-style Utf-16 strings.
58 *
59 * Unfortunately COM on Windows uses UTF-16 everywhere, requiring conversions
60 * back and forth since most of VirtualBox and our libraries use UTF-8.
61 *
62 * To make things more obscure, on Windows, a COM-style BSTR is not just a
63 * pointer to a null-terminated wide character array, but the four bytes (32
64 * bits) BEFORE the memory that the pointer points to are a length DWORD. One
65 * must therefore avoid pointer arithmetic and always use SysAllocString and
66 * the like to deal with BSTR pointers, which manage that DWORD correctly.
67 *
68 * For platforms other than Windows, we provide our own versions of the Sys*
69 * functions in Main/xpcom/helpers.cpp which do NOT use length prefixes though
70 * to be compatible with how XPCOM allocates string parameters to public
71 * functions.
72 *
73 * The Bstr class hides all this handling behind a std::string-like interface
74 * and also provides automatic conversions to RTCString and Utf8Str instances.
75 *
76 * The one advantage of using the SysString* routines is that this makes it
77 * possible to use it as a type of member variables of COM/XPCOM components and
78 * pass their values to callers through component methods' output parameters
79 * using the #cloneTo() operation. Also, the class can adopt (take ownership
80 * of) string buffers returned in output parameters of COM methods using the
81 * #asOutParam() operation and correctly free them afterwards.
82 *
83 * Starting with VirtualBox 3.2, like Utf8Str, Bstr no longer differentiates
84 * between NULL strings and empty strings. In other words, Bstr("") and
85 * Bstr(NULL) behave the same. In both cases, Bstr allocates no memory,
86 * reports a zero length and zero allocated bytes for both, and returns an
87 * empty C wide string from raw().
88 *
89 * @note All Bstr methods ASSUMES valid UTF-16 or UTF-8 input strings.
90 * The VirtualBox policy in this regard is to validate strings coming
91 * from external sources before passing them to Bstr or Utf8Str.
92 */
93class Bstr
94{
95public:
96
97 Bstr()
98 : m_bstr(NULL)
99 { }
100
101 Bstr(const Bstr &that)
102 {
103 copyFrom((const OLECHAR *)that.m_bstr);
104 }
105
106 Bstr(CBSTR that)
107 {
108 copyFrom((const OLECHAR *)that);
109 }
110
111#if defined(VBOX_WITH_XPCOM)
112 Bstr(const wchar_t *that)
113 {
114 AssertCompile(sizeof(wchar_t) == sizeof(OLECHAR));
115 copyFrom((const OLECHAR *)that);
116 }
117#endif
118
119 Bstr(const RTCString &that)
120 {
121 copyFrom(that.c_str());
122 }
123
124 Bstr(const char *that)
125 {
126 copyFrom(that);
127 }
128
129 Bstr(const char *a_pThat, size_t a_cchMax)
130 {
131 copyFromN(a_pThat, a_cchMax);
132 }
133
134 ~Bstr()
135 {
136 setNull();
137 }
138
139 Bstr& operator=(const Bstr &that)
140 {
141 cleanup();
142 copyFrom((const OLECHAR *)that.m_bstr);
143 return *this;
144 }
145
146 Bstr& operator=(CBSTR that)
147 {
148 cleanup();
149 copyFrom((const OLECHAR *)that);
150 return *this;
151 }
152
153#if defined(VBOX_WITH_XPCOM)
154 Bstr& operator=(const wchar_t *that)
155 {
156 cleanup();
157 copyFrom((const OLECHAR *)that);
158 return *this;
159 }
160#endif
161
162 Bstr& setNull()
163 {
164 cleanup();
165 return *this;
166 }
167
168#ifdef _MSC_VER
169# if _MSC_VER >= 1400
170 RTMEMEF_NEW_AND_DELETE_OPERATORS();
171# endif
172#else
173 RTMEMEF_NEW_AND_DELETE_OPERATORS();
174#endif
175
176 /** Case sensitivity selector. */
177 enum CaseSensitivity
178 {
179 CaseSensitive,
180 CaseInsensitive
181 };
182
183 /**
184 * Compares the member string to str.
185 * @param str
186 * @param cs Whether comparison should be case-sensitive.
187 * @return
188 */
189 int compare(CBSTR str, CaseSensitivity cs = CaseSensitive) const
190 {
191 if (cs == CaseSensitive)
192 return ::RTUtf16Cmp((PRTUTF16)m_bstr, (PRTUTF16)str);
193 return ::RTUtf16LocaleICmp((PRTUTF16)m_bstr, (PRTUTF16)str);
194 }
195
196 int compare(BSTR str, CaseSensitivity cs = CaseSensitive) const
197 {
198 return compare((CBSTR)str, cs);
199 }
200
201 int compare(const Bstr &that, CaseSensitivity cs = CaseSensitive) const
202 {
203 return compare(that.m_bstr, cs);
204 }
205
206 bool operator==(const Bstr &that) const { return !compare(that.m_bstr); }
207 bool operator==(CBSTR that) const { return !compare(that); }
208 bool operator==(BSTR that) const { return !compare(that); }
209 bool operator!=(const Bstr &that) const { return !!compare(that.m_bstr); }
210 bool operator!=(CBSTR that) const { return !!compare(that); }
211 bool operator!=(BSTR that) const { return !!compare(that); }
212 bool operator<(const Bstr &that) const { return compare(that.m_bstr) < 0; }
213 bool operator<(CBSTR that) const { return compare(that) < 0; }
214 bool operator<(BSTR that) const { return compare(that) < 0; }
215 bool operator<=(const Bstr &that) const { return compare(that.m_bstr) <= 0; }
216 bool operator<=(CBSTR that) const { return compare(that) <= 0; }
217 bool operator<=(BSTR that) const { return compare(that) <= 0; }
218 bool operator>(const Bstr &that) const { return compare(that.m_bstr) > 0; }
219 bool operator>(CBSTR that) const { return compare(that) > 0; }
220 bool operator>(BSTR that) const { return compare(that) > 0; }
221 bool operator>=(const Bstr &that) const { return compare(that.m_bstr) >= 0; }
222 bool operator>=(CBSTR that) const { return compare(that) >= 0; }
223 bool operator>=(BSTR that) const { return compare(that) >= 0; }
224
225 /**
226 * Returns true if the member string has no length.
227 * This is true for instances created from both NULL and "" input strings.
228 *
229 * @note Always use this method to check if an instance is empty. Do not
230 * use length() because that may need to run through the entire string
231 * (Bstr does not cache string lengths).
232 */
233 bool isEmpty() const { return m_bstr == NULL || *m_bstr == 0; }
234
235 /**
236 * Returns true if the member string has a length of one or more.
237 *
238 * @returns true if not empty, false if empty (NULL or "").
239 */
240 bool isNotEmpty() const { return m_bstr != NULL && *m_bstr != 0; }
241
242 size_t length() const { return isEmpty() ? 0 : ::RTUtf16Len((PRTUTF16)m_bstr); }
243
244#if defined(VBOX_WITH_XPCOM)
245 /**
246 * Returns a pointer to the raw member UTF-16 string. If the member string is empty,
247 * returns a pointer to a global variable containing an empty BSTR with a proper zero
248 * length prefix so that Windows is happy.
249 */
250 CBSTR raw() const
251 {
252 if (m_bstr)
253 return m_bstr;
254
255 return g_bstrEmpty;
256 }
257#else
258 /**
259 * Windows-only hack, as the automatically generated headers use BSTR.
260 * So if we don't want to cast like crazy we have to be more loose than
261 * on XPCOM.
262 *
263 * Returns a pointer to the raw member UTF-16 string. If the member string is empty,
264 * returns a pointer to a global variable containing an empty BSTR with a proper zero
265 * length prefix so that Windows is happy.
266 */
267 BSTR raw() const
268 {
269 if (m_bstr)
270 return m_bstr;
271
272 return g_bstrEmpty;
273 }
274#endif
275
276 /**
277 * Returns a non-const raw pointer that allows to modify the string directly.
278 * As opposed to raw(), this DOES return NULL if the member string is empty
279 * because we cannot return a mutable pointer to the global variable with the
280 * empty string.
281 *
282 * @warning
283 * Be sure not to modify data beyond the allocated memory! The
284 * guaranteed size of the allocated memory is at least #length()
285 * bytes after creation and after every assignment operation.
286 */
287 BSTR mutableRaw() { return m_bstr; }
288
289 /**
290 * Intended to assign copies of instances to |BSTR| out parameters from
291 * within the interface method. Transfers the ownership of the duplicated
292 * string to the caller.
293 *
294 * If the member string is empty, this allocates an empty BSTR in *pstr
295 * (i.e. makes it point to a new buffer with a null byte).
296 *
297 * @deprecated Use cloneToEx instead to avoid throwing exceptions.
298 */
299 void cloneTo(BSTR *pstr) const
300 {
301 if (pstr)
302 {
303 *pstr = ::SysAllocString((const OLECHAR *)raw()); // raw() returns a pointer to "" if empty
304#ifdef RT_EXCEPTIONS_ENABLED
305 if (!*pstr)
306 throw std::bad_alloc();
307#endif
308 }
309 }
310
311 /**
312 * A version of cloneTo that does not throw any out of memory exceptions, but
313 * returns E_OUTOFMEMORY intead.
314 * @returns S_OK or E_OUTOFMEMORY.
315 */
316 HRESULT cloneToEx(BSTR *pstr) const
317 {
318 if (!pstr)
319 return S_OK;
320 *pstr = ::SysAllocString((const OLECHAR *)raw()); // raw() returns a pointer to "" if empty
321 return pstr ? S_OK : E_OUTOFMEMORY;
322 }
323
324 /**
325 * Intended to assign instances to |BSTR| out parameters from within the
326 * interface method. Transfers the ownership of the original string to the
327 * caller and resets the instance to null.
328 *
329 * As opposed to cloneTo(), this method doesn't create a copy of the
330 * string.
331 *
332 * If the member string is empty, this allocates an empty BSTR in *pstr
333 * (i.e. makes it point to a new buffer with a null byte).
334 *
335 * @param pbstrDst The BSTR variable to detach the string to.
336 *
337 * @throws std::bad_alloc if we failed to allocate a new empty string.
338 */
339 void detachTo(BSTR *pbstrDst)
340 {
341 if (m_bstr)
342 {
343 *pbstrDst = m_bstr;
344 m_bstr = NULL;
345 }
346 else
347 {
348 // allocate null BSTR
349 *pbstrDst = ::SysAllocString((const OLECHAR *)g_bstrEmpty);
350#ifdef RT_EXCEPTIONS_ENABLED
351 if (!*pbstrDst)
352 throw std::bad_alloc();
353#endif
354 }
355 }
356
357 /**
358 * A version of detachTo that does not throw exceptions on out-of-memory
359 * conditions, but instead returns E_OUTOFMEMORY.
360 *
361 * @param pbstrDst The BSTR variable to detach the string to.
362 * @returns S_OK or E_OUTOFMEMORY.
363 */
364 HRESULT detachToEx(BSTR *pbstrDst)
365 {
366 if (m_bstr)
367 {
368 *pbstrDst = m_bstr;
369 m_bstr = NULL;
370 }
371 else
372 {
373 // allocate null BSTR
374 *pbstrDst = ::SysAllocString((const OLECHAR *)g_bstrEmpty);
375 if (!*pbstrDst)
376 return E_OUTOFMEMORY;
377 }
378 return S_OK;
379 }
380
381 /**
382 * Intended to pass instances as |BSTR| out parameters to methods.
383 * Takes the ownership of the returned data.
384 */
385 BSTR *asOutParam()
386 {
387 cleanup();
388 return &m_bstr;
389 }
390
391 /**
392 * Static immutable empty-string object. May be used for comparison purposes.
393 */
394 static const Bstr Empty;
395
396protected:
397
398 void cleanup()
399 {
400 if (m_bstr)
401 {
402 ::SysFreeString(m_bstr);
403 m_bstr = NULL;
404 }
405 }
406
407 /**
408 * Protected internal helper to copy a string. This ignores the previous object
409 * state, so either call this from a constructor or call cleanup() first.
410 *
411 * This variant copies from a zero-terminated UTF-16 string (which need not
412 * be a BSTR, i.e. need not have a length prefix).
413 *
414 * If the source is empty, this sets the member string to NULL.
415 *
416 * @param a_bstrSrc The source string. The caller guarantees
417 * that this is valid UTF-16.
418 *
419 * @throws std::bad_alloc - the object is representing an empty string.
420 */
421 void copyFrom(const OLECHAR *a_bstrSrc)
422 {
423 if (a_bstrSrc && *a_bstrSrc)
424 {
425 m_bstr = ::SysAllocString(a_bstrSrc);
426#ifdef RT_EXCEPTIONS_ENABLED
427 if (!m_bstr)
428 throw std::bad_alloc();
429#endif
430 }
431 else
432 m_bstr = NULL;
433 }
434
435 /**
436 * Protected internal helper to copy a string. This ignores the previous object
437 * state, so either call this from a constructor or call cleanup() first.
438 *
439 * This variant copies and converts from a zero-terminated UTF-8 string.
440 *
441 * If the source is empty, this sets the member string to NULL.
442 *
443 * @param a_pszSrc The source string. The caller guarantees
444 * that this is valid UTF-8.
445 *
446 * @throws std::bad_alloc - the object is representing an empty string.
447 */
448 void copyFrom(const char *a_pszSrc)
449 {
450 copyFromN(a_pszSrc, RTSTR_MAX);
451 }
452
453 /**
454 * Variant of copyFrom for sub-string constructors.
455 *
456 * @param a_pszSrc The source string. The caller guarantees
457 * that this is valid UTF-8.
458 * @param a_cchMax The maximum number of chars (not
459 * codepoints) to copy. If you pass RTSTR_MAX
460 * it'll be exactly like copyFrom().
461 *
462 * @throws std::bad_alloc - the object is representing an empty string.
463 */
464 void copyFromN(const char *a_pszSrc, size_t a_cchSrc);
465
466 BSTR m_bstr;
467
468 friend class Utf8Str; /* to access our raw_copy() */
469};
470
471/* symmetric compare operators */
472inline bool operator==(CBSTR l, const Bstr &r) { return r.operator==(l); }
473inline bool operator!=(CBSTR l, const Bstr &r) { return r.operator!=(l); }
474inline bool operator==(BSTR l, const Bstr &r) { return r.operator==(l); }
475inline bool operator!=(BSTR l, const Bstr &r) { return r.operator!=(l); }
476
477
478
479
480/**
481 * String class used universally in Main for UTF-8 strings.
482 *
483 * This is based on RTCString, to which some functionality has been
484 * moved. Here we keep things that are specific to Main, such as conversions
485 * with UTF-16 strings (Bstr).
486 *
487 * Like RTCString, Utf8Str does not differentiate between NULL strings
488 * and empty strings. In other words, Utf8Str("") and Utf8Str(NULL) behave the
489 * same. In both cases, RTCString allocates no memory, reports
490 * a zero length and zero allocated bytes for both, and returns an empty
491 * C string from c_str().
492 *
493 * @note All Utf8Str methods ASSUMES valid UTF-8 or UTF-16 input strings.
494 * The VirtualBox policy in this regard is to validate strings coming
495 * from external sources before passing them to Utf8Str or Bstr.
496 */
497class Utf8Str : public RTCString
498{
499public:
500
501 Utf8Str() {}
502
503 Utf8Str(const RTCString &that)
504 : RTCString(that)
505 {}
506
507 Utf8Str(const char *that)
508 : RTCString(that)
509 {}
510
511 Utf8Str(const Bstr &that)
512 {
513 copyFrom(that.raw());
514 }
515
516 Utf8Str(CBSTR that)
517 {
518 copyFrom(that);
519 }
520
521 Utf8Str(const char *a_pszSrc, size_t a_cchSrc)
522 : RTCString(a_pszSrc, a_cchSrc)
523 {
524 }
525
526 /**
527 * Constructs a new string given the format string and the list of the
528 * arguments for the format string.
529 *
530 * @param a_pszFormat Pointer to the format string (UTF-8),
531 * @see pg_rt_str_format.
532 * @param a_va Argument vector containing the arguments
533 * specified by the format string.
534 * @sa RTCString::printfV
535 */
536 Utf8Str(const char *a_pszFormat, va_list a_va)
537 : RTCString(a_pszFormat, a_va)
538 {
539 }
540
541 Utf8Str& operator=(const RTCString &that)
542 {
543 RTCString::operator=(that);
544 return *this;
545 }
546
547 Utf8Str& operator=(const char *that)
548 {
549 RTCString::operator=(that);
550 return *this;
551 }
552
553 Utf8Str& operator=(const Bstr &that)
554 {
555 cleanup();
556 copyFrom(that.raw());
557 return *this;
558 }
559
560 Utf8Str& operator=(CBSTR that)
561 {
562 cleanup();
563 copyFrom(that);
564 return *this;
565 }
566
567 /**
568 * Extended assignment method that returns a COM status code instead of an
569 * exception on failure.
570 *
571 * @returns S_OK or E_OUTOFMEMORY.
572 * @param a_rSrcStr The source string
573 */
574 HRESULT assignEx(Utf8Str const &a_rSrcStr)
575 {
576 return copyFromExNComRC(a_rSrcStr.m_psz, 0, a_rSrcStr.m_cch);
577 }
578
579 /**
580 * Extended assignment method that returns a COM status code instead of an
581 * exception on failure.
582 *
583 * @returns S_OK, E_OUTOFMEMORY or E_INVALIDARG.
584 * @param a_pcszSrc The source string
585 * @param a_offSrc The character (byte) offset of the substring.
586 * @param a_cchSrc The number of characters (bytes) to copy from the source
587 * string.
588 */
589 HRESULT assignEx(Utf8Str const &a_rSrcStr, size_t a_offSrc, size_t a_cchSrc)
590 {
591 if ( a_offSrc + a_cchSrc > a_rSrcStr.m_cch
592 || a_offSrc > a_rSrcStr.m_cch)
593 return E_INVALIDARG;
594 return copyFromExNComRC(a_rSrcStr.m_psz, a_offSrc, a_cchSrc);
595 }
596
597 /**
598 * Extended assignment method that returns a COM status code instead of an
599 * exception on failure.
600 *
601 * @returns S_OK or E_OUTOFMEMORY.
602 * @param a_pcszSrc The source string
603 */
604 HRESULT assignEx(const char *a_pcszSrc)
605 {
606 return copyFromExNComRC(a_pcszSrc, 0, a_pcszSrc ? strlen(a_pcszSrc) : 0);
607 }
608
609 /**
610 * Extended assignment method that returns a COM status code instead of an
611 * exception on failure.
612 *
613 * @returns S_OK or E_OUTOFMEMORY.
614 * @param a_pcszSrc The source string
615 * @param a_cchSrc The number of characters (bytes) to copy from the source
616 * string.
617 */
618 HRESULT assignEx(const char *a_pcszSrc, size_t a_cchSrc)
619 {
620 return copyFromExNComRC(a_pcszSrc, 0, a_cchSrc);
621 }
622
623 RTMEMEF_NEW_AND_DELETE_OPERATORS();
624
625#if defined(VBOX_WITH_XPCOM)
626 /**
627 * Intended to assign instances to |char *| out parameters from within the
628 * interface method. Transfers the ownership of the duplicated string to the
629 * caller.
630 *
631 * This allocates a single 0 byte in the target if the member string is empty.
632 *
633 * This uses XPCOM memory allocation and thus only works on XPCOM. MSCOM doesn't
634 * like char* strings anyway.
635 */
636 void cloneTo(char **pstr) const;
637
638 /**
639 * A version of cloneTo that does not throw allocation errors but returns
640 * E_OUTOFMEMORY instead.
641 * @returns S_OK or E_OUTOFMEMORY (COM status codes).
642 */
643 HRESULT cloneToEx(char **pstr) const;
644#endif
645
646 /**
647 * Intended to assign instances to |BSTR| out parameters from within the
648 * interface method. Transfers the ownership of the duplicated string to the
649 * caller.
650 */
651 void cloneTo(BSTR *pstr) const
652 {
653 if (pstr)
654 {
655 Bstr bstr(*this);
656 bstr.cloneTo(pstr);
657 }
658 }
659
660 /**
661 * A version of cloneTo that does not throw allocation errors but returns
662 * E_OUTOFMEMORY instead.
663 *
664 * @param pbstr Where to store a clone of the string.
665 * @returns S_OK or E_OUTOFMEMORY (COM status codes).
666 */
667 HRESULT cloneToEx(BSTR *pbstr) const
668 {
669 if (!pbstr)
670 return S_OK;
671 Bstr bstr(*this);
672 return bstr.detachToEx(pbstr);
673 }
674
675 /**
676 * Safe assignment from BSTR.
677 *
678 * @param pbstrSrc The source string.
679 * @returns S_OK or E_OUTOFMEMORY (COM status codes).
680 */
681 HRESULT cloneEx(CBSTR pbstrSrc)
682 {
683 cleanup();
684 return copyFromEx(pbstrSrc);
685 }
686
687 /**
688 * Removes a trailing slash from the member string, if present.
689 * Calls RTPathStripTrailingSlash() without having to mess with mutableRaw().
690 */
691 Utf8Str& stripTrailingSlash();
692
693 /**
694 * Removes a trailing filename from the member string, if present.
695 * Calls RTPathStripFilename() without having to mess with mutableRaw().
696 */
697 Utf8Str& stripFilename();
698
699 /**
700 * Removes the path component from the member string, if present.
701 * Calls RTPathFilename() without having to mess with mutableRaw().
702 */
703 Utf8Str& stripPath();
704
705 /**
706 * Removes a trailing file name suffix from the member string, if present.
707 * Calls RTPathStripSuffix() without having to mess with mutableRaw().
708 */
709 Utf8Str& stripSuffix();
710
711 // Parse key=value pairs from string
712 size_t parseKeyValue(Utf8Str &key, Utf8Str &value, size_t pos = 0, const Utf8Str &pairSeparator = ",", const Utf8Str &keyValueSeparator = "=") const;
713
714 /**
715 * Static immutable empty-string object. May be used for comparison purposes.
716 */
717 static const Utf8Str Empty;
718protected:
719
720 void copyFrom(CBSTR a_pbstr);
721 HRESULT copyFromEx(CBSTR a_pbstr);
722 HRESULT copyFromExNComRC(const char *a_pcszSrc, size_t a_offSrc, size_t a_cchSrc);
723
724 friend class Bstr; /* to access our raw_copy() */
725};
726
727/**
728 * Class with RTCString::printf as constructor for your convenience.
729 *
730 * Constructing a Utf8Str string object from a format string and a variable
731 * number of arguments can easily be confused with the other Utf8Str
732 * constructures, thus this child class.
733 *
734 * The usage of this class is like the following:
735 * @code
736 Utf8StrFmt strName("program name = %s", argv[0]);
737 @endcode
738 */
739class Utf8StrFmt : public Utf8Str
740{
741public:
742
743 /**
744 * Constructs a new string given the format string and the list of the
745 * arguments for the format string.
746 *
747 * @param a_pszFormat Pointer to the format string (UTF-8),
748 * @see pg_rt_str_format.
749 * @param ... Ellipsis containing the arguments specified by
750 * the format string.
751 */
752 explicit Utf8StrFmt(const char *a_pszFormat, ...)
753 {
754 va_list va;
755 va_start(va, a_pszFormat);
756 printfV(a_pszFormat, va);
757 va_end(va);
758 }
759
760 RTMEMEF_NEW_AND_DELETE_OPERATORS();
761
762protected:
763 Utf8StrFmt()
764 { }
765
766private:
767};
768
769/**
770 * The BstrFmt class is a shortcut to <tt>Bstr(Utf8StrFmt(...))</tt>.
771 */
772class BstrFmt : public Bstr
773{
774public:
775
776 /**
777 * Constructs a new string given the format string and the list of the
778 * arguments for the format string.
779 *
780 * @param aFormat printf-like format string (in UTF-8 encoding).
781 * @param ... List of the arguments for the format string.
782 */
783 explicit BstrFmt(const char *aFormat, ...)
784 {
785 va_list args;
786 va_start(args, aFormat);
787 copyFrom(Utf8Str(aFormat, args).c_str());
788 va_end(args);
789 }
790
791 RTMEMEF_NEW_AND_DELETE_OPERATORS();
792};
793
794/**
795 * The BstrFmtVA class is a shortcut to <tt>Bstr(Utf8Str(format,va))</tt>.
796 */
797class BstrFmtVA : public Bstr
798{
799public:
800
801 /**
802 * Constructs a new string given the format string and the list of the
803 * arguments for the format string.
804 *
805 * @param aFormat printf-like format string (in UTF-8 encoding).
806 * @param aArgs List of arguments for the format string
807 */
808 BstrFmtVA(const char *aFormat, va_list aArgs)
809 {
810 copyFrom(Utf8Str(aFormat, aArgs).c_str());
811 }
812
813 RTMEMEF_NEW_AND_DELETE_OPERATORS();
814};
815
816} /* namespace com */
817
818#endif /* !___VBox_com_string_h */
819
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