MyGUI_UString.h

Go to the documentation of this file.

// Modified from OpenGUI under lenient license
// Original copyright details and licensing below:
// OpenGUI (http://opengui.sourceforge.net)
// This source code is released under the BSD License
 
// Permission is given to the MyGUI project to use the contents of file within its
// source and binary applications, as well as any derivative works, in accordance
// with the terms of any license under which MyGUI is or will be distributed.
//
// MyGUI may relicense its copy of this file, as well as any OpenGUI released updates
// to this file, under any terms that it deems fit, and is not required to maintain
// the original BSD licensing terms of this file, however OpenGUI retains the right
// to present its copy of this file under the terms of any license under which
// OpenGUI is distributed.
//
// MyGUI is not required to release to OpenGUI any future changes that it makes to
// this file, and understands and agrees that any such changes that are released
// back to OpenGUI will become available under the terms of any license under which
// OpenGUI is distributed.
//
// For brevity, this permission text may be removed from this file if desired.
// The original record kept within the SourceForge (http://sourceforge.net/) tracker
// is sufficient.
//
// - Eric Shorkey (zero/zeroskill) <opengui@rightbracket.com> [January 20th, 2007]
 
#ifndef MYGUI_U_STRING_H_
#define MYGUI_U_STRING_H_
 
 
#include "MyGUI_Prerequest.h"
#include "MyGUI_Types.h"
 
// these are explained later
#include <iterator>
#include <string>
#include <stdexcept>
 
namespace MyGUI
{
 
    /* READ THIS NOTICE BEFORE USING IN YOUR OWN APPLICATIONS
    =NOTICE=
    This class is not a complete Unicode solution. It purposefully does not
    provide certain functionality, such as proper lexical sorting for
    Unicode values. It does provide comparison operators for the sole purpose
    of using UString as an index with std::map and other operator< sorted
    containers, but it should NOT be relied upon for meaningful lexical
    operations, such as alphabetical sorts. If you need this type of
    functionality, look into using ICU instead (http://icu.sourceforge.net/).
 
    =REQUIREMENTS=
    There are a few requirements for proper operation. They are fairly small,
    and shouldn't restrict usage on any reasonable target.
    * Compiler must support unsigned 16-bit integer types
    * Compiler must support signed 32-bit integer types
    * wchar_t must be either UTF-16 or UTF-32 encoding, and specified as such
        using the WCHAR_UTF16 macro as outlined below.
    * You must include <iterator>, <string>, and <wchar>. Probably more, but
        these are the most obvious.
 
    =REQUIRED PREPROCESSOR MACROS=
    This class requires two preprocessor macros to be defined in order to
    work as advertised.
    INT32 - must be mapped to a signed 32 bit integer (ex. #define INT32 int)
    UINT16 - must be mapped to an unsigned 16 bit integer (ex. #define UINT32 unsigned short)
 
    Additionally, a third macro should be defined to control the evaluation of wchar_t:
    WCHAR_UTF16 - should be defined when wchar_t represents UTF-16 code points,
        such as in Windows. Otherwise it is assumed that wchar_t is a 32-bit
        integer representing UTF-32 code points.
    */
 
    // THIS IS A VERY BRIEF AUTO DETECTION. YOU MAY NEED TO TWEAK THIS
#ifdef __STDC_ISO_10646__
// for any compiler that provides this, wchar_t is guaranteed to hold any Unicode value with a single code point (32-bit or larger)
// so we can safely skip the rest of the testing
#else // #ifdef __STDC_ISO_10646__
#if defined( __WIN32__ ) || defined( _WIN32 )
#define WCHAR_UTF16 // All currently known Windows platforms utilize UTF-16 encoding in wchar_t
#else // #if defined( __WIN32__ ) || defined( _WIN32 )
#if WCHAR_MAX <= 0xFFFF // this is a last resort fall back test; WCHAR_MAX is defined in <wchar.h>
#define WCHAR_UTF16 // best we can tell, wchar_t is not larger than 16-bit
#endif // #if WCHAR_MAX <= 0xFFFF
#endif // #if defined( __WIN32__ ) || defined( _WIN32 )
#endif // #ifdef __STDC_ISO_10646__
 
 
// MYGUI_IS_NATIVE_WCHAR_T means that wchar_t isn't a typedef of
// uint16_t or uint32_t.
#if MYGUI_COMPILER == MYGUI_COMPILER_MSVC
 
// Don't define wchar_t related functions since it'll duplicate
// with UString::code_point related functions when compile
// without /Zc:wchar_t, because in this case both of them are
// a typedef of uint16_t.
# if defined(_NATIVE_WCHAR_T_DEFINED)
#   define MYGUI_IS_NATIVE_WCHAR_T      1
# else
#   define MYGUI_IS_NATIVE_WCHAR_T      0
# endif
#else   // MYGUI_COMPILER != MYGUI_COMPILER_MSVC
 
// Assumed wchar_t is natively for other compilers
#   define MYGUI_IS_NATIVE_WCHAR_T     1
 
#endif  // MYGUI_COMPILER == MYGUI_COMPILER_MSVC
 
 
    class MYGUI_EXPORT UString {
        // constants used in UTF-8 conversions
        static const unsigned char _lead1 = 0xC0;      //110xxxxx
        static const unsigned char _lead1_mask = 0x1F; //00011111
        static const unsigned char _lead2 = 0xE0;      //1110xxxx
        static const unsigned char _lead2_mask = 0x0F; //00001111
        static const unsigned char _lead3 = 0xF0;      //11110xxx
        static const unsigned char _lead3_mask = 0x07; //00000111
        static const unsigned char _lead4 = 0xF8;      //111110xx
        static const unsigned char _lead4_mask = 0x03; //00000011
        static const unsigned char _lead5 = 0xFC;      //1111110x
        static const unsigned char _lead5_mask = 0x01; //00000001
        static const unsigned char _cont = 0x80;       //10xxxxxx
        static const unsigned char _cont_mask = 0x3F;  //00111111
 
    public:
        using size_type = size_t;
        static const size_type npos = static_cast<size_type>(~0);
 
        using unicode_char = uint32;
 
        using code_point = uint16;
 
        using value_type = code_point;
 
        using dstring = std::basic_string<code_point>; // data string
 
        using utf32string = std::basic_string<unicode_char>;
 
    class MYGUI_EXPORT invalid_data: public std::runtime_error { /* i don't know why the beautifier is freaking out on this line */
        public:
            explicit invalid_data( const std::string& _Message ): std::runtime_error( _Message ) {
                /* The thing is, Bob, it's not that I'm lazy, it's that I just don't care. */
            }
        };
 
        //#########################################################################
    class MYGUI_EXPORT _base_iterator
    {
            friend class UString;
        protected:
            typedef ptrdiff_t difference_type;
 
            _base_iterator();
 
            void _seekFwd( size_type c );
            void _seekRev( size_type c );
            void _become( const _base_iterator& i );
            bool _test_begin() const;
            bool _test_end() const;
            size_type _get_index() const;
            void _jump_to( size_type index );
 
            unicode_char _getCharacter() const;
            int _setCharacter( unicode_char uc );
 
            void _moveNext();
            void _movePrev();
 
            dstring::iterator mIter;
            UString* mString;
        };
 
        //#########################################################################
        // FORWARD ITERATORS
        //#########################################################################
        class _const_fwd_iterator; // forward declaration
 
    class MYGUI_EXPORT _fwd_iterator: public _base_iterator
    {
            friend class _const_fwd_iterator;
        public:
            _fwd_iterator();
            _fwd_iterator( const _fwd_iterator& i );
            _fwd_iterator& operator=( const _fwd_iterator& i );
 
            _fwd_iterator& operator++();
            _fwd_iterator operator++( int );
 
            _fwd_iterator& operator--();
            _fwd_iterator operator--( int );
 
            _fwd_iterator operator+( difference_type n );
            _fwd_iterator operator-( difference_type n );
 
            _fwd_iterator& operator+=( difference_type n );
            _fwd_iterator& operator-=( difference_type n );
 
            value_type& operator*() const;
 
            value_type& operator[]( difference_type n ) const;
 
