PMString.h

//========================================================================================
// 
// $File$
// 
// Owner: EricM
// 
// $Author$
// 
// $DateTime$
// 
// $Revision$
// 
// $Change$
// 
// Copyright 1997-2010 Adobe Systems Incorporated. All rights reserved.
// 
// NOTICE: Adobe permits you to use, modify, and distribute this file in accordance 
// with the terms of the Adobe license agreement accompanying it. If you have received
// this file from a source other than Adobe, then your use, modification, or 
// distribution of it requires the prior written permission of Adobe.
// 
//========================================================================================

#ifndef __PMSTRING__
#define __PMSTRING__

#include "K2Debugging.h"
#include "K2TypeTraits.h"
#include "PMTypes.h"
#include "UnicodeSavvyString.h"
#include <string>
#include <adobe/move.hpp>
#include <adobe/typeinfo.hpp>

class IPMStream;
class PMLocaleId;
class WideString;

#include "PlatformChar.h"
#include "Invariant.h"

// API's with DEPRECATED_PLATFORM_BUFFER will be removed in the 
// future. 
#define DEPRECATED_PLATFORM_BUFFER 1

class PMString : public UnicodeSavvyString
{
 public:
 typedef object_type data_type;

 enum TranslateDuringCall
 {
 kDontTranslateDuringCall,
 kTranslateDuringCall
 };

 //----------Constructors-----------------
 
 PMString();

 PMString(ConstCString key, TranslateDuringCall translate = kDontTranslateDuringCall);

 PMString(const UTF16TextChar * string, int32 nDblBytes);

 explicit PMString(const wchar_t* s);
 
 PMString(const wchar_t* s, size_t len);

 PMString(adobe::move_from<PMString> other)
 : UnicodeSavvyString(adobe::move_from<UnicodeSavvyString>(other.source)),
 fEncoding(other.source.fEncoding),
 fShouldTranslate(other.source.fShouldTranslate), fHasTranslated(other.source.fHasTranslated)
#if defined(DEBUG) 
 ,fFormatNumber(other.source.fFormatNumber)
#endif 
 {
 }

 PMString(PMString &&other) noexcept
 : UnicodeSavvyString(std::move(other)),
 fEncoding(other.fEncoding),
 fShouldTranslate(other.fShouldTranslate), fHasTranslated(other.fHasTranslated)
#if defined(DEBUG) 
 , fFormatNumber(other.fFormatNumber)
#endif 
 {
 }

 PMString(const PMString& s);
 PMString(const WideString& s);
 ~PMString();


 //----------GET/SET STRING Routines-----------------
 
 void SetString(const PMString& s);

 void SetKey(ConstCString key, TranslateDuringCall translate = kDontTranslateDuringCall);
 
 //----------GET/SET UNICODE STRING Routines-----------------
 
 void GetWChar_tString(wchar_t *wchar_tString, int32 bufferSize) const;


 void SetXString(const UTF16TextChar* x, int32 nDblBytes);
 
 // Discriminator for wchar_t size
 template<int bytes>
 struct wchar_size{};
 
 inline PMString& assign(const wchar_t* s, size_t len)
 {
 fShouldTranslate = kFalse;
 fHasTranslated = kFalse;
 return assign_impl(s, len, wchar_size<sizeof(wchar_t)>());
 }

#if 0// routine defined in UnicodeSavvyString.h included here for reference

 const UTF16TextChar * GrabUTF16Buffer(int32 *numUTF16s) const;

 int32 NumUTF16TextChars() const;
#endif

 std::string GetUTF8String() const;

 void SetUTF8String(const std::string &utf8String);

 //----------GET/SET OS STRING Routines-----------------

#ifdef MACINTOSH

 CFStringRef CreateCFString() const;

 void SetCFString(CFStringRef cfstring);
#endif

#ifdef WINDOWS

 TCHAR* GrabTString(void)
 { return (TCHAR*)UnicodeSavvyString::GrabUTF16Buffer(nil); }

 const TCHAR* GrabTString(void) const
 { return (const TCHAR*)UnicodeSavvyString::GrabUTF16Buffer(nil); }

 void SetTString(const TCHAR* x);

 uint32 GetTLength() const;
#endif


 //---------CHARACTER LEVEL ROUTINES-----------------

 // NOTE: Routines with a "W" in the name imply the operation occurs on the Unicode representation
 // of the string.
 // Using the Unicode version is recommended.

 UTF32TextChar GetWChar(int32 pos) const;


 //---------BASIC STRING ROUTINES-----------------

 // basic string routines, clear, length, etc.

#if 0// routine defined in UnicodeSavvyString.h included here for reference

 size_type CharCount() const;
#endif

 int32 WCharLength(void) const;

 bool16 empty() const;
 
 void clear();

 //---------APPEND ROUTINES-----------------

 void Append(const PMString &s, CharCounter nCharacters = kMaxInt32);

 void Append(const WideString& s);

 void AppendW(const UTF16TextChar * ws, int32 nDblBytes = kMaxInt32);

 void AppendW(UTF32TextChar wc);

