string.h revision a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fc
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * MS COM / XPCOM Abstraction Layer:
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Smart string classes declaration
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Copyright (C) 2006-2007 innotek GmbH
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * available from http://www.virtualbox.org. This file is free software;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * you can redistribute it and/or modify it under the terms of the GNU
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * General Public License (GPL) as published by the Free Software
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * The contents of this file may alternatively be used under the terms
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * of the Common Development and Distribution License Version 1.0
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * VirtualBox OSE distribution, in which case the provisions of the
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * CDDL are applicable instead of those of the GPL.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * You may elect to license modified versions of this file under the
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * terms and conditions of either the GPL or the CDDL or both.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Helper class that represents the |BSTR| type and hides platform-specific
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * implementation details.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * This class uses COM/XPCOM-provided memory management routines to allocate
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * and free string buffers. This makes it possible to:
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * - use it as a type of member variables of COM/XPCOM components and pass
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * their values to callers through component methods' output parameters
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * using the #cloneTo() operation;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * - adopt (take ownership of) string buffers returned in output parameters
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * of COM methods using the #asOutParam() operation and correctly free them
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * afterwards.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr (const Bstr &that) : bstr (NULL) { raw_copy (bstr, that.bstr); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr (const BSTR that) : bstr (NULL) { raw_copy (bstr, that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync AssertCompile (sizeof (wchar_t) == sizeof (OLECHAR));
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /** Shortcut that calls #alloc(aSize) right after object creation. */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr (size_t aSize) : bstr (NULL) { alloc (aSize); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr &operator = (const Bstr &that) { safe_assign (that.bstr); return *this; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr &operator = (const BSTR that) { safe_assign (that); return *this; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Allocates memory for a string capable to store \a aSize - 1 characters
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * plus the terminating zero character. If \a aSize is zero, or if a
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * memory allocation error occurs, this object will become null.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync unsigned int size = (unsigned int) aSize; Assert (size == aSize);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return ::RTStrUcs2Cmp ((PRTUCS2) bstr, (PRTUCS2) str);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool operator == (const Bstr &that) const { return !compare (that.bstr); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool operator != (const Bstr &that) const { return !!compare (that.bstr); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool operator == (const BSTR that) const { return !compare (that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync AssertCompile (sizeof (wchar_t) == sizeof (OLECHAR));
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync AssertCompile (sizeof (wchar_t) == sizeof (OLECHAR));
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool operator != (const BSTR that) const { return !!compare (that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool operator < (const Bstr &that) const { return compare (that.bstr) < 0; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool operator < (const BSTR that) const { return compare (that) < 0; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync AssertCompile (sizeof (wchar_t) == sizeof (OLECHAR));
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool isEmpty() const { return isNull() || *bstr == 0; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync size_t length() const { return isNull() ? 0 : ::RTStrUcs2Len ((PRTUCS2) bstr); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /** Intended to to pass instances as |BSTR| input parameters to methods. */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /** The same as operator const BSTR(), but for situations where the compiler
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync cannot typecast implicitly (for example, in printf() argument list). */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Returns a non-const raw pointer that allows to modify the string directly.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Be sure not to modify data beyond the allocated memory! The
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * guaranteed size of the allocated memory is at least #length()
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * bytes after creation and after every assignment operation.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Intended to assign instances to |BSTR| out parameters from within the
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * interface method. Transfers the ownership of the duplicated string to
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * the caller.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Intended to assign instances to |char *| out parameters from within the
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * interface method. Transfers the ownership of the duplicated string to
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * the caller.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Intended to pass instances as |BSTR| out parameters to methods.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Takes the ownership of the returned data.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync inline static void raw_copy (BSTR &ls, const BSTR rs)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync inline static void raw_copy (BSTR &ls, const char *rs)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync// symmetric compare operators
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncinline bool operator== (const BSTR l, const Bstr &r) { return r.operator== (l); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncinline bool operator!= (const BSTR l, const Bstr &r) { return r.operator!= (l); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync////////////////////////////////////////////////////////////////////////////////
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Helper class that represents UTF8 (|char *|) strings. Useful in
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * conjunction with Bstr to simplify conversions beetween UCS2 (|BSTR|)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * and UTF8.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * This class uses COM/XPCOM-provided memory management routines to allocate
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * and free string buffers. This makes it possible to:
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * - use it as a type of member variables of COM/XPCOM components and pass
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * their values to callers through component methods' output parameters
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * using the #cloneTo() operation;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * - adopt (take ownership of) string buffers returned in output parameters
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * of COM methods using the #asOutParam() operation and correctly free them
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * afterwards.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync typedef char *String;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync typedef const char *ConstString;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str (const Utf8Str &that) : str (NULL) { raw_copy (str, that.str); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str (const char *that) : str (NULL) { raw_copy (str, that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str (const Bstr &that) : str (NULL) { raw_copy (str, that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str (const BSTR that) : str (NULL) { raw_copy (str, that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /** Shortcut that calls #alloc(aSize) right after object creation. */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str (size_t aSize) : str (NULL) { alloc(aSize); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str &operator = (const Utf8Str &that) { safe_assign (that.str); return *this; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str &operator = (const char *that) { safe_assign (that); return *this; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Allocates memory for a string capable to store \a aSize - 1 characters
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * plus the terminating zero character. If \a aSize is zero, or if a
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * memory allocation error occurs, this object will become null.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync int compare (const char *s) const
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool operator == (const Utf8Str &that) const { return !compare (that.str); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool operator != (const Utf8Str &that) const { return !!compare (that.str); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool operator == (const char *that) const { return !compare (that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool operator != (const char *that) const { return !!compare (that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool operator < (const Utf8Str &that) const { return compare (that.str) < 0; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool operator < (const char *that) const { return compare (that) < 0; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool isEmpty() const { return isNull() || *str == 0; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync size_t length() const { return isNull() ? 0 : ::strlen (str); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /** Intended to to pass instances as input (|char *|) parameters to methods. */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /** The same as operator const char *(), but for situations where the compiler
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync cannot typecast implicitly (for example, in printf() argument list). */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Returns a non-const raw pointer that allows to modify the string directly.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Be sure not to modify data beyond the allocated memory! The
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * guaranteed size of the allocated memory is at least #length()
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * bytes after creation and after every assignment operation.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Intended to assign instances to |char *| out parameters from within the
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * interface method. Transfers the ownership of the duplicated string to the
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Intended to assign instances to |BSTR| out parameters from within the
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * interface method. Transfers the ownership of the duplicated string to the
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Intended to pass instances as out (|char **|) parameters to methods.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Takes the ownership of the returned data.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync void safe_assign (const char *s)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync inline static void raw_copy (char *&ls, const char *rs)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync ls = (char *) nsMemory::Clone (rs, strlen (rs) + 1);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync inline static void raw_copy (char *&ls, const BSTR rs)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync// symmetric compare operators
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncinline bool operator== (const char *l, const Utf8Str &r) { return r.operator== (l); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncinline bool operator!= (const char *l, const Utf8Str &r) { return r.operator!= (l); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync// work around error C2593 of the stupid MSVC 7.x ambiguity resolver
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync////////////////////////////////////////////////////////////////////////////////
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync// inlined Bstr members that depend on Utf8Str
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncinline Bstr::Bstr (const Utf8Str &that) : bstr (NULL) { raw_copy (bstr, that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncinline Bstr::Bstr (const char *that) : bstr (NULL) { raw_copy (bstr, that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncinline const Bstr &Bstr::cloneTo (char **pstr) const
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync////////////////////////////////////////////////////////////////////////////////
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * This class is a printf-like formatter for Utf8Str strings. Its purpose is
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * to construct Utf8Str objects from a format string and a list of arguments
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * for the format string.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * The usage of this class is like the following:
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Utf8StrFmt string ("program name = %s", argv[0]);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Constructs a new string given the format string and the list
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * of the arguments for the format string.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * @param format printf-like format string (in UTF-8 encoding)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * @param ... list of the arguments for the format string
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync static DECLCALLBACK(size_t) strOutput (void *pvArg, const char *pachChars,
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * This class is a vprintf-like formatter for Utf8Str strings. It is
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * identical to Utf8StrFmt except that its constructor takes a va_list
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * argument instead of ellipsis.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Note that a separate class is necessary because va_list is defined as
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * |char *| on most platforms. For this reason, if we had two overloaded
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * constructors in Utf8StrFmt (one taking ellipsis and another one taking
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * va_list) then composing a constructor call using exactly two |char *|
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * arguments would cause the compiler to use the va_list overload instead of
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * the ellipsis one which is obviously wrong. The compiler would choose
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * va_list because ellipsis has the lowest rank when it comes to resolving
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * overloads, as opposed to va_list which is an exact match for |char *|.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Constructs a new string given the format string and the list
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * of the arguments for the format string.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * @param format printf-like format string (in UTF-8 encoding)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * @param args list of arguments for the format string
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8StrFmtVA (const char *format, va_list args) { init (format, args); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync} /* namespace com */