string.h revision 37d272760bb0f54f8909f33ca8940a107c467151
/** @file
*
* MS COM / XPCOM Abstraction Layer:
* Smart string classes declaration
*/
/*
* Copyright (C) 2006 InnoTek Systemberatung GmbH
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License as published by the Free Software Foundation,
* in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
* distribution. VirtualBox OSE is distributed in the hope that it will
* be useful, but WITHOUT ANY WARRANTY of any kind.
*
* If you received this file as part of a commercial VirtualBox
* distribution, then only the terms of your commercial VirtualBox
* license agreement apply instead of the previous paragraph.
*/
#ifndef __VBox_com_string_h__
#define __VBox_com_string_h__
#if !defined(__WIN__)
#include <nsMemory.h>
#endif
{
/**
* Helper class that represents the |BSTR| type and hides platform-specific
* implementation details.
*
* @note
* This class follows the common ownership transfer rule, Regarding to passing
* strings as method parameters, this means that the instance data is always
* owned by the caller.
*/
{
typedef const BSTR ConstString;
{
}
/** Shortcut that calls #alloc(aSize) right after object creation. */
{
if (bstr)
{
::SysFreeString (bstr);
}
return *this;
}
{
{
::SysFreeString (bstr);
}
return *this;
}
/**
* Allocates memory for a string capable to store \a aSize - 1 characters
* plus the terminating zero character. If \a aSize is zero, or if a
* memory allocation error occurs, this object will become null.
*/
{
setNull();
if (aSize)
{
if (bstr)
bstr [0] = 0;
}
return *this;
}
{
}
{
}
{
}
{
}
{
}
/** Intended to to pass instances as |BSTR| input parameters to methods. */
/** The same as operator const BSTR(), but for situations where the compiler
cannot typecast implicitly (for example, in printf() argument list). */
/**
* Returns a non-const raw pointer that allows to modify the string directly.
* @warning
* Be sure not to modify data beyond the allocated memory! The
* guaranteed size of the allocated memory is at least #length()
* bytes after creation and after every assignment operation.
*/
/**
* Intended to assign instances to |BSTR| out parameters from within the
* interface method. Transfers the ownership of the duplicated string to
* the caller.
*/
{
if (pstr)
{
}
return *this;
}
/**
* Intended to assign instances to |char *| out parameters from within the
* interface method. Transfers the ownership of the duplicated string to
* the caller.
*/
/**
* Intended to pass instances as |BSTR| out parameters to methods.
* Takes the ownership of the returned data.
*/
{
{
setNull();
}
}
{
if (rs)
}
{
if (rs)
{
::RTStrUtf8ToUcs2 (&s, rs);
::RTStrUcs2Free (s);
}
}
};
// symmetric compare operators
////////////////////////////////////////////////////////////////////////////////
/**
* Helper class that represents UTF8 (|char *|) strings. Useful in
* conjunction with Bstr to simplify conversions beetween UCS2 (|BSTR|)
* and UTF8.
*/
{
typedef char *String;
typedef const char *ConstString;
/** Shortcut that calls #alloc(aSize) right after object creation. */
{
setNull();
return *this;
}
{
setNull();
return *this;
}
{
if (str)
{
#if defined (__WIN__)
#else
#endif
}
return *this;
}
{
{
#if defined (__WIN__)
#else
#endif
}
return *this;
}
/**
* Allocates memory for a string capable to store \a aSize - 1 characters
* plus the terminating zero character. If \a aSize is zero, or if a
* memory allocation error occurs, this object will become null.
*/
{
setNull();
if (aSize)
{
#if defined (__WIN__)
#else
#endif
if (str)
str [0] = 0;
}
return *this;
}
int compare (const char *s) const
{
}
/** Intended to to pass instances as input (|char *|) parameters to methods. */
/** The same as operator const char *(), but for situations where the compiler
cannot typecast implicitly (for example, in printf() argument list). */
/**
* Returns a non-const raw pointer that allows to modify the string directly.
* @warning
* Be sure not to modify data beyond the allocated memory! The
* guaranteed size of the allocated memory is at least #length()
* bytes after creation and after every assignment operation.
*/
char *mutableRaw() { return str; }
/**
* Intended to assign instances to |char *| out parameters from within the
* interface method. Transfers the ownership of the duplicated string to the
* caller.
*/
{
if (pstr)
{
}
return *this;
}
/**
* Intended to assign instances to |BSTR| out parameters from within the
* interface method. Transfers the ownership of the duplicated string to the
* caller.
*/
{
if (pstr)
{
}
return *this;
}
/**
* Intended to pass instances as out (|char **|) parameters to methods.
* Takes the ownership of the returned data.
*/
void safe_assign (const char *s)
{
if (str != s)
{
setNull();
}
}
{
if (rs)
#if defined (__WIN__)
#else
#endif
}
{
if (rs)
{
#if defined (__WIN__)
#else
char *s = NULL;
::RTStrFree (s);
#endif
}
}
char *str;
};
// symmetric compare operators
// work around error C2593 of the stupid MSVC 7.x ambiguity resolver
////////////////////////////////////////////////////////////////////////////////
// inlined Bstr members that depend on Utf8Str
{
setNull();
return *this;
}
{
setNull();
return *this;
}
{
if (pstr) {
}
return *this;
}
////////////////////////////////////////////////////////////////////////////////
/**
* This class is a printf-like formatter for Utf8Str strings. Its purpose is
* to construct Utf8Str objects from a format string and a list of arguments
* for the format string.
*
* The usage of this class is like the following:
* <code>
* Utf8StrFmt string ("program name = %s", argv[0]);
* </code>
*/
{
/**
* Constructs a new string given the format string and the list
* of the arguments for the format string.
*
* @param format printf-like format string (in UTF-8 encoding)
* @param ... list of the arguments for the format string
*
* @note Be extremely careful when passing exactly one argument in the
* ellipsis. If this is a string the C++ could decide to use the
* other constructor since va_list is defined as char * on some
* platforms. If unsure, add an extra dummy argument.
*/
{
}
/**
* Constructs a new string given the format string and the list
* of the arguments for the format string.
*
* @param format printf-like format string (in UTF-8 encoding)
* @param args list of arguments for the format string
*/
};
} // namespace com
#endif // __VBox_com_string_h__