//----------------------------------------------------------------------------------------------------------------------
/// \file
/// <summary>
/// Wex String classes.  Use the String class in exception-throwing environments,
/// and the NoThrowString class in non exception-throwing environments.  The NoThrowString
/// class is an exception-safe wrapper around the String class.
/// </summary>
/// <remarks>
/// When using the String class, you must be sure that you are handling WEX::Common::Exceptions around any
/// non-const member function calls.  
/// 
/// When using the NoThrowString class, you should call IsValid after every call to a non-const
/// member function in order to check that the string contents are still valid.  
/// You can also call GetLastHResult() for more information.
/// </remarks>
// Copyright (c) Microsoft Corporation.  All Rights Reserved.
//----------------------------------------------------------------------------------------------------------------------
#if !defined(__WEXSTRING_H__) && defined(_WIN32)
#define __WEXSTRING_H__

#include "Wex.Common.h"
#include "WexTypes.h"

#include <specstrings.h>
#include <stdarg.h>

/// \namespace WEX::Common
/// <summary>
/// The WEX::Common namespace contains fundamental declarations.
/// </summary>
namespace WEX { namespace Common
{
    class NoThrowString;

    /// <summary>
    /// Wex String classes.  Use the String class in exception-throwing environments,
    /// and the NoThrowString class in non exception-throwing environments.  The NoThrowString
    /// class is an exception-safe wrapper around the String class.
    /// </summary>
    class WEXCOMMON_API String
    {
        friend class NoThrowString;
    public:
        /// <summary>Constructs an empty String.</summary>
        String();

        /// <summary>Constructs a String with the same contents as the specified NoThrowString.</summary>
        /// <param name="str">The NoThrowString instance to copy the contents from.</param>
        String(const NoThrowString& str);

        /// <summary></summary>
        /// <param name="psz"> </param>
        String(_In_opt_z_ wchar_t* psz);

        /// <summary>Constructs a String object, and copies the requested number of characters from the specified wchar_t*</summary>
        /// <param name="psz"> </param>
        /// <param name="count"> </param>
        String(_In_reads_or_z_opt_(count) const wchar_t* psz, int count);

        /// <summary></summary>
        /// <param name="psz"> </param>
        String(_In_opt_z_ char* psz);

        /// <summary></summary>
        /// <param name="psz"> </param>
        String(_In_opt_z_ const wchar_t* psz);

        /// <summary></summary>
        /// <param name="psz"> </param>
        String(_In_opt_z_ const char* psz);

        /// <summary>Destroys the String free'ing all associated resources.</summary>
        ~String();

        /// <summary>Move constructor</summary>
        /// <param name="str"> </param>
        String(String&& str);

        // Copy constructor
        /// <summary> </summary>
        /// <param name="str"> </param>
        String(const String& str);

        // Assignment
        /// <summary>Move assignment operator from NoThrowString. If the NoThrowString is not valid, the String remains unchanged.</summary>
        /// <param name="strSrc"> </param>
        const String& operator =(NoThrowString&& strSrc);

        /// <summary></summary>
        /// <param name="strSrc"> </param>
        const String& operator =(String strSrc);

        /// <summary>Copy assignment operator from NoThrowString. If the NoThrowString is not valid, the String remains unchanged.</summary>
        /// <param name="strSrc"> </param>
        const String& operator =(const NoThrowString& strSrc);

        /// <summary></summary>
        /// <param name="ch"> </param>
        const String& operator =(wchar_t ch);

        /// <summary></summary>
        /// <param name="ch"> </param>
        const String& operator =(char ch);

        /// <summary></summary>
        /// <param name="psz"> </param>
        const String& operator =(_In_opt_z_ const wchar_t* psz);

        /// <summary></summary>
        /// <param name="psz"> </param>
        const String& operator =(_In_opt_z_ const char* psz);

        /// <summary></summary>
        /// <param name="psz"> </param>
        const String& operator =(_In_opt_z_ const unsigned char* psz); 

        // Appending (For concatenation, see outside of the class definition below)

        /// <summary></summary>
        /// <param name="str"> </param>
        const String& operator +=(const String& str);

        /// <summary></summary>
        /// <param name="ch"> </param>
        /// <param name="ch"> </param>
        const String& operator +=(wchar_t ch);

        /// <summary></summary>
        /// <param name="ch"> </param>
        const String& operator +=(char ch);

        /// <summary></summary>
        /// <param name="psz"> </param>
        const String& operator +=(_In_z_ const wchar_t* psz);