            _fwd_iterator& moveNext();
            _fwd_iterator& movePrev();
            unicode_char getCharacter() const;
            int setCharacter( unicode_char uc );
        };
 
 
 
        //#########################################################################
    class MYGUI_EXPORT _const_fwd_iterator: public _base_iterator { /* i don't know why the beautifier is freaking out on this line */
        public:
            _const_fwd_iterator();
            _const_fwd_iterator( const _const_fwd_iterator& i );
            _const_fwd_iterator& operator=( const _const_fwd_iterator& i );
            _const_fwd_iterator( const _fwd_iterator& i );
 
            _const_fwd_iterator& operator++();
            _const_fwd_iterator operator++( int );
 
            _const_fwd_iterator& operator--();
            _const_fwd_iterator operator--( int );
 
            _const_fwd_iterator operator+( difference_type n );
            _const_fwd_iterator operator-( difference_type n );
 
            _const_fwd_iterator& operator+=( difference_type n );
            _const_fwd_iterator& operator-=( difference_type n );
 
            const value_type& operator*() const;
 
            const value_type& operator[]( difference_type n ) const;
 
            _const_fwd_iterator& moveNext();
            _const_fwd_iterator& movePrev();
            unicode_char getCharacter() const;
 
            friend size_type operator-( const _const_fwd_iterator& left, const _const_fwd_iterator& right );
            friend bool operator==( const _const_fwd_iterator& left, const _const_fwd_iterator& right );
            friend bool operator!=( const _const_fwd_iterator& left, const _const_fwd_iterator& right );
            friend bool operator<( const _const_fwd_iterator& left, const _const_fwd_iterator& right );
            friend bool operator<=( const _const_fwd_iterator& left, const _const_fwd_iterator& right );
            friend bool operator>( const _const_fwd_iterator& left, const _const_fwd_iterator& right );
            friend bool operator>=( const _const_fwd_iterator& left, const _const_fwd_iterator& right );
 
        };
 
        //#########################################################################
        // REVERSE ITERATORS
        //#########################################################################
        class _const_rev_iterator; // forward declaration
    class MYGUI_EXPORT _rev_iterator: public _base_iterator { /* i don't know why the beautifier is freaking out on this line */
            friend class _const_rev_iterator;
        public:
            _rev_iterator();
            _rev_iterator( const _rev_iterator& i );
 
            _rev_iterator& operator++();
            _rev_iterator operator++( int );
 
            _rev_iterator& operator--();
            _rev_iterator operator--( int );
 
            _rev_iterator operator+( difference_type n );
            _rev_iterator operator-( difference_type n );
 
            _rev_iterator& operator+=( difference_type n );
            _rev_iterator& operator-=( difference_type n );
 
            value_type& operator*() const;
 
            value_type& operator[]( difference_type n ) const;
        };
        //#########################################################################
    class MYGUI_EXPORT _const_rev_iterator: public _base_iterator { /* i don't know why the beautifier is freaking out on this line */
        public:
            _const_rev_iterator();
            _const_rev_iterator( const _const_rev_iterator& i );
            _const_rev_iterator( const _rev_iterator& i );
            _const_rev_iterator& operator++();
            _const_rev_iterator operator++( int );
 
            _const_rev_iterator& operator--();
            _const_rev_iterator operator--( int );
 
            _const_rev_iterator operator+( difference_type n );
            _const_rev_iterator operator-( difference_type n );
 
            _const_rev_iterator& operator+=( difference_type n );
            _const_rev_iterator& operator-=( difference_type n );
 
            const value_type& operator*() const;
 
            const value_type& operator[]( difference_type n ) const;
 
            friend size_type operator-( const _const_rev_iterator& left, const _const_rev_iterator& right );
            friend bool operator==( const _const_rev_iterator& left, const _const_rev_iterator& right );
            friend bool operator!=( const _const_rev_iterator& left, const _const_rev_iterator& right );
            friend bool operator<( const _const_rev_iterator& left, const _const_rev_iterator& right );
            friend bool operator<=( const _const_rev_iterator& left, const _const_rev_iterator& right );
            friend bool operator>( const _const_rev_iterator& left, const _const_rev_iterator& right );
            friend bool operator>=( const _const_rev_iterator& left, const _const_rev_iterator& right );
        };
        //#########################################################################
 