 void append(const wchar_t *s);


 //---------INSERT ROUTINES-----------------

 void Insert(const PMString &s, CharCounter pos = 0, CharCounter nCharacters = kMaxInt32);

 void InsertW(const UTF16TextChar *ws, int32 nDblBytes = kMaxInt32, int32 pos = 0);

 void InsertW(UTF32TextChar wc, int32 pos = 0);


 //---------PARSE ROUTINES-----------------

 PMString* Substring(CharCounter pos, CharCounter count = kMaxInt32) const;

 PMString* GetItem(const PMString& delimiter, const int32 nItem) const;

 void Remove(CharCounter pos, CharCounter count = 1); 

 void Truncate(CharCounter count = 1); 

 
 typedef enum {
 kLeadingWhiteSpace = 0,
 kTrailingWhiteSpace,
 kLeadingAndTrailingWhiteSpace,
 kAllWhiteSpace
 } WhitespaceType; 

 void StripWhiteSpace(WhitespaceType wsType = kAllWhiteSpace);

 CharCounter IndexOfString(const PMString& keyString, CharCounter pos = 0) const;

 CharCounter LastIndexOfString(const PMString& keyString) const;

 CharCounter IndexOfWChar(UTF32TextChar wc, int32 pos = 0) const;

 CharCounter LastIndexOfWChar(UTF32TextChar wc) const;

 bool16 Contains(const PMString& searchString, CharCounter pos = 0) const;

 bool16 BeginsWith(const PMString& searchString, CharCounter pos = 0) const;

 bool16 ParseForEmbeddedCharacters();

 
 //----------Compare Routines---------------

 int32 Compare(bool16 casesensitive, const PMString &s) const;

 bool16 IsEqual(const PMString &s, bool8 casesensitive = kTrue, bool8 limitCompareToShorterLength = kFalse) const;
 
 
 //----------OPERATORS---------------
 
 bool16 operator == (const PMString &s) const;

 bool16 operator == (ConstCString key) const;

 bool16 operator != (const PMString &s) const;
 
 bool16 operator < (const PMString &s) const;

 bool16 operator > (const PMString &s) const;

 bool16 operator <= (const PMString &s) const;

 bool16 operator >= (const PMString &s) const;

 PMString& operator+=(const PMString& s);

 friend PMString operator+(const PMString& s1, const PMString& s2);


 friend void swap( PMString& left, PMString& right ) noexcept;

 inline PMString& operator=(const PMString &other)
 {
 if (&other != this)
 SetString(other);
 return *this;
 }

 inline PMString& operator=(PMString &&other) noexcept
 {
 swap(*this, other);
 return *this;
 }

 //---------------MISC ROUTINES------------------------
 
 uint32 Hash(void) const;

 void AppendNumber(int32 i);

 void AppendNumber(const PMReal& r,int32 digitsPrecision = -1, bool16 round = kFalse, bool16 eliminateTrailingZeros = kFalse);

 void AsNumber(int32 i);

 void AsNumber(const PMReal& r,int32 digitsPrecision = -1, bool16 round = kFalse, bool16 eliminateTrailingZeros = kFalse);

 void AppendFixed(Fixed f)
 { AppendNumber( PMReal((double)(f/(double)65536.0))); }

 void AsFixed(Fixed f)
 { AsNumber( PMReal((double)(f / (double)65536.0))); }

 typedef enum {
 kNoError = 0,
 kNoNumber,
 kNotJustNumber
 } ConversionError; 
 int32 GetAsNumber( ConversionError *pError = nil, CharCounter *lenNotConverted = nil ) const;

 double GetAsDouble( ConversionError *pError = nil, CharCounter *lenNotConverted = nil ) const;

 void ToUpper(void);

 void ToLower(void);


 //----------READ/WRITE ROUTINES---------------

 void ReadWrite(IPMStream *s);
 
 void ReadWriteKey(IPMStream *s); 

 typedef enum { 
 kPlatformEncodingWin, 
 kPlatformEncodingMac,
 kPlatformEncodingOther,
 kUTF8Encoding
 } StringPlatformEncoding;
 void ReadPlatformWriteUnicode(IPMStream *s, PMString::StringPlatformEncoding encoding = kPlatformEncodingOther, bool16 includeBools = kTrue);


 //----------TRANSLATE ROUTINES---------------

 bool16 Translate(const PMLocaleId& locale);

 bool16 Translate();

 //----------DISCOURAGED TRANSLATE ROUTINES---------------
 // DISCOURAGED.
 // As much as possible do not use these routines. If the usage does not need translation
 // consider using WideString.

 bool16 IsTranslatable() const;

 PMString& SetTranslatable(bool16 shouldTranslate); 

 bool16 HasTranslated() const;

 void SetTranslated();


 //----------PLATFORM STRING Routines-----------------
 // DISCOURAGED
 // PMString using Unicode internally so as much as possible restrict the use of 
 // platform string calls
 
