string.h revision a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fc
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync/** @file
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * MS COM / XPCOM Abstraction Layer:
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Smart string classes declaration
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync/*
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Copyright (C) 2006-2007 innotek GmbH
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync *
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 *
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 *
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 */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#ifndef ___VBox_com_string_h
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#define ___VBox_com_string_h
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#if !defined(RT_OS_WINDOWS)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#include <nsMemory.h>
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#endif
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#include "VBox/com/defs.h"
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#include "VBox/com/assert.h"
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#include <iprt/string.h>
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#include <iprt/alloc.h>
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncnamespace com
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync{
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncclass Utf8Str;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync/**
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Helper class that represents the |BSTR| type and hides platform-specific
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * implementation details.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync *
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 */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncclass Bstr
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync{
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncpublic:
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync typedef BSTR String;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync typedef const BSTR ConstString;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr () : bstr (NULL) {}
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr (const Bstr &that) : bstr (NULL) { raw_copy (bstr, that.bstr); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr (const BSTR that) : bstr (NULL) { raw_copy (bstr, that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr (const wchar_t *that) : bstr (NULL)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync AssertCompile (sizeof (wchar_t) == sizeof (OLECHAR));
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync raw_copy (bstr, (const BSTR) that);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr (const Utf8Str &that);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr (const char *that);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /** Shortcut that calls #alloc(aSize) right after object creation. */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr (size_t aSize) : bstr (NULL) { alloc (aSize); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync ~Bstr () { setNull(); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr &operator = (const Bstr &that) { safe_assign (that.bstr); return *this; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr &operator = (const BSTR that) { safe_assign (that); return *this; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr &operator = (const Utf8Str &that);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr &operator = (const char *that);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr &setNull()
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (bstr)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync ::SysFreeString (bstr);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bstr = NULL;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return *this;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr &setNullIfEmpty()
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (bstr && *bstr == 0)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync ::SysFreeString (bstr);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bstr = NULL;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return *this;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /**
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 */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr &alloc (size_t aSize)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync setNull();
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (aSize)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync unsigned int size = (unsigned int) aSize; Assert (size == aSize);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bstr = ::SysAllocStringLen (NULL, size - 1);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (bstr)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bstr [0] = 0;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return *this;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync int compare (const BSTR str) const
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return ::RTStrUcs2Cmp ((PRTUCS2) bstr, (PRTUCS2) str);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
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 bool operator != (const wchar_t *that) const
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync AssertCompile (sizeof (wchar_t) == sizeof (OLECHAR));
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return !!compare ((const BSTR) that);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool operator == (const wchar_t *that) const
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync AssertCompile (sizeof (wchar_t) == sizeof (OLECHAR));
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return !compare ((const BSTR) that);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
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 bool operator < (const wchar_t *that) const
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync AssertCompile (sizeof (wchar_t) == sizeof (OLECHAR));
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return compare ((const BSTR) that) < 0;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync int compareIgnoreCase (const BSTR str) const
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return ::RTUtf16LocaleICmp (bstr, str);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool isNull() const { return bstr == NULL; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync operator bool() const { return !isNull(); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool isEmpty() const { return isNull() || *bstr == 0; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync size_t length() const { return isNull() ? 0 : ::RTStrUcs2Len ((PRTUCS2) bstr); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /** Intended to to pass instances as |BSTR| input parameters to methods. */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync operator const BSTR () const { return bstr; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /** The same as operator const BSTR(), but for situations where the compiler
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync cannot typecast implicitly (for example, in printf() argument list). */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync const BSTR raw() const { return bstr; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /**
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Returns a non-const raw pointer that allows to modify the string directly.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * @warning
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 */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync BSTR mutableRaw() { return bstr; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /**
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 */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync const Bstr &cloneTo (BSTR *pstr) const
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (pstr)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync *pstr = NULL;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync raw_copy (*pstr, bstr);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return *this;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /**
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 */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync const Bstr &cloneTo (char **pstr) const;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /**
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Intended to pass instances as |BSTR| out parameters to methods.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Takes the ownership of the returned data.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync BSTR *asOutParam() { setNull(); return &bstr; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncprivate:
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync void safe_assign (const BSTR str)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (bstr != str)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync setNull();
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync raw_copy (bstr, str);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync inline static void raw_copy (BSTR &ls, const BSTR rs)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (rs)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync ls = ::SysAllocString ((const OLECHAR *) rs);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync inline static void raw_copy (BSTR &ls, const char *rs)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (rs)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync PRTUCS2 s = NULL;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync ::RTStrUtf8ToUcs2 (&s, rs);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync raw_copy (ls, (BSTR) s);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync ::RTStrUcs2Free (s);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync BSTR bstr;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync friend class Utf8Str; // to access our raw_copy()
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync};
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
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////////////////////////////////////////////////////////////////////////////////
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
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 *
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 */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncclass Utf8Str
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync{
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncpublic:
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync typedef char *String;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync typedef const char *ConstString;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str () : str (NULL) {}
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str (const Utf8Str &that) : str (NULL) { raw_copy (str, that.str); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str (const char *that) : str (NULL) { raw_copy (str, that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str (const Bstr &that) : str (NULL) { raw_copy (str, that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str (const BSTR that) : str (NULL) { raw_copy (str, that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /** Shortcut that calls #alloc(aSize) right after object creation. */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str (size_t aSize) : str (NULL) { alloc(aSize); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync virtual ~Utf8Str () { setNull(); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str &operator = (const Utf8Str &that) { safe_assign (that.str); return *this; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str &operator = (const char *that) { safe_assign (that); return *this; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str &operator = (const Bstr &that)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync setNull();
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync raw_copy (str, that);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return *this;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str &operator = (const BSTR that)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync setNull();
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync raw_copy (str, that);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return *this;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str &setNull()
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (str)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#if defined (RT_OS_WINDOWS)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync ::RTStrFree (str);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#else
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync nsMemory::Free (str);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#endif
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync str = NULL;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return *this;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str &setNullIfEmpty()
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (str && *str == 0)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#if defined (RT_OS_WINDOWS)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync ::RTStrFree (str);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#else
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync nsMemory::Free (str);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#endif
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync str = NULL;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return *this;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /**
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 */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str &alloc (size_t aSize)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync setNull();
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (aSize)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#if defined (RT_OS_WINDOWS)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync str = (char *) ::RTMemTmpAlloc (aSize);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#else
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync str = (char *) nsMemory::Alloc (aSize);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#endif
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (str)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync str [0] = 0;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return *this;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync int compare (const char *s) const
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return str == s ? 0 : ::strcmp (str, s);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
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
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool isNull() const { return str == NULL; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync operator bool() const { return !isNull(); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync bool isEmpty() const { return isNull() || *str == 0; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync size_t length() const { return isNull() ? 0 : ::strlen (str); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /** Intended to to pass instances as input (|char *|) parameters to methods. */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync operator const char *() const { return str; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /** The same as operator const char *(), but for situations where the compiler
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync cannot typecast implicitly (for example, in printf() argument list). */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync const char *raw() const { return str; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /**
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Returns a non-const raw pointer that allows to modify the string directly.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * @warning
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 */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync char *mutableRaw() { return str; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /**
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 * caller.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync const Utf8Str &cloneTo (char **pstr) const
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (pstr)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync *pstr = NULL;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync raw_copy (*pstr, str);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return *this;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /**
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 * caller.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync const Utf8Str &cloneTo (BSTR *pstr) const
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (pstr)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync *pstr = NULL;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Bstr::raw_copy (*pstr, str);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return *this;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /**
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Intended to pass instances as out (|char **|) parameters to methods.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Takes the ownership of the returned data.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync char **asOutParam() { setNull(); return &str; }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncprivate:
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync void safe_assign (const char *s)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (str != s)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync setNull();
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync raw_copy (str, s);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync inline static void raw_copy (char *&ls, const char *rs)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (rs)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#if defined (RT_OS_WINDOWS)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync ::RTStrDupEx (&ls, rs);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#else
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync ls = (char *) nsMemory::Clone (rs, strlen (rs) + 1);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#endif
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync inline static void raw_copy (char *&ls, const BSTR rs)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (rs)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#if defined (RT_OS_WINDOWS)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync ::RTStrUcs2ToUtf8 (&ls, (PRTUCS2) rs);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#else
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync char *s = NULL;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync ::RTStrUcs2ToUtf8 (&s, (PRTUCS2) rs);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync raw_copy (ls, s);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync ::RTStrFree (s);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#endif
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync char *str;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync friend class Bstr; // to access our raw_copy()
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync};
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
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
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync// work around error C2593 of the stupid MSVC 7.x ambiguity resolver
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncWORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP (Bstr)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncWORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP (Utf8Str)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync////////////////////////////////////////////////////////////////////////////////
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync// inlined Bstr members that depend on Utf8Str
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncinline Bstr::Bstr (const Utf8Str &that) : bstr (NULL) { raw_copy (bstr, that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncinline Bstr::Bstr (const char *that) : bstr (NULL) { raw_copy (bstr, that); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncinline Bstr &Bstr::operator = (const Utf8Str &that)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync{
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync setNull();
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync raw_copy (bstr, that);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return *this;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync}
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncinline Bstr &Bstr::operator = (const char *that)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync{
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync setNull();
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync raw_copy (bstr, that);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return *this;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync}
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncinline const Bstr &Bstr::cloneTo (char **pstr) const
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync{
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync if (pstr) {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync *pstr = NULL;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8Str::raw_copy (*pstr, bstr);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync return *this;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync}
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync////////////////////////////////////////////////////////////////////////////////
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
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 *
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * The usage of this class is like the following:
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * <code>
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Utf8StrFmt string ("program name = %s", argv[0]);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * </code>
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncclass Utf8StrFmt : public Utf8Str
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync{
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncpublic:
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /**
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Constructs a new string given the format string and the list
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * of the arguments for the format string.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync *
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * @param format printf-like format string (in UTF-8 encoding)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * @param ... list of the arguments for the format string
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync explicit Utf8StrFmt (const char *format, ...)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync {
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync va_list args;
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync va_start (args, format);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync init (format, args);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync va_end (args);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncprotected:
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8StrFmt() {}
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync void init (const char *format, va_list args);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncprivate:
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync static DECLCALLBACK(size_t) strOutput (void *pvArg, const char *pachChars,
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync size_t cbChars);
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync};
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync/**
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 *
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 */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncclass Utf8StrFmtVA : public Utf8StrFmt
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync{
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsyncpublic:
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync /**
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * Constructs a new string given the format string and the list
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * of the arguments for the format string.
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync *
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * @param format printf-like format string (in UTF-8 encoding)
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync * @param args list of arguments for the format string
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync Utf8StrFmtVA (const char *format, va_list args) { init (format, args); }
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync};
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync} /* namespace com */
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync#endif
a5e7ae69e440f6816420fc99599f044e79e716b6vboxsync