        using iterator = _fwd_iterator;                     
        using reverse_iterator = _rev_iterator;             
        using const_iterator = _const_fwd_iterator;         
        using const_reverse_iterator = _const_rev_iterator; 
 
 
 
 
        UString();
        UString( const UString& copy );
        UString( size_type length, const code_point& ch );
        UString( const code_point* str );
        UString( const code_point* str, size_type length );
        UString( const UString& str, size_type index, size_type length );
#if MYGUI_IS_NATIVE_WCHAR_T
        UString( const wchar_t* w_str );
        UString( const wchar_t* w_str, size_type length );
#endif
        UString( const std::wstring& wstr );
        UString( const char* c_str );
        UString( const char* c_str, size_type length );
        UString( const std::string& str );
 
        explicit UString( const utf32string & str );
 
        ~UString();
 
 
 
 
        size_type size() const;
        size_type length() const;
 
        size_type length_Characters() const;
        size_type max_size() const;
        void reserve( size_type size );
        void resize( size_type num, const code_point& val = 0 );
        void swap( UString& from );
        bool empty() const;
        const code_point* c_str() const;
        const code_point* data() const;
        size_type capacity() const;
        void clear();
 
        UString substr( size_type index, size_type num = npos ) const;
        void push_back( unicode_char val );
#if MYGUI_IS_NATIVE_WCHAR_T
        void push_back( wchar_t val );
#endif
 
        void push_back( code_point val );
 
        void push_back( char val );
        bool inString( unicode_char ch ) const;
 
 
 
 
        const std::string& asUTF8() const;
        const char* asUTF8_c_str() const;
        const utf32string& asUTF32() const;
        const unicode_char* asUTF32_c_str() const;
        const std::wstring& asWStr() const;
        const wchar_t* asWStr_c_str() const;
 
 
 
 
        code_point& at( size_type loc );
        const code_point& at( size_type loc ) const;
 
        unicode_char getChar( size_type loc ) const;
 
        int setChar( size_type loc, unicode_char ch );
 
 
 
 
        iterator begin();
        const_iterator begin() const;
        iterator end();
        const_iterator end() const;
        reverse_iterator rbegin();
        const_reverse_iterator rbegin() const;
        reverse_iterator rend();
        const_reverse_iterator rend() const;
 
 
 
 
        UString& assign( iterator start, iterator end );
        UString& assign( const UString& str );
        UString& assign( const code_point* str );
        UString& assign( const code_point* str, size_type num );
        UString& assign( const UString& str, size_type index, size_type len );
        UString& assign( size_type num, const code_point& ch );
        UString& assign( const std::wstring& wstr );
#if MYGUI_IS_NATIVE_WCHAR_T
        UString& assign( const wchar_t* w_str );
        UString& assign( const wchar_t* w_str, size_type num );
#endif
        UString& assign( const std::string& str );
 