        // Conversion
        operator const wchar_t*() const;

        // Helper Methods
        /// <summary>Append a specified string to an existing String</summary>
        /// <param name="strSrc">The String to append.</param>
        /// <param name="strSrc"> </param>
        String& Append(const String& strSrc);

        /// <summary>Append a specified string to an existing String</summary>
        /// <param name="pszSrc"> </param>
        String& Append(_In_z_ const wchar_t* pszSrc);

        /// <summary>Append a given character to this string</summary>
        /// <param name="ch"> </param>
        String& Append(wchar_t ch);

        /// <summary>Append a given character to this string</summary>
        /// <param name="ch"> </param>
        String& Append(char ch);

        /// <summary>Appends formatted data to an existing string</summary>
        /// <param name="pszFormat"> </param>
        String& AppendFormat(_In_z_ _Printf_format_string_ const wchar_t* pszFormat, ...);

        /// <summary>Appends formatted data to an existing string</summary>
        /// <param name="pszFormat"> </param>
        /// <param name="args"> </param>
        String& AppendFormatV(_In_z_ _Printf_format_string_ const wchar_t* pszFormat, va_list args);

        /// <summary>Compares two strings (case sensitive)</summary>
        /// <param name="pszCompare"> </param>
        int Compare(_In_z_ const wchar_t* pszCompare) const;

        /// <summary>Compares two strings (case insensitive).</summary>
        /// <param name="pszCompare"> </param>
        int CompareNoCase(_In_z_ const wchar_t* pszCompare) const;

        /// <summary>Copies the requested number of characters from the specified wchar_t*.  Allocates more space if necessary.</summary>
        /// <param name="pszSrc"> </param>
        /// <param name="count"> </param>
        void Copy(_In_reads_or_z_(count) const wchar_t* pszSrc, int count);

        /// <summary>Deletes a character or characters from a string</summary>
        /// <param name="index"> </param>
        /// <param name="count"> </param>
        int Delete(int index, int count = 1);

        /// <summary>Empties the string</summary>
        void Empty();

        /// <summary>Searches the string for the first match of the specified character</summary>
        /// <param name="ch"> </param>
        /// <returns>The zero-based index of the first character in this String object that matches
        /// the requested character or -1 if the character is not found.</returns>
        int Find(wchar_t ch) const;

        /// <summary>Searches the string for the first match of the specified character</summary>
        /// <param name="ch"> </param>
        /// <param name="start"> </param>
        /// <returns>The zero-based index of the first character in this String object after the start
        /// offset that matches the requested character or -1 if the character is not found.</returns>
        int Find(wchar_t ch, int start) const;

        /// <summary>Searches the string for the first match of the specified substring</summary>
        /// <param name="pszSub"> </param>
        /// <returns>The zero-based index of the first substring in this String object that matches
        /// the requested substring or -1 if the substring is not found.</returns>
        int Find(_In_z_ const wchar_t* pszSub) const;

        /// <summary>Searches the string for the first match of the specified substring</summary>
        /// <param name="pszSub"> </param>
        /// <param name="start"> </param>
        /// <returns>The zero-based index of the first substring in this String object after the start
        /// offset that matches the requested substring or -1 if the substring is not found.</returns>
        int Find(_In_z_ const wchar_t* pszSub, int start) const;

        /// <summary>Formats the string as swprintf does</summary>
        /// <param name="pszFormat"> </param>
        String& Format(_In_z_ _Printf_format_string_ const wchar_t* pszFormat, ...);

        /// <summary>Formats the string as swprintf does</summary>
        /// <param name="pszFormat"> </param>
        /// <param name="args"> </param>
        String& FormatV(_In_z_ _Printf_format_string_ const wchar_t* pszFormat, va_list args);

        /// <summary>Frees any extra memory previously allocated by the string but no longer needed</summary>
        void FreeExtra();

        /// <summary>Returns the count of characters in the string</summary>
        int GetLength() const;

        /// <summary>Inserts a single character at the given index within the string</summary>
        /// <param name="index"> </param>
        /// <param name="ch"> </param>
        int Insert(int index, wchar_t ch);

        /// <summary>Inserts a substring at the given index within the string</summary>
        /// <param name="index"> </param>
        /// <param name="psz"> </param>
        int Insert(int index, _In_z_ const wchar_t* psz);

        /// <summary>Returns whether or not the string is empty</summary>
        bool IsEmpty() const;

