string.h@ 17955

Last change on this file since 17955 was 17955, checked in by vboxsync, 16 years ago
Main: add some converter methods
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 17955 2009-03-16 16:53:18Z vboxsync $ */
2
3	/** @file
4	* MS COM / XPCOM Abstraction Layer:
5	* Smart string classes declaration
6	*/
7
8	/*
9	* Copyright (C) 2006-2009 Sun Microsystems, Inc.
10	*
11	* This file is part of VirtualBox Open Source Edition (OSE), as
12	* available from http://www.virtualbox.org. This file is free software;
13	* you can redistribute it and/or modify it under the terms of the GNU
14	* General Public License (GPL) as published by the Free Software
15	* Foundation, in version 2 as it comes in the "COPYING" file of the
16	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
17	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
18	*
19	* The contents of this file may alternatively be used under the terms
20	* of the Common Development and Distribution License Version 1.0
21	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
22	* VirtualBox OSE distribution, in which case the provisions of the
23	* CDDL are applicable instead of those of the GPL.
24	*
25	* You may elect to license modified versions of this file under the
26	* terms and conditions of either the GPL or the CDDL or both.
27	*
28	* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
29	* Clara, CA 95054 USA or visit http://www.sun.com if you need
30	* additional information or have any questions.
31	*/
32
33	#ifndef ___VBox_com_string_h
34	#define ___VBox_com_string_h
35
36	/* Make sure all the stdint.h macros are included - must come first! */
37	#ifndef __STDC_LIMIT_MACROS
38	# define __STDC_LIMIT_MACROS
39	#endif
40	#ifndef __STDC_CONSTANT_MACROS
41	# define __STDC_CONSTANT_MACROS
42	#endif
43
44	#if defined (VBOX_WITH_XPCOM)
45	# include <nsMemory.h>
46	#endif
47
48	#include "VBox/com/defs.h"
49	#include "VBox/com/assert.h"
50
51	#include <iprt/string.h>
52	#include <iprt/cpputils.h>
53	#include <iprt/alloc.h>
54
55	namespace com
56	{
57
58	class Utf8Str;
59
60	/**
61	* Helper class that represents the \|BSTR\| type and hides platform-specific
62	* implementation details.
63	*
64	* This class uses COM/XPCOM-provided memory management routines to allocate
65	* and free string buffers. This makes it possible to:
66	* - use it as a type of member variables of COM/XPCOM components and pass
67	* their values to callers through component methods' output parameters
68	* using the #cloneTo() operation;
69	* - adopt (take ownership of) string buffers returned in output parameters
70	* of COM methods using the #asOutParam() operation and correctly free them
71	* afterwards.
72	*/
73	class Bstr
74	{
75	public:
76
77	typedef BSTR String;
78	typedef CBSTR ConstString;
79
80	Bstr () : bstr (NULL) {}
81
82	Bstr (const Bstr &that) : bstr (NULL) { raw_copy (bstr, that.bstr); }
83	Bstr (CBSTR that) : bstr (NULL) { raw_copy (bstr, that); }
84
85	#if defined (VBOX_WITH_XPCOM)
86	Bstr (const wchar_t *that) : bstr (NULL)
87	{
88	AssertCompile (sizeof (wchar_t) == sizeof (OLECHAR));
89	raw_copy (bstr, (CBSTR) that);
90	}
91	#endif
92
93	Bstr (const Utf8Str &that);
94	Bstr (const char *that);
95
96	/** Shortcut that calls #alloc(aSize) right after object creation. */
97	Bstr (size_t aSize) : bstr (NULL) { alloc (aSize); }
98
99	~Bstr () { setNull(); }
100
101	Bstr &operator = (const Bstr &that) { safe_assign (that.bstr); return *this; }
102	Bstr &operator = (CBSTR that) { safe_assign (that); return *this; }
103
104	Bstr &operator = (const Utf8Str &that);
105	Bstr &operator = (const char *that);
106
107	Bstr &setNull()
108	{
109	if (bstr)
110	{
111	::SysFreeString (bstr);
112	bstr = NULL;
113	}
114	return *this;
115	}
116
117	Bstr &setNullIfEmpty()
118	{
119	if (bstr && *bstr == 0)
120	{
121	::SysFreeString (bstr);
122	bstr = NULL;
123	}
124	return *this;
125	}
126
127	/**
128	* Allocates memory for a string capable to store \a aSize - 1 characters;
129	* in other words, aSize includes the terminating zero character. If \a aSize
130	* is zero, or if a memory allocation error occurs, this object will become null.
131	*/
132	Bstr &alloc (size_t aSize)
133	{
134	setNull();
135	if (aSize)
136	{
137	unsigned int size = (unsigned int) aSize; Assert (size == aSize);
138	bstr = ::SysAllocStringLen (NULL, size - 1);
139	if (bstr)
140	bstr [0] = 0;
141	}
142	return *this;
143	}
144
145	int compare (CBSTR str) const
146	{
147	return ::RTUtf16Cmp ((PRTUTF16) bstr, (PRTUTF16) str);
148	}
149
150	int compare (BSTR str) const
151	{
152	return ::RTUtf16Cmp ((PRTUTF16) bstr, (PRTUTF16) str);
153	}
154
155	bool operator == (const Bstr &that) const { return !compare (that.bstr); }
156	bool operator != (const Bstr &that) const { return !!compare (that.bstr); }
157	bool operator == (CBSTR that) const { return !compare (that); }
158	bool operator == (BSTR that) const { return !compare (that); }
159
160	#if defined (VBOX_WITH_XPCOM)
161	bool operator != (const wchar_t *that) const
162	{
163	AssertCompile (sizeof (wchar_t) == sizeof (OLECHAR));
164	return !!compare ((CBSTR) that);
165	}
166	bool operator == (const wchar_t *that) const
167	{
168	AssertCompile (sizeof (wchar_t) == sizeof (OLECHAR));
169	return !compare ((CBSTR) that);
170	}
171	#endif
172
173	bool operator != (CBSTR that) const { return !!compare (that); }
174	bool operator != (BSTR that) const { return !!compare (that); }
175	bool operator < (const Bstr &that) const { return compare (that.bstr) < 0; }
176	bool operator < (CBSTR that) const { return compare (that) < 0; }
177	bool operator < (BSTR that) const { return compare (that) < 0; }
178	#if defined (VBOX_WITH_XPCOM)
179	bool operator < (const wchar_t *that) const
180	{
181	AssertCompile (sizeof (wchar_t) == sizeof (OLECHAR));
182	return compare ((CBSTR) that) < 0;
183	}
184	#endif
185
186	int compareIgnoreCase (CBSTR str) const
187	{
188	return ::RTUtf16LocaleICmp (bstr, str);
189	}
190
191	bool isNull() const { return bstr == NULL; }
192	operator bool() const { return !isNull(); }
193
194	bool isEmpty() const { return isNull() \|\| *bstr == 0; }
195
196	size_t length() const { return isNull() ? 0 : ::RTUtf16Len ((PRTUTF16) bstr); }
197
198	/** Intended to to pass instances as \|CBSTR\| input parameters to methods. */
199	operator CBSTR () const { return bstr; }
200
201	/**
202	* Intended to to pass instances as \|BSTR\| input parameters to methods.
203	* Note that we have to provide this mutable BSTR operator since in MS COM
204	* input BSTR parameters of interface methods are not const.
205	*/
206	operator BSTR () { return bstr; }
207
208	/**
209	* The same as operator CBSTR(), but for situations where the compiler
210	* cannot typecast implicitly (for example, in printf() argument list).
211	*/
212	CBSTR raw() const { return bstr; }
213
214	/**
215	* Returns a non-const raw pointer that allows to modify the string directly.
216	* @warning
217	* Be sure not to modify data beyond the allocated memory! The
218	* guaranteed size of the allocated memory is at least #length()
219	* bytes after creation and after every assignment operation.
220	*/
221	BSTR mutableRaw() { return bstr; }
222
223	/**
224	* Intended to assign copies of instances to \|BSTR\| out parameters from
225	* within the interface method. Transfers the ownership of the duplicated
226	* string to the caller.
227	*/
228	const Bstr &cloneTo (BSTR *pstr) const
229	{
230	if (pstr)
231	{
232	*pstr = NULL;
233	raw_copy (*pstr, bstr);
234	}
235	return *this;
236	}
237
238	/**
239	* Intended to assign instances to \|BSTR\| out parameters from within the
240	* interface method. Transfers the ownership of the original string to the
241	* caller and resets the instance to null.
242	*
243	* As opposed to cloneTo(), this method doesn't create a copy of the
244	* string.
245	*/
246	Bstr &detachTo (BSTR *pstr)
247	{
248	*pstr = bstr;
249	bstr = NULL;
250	return *this;
251	}
252
253	/**
254	* Intended to assign copies of instances to \|char *\| out parameters from
255	* within the interface method. Transfers the ownership of the duplicated
256	* string to the caller.
257	*/
258	const Bstr &cloneTo (char **pstr) const;
259
260	/**
261	* Intended to pass instances as \|BSTR\| out parameters to methods.
262	* Takes the ownership of the returned data.
263	*/
264	BSTR *asOutParam() { setNull(); return &bstr; }
265
266	/**
267	* Static immutable null object. May be used for comparison purposes.
268	*/
269	static const Bstr Null;
270
271	protected:
272
273	void safe_assign (CBSTR str)
274	{
275	if (bstr != str)
276	{
277	setNull();
278	raw_copy (bstr, str);
279	}
280	}
281
282	inline static void raw_copy (BSTR &ls, CBSTR rs)
283	{
284	if (rs)
285	ls = ::SysAllocString ((const OLECHAR *) rs);
286	}
287
288	inline static void raw_copy (BSTR &ls, const char *rs)
289	{
290	if (rs)
291	{
292	PRTUTF16 s = NULL;
293	::RTStrToUtf16 (rs, &s);
294	raw_copy (ls, (BSTR) s);
295	::RTUtf16Free (s);
296	}
297	}
298
299	BSTR bstr;
300
301	friend class Utf8Str; /* to access our raw_copy() */
302	};
303
304	/* symmetric compare operators */
305	inline bool operator== (CBSTR l, const Bstr &r) { return r.operator== (l); }
306	inline bool operator!= (CBSTR l, const Bstr &r) { return r.operator!= (l); }
307	inline bool operator== (BSTR l, const Bstr &r) { return r.operator== (l); }
308	inline bool operator!= (BSTR l, const Bstr &r) { return r.operator!= (l); }
309
310	////////////////////////////////////////////////////////////////////////////////
311
312	/**
313	* Helper class that represents UTF8 (\|char *\|) strings. Useful in
314	* conjunction with Bstr to simplify conversions between UTF16 (\|BSTR\|)
315	* and UTF8.
316	*
317	* This class uses COM/XPCOM-provided memory management routines to allocate
318	* and free string buffers. This makes it possible to:
319	* - use it as a type of member variables of COM/XPCOM components and pass
320	* their values to callers through component methods' output parameters
321	* using the #cloneTo() operation;
322	* - adopt (take ownership of) string buffers returned in output parameters
323	* of COM methods using the #asOutParam() operation and correctly free them
324	* afterwards.
325	*/
326	class Utf8Str
327	{
328	public:
329
330	enum CaseSensitivity
331	{
332	CaseSensitive,
333	CaseInsensitive
334	};
335
336	typedef char *String;
337	typedef const char *ConstString;
338
339	Utf8Str () : str (NULL) {}
340
341	Utf8Str (const Utf8Str &that) : str (NULL) { raw_copy (str, that.str); }
342	Utf8Str (const char *that) : str (NULL) { raw_copy (str, that); }
343
344	Utf8Str (const Bstr &that) : str (NULL) { raw_copy (str, that); }
345	Utf8Str (CBSTR that) : str (NULL) { raw_copy (str, that); }
346
347	/** Shortcut that calls #alloc(aSize) right after object creation. */
348	Utf8Str (size_t aSize) : str (NULL) { alloc(aSize); }
349
350	virtual ~Utf8Str () { setNull(); }
351
352	Utf8Str &operator = (const Utf8Str &that) { safe_assign (that.str); return *this; }
353	Utf8Str &operator = (const char that) { safe_assign (that); return this; }
354
355	Utf8Str &operator = (const Bstr &that)
356	{
357	setNull();
358	raw_copy (str, that);
359	return *this;
360	}
361	Utf8Str &operator = (CBSTR that)
362	{
363	setNull();
364	raw_copy (str, that);
365	return *this;
366	}
367
368	Utf8Str &setNull()
369	{
370	if (str)
371	{
372	#if !defined (VBOX_WITH_XPCOM)
373	::RTStrFree (str);
374	#else
375	nsMemory::Free (str);
376	#endif
377	str = NULL;
378	}
379	return *this;
380	}
381
382	Utf8Str &setNullIfEmpty()
383	{
384	if (str && *str == 0)
385	{
386	#if !defined (VBOX_WITH_XPCOM)
387	::RTStrFree (str);
388	#else
389	nsMemory::Free (str);
390	#endif
391	str = NULL;
392	}
393	return *this;
394	}
395
396	/**
397	* Allocates memory for a string capable to store \a aSize - 1 bytes (not characters!);
398	* in other words, aSize includes the terminating zero character. If \a aSize
399	* is zero, or if a memory allocation error occurs, this object will become null.
400	*/
401	Utf8Str &alloc (size_t aSize)
402	{
403	setNull();
404	if (aSize)
405	{
406	#if !defined (VBOX_WITH_XPCOM)
407	str = (char *) ::RTMemTmpAlloc (aSize);
408	#else
409	str = (char *) nsMemory::Alloc (aSize);
410	#endif
411	if (str)
412	str [0] = 0;
413	}
414	return *this;
415	}
416
417	void append(const Utf8Str &that)
418	{
419	size_t cbThis = length();
420	size_t cbThat = that.length();
421
422	if (cbThat)
423	{
424	size_t cbBoth = cbThis + cbThat + 1;
425
426	// @todo optimize with realloc() once the memory management is fixed
427	char *pszTemp;
428	#if !defined (VBOX_WITH_XPCOM)
429	pszTemp = (char*)::RTMemTmpAlloc(cbBoth);
430	#else
431	pszTemp = (char*)nsMemory::Alloc(cbBoth);
432	#endif
433	if (str)
434	{
435	memcpy(pszTemp, str, cbThis);
436	setNull();
437	}
438	if (that.str)
439	memcpy(pszTemp + cbThis, that.str, cbThat);
440	pszTemp[cbThis + cbThat] = '\0';
441
442	str = pszTemp;
443	}
444	}
445
446	int compare (const char *pcsz, CaseSensitivity cs = CaseSensitive) const
447	{
448	if (str == pcsz)
449	return 0;
450	if (str == NULL)
451	return -1;
452	if (pcsz == NULL)
453	return 1;
454
455	if (cs == CaseSensitive)
456	return ::RTStrCmp(str, pcsz);
457	else
458	return ::RTStrICmp(str, pcsz);
459	}
460
461	int compare (const Utf8Str &that, CaseSensitivity cs = CaseSensitive) const
462	{
463	return compare (that.str, cs);
464	}
465
466	bool operator == (const Utf8Str &that) const { return !compare (that); }
467	bool operator != (const Utf8Str &that) const { return !!compare (that); }
468	bool operator == (const char *that) const { return !compare (that); }
469	bool operator != (const char *that) const { return !!compare (that); }
470	bool operator < (const Utf8Str &that) const { return compare (that) < 0; }
471	bool operator < (const char *that) const { return compare (that) < 0; }
472
473	bool endsWith (const Utf8Str &that, CaseSensitivity cs = CaseSensitive) const
474	{
475	if (isNull() \|\| that.isNull())
476	return false;
477
478	if (length() < that.length())
479	return false;
480
481	int l = length() - that.length();
482	if (cs == CaseSensitive)
483	return ::RTStrCmp(&str[l], that.str) == 0;
484	else
485	return ::RTStrICmp(&str[l], that.str) == 0;
486	}
487
488	bool startsWith (const Utf8Str &that, CaseSensitivity cs = CaseSensitive) const
489	{
490	if (isNull() \|\| that.isNull())
491	return false;
492
493	if (length() < that.length())
494	return false;
495
496	if (cs == CaseSensitive)
497	return ::RTStrNCmp(str, that.str, that.length()) == 0;
498	else
499	return ::RTStrNICmp(str, that.str, that.length()) == 0;
500	}
501
502	bool isNull() const { return str == NULL; }
503	operator bool() const { return !isNull(); }
504
505	bool isEmpty() const { return isNull() \|\| *str == 0; }
506
507	size_t length() const { return isNull() ? 0 : ::strlen (str); }
508
509	/** Intended to to pass instances as input (\|char \|) parameters to methods. /
510	operator const char *() const { return str; }
511
512	/** The same as operator const char *(), but for situations where the compiler
513	cannot typecast implicitly (for example, in printf() argument list). */
514	const char *raw() const { return str; }
515
516	/** The same as operator const char *(), but for situations where the compiler
517	cannot typecast implicitly (for example, in printf() argument list). */
518	const char *c_str() const { return str; }
519
520	/**
521	* Returns a non-const raw pointer that allows to modify the string directly.
522	* @warning
523	* Be sure not to modify data beyond the allocated memory! The
524	* guaranteed size of the allocated memory is at least #length()
525	* bytes after creation and after every assignment operation.
526	*/
527	char *mutableRaw() { return str; }
528
529	/**
530	* Intended to assign instances to \|char *\| out parameters from within the
531	* interface method. Transfers the ownership of the duplicated string to the
532	* caller.
533	*/
534	const Utf8Str &cloneTo (char **pstr) const
535	{
536	if (pstr)
537	{
538	*pstr = NULL;
539	raw_copy (*pstr, str);
540	}
541	return *this;
542	}
543
544	/**
545	* Intended to assign instances to \|char *\| out parameters from within the
546	* interface method. Transfers the ownership of the original string to the
547	* caller and resets the instance to null.
548	*
549	* As opposed to cloneTo(), this method doesn't create a copy of the
550	* string.
551	*/
552	Utf8Str &detachTo (char **pstr)
553	{
554	*pstr = str;
555	str = NULL;
556	return *this;
557	}
558
559	/**
560	* Intended to assign instances to \|BSTR\| out parameters from within the
561	* interface method. Transfers the ownership of the duplicated string to the
562	* caller.
563	*/
564	const Utf8Str &cloneTo (BSTR *pstr) const
565	{
566	if (pstr)
567	{
568	*pstr = NULL;
569	Bstr::raw_copy (*pstr, str);
570	}
571	return *this;
572	}
573
574	static const size_t npos;
575
576	/**
577	* Looks for pcszFind in "this" starting at "pos" and returns its position,
578	* counting from the beginning of "this" at 0. Returns npos if not found.
579	*/
580	size_t find(const char *pcszFind, size_t pos = 0) const;
581
582	/**
583	* Returns a substring of "this" as a new Utf8Str. Works exactly like
584	* its equivalent in std::string except that this interprets pos and n
585	* as UTF-8 codepoints instead of bytes. With the default parameters "0"
586	* and "npos", this always copies the entire string.
587	* @param pos Index of first codepoint to copy from "this", counting from 0.
588	* @param n Number of codepoints to copy, starting with the one at "pos".
589	*/
590	Utf8Str substr(size_t pos = 0, size_t n = npos) const;
591
592	/**
593	* Attempts to convert the member string into an 32-bit integer.
594	*
595	* @returns 32-bit unsigned number on success.
596	* @returns 0 on failure.
597	*/
598	int toInt32() const
599	{
600	return RTStrToInt32(str);
601	}
602
603	/**
604	* Attempts to convert the member string into an unsigned 32-bit integer.
605	*
606	* @returns 32-bit unsigned number on success.
607	* @returns 0 on failure.
608	*/
609	int toUInt32() const
610	{
611	return RTStrToUInt32(str);
612	}
613
614	/**
615	* Attempts to convert the member string into an 64-bit integer.
616	*
617	* @returns 64-bit unsigned number on success.
618	* @returns 0 on failure.
619	*/
620	int toInt64() const
621	{
622	return RTStrToInt64(str);
623	}
624
625	/**
626	* Attempts to convert the member string into an unsigned 64-bit integer.
627	*
628	* @returns 64-bit unsigned number on success.
629	* @returns 0 on failure.
630	*/
631	int toUInt64() const
632	{
633	return RTStrToUInt64(str);
634	}
635
636	/**
637	* Attempts to convert the member string into an unsigned 64-bit integer.
638	* @return IPRT error code.
639	* @param i Output buffer.
640	*/
641	int toInt(uint64_t &i) const;
642
643	/**
644	* Attempts to convert the member string into an unsigned 32-bit integer.
645	* @return IPRT error code.
646	* @param i Output buffer.
647	*/
648	int toInt(uint32_t &i) const;
649
650	/**
651	* Intended to pass instances as out (\|char **\|) parameters to methods.
652	* Takes the ownership of the returned data.
653	*/
654	char **asOutParam() { setNull(); return &str; }
655
656	/**
657	* Static immutable null object. May be used for comparison purposes.
658	*/
659	static const Utf8Str Null;
660
661	protected:
662
663	void safe_assign (const char *s)
664	{
665	if (str != s)
666	{
667	setNull();
668	raw_copy (str, s);
669	}
670	}
671
672	inline static void raw_copy (char &ls, const char rs)
673	{
674	if (rs)
675	#if !defined (VBOX_WITH_XPCOM)
676	::RTStrDupEx (&ls, rs);
677	#else
678	ls = (char *) nsMemory::Clone (rs, strlen (rs) + 1);
679	#endif
680	}
681
682	inline static void raw_copy (char *&ls, CBSTR rs)
683	{
684	if (rs)
685	{
686	#if !defined (VBOX_WITH_XPCOM)
687	::RTUtf16ToUtf8 ((PRTUTF16) rs, &ls);
688	#else
689	char *s = NULL;
690	::RTUtf16ToUtf8 ((PRTUTF16) rs, &s);
691	raw_copy (ls, s);
692	::RTStrFree (s);
693	#endif
694	}
695	}
696
697	char *str;
698
699	friend class Bstr; /* to access our raw_copy() */
700	};
701
702	// symmetric compare operators
703	inline bool operator== (const char *l, const Utf8Str &r) { return r.operator== (l); }
704	inline bool operator!= (const char *l, const Utf8Str &r) { return r.operator!= (l); }
705
706	// work around error C2593 of the stupid MSVC 7.x ambiguity resolver
707	WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP (Bstr)
708	WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP (Utf8Str)
709
710	////////////////////////////////////////////////////////////////////////////////
711
712	// inlined Bstr members that depend on Utf8Str
713
714	inline Bstr::Bstr (const Utf8Str &that) : bstr (NULL) { raw_copy (bstr, that); }
715	inline Bstr::Bstr (const char *that) : bstr (NULL) { raw_copy (bstr, that); }
716
717	inline Bstr &Bstr::operator = (const Utf8Str &that)
718	{
719	setNull();
720	raw_copy (bstr, that);
721	return *this;
722	}
723	inline Bstr &Bstr::operator = (const char *that)
724	{
725	setNull();
726	raw_copy (bstr, that);
727	return *this;
728	}
729
730	inline const Bstr &Bstr::cloneTo (char **pstr) const
731	{
732	if (pstr) {
733	*pstr = NULL;
734	Utf8Str::raw_copy (*pstr, bstr);
735	}
736	return *this;
737	}
738
739	////////////////////////////////////////////////////////////////////////////////
740
741	/**
742	* This class is a printf-like formatter for Utf8Str strings. Its purpose is
743	* to construct Utf8Str objects from a format string and a list of arguments
744	* for the format string.
745	*
746	* The usage of this class is like the following:
747	* <code>
748	* Utf8StrFmt string ("program name = %s", argv[0]);
749	* </code>
750	*/
751	class Utf8StrFmt : public Utf8Str
752	{
753	public:
754
755	/**
756	* Constructs a new string given the format string and the list
757	* of the arguments for the format string.
758	*
759	* @param format printf-like format string (in UTF-8 encoding)
760	* @param ... list of the arguments for the format string
761	*/
762	explicit Utf8StrFmt (const char *format, ...)
763	{
764	va_list args;
765	va_start (args, format);
766	init (format, args);
767	va_end (args);
768	}
769
770	protected:
771
772	Utf8StrFmt() {}
773
774	void init (const char *format, va_list args);
775
776	private:
777
778	static DECLCALLBACK(size_t) strOutput (void pvArg, const char pachChars,
779	size_t cbChars);
780	};
781
782	/**
783	* This class is a vprintf-like formatter for Utf8Str strings. It is
784	* identical to Utf8StrFmt except that its constructor takes a va_list
785	* argument instead of ellipsis.
786	*
787	* Note that a separate class is necessary because va_list is defined as
788	* \|char *\| on most platforms. For this reason, if we had two overloaded
789	* constructors in Utf8StrFmt (one taking ellipsis and another one taking
790	* va_list) then composing a constructor call using exactly two \|char *\|
791	* arguments would cause the compiler to use the va_list overload instead of
792	* the ellipsis one which is obviously wrong. The compiler would choose
793	* va_list because ellipsis has the lowest rank when it comes to resolving
794	* overloads, as opposed to va_list which is an exact match for \|char *\|.
795	*/
796	class Utf8StrFmtVA : public Utf8StrFmt
797	{
798	public:
799
800	/**
801	* Constructs a new string given the format string and the list
802	* of the arguments for the format string.
803	*
804	* @param format printf-like format string (in UTF-8 encoding)
805	* @param args list of arguments for the format string
806	*/
807	Utf8StrFmtVA (const char *format, va_list args) { init (format, args); }
808	};
809
810	/**
811	* The BstrFmt class is a shortcut to <tt>Bstr (Utf8StrFmt (...))</tt>.
812	*/
813	class BstrFmt : public Bstr
814	{
815	public:
816
817	/**
818	* Constructs a new string given the format string and the list of the
819	* arguments for the format string.
820	*
821	* @param aFormat printf-like format string (in UTF-8 encoding).
822	* @param ... List of the arguments for the format string.
823	*/
824	explicit BstrFmt (const char *aFormat, ...)
825	{
826	va_list args;
827	va_start (args, aFormat);
828	raw_copy (bstr, Utf8StrFmtVA (aFormat, args));
829	va_end (args);
830	}
831	};
832
833	/**
834	* The BstrFmtVA class is a shortcut to <tt>Bstr (Utf8StrFmtVA (...))</tt>.
835	*/
836	class BstrFmtVA : public Bstr
837	{
838	public:
839
840	/**
841	* Constructs a new string given the format string and the list of the
842	* arguments for the format string.
843	*
844	* @param aFormat printf-like format string (in UTF-8 encoding).
845	* @param aArgs List of arguments for the format string
846	*/
847	BstrFmtVA (const char *aFormat, va_list aArgs)
848	{
849	raw_copy (bstr, Utf8StrFmtVA (aFormat, aArgs));
850	}
851	};
852
853	} /* namespace com */
854
855	#endif /* ___VBox_com_string_h */

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: