string.h revision a97f26ece82a85f69a131fb74b057774c85db9c8
/* $Id$ */
/** @file
* MS COM / XPCOM Abstraction Layer:
* UTF-8 and UTF-16 string classes
*/
/*
* Copyright (C) 2006-2009 Sun Microsystems, Inc.
*
* 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 (GPL) 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.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 USA or visit http://www.sun.com if you need
* additional information or have any questions.
*/
#ifndef ___VBox_com_string_h
#define ___VBox_com_string_h
/* Make sure all the stdint.h macros are included - must come first! */
#ifndef __STDC_LIMIT_MACROS
# define __STDC_LIMIT_MACROS
#endif
#ifndef __STDC_CONSTANT_MACROS
# define __STDC_CONSTANT_MACROS
#endif
#if defined (VBOX_WITH_XPCOM)
# include <nsMemory.h>
#endif
{
/**
* String class used universally in Main for COM-style Utf-16 strings.
* Unfortunately COM on Windows uses UTF-16 everywhere, requiring conversions
* back and forth since most of VirtualBox and our libraries use UTF-8.
* The Bstr class makes such conversions easier.
*
* Whereas the BSTR identifier is a typedef for a pointer to a wide character
* array (const char *uint_16 effectively, depending on the platform),
* the Bstr class is a fully featured string class with memory management
* for such strings.
*
* Bstr uses COM/XPCOM-provided memory management routines (SysAlloc* etc.)
* to allocate and free string buffers. This makes it possible to use it as
* to callers through component methods' output parameters using the #cloneTo()
* operation. Also, the class can adopt (take ownership of) string buffers
* returned in output parameters of COM methods using the #asOutParam()
* operation and correctly free them afterwards.
*
* As opposed to the Ut8Str class, which is very efficient, Bstr does not
* cache the length of its member string. As a result, copying Bstr's is
* more expensive, and Bstr really should only be used to capture arguments
* from and return data to public COM methods.
*
* Starting with VirtualBox 3.2, like Utf8Str, Bstr no longer differentiates
* between NULL strings and empty strings. In other words, Bstr("") and
* Bstr(NULL) behave the same. In both cases, Bstr allocates no memory,
* reports a zero length and zero allocated bytes for both, and returns an
* empty C wide string from raw().
*/
{
/**
* Creates an empty string that has no memory allocated.
*/
Bstr()
{
}
/**
* Creates a copy of another Bstr.
*
* This allocates s.length() + 1 wide characters for the new instance, unless s is empty.
*
* @param s The source string.
*
* @throws std::bad_alloc
*/
{
copyFrom(s);
}
/**
* Creates a copy of a wide char string buffer.
*
* This allocates SysStringLen(pw) + 1 wide characters for the new instance, unless s is empty.
*
* @param pcsz The source string.
*
* @throws std::bad_alloc
*/
{
}
#if defined (VBOX_WITH_XPCOM)
{
}
#endif
/**
* Creates a copy of an IPRT MiniString (which includes Utf8Str).
*
* This allocates s.length() + 1 wide characters for the new instance, unless s is empty.
*
* @param pcsz The source string.
*
* @throws std::bad_alloc
*/
{
}
/**
* Creates a copy of a C string.
*
* This allocates strlen(pcsz) + 1 bytes for the new instance, unless s is empty.
*
* @param pcsz The source string.
*
* @throws std::bad_alloc
*/
{
}
/**
* String length in wide characters.
*
* Returns the length of the member string, which is equal to SysStringLen(raw()).
* In other words, this returns neither bytes nor the number of unicode codepoints.
*
* As opposed to Utf8Str::length(), this is _not_ cached and expensive.
*/
{
return ::SysStringLen(m_bstr);
}
/**
* Deallocates all memory.
*/
inline void setNull()
{
cleanup();
}
/**
* Returns a const pointer to the member string. If the member string is empty,
* returns a pointer to a static null character.
* @return
*/
{
}
/**
* Empty string or not?
*
* Returns true if the member string has no length.
*
* @returns true if empty, false if not.
*/
bool isEmpty() const
{
}
operator bool() const
{
return !isEmpty();
}
bool operator!() const
{
return isEmpty();
}
/** Case sensitivity selector. */
enum CaseSensitivity
{
};
{
return 0;
return -1;
return 1;
if (cs == CaseSensitive)
else
}
{
}
/** @name Comparison operators.
* @{ */
// the following two are necessary or stupid MSVC will complain with "ambiguous operator=="
/** @} */
/** Intended to to pass instances as |CBSTR| input parameters to methods. */
/**
* Intended to to pass instances as |BSTR| input parameters to methods.
* Note that we have to provide this mutable BSTR operator since in MS COM
* input BSTR parameters of interface methods are not const.
*/
/**
* Intended to assign copies of instances to |BSTR| out parameters from
* within the interface method. Transfers the ownership of the duplicated
* string to the caller.
*
* This allocates a single 0 byte in the target if the member string is empty.
*/
{
if (pstr)
// raw() never returns NULL, so we always allocate something here
return *this;
}
/**
* Intended to assign instances to |BSTR| out parameters from within the
* interface method. Transfers the ownership of the original string to the
* caller and resets the instance to null.
*
* As opposed to cloneTo(), this method doesn't create a copy of the
* string.
*
* This allocates a single 0 byte in the target if the member string is empty.
*/
{
return *this;
}
/**
* Intended to pass instances as |BSTR| out parameters to methods.
* Takes the ownership of the returned data.
*/
BSTR* asOutParam()
{
cleanup();
return &m_bstr;
}
/**
* Static immutable null object. May be used for comparison purposes.
*/
/**
* Destructor implementation, also used to clean up in operator=() before
* assigning a new string.
*/
void cleanup()
{
if (m_bstr)
{
::SysFreeString(m_bstr);
}
}
/**
* Protected internal helper which allocates memory for a string capable of
* storing \a aSize - 1 characters (not bytes, not codepoints); in other words,
* aSize includes the terminating null character.
*
* Does NOT call cleanup() before allocating!
*
* @throws std::bad_alloc On allocation failure. The object is left describing
* a NULL string.
*/
{
if (cw)
{
#ifdef RT_EXCEPTIONS_ENABLED
if (!m_bstr)
#endif
}
}
/**
* Protected internal helper to copy a string, ignoring the previous object state.
*
* copyFrom() unconditionally sets the members to a copy of the given other
* strings and makes no assumptions about previous contents. Can therefore be
* used both in copy constructors, when member variables have no defined value,
* and in assignments after having called cleanup().
*
* This variant copies from another Bstr. Since Bstr does _not_ cache string lengths,
* this is not fast.
*
* @param s The source string.
*
* @throws std::bad_alloc On allocation failure. The object is left describing
* a NULL string.
*/
{
}
/**
* Protected internal helper to copy a string, ignoring the previous object state.
*
* See copyFrom() above.
*
* This variant copies from a wide char C string.
*
* @param pcsz The source string.
*
* @throws std::bad_alloc On allocation failure. The object is left describing
* a NULL string.
*/
{
if ( (pw)
)
{
}
else
}
/**
* Protected internal helper to copy a string, ignoring the previous object state.
*
* See copyFrom() above.
*
* This variant converts from a Utf-8 C string.
*
* @param pcsz The source string.
*
* @throws std::bad_alloc On allocation failure. The object is left describing
* a NULL string.
*/
{
{
// @todo r=dj apparently this was copied twice in the original because our buffers
// use memory from SysAllocMem and IPRT doesn't, but check if this can be made faster
::RTStrToUtf16(pcsz, &s);
::RTUtf16Free(s);
}
else
}
};
/* symmetric compare operators */
// inline bool operator==(CBSTR l, const Bstr &r) { return r.operator==(l); }
// inline bool operator!=(CBSTR l, const Bstr &r) { return r.operator!=(l); }
// inline bool operator==(BSTR l, const Bstr &r) { return r.operator==(l); }
// inline bool operator!=(BSTR l, const Bstr &r) { return r.operator!=(l); }
////////////////////////////////////////////////////////////////////////////////
/**
* String class used universally in Main for Utf-8 strings.
*
* This is based on iprt::MiniString, to which some functionality has been
* moved. Here we keep things that are specific to Main, such as conversions
* with UTF-16 strings (Bstr).
*
* Like iprt::MiniString, Utf8Str does not differentiate between NULL strings
* and empty strings. In other words, Utf8Str("") and Utf8Str(NULL)
* behave the same. In both cases, MiniString allocates no memory, reports
* a zero length and zero allocated bytes for both, and returns an empty
* C string from c_str().
*/
{
Utf8Str() {}
: MiniString(that)
{}
: MiniString(that)
{}
{
}
{
}
{
return *this;
}
{
return *this;
}
{
cleanup();
return *this;
}
{
cleanup();
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.
*
* This allocates a single 0 byte in the target if the member string is empty.
*
* @remarks The returned string must be freed by RTStrFree, not RTMemFree.
*/
{
if (pstr)
{
#ifdef RT_EXCEPTIONS_ENABLED
if (!*pstr)
#endif
}
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.
*
* This allocates a single 0 byte in the target if the member string is empty.
*/
{
if (pstr)
{
}
return *this;
}
/**
* Converts "this" to lower case by calling RTStrToLower().
* @return
*/
/**
* Converts "this" to upper case by calling RTStrToUpper().
* @return
*/
/**
* Removes a trailing slash from the member string, if present.
* Calls RTPathStripTrailingSlash() without having to mess with mutableRaw().
*/
void stripTrailingSlash();
/**
* Removes a trailing filename from the member string, if present.
* Calls RTPathStripFilename() without having to mess with mutableRaw().
*/
void stripFilename();
/**
* Removes a trailing file name extension from the member string, if present.
* Calls RTPathStripExt() without having to mess with mutableRaw().
*/
void stripExt();
/**
* Attempts to convert the member string into a 32-bit integer.
*
* @returns 32-bit unsigned number on success.
* @returns 0 on failure.
*/
int toInt32() const
{
return RTStrToInt32(m_psz);
}
/**
* Attempts to convert the member string into an unsigned 32-bit integer.
*
* @returns 32-bit unsigned number on success.
* @returns 0 on failure.
*/
int toUInt32() const
{
return RTStrToUInt32(m_psz);
}
/**
* Intended to pass instances as out (|char **|) parameters to methods. Takes
* the ownership of the returned data.
*
* @remarks See ministring::jolt().
*/
char **asOutParam()
{
cleanup();
return &m_psz;
}
/**
* Static immutable null object. May be used for comparison purposes.
*/
/**
* As with the ministring::copyFrom() variants, this unconditionally
* sets the members to a copy of the given other strings and makes
* no assumptions about previous contents. This can therefore be used
* both in copy constructors, when member variables have no defined
* value, and in assignments after having called cleanup().
*
* This variant converts from a UTF-16 string, most probably from
* a Bstr assignment.
*
* @param rs
*/
{
if (s)
{
RTUtf16ToUtf8((PRTUTF16)s, &m_psz); /** @todo r=bird: This technically requires using RTStrFree, ministring::cleanup() uses RTMemFree. */
#ifdef RT_EXCEPTIONS_ENABLED
if (!m_psz)
#endif
}
else
{
m_cbLength = 0;
m_cbAllocated = 0;
}
}
};
// work around error C2593 of the stupid MSVC 7.x ambiguity resolver
// @todo r=dj if I enable this I get about five warnings every time this header
// is included, figure out what that is... for now I have modified the calling code instead
// WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP(Bstr)
////////////////////////////////////////////////////////////////////////////////
/**
* 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
*/
{
}
Utf8StrFmt() {}
};
/**
* This class is a vprintf-like formatter for Utf8Str strings. It is
* identical to Utf8StrFmt except that its constructor takes a va_list
* argument instead of ellipsis.
*
* Note that a separate class is necessary because va_list is defined as
* |char *| on most platforms. For this reason, if we had two overloaded
* constructors in Utf8StrFmt (one taking ellipsis and another one taking
* va_list) then composing a constructor call using exactly two |char *|
* arguments would cause the compiler to use the va_list overload instead of
* the ellipsis one which is obviously wrong. The compiler would choose
* va_list because ellipsis has the lowest rank when it comes to resolving
* overloads, as opposed to va_list which is an exact match for |char *|.
*/
{
/**
* 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
*/
};
/**
* The BstrFmt class is a shortcut to <tt>Bstr(Utf8StrFmt(...))</tt>.
*/
{
/**
* Constructs a new string given the format string and the list of the
* arguments for the format string.
*
* @param aFormat printf-like format string (in UTF-8 encoding).
* @param ... List of the arguments for the format string.
*/
{
}
};
/**
* The BstrFmtVA class is a shortcut to <tt>Bstr(Utf8StrFmtVA(...))</tt>.
*/
{
/**
* Constructs a new string given the format string and the list of the
* arguments for the format string.
*
* @param aFormat printf-like format string (in UTF-8 encoding).
* @param aArgs List of arguments for the format string
*/
{
}
};
} /* namespace com */
#endif /* !___VBox_com_string_h */