        /// <summary>Returns a non-const pointer to the underlying string buffer.  If you write to the buffer using this pointer, be sure to call ReleaseBuffer when finished.</summary>
        unsigned short* GetBuffer();

        /// <summary>Returns a pointer to the internal character buffer for the String object, truncating or growing its length if necessary to exactly match the length specified in Length</summary>
        /// <param name="length"> </param>
        _Ret_writes_(length + 1) unsigned short* GetBufferSetLength(int length);

        /// <summary>Call this method to reallocate or free up the buffer of the string object, If you know that the string in the buffer is null terminated, you can omit the newLength argument. If your string is not null terminated, use newLength to specify its length. NOTE: The address returned by GetBuffer is invalid after the call to ReleaseBuffer </summary>
        /// <param name="newLength"> </param>
        void ReleaseBuffer(int newLength = -1);

        /// <summary>Extracts the first (leftmost) count characters from the string</summary>
        /// <param name="count"> </param>
        String Left(int count) const;

        /// <summary>Extracts a substring of length count characters, starting at position first </summary>
        /// <param name="first"> </param>
        /// <param name="count"> </param>
        String Mid(int first, int count) const;

        /// <summary>Extracts a substring of length count characters, starting at position first </summary>
        /// <param name="first"> </param>
        String Mid(int first) const;

        /// <summary>Removes instances of the specified character from the string</summary>
        /// <param name="removeChar"> </param>
        int Remove(wchar_t removeChar);

        /// <summary>Replaces all instances of one character with another</summary>
        /// <param name="oldChar"> </param>
        /// <param name="newChar"> </param>
        int Replace(wchar_t oldChar, wchar_t newChar);

        /// <summary>Replaces all instances of one substring with another</summary>
        /// <param name="pszOld"> </param>
        /// <param name="pszNew"> </param>
        int Replace(_In_z_ const wchar_t* pszOld, _In_z_ const wchar_t* pszNew);

        /// <summary>Reverses the order of characters in the string</summary>
        void Reverse();

        /// <summary>Searches for a character inside a larger string; starts at the end of the string</summary>
        /// <returns>The zero-based index of the last character in this String object that matches the requested character, or -1 if the character is not found.</returns>
        /// <param name="ch">The character to look for.</param>
        int ReverseFind(wchar_t ch) const;

        /// <summary>Extracts the last (rightmost) count characters from the string </summary>
        /// <param name="count"> </param>
        String Right(int count) const;

        /// <summary>Converts all the characters in this string to lower-case </summary>
        String& ToLower();

        /// <summary>Converts all the characters in this string to upper-case </summary>
        String& ToUpper();

        /// <summary>Trims all leading and trailing whitespace, new line, tab and space characters from the string</summary>
        void Trim();

        /// <summary>Trims all leading and trailing occurrences of character 'ch'</summary>
        void Trim(unsigned short ch);

        /// <summary>Trims all leading and trailing whitespace, new line, tab and space characters from the left portion of the string</summary>
        void TrimLeft();

        /// <summary>Trims all leading and trailing whitespace, new line, tab and space characters from the right portion of the string</summary>
        void TrimRight();

        /// <summary>Returns whether or not the specified const wchar_t* is null or an empty string</summary>
        /// <param name="psz">The const wchar_t* to check.</param>
        /// <returns> </returns>
        _Post_equal_to_(!psz || *psz == 0)
        static bool WEXCOMMON_STDCALL IsNullOrEmpty(_In_opt_z_ const wchar_t* psz)
        {
            return !psz || *psz == L'\0';
        }

        // unsigned short exports
        #if defined(WEXCOMMON_FULL_BUILD)
        operator const unsigned short*() const;

        String(_In_opt_z_ unsigned short* psz);
        String(_In_reads_or_z_opt_(count) const unsigned short* psz, int count);
        String(_In_opt_z_ const unsigned short* psz);

        const String& operator =(unsigned short ch);
        const String& operator =(_In_opt_z_ const unsigned short* psz);

        const String& operator +=(unsigned short ch);
        const String& operator +=(_In_z_ const unsigned short* psz);

