Merge remote-tracking branch 'TsudaKageyu/string-api-master'

taglib/toolkit/tstring.cpp

@@ -312,6 +312,11 @@ const char *String::toCString(bool unicode) const
   return d->cstring.c_str();
 }
 
+const wchar_t *String::toCWString() const
+{
+  return d->data.c_str();
+}
+
 String::Iterator String::begin()
 {
   return d->data.begin();

taglib/toolkit/tstring.h

@@ -178,34 +178,59 @@ namespace TagLib {
     virtual ~String();
 
     /*!
-     * If \a unicode if false (the default) this will return a \e Latin1 encoded
-     * std::string.  If it is true the returned std::wstring will be UTF-8
-     * encoded.
+     * Returns a deep copy of this String as an std::string.  The returned string 
+     * is encoded in UTF8 if \a unicode is true, otherwise Latin1.
+     *
+     * \see toCString()
      */
     std::string to8Bit(bool unicode = false) const;
 
     /*!
-     * Returns a wstring version of the TagLib string as a wide string.
+     * Returns a deep copy of this String as a wstring.  The returned string is 
+     * encoded in UTF-16 (without BOM/CPU byte order).
+     *
+     * \see toCWString()
      */
     wstring toWString() const;
 
     /*!
-     * Creates and returns a C-String based on the data.  This string is still
-     * owned by the String (class) and as such should not be deleted by the user.
+     * Creates and returns a standard C-style (null-terminated) version of this 
+     * String.  The returned string is encoded in UTF8 if \a unicode is true, 
+     * otherwise Latin1.
+     * 
+     * The returned string is still owned by this String and should not be deleted 
+     * by the user.
      *
-     * If \a unicode if false (the default) this string will be encoded in
-     * \e Latin1.  If it is true the returned C-String will be UTF-8 encoded.
+     * The returned pointer remains valid until this String instance is destroyed 
+     * or toCString() is called again.
      *
-     * This string remains valid until the String instance is destroyed or
-     * another export method is called.
-     *
-     * \warning This however has the side effect that this C-String will remain
-     * in memory <b>in addition to</b> other memory that is consumed by the
+     * \warning This however has the side effect that the returned string will remain
+     * in memory <b>in addition to</b> other memory that is consumed by this 
      * String instance.  So, this method should not be used on large strings or
-     * where memory is critical.
+     * where memory is critical.  Consider using to8Bit() instead to avoid it.
+     *
+     * \see to8Bit()
      */
     const char *toCString(bool unicode = false) const;
-
+    
+    /*!
+     * Returns a standard C-style (null-terminated) wide character version of 
+     * this String.  The returned string is encoded in UTF-16 (without BOM/CPU byte 
+     * order).
+     * 
+     * The returned string is still owned by this String and should not be deleted 
+     * by the user.
+     *
+     * The returned pointer remains valid until this String instance is destroyed 
+     * or any other method of this String is called.
+     *
+     * /note This returns a pointer to the String's internal data without any 
+     * conversions.
+     *
+     * \see toWString()
+     */
+    const wchar_t *toCWString() const;
+    
     /*!
      * Returns an iterator pointing to the beginning of the string.
      */

tests/test_string.cpp

@@ -72,6 +72,9 @@ public:
     String unicode2(unicode.to8Bit(true), String::UTF8);
     CPPUNIT_ASSERT(unicode == unicode2);
 
+	String unicode3(L"\u65E5\u672C\u8A9E");
+	CPPUNIT_ASSERT(*(unicode3.toCWString() + 1) == L'\u672C');
+
     CPPUNIT_ASSERT(strcmp(String::number(0).toCString(), "0") == 0);
     CPPUNIT_ASSERT(strcmp(String::number(12345678).toCString(), "12345678") == 0);
     CPPUNIT_ASSERT(strcmp(String::number(-12345678).toCString(), "-12345678") == 0);