        UString& assign( const utf32string & str );
        UString& assign( const char* c_str );
        UString& assign( const char* c_str, size_type num );
 
 
 
 
        UString& append( const UString& str );
        UString& append( const code_point* str );
        UString& append( const UString& str, size_type index, size_type len );
        UString& append( const code_point* str, size_type num );
        UString& append( size_type num, code_point ch );
        UString& append( iterator start, iterator end );
#if MYGUI_IS_NATIVE_WCHAR_T
        UString& append( const wchar_t* w_str, size_type num );
        UString& append( size_type num, wchar_t ch );
#endif
        UString& append( const char* c_str, size_type num );
        UString& append( size_type num, char ch );
        UString& append( size_type num, unicode_char ch );
 
 
 
 
        iterator insert( iterator i, const code_point& ch );
        UString& insert( size_type index, const UString& str );
        UString& insert( size_type index, const code_point* str ) {
            mData.insert( index, str );
            return *this;
        }
        UString& insert( size_type index1, const UString& str, size_type index2, size_type num );
        void insert( iterator i, iterator start, iterator end );
        UString& insert( size_type index, const code_point* str, size_type num );
#if MYGUI_IS_NATIVE_WCHAR_T
        UString& insert( size_type index, const wchar_t* w_str, size_type num );
#endif
        UString& insert( size_type index, const char* c_str, size_type num );
        UString& insert( size_type index, size_type num, code_point ch );
#if MYGUI_IS_NATIVE_WCHAR_T
        UString& insert( size_type index, size_type num, wchar_t ch );
#endif
        UString& insert( size_type index, size_type num, char ch );
        UString& insert( size_type index, size_type num, unicode_char ch );
        void insert( iterator i, size_type num, const code_point& ch );
#if MYGUI_IS_NATIVE_WCHAR_T
        void insert( iterator i, size_type num, const wchar_t& ch );
#endif
        void insert( iterator i, size_type num, const char& ch );
        void insert( iterator i, size_type num, const unicode_char& ch );
 
 
 
 
        iterator erase( iterator loc );
        iterator erase( iterator start, iterator end );
        UString& erase( size_type index = 0, size_type num = npos );
 
 
 
 
        UString& replace( size_type index1, size_type num1, const UString& str );
        UString& replace( size_type index1, size_type num1, const UString& str, size_type num2 );
        UString& replace( size_type index1, size_type num1, const UString& str, size_type index2, size_type num2 );
        UString& replace( iterator start, iterator end, const UString& str, size_type num = npos );
        UString& replace( size_type index, size_type num1, size_type num2, code_point ch );
        UString& replace( iterator start, iterator end, size_type num, code_point ch );
 
 
 
 
        int compare( const UString& str ) const;
        int compare( const code_point* str ) const;
        int compare( size_type index, size_type length, const UString& str ) const;
        int compare( size_type index, size_type length, const UString& str, size_type index2, size_type length2 ) const;
        int compare( size_type index, size_type length, const code_point* str, size_type length2 ) const;
#if MYGUI_IS_NATIVE_WCHAR_T
        int compare( size_type index, size_type length, const wchar_t* w_str, size_type length2 ) const;
#endif
        int compare( size_type index, size_type length, const char* c_str, size_type length2 ) const;
 
 
 
 
        size_type find( const UString& str, size_type index = 0 ) const;
 
        size_type find( const code_point* cp_str, size_type index, size_type length ) const;
 
        size_type find( const char* c_str, size_type index, size_type length ) const;
#if MYGUI_IS_NATIVE_WCHAR_T
 
        size_type find( const wchar_t* w_str, size_type index, size_type length ) const;
#endif
 
        size_type find( char ch, size_type index = 0 ) const;
 
        size_type find( code_point ch, size_type index = 0 ) const;
#if MYGUI_IS_NATIVE_WCHAR_T
 
        size_type find( wchar_t ch, size_type index = 0 ) const;
#endif
 
        size_type find( unicode_char ch, size_type index = 0 ) const;
 
        size_type rfind( const UString& str, size_type index = 0 ) const;
        size_type rfind( const code_point* cp_str, size_type index, size_type num ) const;
        size_type rfind( const char* c_str, size_type index, size_type num ) const;
#if MYGUI_IS_NATIVE_WCHAR_T
        size_type rfind( const wchar_t* w_str, size_type index, size_type num ) const;
#endif
        size_type rfind( char ch, size_type index = 0 ) const;
        size_type rfind( code_point ch, size_type index ) const;
#if MYGUI_IS_NATIVE_WCHAR_T
        size_type rfind( wchar_t ch, size_type index = 0 ) const;
#endif
        size_type rfind( unicode_char ch, size_type index = 0 ) const;
 
 
 
 
        size_type find_first_of( const UString &str, size_type index = 0, size_type num = npos ) const;
        size_type find_first_of( code_point ch, size_type index = 0 ) const;
        size_type find_first_of( char ch, size_type index = 0 ) const;
#if MYGUI_IS_NATIVE_WCHAR_T
        size_type find_first_of( wchar_t ch, size_type index = 0 ) const;
#endif
        size_type find_first_of( unicode_char ch, size_type index = 0 ) const;
 