        String& Append(_In_z_ const unsigned short* pszSrc);
        String& Append(unsigned short ch);
        String& AppendFormat(_In_z_ _Printf_format_string_ const unsigned short* pszFormat, ...);
        String& AppendFormatV(_In_z_ _Printf_format_string_ const unsigned short* pszFormat, va_list args);
        int Compare(_In_z_ const unsigned short* pszCompare) const;
        int CompareNoCase(_In_z_ const unsigned short* pszCompare) const;
        void Copy(_In_reads_or_z_(count) const unsigned short* pszSrc, int count);
        int Find(unsigned short ch) const;
        int Find(unsigned short ch, int start) const;
        int Find(_In_z_ const unsigned short* pszSub) const;
        int Find(_In_z_ const unsigned short* pszSub, int start) const;
        String& Format(_In_z_ _Printf_format_string_ const unsigned short* pszFormat, ...);
        String& FormatV(_In_z_ _Printf_format_string_ const unsigned short* pszFormat, va_list args);
        int Insert(int index, unsigned short ch);
        int Insert(int index, _In_z_ const unsigned short* psz);
        int Remove(unsigned short removeChar);
        int Replace(unsigned short oldChar, unsigned short newChar);
        int Replace(_In_z_ const unsigned short* pszOld, _In_z_ const unsigned short* pszNew);
        int ReverseFind(unsigned short ch) const;

        static bool WEXCOMMON_STDCALL IsNullOrEmpty(const unsigned short* psz)
        {
            return IsNullOrEmpty(reinterpret_cast<const wchar_t*>(psz));
        }
        #endif // WEXCOMMON_FULL_BUILD

    private:
        friend WEXCOMMON_API int WEXCOMMON_STDCALL GetBufferLength(const String& string);
        friend WEXCOMMON_API void WEXCOMMON_STDCALL swap(String& str1, String& str2);

        // m_pReserved is not currently used. It exists to ensure the class has the size expected by code built against older TAEF headers.
        void* m_pReserved;
        wchar_t* m_psz;
    };

    /// <summary>A function that retrieves the length of the allocated buffer backing a String instance.</summary>
    /// <param name="string">The String to retrieve the buffer length of.</param>
    /// <returns>The length of the allocated buffer, in characters.</returns>
    WEXCOMMON_API int WEXCOMMON_STDCALL GetBufferLength(const String& string);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator==(const String& str1, const String& str2);

    WEXCOMMON_API bool WEXCOMMON_STDCALL operator==(const String& str, _In_z_ const wchar_t* psz);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator==(_In_z_ const wchar_t* psz, const String& str);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator!=(const String& str1, const String& str2);

    WEXCOMMON_API bool WEXCOMMON_STDCALL operator!=(const String& str, _In_z_ const wchar_t* psz);

    WEXCOMMON_API bool WEXCOMMON_STDCALL operator!=(_In_z_ const wchar_t* psz, const String& str);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<(const String& str1, const String& str2);

    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<(const String& str, _In_z_ const wchar_t* psz);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<(_In_z_ const wchar_t* psz, const String& str);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>(const String& str1, const String& str2);

    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>(const String& str, _In_z_ const wchar_t* psz);

    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>(_In_z_ const wchar_t* psz, const String& str);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<=(const String& str1, const String& str2);

    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<=(const String& str, _In_z_ const wchar_t* psz);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<=(_In_z_ const wchar_t* psz, const String& str);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>=(const String& str1, const String& str2);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>=(const String& str, _In_z_ const wchar_t* psz);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>=(_In_z_ const wchar_t* psz, const String& str);

    // Concatenation
    /// <summary></summary>
    /// <param name="str1"> </param>
    /// <param name="str2"> </param>
    WEXCOMMON_API String WEXCOMMON_STDCALL operator+(String str1, const String& str2);

    /// <summary></summary>
    /// <param name="str"> </param>
    /// <param name="ch"> </param>
    WEXCOMMON_API String WEXCOMMON_STDCALL operator+(String str, wchar_t ch);

    /// <summary></summary>
    /// <param name="ch"> </param>
    /// <param name="str"> </param>
    WEXCOMMON_API String WEXCOMMON_STDCALL operator+(wchar_t ch, const String& str);

    /// <summary></summary>
    /// <param name="str"> </param>
    /// <param name="ch"> </param>
    WEXCOMMON_API String WEXCOMMON_STDCALL operator+(String str, char ch);

    /// <summary></summary>
    /// <param name="ch"> </param>
    /// <param name="str"> </param>
    WEXCOMMON_API String WEXCOMMON_STDCALL operator+(char ch, const String& str);

    /// <summary></summary>
    /// <param name="str"> </param>
    /// <param name="lpsz"> </param>
    WEXCOMMON_API String WEXCOMMON_STDCALL operator+(String str, _In_z_ const wchar_t* lpsz);