 enum StringEncoding
 { 
 kEncodingASCII,
 kEncodingShiftJIS,
 kEncodingChineseBig5,
 kEncodingKorean,
 kEncodingArabic,
 kEncodingHebrew,
 kEncodingGreek, 
 kEncodingCyrillic,
 kEncodingThai = 21,
 kEncodingChineseGBK = 25,
 kEncodingEastEuropean = 29,
 kEncodingVietnamese,
 
 kUnknownEncoding = -1
 };

 PMString(ConstCString string, PMString::StringEncoding encoding);

 void SetPString(ConstPString p, PMString::StringEncoding encoding);

 void SetCString(ConstCString C, PMString::StringEncoding encoding);
 
 void SetXString(const char* x, int32 nBytes, PMString::StringEncoding encoding = kUnknownEncoding);

 void GetPString(PString p, int32 bufferSize, PMString::StringEncoding encoding = kUnknownEncoding) const;

 void GetCString(CString C, int32 bufferSize, PMString::StringEncoding encoding = kUnknownEncoding) const;

 std::string GetPlatformString(PMString::StringEncoding encoding = kUnknownEncoding) const;

 void Insert(const char* ps, int32 nBytes = kMaxInt32, CharCounter pos = 0, PMString::StringEncoding encoding = kUnknownEncoding);

 void Insert(char pc, CharCounter pos = 0, PMString::StringEncoding encoding = kUnknownEncoding);

 void Insert(const PlatformChar &pc, CharCounter pos = 0);

 void Append(const char* ps, int32 nBytes = kMaxInt32, PMString::StringEncoding encoding = kUnknownEncoding);

 void Append(char pc, PMString::StringEncoding encoding = kUnknownEncoding);

 void Append(const PlatformChar &pc);

 const PlatformChar operator[](CharCounter index) const; // based on new multibyte safe GetChar()

 const PlatformChar GetChar(CharCounter pos, PMString::StringEncoding encoding = kUnknownEncoding) const;
 
 CharCounter IndexOfCharacter(const PlatformChar &pc, CharCounter pos = 0) const;

 CharCounter LastIndexOfCharacter(const PlatformChar &pc) const;


 //----------NOT RECOMMENDED. All these APIs should not be used---------------
 //API's at top are the least recommend. Please remove them first.

#ifdef DEPRECATED_PLATFORM_BUFFER

 uint8 GetScript() const;

 void SetScript(uint8 script);

 PMString::StringEncoding GetEncoding() const;

 void SetEncoding(PMString::StringEncoding encoding);

 const UTF16TextChar* GrabWString(void) const;

 void SetCString(ConstCString C);

 bool16 IsNull(void) const;

 bool16 IsEmpty() const;

 void Clear(void)
 {
 PMString::clear();
 }
#endif

 protected:

 void AssignToPlatformBuffer(ConstCString src, int32 lengthInBytes);

#ifdef DEBUG 
 mutable InvariantCount fInvariant;
public:
 void Invariant() const;
#endif
 private:
 int32 CountChars() const;

 void SetUTF16Buffer(const char* x, int32 nBytes, PMString::StringEncoding encoding);

 int32 GetPlatformBuffer(char *buffer, int32 bufferSize, PMString::StringEncoding encoding) const;
 void ReadUnicode(IPMStream *s);
 void WriteUnicode(IPMStream *s);
 
 inline PMString& assign_impl(const wchar_t* s, size_t len, wchar_size<2>)
 { 
 SetXString(reinterpret_cast<const UTF16TextChar*>(s), static_cast<int32>(len));
 return *this;
 }
 
 PMString& assign_impl(const wchar_t* s, size_t len, wchar_size<4>);

 inline PMString& append_dispatch(const wchar_t* s, size_t len)
 {
 return append_impl(s, len, wchar_size<sizeof(wchar_t)>());
 }

 inline PMString& append_impl(const wchar_t* s, size_t len, wchar_size<2>)
 { 
 AppendW(reinterpret_cast<const UTF16TextChar*>(s), static_cast<int32>(len));
 return *this;
 }
 
 PMString& append_impl(const wchar_t* s, size_t len, wchar_size<4>);

 StringEncoding fEncoding;
 bool16 fShouldTranslate;
 bool16 fHasTranslated;

public:
#if defined(DEBUG)
 uchar fFormatNumber;
#endif
};

extern const PMString kNullString;


// Friend functions ---

inline PMString operator+(const PMString& s1, const PMString& s2)
{
 PMString result(s1);
 result.Append(s2);
 return result;
}

inline void swap( PMString& left, PMString& right ) noexcept
{
 // Base class swap
 swap(static_cast<UnicodeSavvyString&>(left), static_cast<UnicodeSavvyString&>(right));

 std::swap(left.fEncoding, right.fEncoding);
 std::swap(left.fShouldTranslate, right.fShouldTranslate);
 std::swap(left.fHasTranslated, right.fHasTranslated);
#if defined(DEBUG) 
 std::swap(left.fFormatNumber, right.fFormatNumber);
#endif
}

// specialize adobe::type_info<> to avoid typeid problems across DLL boundaries
ADOBE_NAME_TYPE_0("pmstring:indesign:adobe",PMString);
#endif