        size_type find_first_not_of( const UString& str, size_type index = 0, size_type num = npos ) const;
        size_type find_first_not_of( code_point ch, size_type index = 0 ) const;
        size_type find_first_not_of( char ch, size_type index = 0 ) const;
#if MYGUI_IS_NATIVE_WCHAR_T
        size_type find_first_not_of( wchar_t ch, size_type index = 0 ) const;
#endif
        size_type find_first_not_of( unicode_char ch, size_type index = 0 ) const;
 
        size_type find_last_of( const UString& str, size_type index = npos, size_type num = npos ) const;
        size_type find_last_of( code_point ch, size_type index = npos ) const;
        size_type find_last_of( char ch, size_type index = npos ) const {
            return find_last_of( static_cast<code_point>( ch ), index );
        }
#if MYGUI_IS_NATIVE_WCHAR_T
        size_type find_last_of( wchar_t ch, size_type index = npos ) const;
#endif
        size_type find_last_of( unicode_char ch, size_type index = npos ) const;
 
        size_type find_last_not_of( const UString& str, size_type index = npos, size_type num = npos ) const;
        size_type find_last_not_of( code_point ch, size_type index = npos ) const;
        size_type find_last_not_of( char ch, size_type index = npos ) const;
#if MYGUI_IS_NATIVE_WCHAR_T
        size_type find_last_not_of( wchar_t ch, size_type index = npos ) const;
#endif
        size_type find_last_not_of( unicode_char ch, size_type index = npos ) const;
 
 
 
 
        bool operator<( const UString& right ) const;
        bool operator<=( const UString& right ) const;
        bool operator>( const UString& right ) const;
        bool operator>=( const UString& right ) const;
        bool operator==( const UString& right ) const;
        bool operator!=( const UString& right ) const;
        UString& operator=( const UString& s );
        UString& operator=( code_point ch );
        UString& operator=( char ch );
#if MYGUI_IS_NATIVE_WCHAR_T
        UString& operator=( wchar_t ch );
#endif
        UString& operator=( unicode_char ch );
        code_point& operator[]( size_type index );
        const code_point& operator[]( size_type index ) const;
 
 
 
 
        operator std::string() const;
        operator std::wstring() const;
 
 
 
 
        static bool _utf16_independent_char( code_point cp );
        static bool _utf16_surrogate_lead( code_point cp );
        static bool _utf16_surrogate_follow( code_point cp );
        static size_t _utf16_char_length( code_point cp );
        static size_t _utf16_char_length( unicode_char uc );
 
        static size_t _utf16_to_utf32( const code_point in_cp[2], unicode_char& out_uc );
 
        static size_t _utf32_to_utf16( const unicode_char& in_uc, code_point out_cp[2] );
 
 
 
 
        static bool _utf8_start_char( unsigned char cp );
        static size_t _utf8_char_length( unsigned char cp );
        static size_t _utf8_char_length( unicode_char uc );
 
        static size_t _utf8_to_utf32( const unsigned char in_cp[6], unicode_char& out_uc );
        static size_t _utf32_to_utf8( const unicode_char& in_uc, unsigned char out_cp[6] );
 
        static size_type _verifyUTF8( const unsigned char* c_str );
        static size_type _verifyUTF8( const std::string& str );
 
    private:
        //template<class ITER_TYPE> friend class _iterator;
        dstring mData;
 
        enum BufferType {
            bt_none,
            bt_string,
            bt_wstring,
            bt_utf32string
        };
 
        void _init();
 
        // Scratch buffer
        void _cleanBuffer() const;
 
        void _getBufferStr() const;
        void _getBufferWStr() const;
        void _getBufferUTF32Str() const;
 
        void _load_buffer_UTF8() const;
        void _load_buffer_WStr() const;
        void _load_buffer_UTF32() const;
 
        mutable BufferType m_bufferType; // identifies the data type held in m_buffer
        mutable size_t m_bufferSize; // size of the CString buffer
 
        // multi-purpose buffer used everywhere we need a throw-away buffer
        union {
            mutable void* mVoidBuffer;
            mutable std::string* mStrBuffer;
            mutable std::wstring* mWStrBuffer;
            mutable utf32string* mUTF32StrBuffer;
        }
        m_buffer;
    };
 