    /// <summary></summary>
    /// <param name="psz"> </param>
    /// <param name="str"> </param>
    WEXCOMMON_API String WEXCOMMON_STDCALL operator+(_In_z_ const wchar_t* psz, const String& str);

    // unsigned short exports
    #if defined(WEXCOMMON_FULL_BUILD)
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator==(const String& str, _In_z_ const unsigned short* psz);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator==(_In_z_ const unsigned short* psz, const String& str);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator!=(const String& str, _In_z_ const unsigned short* psz);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator!=(_In_z_ const unsigned short* psz, const String& str);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<(const String& str, _In_z_ const unsigned short* psz);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<(_In_z_ const unsigned short* psz, const String& str);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>(const String& str, _In_z_ const unsigned short* psz);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>(_In_z_ const unsigned short* psz, const String& str);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<=(const String& str, _In_z_ const unsigned short* psz);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<=(_In_z_ const unsigned short* psz, const String& str);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>=(const String& str, _In_z_ const unsigned short* psz);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>=(_In_z_ const unsigned short* psz, const String& str);
    WEXCOMMON_API String WEXCOMMON_STDCALL operator+(String str, unsigned short ch);
    WEXCOMMON_API String WEXCOMMON_STDCALL operator+(unsigned short ch, const String& str);
    WEXCOMMON_API String WEXCOMMON_STDCALL operator+(String str, _In_z_ const unsigned short* lpsz);
    WEXCOMMON_API String WEXCOMMON_STDCALL operator+(_In_z_ const unsigned short* psz, const String& str);
    #endif

    WEXCOMMON_API void WEXCOMMON_STDCALL swap(String& str1, String& str2);

    /// <summary>
    /// Wex String classes.  Use the String class in exception-throwing environments,
    /// and the NoThrowString class in non exception-throwing environments.  The NoThrowString
    /// class is an exception-safe wrapper around the String class.
    /// </summary>
    class WEXCOMMON_API NoThrowString
    {
    friend class String;
    public:
        NoThrowString();
        NoThrowString(const String& str);
        NoThrowString(_In_opt_z_ wchar_t* psz);
        NoThrowString(_In_reads_or_z_opt_(count) const wchar_t* psz, int count); // Constructs a NoThrowString object, and copies the requested number of characters from the specified wchar_t*
        NoThrowString(_In_opt_z_ char* psz);
        NoThrowString(_In_opt_z_ const wchar_t* psz);
        NoThrowString(_In_opt_z_ const char* psz);
        ~NoThrowString();

        // Move constructor
        NoThrowString(NoThrowString&& str);

        // Copy constructor
        NoThrowString(const NoThrowString& str);

        // Assignment
        const NoThrowString& operator =(NoThrowString strSrc);
        const NoThrowString& operator =(const String& strSrc);
        const NoThrowString& operator =(wchar_t ch);
        const NoThrowString& operator =(char ch);
        const NoThrowString& operator =(_In_opt_z_ const wchar_t* psz);
        const NoThrowString& operator =(_In_opt_z_ const char* psz);
        const NoThrowString& operator =(_In_opt_z_ const unsigned char* psz); 

        // Appending (For concatenation, see outside of the class definition below)
        const NoThrowString& operator +=(const NoThrowString& str);
        const NoThrowString& operator +=(wchar_t ch);
        const NoThrowString& operator +=(char ch);
        const NoThrowString& operator +=(_In_z_ const wchar_t* psz); 

        // Conversion
        operator const wchar_t*() const;

        // Helper Methods
        const wchar_t* ToCStrWithFallbackTo(_In_z_ const wchar_t* pszDefaultString) const;

        /// <summary>Append a specified string to an existing NoThrowString</summary>
        NoThrowString& Append(const NoThrowString& strSrc);

        /// <summary>Append a specified string to an existing NoThrowString</summary>
        NoThrowString& Append(_In_z_ const wchar_t* pszSrc);

        /// <summary>Append a given character to this string</summary>
        NoThrowString& Append(wchar_t ch);

        /// <summary>Append a given character to this string</summary>
        NoThrowString& Append(char ch);

        /// <summary>Appends formatted data to an existing string</summary>
        NoThrowString& AppendFormat(_In_z_ _Printf_format_string_ const wchar_t* pszFormat, ...);

        /// <summary>Appends formatted data to an existing string</summary>
        /// <param name="pszFormat"> </param>
        /// <param name="args"> </param>
        NoThrowString& AppendFormatV(_In_z_ _Printf_format_string_ const wchar_t* pszFormat, va_list args);

        /// <summary>Compares two strings (case sensitive)</summary>
        int Compare(_In_z_ const wchar_t* pszCompare) const;

        /// <summary>Compares two strings (case insensitive).</summary>
        int CompareNoCase(_In_z_ const wchar_t* pszCompare) const;

        /// <summary>Copies the requested number of characters from the specified wchar_t*.  Allocates more space if necessary.</summary>
        void Copy(_In_reads_or_z_(count) const wchar_t* pszSrc, int count);

        /// <summary>Deletes a character or characters from a string</summary>
        int Delete(int index, int count = 1);

        /// <summary>Empties the string</summary>
        void Empty();

        /// <summary>Searches the string for the first match of the specified character</summary>
        int Find(wchar_t ch) const;

        /// <summary>Searches the string for the first match of the specified character</summary>
        int Find(wchar_t ch, int start) const;

        /// <summary>Searches the string for the first match of the specified substring</summary>
        int Find(_In_z_ const wchar_t* pszSub) const;

        /// <summary>Searches the string for the first match of the specified substring</summary>
        int Find(_In_z_ const wchar_t* pszSub, int start) const;

        /// <summary>Formats the string as swprintf does</summary>
        NoThrowString& Format(_In_z_ _Printf_format_string_ const wchar_t* pszFormat, ...);

        /// <summary>Formats the string as swprintf does</summary>
        /// <param name="pszFormat"> </param>
        /// <param name="args"> </param>
        NoThrowString& FormatV(_In_z_ _Printf_format_string_ const wchar_t* pszFormat, va_list args);

        /// <summary>Frees any extra memory previously allocated by the string but no longer needed</summary>
        void FreeExtra();

        /// <summary>Returns the count of characters in the string</summary>
        int GetLength() const;

        /// <summary>Inserts a single character at the given index within the string</summary>
        int Insert(int index, wchar_t ch);

        /// <summary>Inserts a substring at the given index within the string</summary>
        int Insert(int index, _In_z_ const wchar_t* psz);

        /// <summary>Returns whether or not the string is empty</summary>
        bool IsEmpty() const;

        /// <summary>Returns a non-const pointer to the underlying string buffer.  If you write to the buffer using this pointer, be sure to call ReleaseBuffer when finished.</summary>
        unsigned short* GetBuffer();

        /// <summary>Returns a pointer to the internal character buffer for the NoThrowString object, truncating or growing its length if necessary to exactly match the length specified in Length</summary>
        _Ret_writes_maybenull_(length + 1) unsigned short* GetBufferSetLength(int length);

        /// <summary>Call this method to reallocate or free up the buffer of the string object, If you know that the string in the buffer is null terminated, you can omit the newLength argument. If your string is not null terminated, use newLength to specify its length. NOTE: The address returned by GetBuffer is invalid after the call to ReleaseBuffer </summary>
        void ReleaseBuffer(int newLength = -1);

        /// <summary>Extracts the first (leftmost) count characters from the string</summary>
        NoThrowString Left(int count) const;

        /// <summary>Extracts a substring of length count characters, starting at position first </summary>
        NoThrowString Mid(int first, int count) const;

        /// <summary>Extracts a substring of length count characters, starting at position first </summary>
        NoThrowString Mid(int first) const;

        /// <summary>Removes instances of the specified character from the string</summary>
        int Remove(wchar_t removeChar);

        /// <summary>Replaces all instances of one character with another</summary>
        int Replace(wchar_t oldChar, wchar_t newChar);

        /// <summary>Replaces all instances of one substring with another</summary>
        int Replace(_In_z_ const wchar_t* pszOld, _In_z_ const wchar_t* pszNew);

        /// <summary>Reverses the order of characters in the string</summary>
        void Reverse();

        /// <summary>Searches for a character inside a larger string; starts at the end of the string</summary>
        int ReverseFind(wchar_t ch) const;

        /// <summary>Extracts the last (rightmost) count characters from the string </summary>
        NoThrowString Right(int count) const;

        /// <summary>Converts all the characters in this string to lower-case </summary>
        NoThrowString& ToLower();

        /// <summary>Converts all the characters in this string to upper-case </summary>
        NoThrowString& ToUpper();

        /// <summary>Trims all leading and trailing whitespace, new line, tab and space characters from the string</summary>
        void Trim();

        /// <summary>Trims all leading and trailing whitespace, new line, tab and space characters from the left portion of the string</summary>
        void TrimLeft();

        /// <summary>Trims all leading and trailing whitespace, new line, tab and space characters from the right portion of the string</summary>
        void TrimRight();