    inline UString operator+( const UString& s1, const UString& s2 ) {
        return UString( s1 ).append( s2 );
    }
    inline UString operator+( const UString& s1, UString::code_point c ) {
        return UString( s1 ).append( 1, c );
    }
    inline UString operator+( const UString& s1, UString::unicode_char c ) {
        return UString( s1 ).append( 1, c );
    }
    inline UString operator+( const UString& s1, char c ) {
        return UString( s1 ).append( 1, c );
    }
#if MYGUI_IS_NATIVE_WCHAR_T
    inline UString operator+( const UString& s1, wchar_t c ) {
        return UString( s1 ).append( 1, c );
    }
#endif
    inline UString operator+( UString::code_point c, const UString& s2 ) {
        return UString().append( 1, c ).append( s2 );
    }
    inline UString operator+( UString::unicode_char c, const UString& s2 ) {
        return UString().append( 1, c ).append( s2 );
    }
    inline UString operator+( char c, const UString& s2 ) {
        return UString().append( 1, c ).append( s2 );
    }
#if MYGUI_IS_NATIVE_WCHAR_T
    inline UString operator+( wchar_t c, const UString& s2 ) {
        return UString().append( 1, c ).append( s2 );
    }
#endif
 
    // (const) forward iterator common operators
    inline UString::size_type operator-( const UString::_const_fwd_iterator& left, const UString::_const_fwd_iterator& right ) {
        return ( left.mIter - right.mIter );
    }
    inline bool operator==( const UString::_const_fwd_iterator& left, const UString::_const_fwd_iterator& right ) {
        return left.mIter == right.mIter;
    }
    inline bool operator!=( const UString::_const_fwd_iterator& left, const UString::_const_fwd_iterator& right ) {
        return left.mIter != right.mIter;
    }
    inline bool operator<( const UString::_const_fwd_iterator& left, const UString::_const_fwd_iterator& right ) {
        return left.mIter < right.mIter;
    }
    inline bool operator<=( const UString::_const_fwd_iterator& left, const UString::_const_fwd_iterator& right ) {
        return left.mIter <= right.mIter;
    }
    inline bool operator>( const UString::_const_fwd_iterator& left, const UString::_const_fwd_iterator& right ) {
        return left.mIter > right.mIter;
    }
    inline bool operator>=( const UString::_const_fwd_iterator& left, const UString::_const_fwd_iterator& right ) {
        return left.mIter >= right.mIter;
    }
 
    // (const) reverse iterator common operators
    // NB: many of these operations are evaluated in reverse because this is a reverse iterator wrapping a forward iterator
    inline UString::size_type operator-( const UString::_const_rev_iterator& left, const UString::_const_rev_iterator& right ) {
        return ( right.mIter - left.mIter );
    }
    inline bool operator==( const UString::_const_rev_iterator& left, const UString::_const_rev_iterator& right ) {
        return left.mIter == right.mIter;
    }
    inline bool operator!=( const UString::_const_rev_iterator& left, const UString::_const_rev_iterator& right ) {
        return left.mIter != right.mIter;
    }
    inline bool operator<( const UString::_const_rev_iterator& left, const UString::_const_rev_iterator& right ) {
        return right.mIter < left.mIter;
    }
    inline bool operator<=( const UString::_const_rev_iterator& left, const UString::_const_rev_iterator& right ) {
        return right.mIter <= left.mIter;
    }
    inline bool operator>( const UString::_const_rev_iterator& left, const UString::_const_rev_iterator& right ) {
        return right.mIter > left.mIter;
    }
    inline bool operator>=( const UString::_const_rev_iterator& left, const UString::_const_rev_iterator& right ) {
        return right.mIter >= left.mIter;
    }
 
    inline std::ostream& operator << ( std::ostream& os, const UString& s ) {
        return os << s.asUTF8();
    }
 
    inline std::wostream& operator << ( std::wostream& os, const UString& s ) {
        return os << s.asWStr();
    }
 
} // namespace MyGUI
 
#endif  // __MYGUI_U_STRING_H__