        /// <summary>Returns whether or not the string contents are still valid.  This method should be called after any non-const NoThrowString member functions are called in order to check for validity of string contents.</summary>
        bool IsValid() const;

        /// <summary>Returns the last error encountered by the NoThrowString class</summary>
        HRESULT GetLastHResult() const;

        // Returns whether or not the specified const wchar_t* is null or an empty string
        static bool WEXCOMMON_STDCALL IsNullOrEmpty(const wchar_t* psz)
        {
            return !psz || !*psz || *psz == L'\0';
        }

        // unsigned short exports
        #if defined(WEXCOMMON_FULL_BUILD)
        operator const unsigned short*() const;

        NoThrowString(_In_opt_z_ unsigned short* psz);
        NoThrowString(_In_reads_or_z_opt_(count) const unsigned short* psz, int count); // Constructs a String object, and copies the requested number of characters from the specified wchar_t*
        NoThrowString(_In_opt_z_ const unsigned short* psz);

        const NoThrowString& operator =(unsigned short ch);
        const NoThrowString& operator =(_In_opt_z_ const unsigned short* psz);

        const NoThrowString& operator +=(unsigned short ch);
        const NoThrowString& operator +=(_In_z_ const unsigned short* psz);

        const unsigned short* ToCStrWithFallbackTo(_In_z_ const unsigned short* pszDefaultString) const;
        NoThrowString& Append(_In_z_ const unsigned short* pszSrc);
        NoThrowString& Append(unsigned short ch);
        NoThrowString& AppendFormat(_In_z_ _Printf_format_string_ const unsigned short* pszFormat, ...);
        NoThrowString& AppendFormatV(_In_z_ _Printf_format_string_ const unsigned short* pszFormat, va_list args);
        int Compare(_In_z_ const unsigned short* pszCompare) const;
        int CompareNoCase(_In_z_ const unsigned short* pszCompare) const;
        void Copy(_In_reads_or_z_(count) const unsigned short* pszSrc, int count);
        int Find(unsigned short ch) const;
        int Find(unsigned short ch, int start) const;
        int Find(_In_z_ const unsigned short* pszSub) const;
        int Find(_In_z_ const unsigned short* pszSub, int start) const;
        NoThrowString& Format(_In_z_ _Printf_format_string_ const unsigned short* pszFormat, ...);
        NoThrowString& FormatV(_In_z_ _Printf_format_string_ const unsigned short* pszFormat, va_list args);
        int Insert(int index, unsigned short ch);
        int Insert(int index, _In_z_ const unsigned short* psz);
        int Remove(unsigned short removeChar);
        int Replace(unsigned short oldChar, unsigned short newChar);
        int Replace(_In_z_ const unsigned short* pszOld, _In_z_ const unsigned short* pszNew);
        int ReverseFind(unsigned short ch) const;

        static bool WEXCOMMON_STDCALL IsNullOrEmpty(const unsigned short* psz)
        {
            return IsNullOrEmpty(reinterpret_cast<const wchar_t*>(psz));
        }
        #endif // WEXCOMMON_FULL_BUILD

    private:
        explicit NoThrowString(HRESULT hr);

        friend WEXCOMMON_API int WEXCOMMON_STDCALL GetBufferLength(const NoThrowString& string);
        friend WEXCOMMON_API void WEXCOMMON_STDCALL swap(NoThrowString& str1, NoThrowString& str2);

        // m_pReserved is not currently used. It exists to ensure the class has the size expected by code built against older TAEF headers.
        void* m_pReserved;
        HRESULT m_lastHr;
        wchar_t* m_psz;
    };

    WEXCOMMON_API int WEXCOMMON_STDCALL GetBufferLength(const NoThrowString& string);

    WEXCOMMON_API bool WEXCOMMON_STDCALL operator==(const NoThrowString& str1, const NoThrowString& str2);

    WEXCOMMON_API bool WEXCOMMON_STDCALL operator==(const NoThrowString& str, _In_z_ const wchar_t* psz);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator==(_In_z_ const wchar_t* psz, const NoThrowString& str);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator!=(const NoThrowString& str1, const NoThrowString& str2);

    WEXCOMMON_API bool WEXCOMMON_STDCALL operator!=(const NoThrowString& str, _In_z_ const wchar_t* psz);

    WEXCOMMON_API bool WEXCOMMON_STDCALL operator!=(_In_z_ const wchar_t* psz, const NoThrowString& str);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<(const NoThrowString& str1, const NoThrowString& str2);

    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<(const NoThrowString& str, _In_z_ const wchar_t* psz);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<(_In_z_ const wchar_t* psz, const NoThrowString& str);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>(const NoThrowString& str1, const NoThrowString& str2);

    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>(const NoThrowString& str, _In_z_ const wchar_t* psz);

    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>(_In_z_ const wchar_t* psz, const NoThrowString& str);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<=(const NoThrowString& str1, const NoThrowString& str2);

    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<=(const NoThrowString& str, _In_z_ const wchar_t* psz);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<=(_In_z_ const wchar_t* psz, const NoThrowString& str);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>=(const NoThrowString& str1, const NoThrowString& str2);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>=(const NoThrowString& str, _In_z_ const wchar_t* psz);
    
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>=(_In_z_ const wchar_t* psz, const NoThrowString& str);


    // Concatenation
    /// <summary> </summary>
    /// <param name="str1"> </param>
    /// <param name="str2"> </param>
    WEXCOMMON_API NoThrowString WEXCOMMON_STDCALL operator+(NoThrowString str1, const NoThrowString& str2);

    /// <summary> </summary>
    /// <param name="ch"> </param>
    WEXCOMMON_API NoThrowString WEXCOMMON_STDCALL operator+(NoThrowString str, wchar_t ch);

    /// <summary> </summary>
    /// <param name="ch"> </param>
    /// <param name="str"> </param>
    WEXCOMMON_API NoThrowString WEXCOMMON_STDCALL operator+(wchar_t ch, const NoThrowString& str);

    /// <summary> </summary>
    /// <param name="str"> </param>
    /// <param name="ch"> </param>
    WEXCOMMON_API NoThrowString WEXCOMMON_STDCALL operator+(NoThrowString str, char ch);

    /// <summary> </summary>
    /// <param name="ch"> </param>
    /// <param name="str"> </param>
    WEXCOMMON_API NoThrowString WEXCOMMON_STDCALL operator+(char ch, const NoThrowString& str);

    /// <summary> </summary>
    /// <param name="str"> </param>
    /// <param name="lpsz"> </param>
    WEXCOMMON_API NoThrowString WEXCOMMON_STDCALL operator+(NoThrowString str, _In_z_ const wchar_t* lpsz);

    /// <summary> </summary>
    /// <param name="psz"> </param>
    /// <param name="str"> </param>
    WEXCOMMON_API NoThrowString WEXCOMMON_STDCALL operator+(_In_z_ const wchar_t* psz, const NoThrowString& str);

    // unsigned short exports
    #if defined(WEXCOMMON_FULL_BUILD)
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator==(const NoThrowString& str, _In_z_ const unsigned short* psz);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator==(_In_z_ const unsigned short* psz, const NoThrowString& str);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator!=(const NoThrowString& str, _In_z_ const unsigned short* psz);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator!=(_In_z_ const unsigned short* psz, const NoThrowString& str);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<(const NoThrowString& str, _In_z_ const unsigned short* psz);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<(_In_z_ const unsigned short* psz, const NoThrowString& str);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>(const NoThrowString& str, _In_z_ const unsigned short* psz);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>(_In_z_ const unsigned short* psz, const NoThrowString& str);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<=(const NoThrowString& str, _In_z_ const unsigned short* psz);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator<=(_In_z_ const unsigned short* psz, const NoThrowString& str);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>=(const NoThrowString& str, _In_z_ const unsigned short* psz);
    WEXCOMMON_API bool WEXCOMMON_STDCALL operator>=(_In_z_ const unsigned short* psz, const NoThrowString& str);
    WEXCOMMON_API NoThrowString WEXCOMMON_STDCALL operator+(NoThrowString str, unsigned short ch);
    WEXCOMMON_API NoThrowString WEXCOMMON_STDCALL operator+(unsigned short ch, const NoThrowString& str);
    WEXCOMMON_API NoThrowString WEXCOMMON_STDCALL operator+(NoThrowString str, _In_z_ const unsigned short* lpsz);
    WEXCOMMON_API NoThrowString WEXCOMMON_STDCALL operator+(_In_z_ const unsigned short* psz, const NoThrowString& str);
    #endif

    WEXCOMMON_API void WEXCOMMON_STDCALL swap(NoThrowString& str1, NoThrowString& str2);
} /* namespace Common */ } /* namespace WEX */
#endif // #if !defined(__WEXSTRING_H__) && defined(_WIN32)