#include <PMString.h>

Inheritance diagram for PMString:

Classes
struct	wchar_size

Public Types
enum	TranslateDuringCall { kDontTranslateDuringCall, kTranslateDuringCall }

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

enum	ConversionError { kNoError = 0, kNoNumber, kNotJustNumber }

enum	StringPlatformEncoding { kPlatformEncodingWin, kPlatformEncodingMac, kPlatformEncodingOther, kUTF8Encoding }

enum	StringEncoding { kEncodingASCII, kEncodingShiftJIS, kEncodingChineseBig5, kEncodingKorean, kEncodingArabic, kEncodingHebrew, kEncodingGreek, kEncodingCyrillic, kEncodingThai = 21, kEncodingChineseGBK = 25, kEncodingEastEuropean = 29, kEncodingVietnamese, kUnknownEncoding = -1 }

typedef object_type	data_type

Public Types inherited from UnicodeSavvyString
typedef int32	size_type

typedef std::ptrdiff_t	difference_type

typedef UTF16TextChar	code_value

typedef UTF32TextChar	code_point

typedef code_value *	code_value_iterator

typedef code_value const *	const_code_value_iterator

typedef const UnicodeSavvyString &	const_reference

typedef UTF16TextChar	value_type

Public Member Functions
	PMString (ConstCString key, TranslateDuringCall translate=kDontTranslateDuringCall)

	PMString (const UTF16TextChar *string, int32 nDblBytes)

	PMString (const wchar_t *s)

	PMString (const wchar_t *s, size_t len)

	PMString (adobe::move_from< PMString > other)

	PMString (PMString &&other) noexcept

	PMString (const PMString &s)

	PMString (const WideString &s)

void	SetString (const PMString &s)

void	SetKey (ConstCString key, TranslateDuringCall translate=kDontTranslateDuringCall)

void	GetWChar_tString (wchar_t *wchar_tString, int32 bufferSize) const

void	SetXString (const UTF16TextChar *x, int32 nDblBytes)

PMString &	assign (const wchar_t *s, size_t len)

std::string	GetUTF8String () const

void	SetUTF8String (const std::string &utf8String)

UTF32TextChar	GetWChar (int32 pos) const

int32	WCharLength (void) const

bool16	empty () const

void	clear ()

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)

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)

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)

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 ()

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

bool16	IsEqual (const PMString &s, bool8 casesensitive=kTrue, bool8 limitCompareToShorterLength=kFalse) const

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)

PMString &	operator= (const PMString &other)

PMString &	operator= (PMString &&other) noexcept

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)

void	AsFixed (Fixed f)

int32	GetAsNumber (ConversionError pError=nil, CharCounter lenNotConverted=nil) const

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

void	ToUpper (void)

void	ToLower (void)

void	ReadWrite (IPMStream *s)

void	ReadWriteKey (IPMStream *s)

void	ReadPlatformWriteUnicode (IPMStream *s, PMString::StringPlatformEncoding encoding=kPlatformEncodingOther, bool16 includeBools=kTrue)

bool16	Translate (const PMLocaleId &locale)

bool16	Translate ()

bool16	IsTranslatable () const

PMString &	SetTranslatable (bool16 shouldTranslate)

bool16	HasTranslated () const

void	SetTranslated ()

	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

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

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)

Public Member Functions inherited from UnicodeSavvyString
bool16	HasMultiWordUnicode () const

size_type	CharCount () const

size_type	NumUTF16TextChars () const

size_type	capacity (void) const

void	reserve (size_type newCapacity)

void	resize (size_type newSize, code_value fill=code_value())

void	clear ()

const UTF16TextChar *	GrabUTF16Buffer (int32 *numUTF16s) const

int32	CodePointIndexToUTF16Index (int32 index) const

void	Truncate (CharCounter count)

void	Remove (int32 position, CharCounter count)

UTF32TextChar	GetUTF32TextChar (int32 pos) const

const_code_value_iterator	begin () const

const_code_value_iterator	end () const

Protected Member Functions
void	AssignToPlatformBuffer (ConstCString src, int32 lengthInBytes)

Protected Member Functions inherited from UnicodeSavvyString
	UnicodeSavvyString (adobe::move_from< UnicodeSavvyString > other)

	UnicodeSavvyString (UnicodeSavvyString &&other) noexcept

void	move_from (UnicodeSavvyString &other) noexcept

template<class IteratorType >
	UnicodeSavvyString (IteratorType b, IteratorType e, size_type nCodePoints=0)

int32	CountChars () const

int32	CountCharsUtil (const UTF16TextChar *buffer, int32 bufferLength) const

void	InsertGap (uint32 wordWiseIndex, size_type numberOfSpaces)

void	RemoveGap (uint32 wordWiseIndex, size_type numberOfSpaces)

void	InsertUTF32TextChar (UTF32TextChar c, int32 pos=0)

void	InsertUTF16String (const UTF16TextChar *buf, int32 len, int32 position=0)

void	AppendUTF32TextChar (UTF32TextChar c32)

void	CopyFrom (const UnicodeSavvyString &other)

bool16	operator== (const UnicodeSavvyString &s) const

template<class IteratorType >
UnicodeSavvyString &	assign (IteratorType b, IteratorType e, size_type nCodePoints=0)

UnicodeSavvyString &	replace (size_type pos, size_type n1, code_value const *s, size_type n2)

UnicodeSavvyString &	append (code_value const *s, size_type nCodeValues, size_type nCodePoints=0)

UTF32TextChar	surro_GetUTF32TextChar (int32 pos) const

const UTF16TextChar *	ConstBuffer () const

void	insert_safe (code_value_iterator i, const_code_value_iterator sb, const_code_value_iterator se)

void	erase_safe (code_value_iterator b, code_value_iterator e)

void	replace_safe (code_value_iterator b, code_value_iterator e, const_code_value_iterator sb, const_code_value_iterator se)

template<class InputIterator >
void	assign_impl (InputIterator b, InputIterator e, size_type nCodePoints, std::input_iterator_tag)

template<class FwdIterator >
void	assign_impl (FwdIterator b, FwdIterator e, size_type nCodePoints, std::forward_iterator_tag)

bool16	UnicodeBufferIsValid () const

UTF16TextChar *	GetBufferForWriting (size_type size)

Friends
PMString	operator+ (const PMString &s1, const PMString &s2)

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

Additional Inherited Members
Protected Types inherited from UnicodeSavvyString
enum	{ kMaxSmallString = 23 }

Protected Attributes inherited from UnicodeSavvyString
StringStorage *	fStorage

UTF16TextChar	fSmallStorage [kMaxSmallString+1]

size_type	fUTF16BufferLength

size_type	fNumChars

Detailed Description

PMString is used for strings that show in the UI. Given a key then calling Translate will lookup the translation for the key for the current UI locale. This class should not be used for strings that are not in the UI. Please use WideString for strings that do not need to be translated.

Member Enumeration Documentation

enum PMString::ConversionError

Error in converting string to number

See Also: GetAsNumber and GetAsDouble

Enumerator
kNoError	No Error.
kNoNumber	String has no number.
kNotJustNumber	String has more than just number.

enum PMString::StringEncoding

What kind of encoding to use to represent the platform string as. These are platform specific. If running on mac this is mac encoding. On windows it is windows encoding. You should persist Unicode if you want to take data cross platform. Comments for encoding list Macintosh script first than Windows codepage.

See Also: SetEncoding

Enumerator
kEncodingASCII	smRoman, Codepage 1252
kEncodingShiftJIS	smJapanese, Codepage 932
kEncodingChineseBig5	smTradChinese, Codepage 950
kEncodingKorean	smKorean, Codepage 949
kEncodingArabic	smArabic, Codepage 1256
kEncodingHebrew	smHebrew, Codepage 1255
kEncodingGreek	smGreek, Codepage 1253
kEncodingCyrillic	smCyrillic, Codepage 1251
kEncodingThai	smThai, Codepage 874
kEncodingChineseGBK	smSimpChinese, Codepage 936
kEncodingEastEuropean	smCentralEuroRoman, Codepage 1250
kEncodingVietnamese	smVietnamese, Codepage 1258

enum PMString::StringPlatformEncoding

What kind of encoding to use to convert to unicode

See Also: ReadPlatformWriteUnicode

Enumerator
kPlatformEncodingWin	Roman windows encoding
kPlatformEncodingMac	Roman mac encoding
kPlatformEncodingOther	All other platform encodings (uses String encoding to convert)
kUTF8Encoding	UTF8 encoding

enum PMString::TranslateDuringCall

Specify whether to translate during call

See Also: SetKey and Constructor

Enumerator
kDontTranslateDuringCall	Keep as key string. calling Translate will give translation.
kTranslateDuringCall	Translate during call

enum PMString::WhitespaceType

What kind of white space to strip

See Also: StripWhiteSpace

Enumerator
kLeadingWhiteSpace	Strip white space in the beginning of string
kTrailingWhiteSpace	Strip white space at the end of string
kLeadingAndTrailingWhiteSpace	Strip both white space at end and beginning of string
kAllWhiteSpace	Strip all white space

Constructor & Destructor Documentation

PMString::PMString	(	ConstCString	key,
		TranslateDuringCall	translate = `kDontTranslateDuringCall`
	)

Constuctor Construct PMString using a ascii key. Caller is responsible for the memory of ConstCString key. Keys are the first string of the string pair in a resource StringTable.

Parameters

key	platform C string. Need to be null terminated.
translate	using kTranslateDuringCall will put the translation in the string. The key will be lost.

PMString::PMString	(	const UTF16TextChar *	string,
		int32	nDblBytes
	)

Constuctor

Parameters

string	IN Unicode representation (in UTF-16 encoding) of the string for initialization. This string need not be null-terminated
nDblBytes	IN The number of 16-bit values in the string buffer. This value may be greater than the number of characters represented since UTF-16 can contain surrogate pairs, each of which represents a single character. Composed characters are not supported

PMString::PMString ( const wchar_t * s )

explicit

Constructs from Unicode characters. Allows construction of a PMString from L"" constants. On Windows wchar_t matches UTF16, on the Mac they are UTF32s. NOTE: This should be used to set strings that are not keys. Calling Translate on this string will do nothing. If you want to translate the string use SetKey.

Parameters

s	[IN] - buffer containing wchar_t characters. Needs to be null terminated.

PMString::PMString	(	const wchar_t *	s,
		size_t	len
	)

Constructs from Unicode characters. On Windows wchar_t matches UTF16, on the Mac they are UTF32s. NOTE: This should be used to set strings that are not keys. Calling Translate on this string will do nothing. If you want to translate the string use SetKey.

Parameters

s	[IN] - buffer containing wchar_t characters. Doesn't have to be null terminated since the len parameter is mandatory.
len	[IN] - number of wchar_t's in s to be read.

PMString::PMString ( adobe::move_from< PMString > other )

inline

Movable constructor - assumes ownership of the remote part.

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

Constuctor

Set PMString using a platform string. Same as calling - SetCString(ConstCString C, PMString::StringEncoding encoding) This should be used to set strings that are not keys. Calling Translate on this string will do nothing. If you want to translate use the constructor without encoding - PMString(ConstCString key, TranslateDuringCall translate = kDontTranslateDuringCall);

If it is not a key first consider using WideString. If you are you are using a string you don't want to be the same in all languages consider adding it as a key to the notranslate table.

Parameters

string	C string to set PMString to. Make sure script of passed in C string matchs the script of the PMString.
encoding	The desired script of the platform representation of this string. The default value creates a PMString with the encoding set appropriately for the current operating environment of the operating system: ASCII for English language systems, ShiftJIS for Japanese systems, etc. It is recommended that this parameter be set explicitly, however.

Member Function Documentation

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

Append the first n characters of s onto this string.

Parameters

s	string to append
nCharacters	number of characters in s to append

void PMString::Append ( const WideString & s )

Append a WideString

Parameters

s	WideString to append

void PMString::append ( const wchar_t * s )

Append Unicode characters. Allows appending L"" constants to the PMString. On Windows wchar_t matches UTF16, on the Mac they are UTF32s. This does not change whether the string is translatable or not.

Parameters

s	[IN] - buffer containing wchar_t characters. Needs to be null terminated.

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

Append a series of characters which may have NO or MULTIPLE nul characters. No length checking is performed

Parameters

ps	platform string.
nBytes	number of bytes in ps to append
encoding	encoding of ps

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

Append a platform or ascii character [replaces Append(char c)]

RECOMMENDATION -

If you are appending a hard coded value look for the value in TextChar.h and call AppendW(UTF32TextChar wc).

Parameters

pc	platform character.
encoding	encoding of pc

void PMString::Append ( const PlatformChar & pc )

Append a platform or ascii character [replaces Append(char c)]

Parameters

pc	platform character.

void PMString::AppendFixed ( Fixed f )

inline

Append fixed number as string to existing string.

Parameters

f	fixed to to convert to string and append

void PMString::AppendNumber ( int32 i )

Append number as string to existing string.

Parameters

i	number to convert to string and append to existing string.

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

Append number as string to existing string.

Parameters

r	number to convert to string and append to existing string.
digitsPrecision	how many decimal points to show. -1 means show all
round	if kTrue value is rounded else value is floored. Only used if digitsPrecision is > -1.
eliminateTrailingZeros	if kTrue trailing zeros are not in string

void PMString::AppendW	(	const UTF16TextChar *	ws,
		int32	nDblBytes = `kMaxInt32`
	)

Append a Unicode string

Parameters

ws	string to append
nDblBytes	number of UTF16s to append

void PMString::AppendW ( UTF32TextChar wc )

Append a Unicode character

Parameters

wc	character to append

void PMString::AsFixed ( Fixed f )

inline

Set string to fixed value.

Parameters

f	fixed to convert to string.

void PMString::AsNumber ( int32 i )

Set string to value.

Parameters

i	value to convert to string

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

Set string to value.

Parameters

r	PMReal to convert to string
digitsPrecision	how many decimal points to show. -1 means show all
round	if kTrue value is rounded else value is floored. Only used if digitsPrecision is > -1.
eliminateTrailingZeros	if kTrue trailing zeros are not in string

PMString& PMString::assign	(	const wchar_t *	s,
		size_t	len
	)

inline

Sets the content of the PMString using a non-translatable Unicode string.

The string will be marked as non-translatable.

Parameters

s	Unicode buffer. Does not need to be null terminated as len determines how much it will be read.
len	number of wchar_t in s to be read to set PMString. Do not include count of null terminator.

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

Returns true if string starts with searchString

Parameters

searchString	string to look for
pos	where to start looking.

Returns: bool16 kTrue if string begins with searchString at given pos.

void PMString::clear ( )

Erases the string making it empty. Capacity stays the same.

See Also: reserve, capacity

void PMString::Clear ( void )

inline

To be deprecated. Use clear() instead.

PORTING RECIPE - Call clear().

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

Lexicographically compares strings like strcmp or stricmp, except based on UNICODE values. If both strings are roman encoded then compared based on platform values instead of Unicode.

Parameters

casesensitive	if kTrue use case to compare
s	string to compare to

Returns: int32 0 strings are equal. -1 string < s. 1 string > s

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

Returns true if string contains searchString

Parameters

searchString	string to look for
pos	where to start looking.

Returns: bool16 kTrue if searchString is contained in string

bool16 PMString::empty ( ) const

Number of characters is 0.

Returns: bool16 kTrue if no characters in string

double PMString::GetAsDouble	(	ConversionError *	pError = `nil`,
		CharCounter *	lenNotConverted = `nil`
	)		const

Try to interpert the string as a double.

Parameters

pError	sets to a ConversionError if the entire string cannot be converted.
lenNotConverted	number of characters at the end that were not converted

Returns: double number that string represents

int32 PMString::GetAsNumber	(	ConversionError *	pError = `nil`,
		CharCounter *	lenNotConverted = `nil`
	)		const

Try to interpert the string as a number.

Parameters

pError	sets to a ConversionError if the entire string cannot be converted.
lenNotConverted	number of characters at the end that were not converted

Returns: int32 number that string represents

const PlatformChar PMString::GetChar	(	CharCounter	pos,
		PMString::StringEncoding	encoding = `kUnknownEncoding`
	)		const

returns the platform encoded character (as a PlatformChar) at a specific character offset

Parameters

pos	IN The character position (0-based) of the desired character. Note that embedded characters shown in the format "<1234>" returned from GrabCString() count as a single character, which will be returned as an invalid PlatformChar
encoding	encoding to get character as

Returns: The platform character object at the given position. Note that a PMString may contain 0 characters other than the terminating character. GetChar will return an invalid PlatformChar in this case.

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

Gets a C string. If bufferSize is not big enough the call returns and does not copy anything to the buffer c.

Parameters

C	OUT A pointer to string of bufferSize which will be filled in with the characters of the string represented in GetEncoding() encoding.
bufferSize	IN the size of the provided buffer measured in bytes, including space for the terminating zero.

PMString::StringEncoding PMString::GetEncoding ( ) const

Provide the current encoding of the platform buffer for the string

PORTING RECIPE - Encoding (also known as script) should be obtained when calling a routing that gets a platform string. After the encoding if put at the point of the call this API should be removed.

Returns: An identifier in the enumeration of String Encodings above

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

Returns the specified token/item of a string, given a single delimiter

Parameters

delimiter	IN The string to use as a delimiter
nItem	IN The one based item number for the the desired item

Returns: A pointer to a string you need to deallocate, typically via k2::scoped_ptr. If the item does not exist (i.e. nItem is too low or high) then nil will be returned instead of a valid object.

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

Gets a platform string. Check to make sure the code really wants a plaform encoded string if instead it wants utf8 you can call GetUTF8String

Parameters

encoding encoding for string to return.

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

Get pascal string. If PMString byte length is greater than 255 all bytes will still be copied to the buffer but the lenght byte will be truncated to 255. If bufferSize is not big enough the call returns and does not copy anything to the buffer p.

RECOMMENDATION - See if this API is used for a Macintosh API call see if there is a new version of the API that takes a CFString.

Parameters

p	OUT A pointer to string of bufferSize which will be filled in with the characters of the string represented in GetEncoding() encoding.
bufferSize	IN the size of the provided buffer measured in bytes, including space for the length byte.
encoding	encoding of pascal string.

uint8 PMString::GetScript ( ) const

OBSOLETE. Use GetEncoding instead

PORTING RECIPE - Encoding (also known as script) should be obtained when calling a routing that gets a platform string. After the encoding is put at the point of the call this API should be removed.

Returns: uint8 script of string

std::string PMString::GetUTF8String ( ) const

Gets a std::string encoded as UTF8.

Returns: utf8 encoded string

UTF32TextChar PMString::GetWChar ( int32 pos ) const

returns the double byte textchar at a specific character offset into the Unicode string representation.

Parameters

pos	character offset. O based.

Returns: UTF32TextChar character at index

void PMString::GetWChar_tString	(	wchar_t *	wchar_tString,
		int32	bufferSize
	)		const

Get a null terminated wchar_t string.

Parameters

wchar_tString	OUT returns string as wchar_t string
bufferSize	size of wchar_tString buffer

const UTF16TextChar* PMString::GrabWString ( void ) const

DEPRECATED: Use GrabUTF16Buffer

PORTING RECIPE - Use GrabUTF16Buffer(nil)

Returns: UTF16TextChar*

uint32 PMString::Hash ( void ) const

Provide a binary hash value based on numeric codes

Returns: uint32 hash value

bool16 PMString::HasTranslated ( ) const

String has been translated. Calling Translate will set this to kTrue if IsTranslatable is kTrue and the string length is greater than 0. Also calling SetTranslated will set this to kTrue.

Returns: bool16 kTrue if the string has been translated.

CharCounter PMString::IndexOfCharacter	(	const PlatformChar &	pc,
		CharCounter	pos = `0`
	)		const

This routine looks for a character within this string. pos is the platform character offset (not byte count) to start looking.

Parameters

keyString	string to look for
pos	where to start looking.

Returns: CharCounter The character offset (not byte count) at which the character was found, or -1 when not found

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

This routine looks for a substring within this string. pos is the platform character offset (not byte count) to start looking.

Parameters

keyString	string to look for
pos	where to start looking.

Returns: CharCounter The character offset (not byte count) at which the string was found, or -1 when not found

CharCounter PMString::IndexOfWChar	(	UTF32TextChar	wc,
		int32	pos = `0`
	)		const

Index of Unicode char in Unicode version of string

Parameters

wc	Unicode character to find index for
pos	position to start looking

Returns: CharCounter 0 based index. -1 when not found

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

Insert the first n characters of s into this string. pos is interpreted as a true platform character offset not as a byte offset.

Parameters

s	string to insert
pos	insert at this position. move existing characters to end
nCharacters	how many characters of s to insert. Default kMaxInt32 means insert all characters.

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

Insert a platform string

Parameters

ps	platform string to insert
nBytes	number of bytes to insert. kMaxInt32 means insert ::strlen of ps bytes.
pos	insert at this position. This is a character position not a byte position.
encoding	encoding of ps

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

Insert a platform character

RECOMMENDATION -

If you are appending a hard coded value look for the value in TextChar.h and call InsertW(UTF32TextChar wc).

Parameters

pc	platform character
pos	insert at this position
encoding	encoding of pc

void PMString::Insert	(	const PlatformChar &	pc,
		CharCounter	pos = `0`
	)

Insert a platform character

Parameters

pc	platform character
pos	insert at this position

void PMString::InsertW	(	const UTF16TextChar *	ws,
		int32	nDblBytes = `kMaxInt32`,
		int32	pos = `0`
	)

Insert a Unicode string

Parameters

ws	string to insert
nDblBytes	number of UTF16s to insert
pos	insert at this position

void PMString::InsertW	(	UTF32TextChar	wc,
		int32	pos = `0`
	)

Insert a Unicode character

Parameters

wc	character to insert
pos	insert at this position

bool16 PMString::IsEmpty ( ) const

Number of character is 0. Same as calling empty().

PORTING RECIPE - Call empty().

Returns: bool16 kTrue if no characters in string

bool16 PMString::IsEqual	(	const PMString &	s,
		bool8	casesensitive = `kTrue`,
		bool8	limitCompareToShorterLength = `kFalse`
	)		const

If limitCompareToShorterLength is true, you can use IsEqual to compare n characters of 2 strings, where 'n' is the length of the shorter string

Parameters

s	string to compare
casesensitive	if kTrue use case to compare
limitCompareToShorterLength	if kTrue only compare to shortest string

Returns: bool16 kTrue if equal

bool16 PMString::IsNull ( void ) const

Number of character is 0. Same as calling empty().

PORTING RECIPE - Call empty().

Returns: bool16 kTrue if no characters in string

bool16 PMString::IsTranslatable ( ) const

Find out if string is translatable. This is true when constructed with default parameters. This does not mean there is a translation for the string just that calling Translate will look for a translation.

Returns: bool16 kTrue if string is translatable.

CharCounter PMString::LastIndexOfCharacter ( const PlatformChar & pc ) const

Last index of platform char in string. Starts looking from end of string.

Parameters

pc	character to find index for

Returns: CharCounter 0 based index. -1 when not found

CharCounter PMString::LastIndexOfString ( const PMString & keyString ) const

Last index of substring within this string.

Parameters

keyString string to look for

Returns: CharCounter The character offset (not byte count) at which the string was found, or -1 when not found

CharCounter PMString::LastIndexOfWChar ( UTF32TextChar wc ) const

Last index of Unicode char in Unicode version of string

Parameters

wc	Unicode character to find index for

Returns: CharCounter 0 based index. -1 when not found

bool16 PMString::operator!= ( const PMString & s ) const

This is really just a not of the == operator. Calls !(this==s)

Parameters

s	string to compare

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

Appends PMString s

Parameters

s	string to append

bool16 PMString::operator< ( const PMString & s ) const

Lexicographically compares strings like strcmp or stricmp. If both are encoded in roman and neither has embedded unicode then platform compare is done. Otherwise compare is based on UNICODE values.

Parameters

s	string to compare

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

Lexicographically compares strings like strcmp or stricmp. If both are encoded in roman and neither has embedded unicode then platform compare is done. Otherwise compare is based on UNICODE values.

Parameters

s	string to compare

PMString& PMString::operator= ( const PMString & other )

inline

operator copy assignment

PMString& PMString::operator= ( PMString && other )

inlinenoexcept

operator move assignment

bool16 PMString::operator== ( const PMString & s ) const

Equals. Compares buffers. If either has a unicode buffer these are compared. If both have platform buffers then those are compared.

Parameters

s	string to compare

bool16 PMString::operator== ( ConstCString key ) const

Equals. Compares key. Parameter key must be a key. no translation is done.

Parameters

key	key to compare

bool16 PMString::operator> ( const PMString & s ) const

Lexicographically compares strings like strcmp or stricmp. If both are encoded in roman and neither has embedded unicode then platform compare is done. Otherwise compare is based on UNICODE values.

Parameters

s	string to compare

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

Lexicographically compares strings like strcmp or stricmp. If both are encoded in roman and neither has embedded unicode then platform compare is done. Otherwise compare is based on UNICODE values.

Parameters

s	string to compare

const PlatformChar PMString::operator[] ( CharCounter index ) const

returns the platform encoded character (as a PlatformChar) at a specific character offset into the platform string representation. This routine is multibyte (shift-JIS) character safe. It is read-only

bool16 PMString::ParseForEmbeddedCharacters ( )

Search the string and replace valid occurences of the form <xxxx> or <xxxxxx> (where 'x' is a hex digit) into a single character corresponding to that Unicode value

Returns: kTrue if there were embedded characters

void PMString::ReadPlatformWriteUnicode	(	IPMStream *	s,
		PMString::StringPlatformEncoding	encoding = `kPlatformEncodingOther`,
		bool16	includeBools = `kTrue`
	)

This will read a platform encoded string from s and store it in unicode (UTF16) in this PMString. We use this to read the Translations saved in .fr files. This is for performance reasons because when they are drawn to screen the OS wants unicode.

Parameters

s	stream to read string from
encodingClass	how the string being read is encoded
includeBools	includes format, shouldTranslate, HasTranslated. set kTrue if resource is PlatformPMString. set kFalse if resource is wstring

void PMString::ReadWrite ( IPMStream * s )

This writes Unicode representation of string. Encoding, HasTranslated and IsTranslatable are also written.

Parameters

s	string to read or write

void PMString::ReadWriteKey ( IPMStream * s )

Reads a key from a resouce that is of type wstring. If it is a write stream wstring type is written out.

Parameters

*s	IN OUT The stream object from which to read.

void PMString::Remove	(	CharCounter	pos,
		CharCounter	count = `1`
	)

This routines removes count characters (not bytes) from this string, starting after the pos'th platform character.

Parameters

pos	IN zero-based character counter representing the position for the operation.
count	IN The number of characters (not bytes). Using kMaxInt32 will remove from pos to end of string.

void PMString::SetCString	(	ConstCString	C,
		PMString::StringEncoding	encoding
	)

Set PMString using a platform string. Make sure encoding passed in matchs the encoding of C. Caller is responsible for the memory of ConstCString C. This should be used to set strings that are not keys. Calling Translate on this string will do nothing. If you want to translate the string use SetKey.

Parameters

C	platform C string. Need to be null terminated.
encoding	encoding of C string.

void PMString::SetCString ( ConstCString C )

Set PMString using a platform string. Make sure script of passed in string matchs the script of the PMString. This can be changed by calling SetEncoding. Buffer is copied so caller is responsible for the memory of ConstCString C. This is the same as SetKey. defaults to set the string to TRANSLATABLE but not translated.

PORTING RECIPE - If the cstring is a key use SetKey. If the cstring is not a key use SetCString with encoding parameter.

Parameters

C	platform C string. Need to be null terminated.

void PMString::SetEncoding ( PMString::StringEncoding encoding )

Sets to encoding of the string. If there is a platform buffer in the string then this will delete the Unicode buffer so changing the encoding when there is a platform buffer may change the Unicode buffer. However if there is no platform buffer and only a Unicode buffer the unicode will stay the same and calls to get the platform buffer will use the new encoding to convert the unicode to platform. Due to this it is best to call this when your string is empty so you have easy to understand behavior.

PORTING RECIPE - Encoding (also known as script) should be set when calling a routine that sets or gets a platform string. After the encoding is put at the point of the call this API should be removed.

Parameters

encoding new encoding to set for string.

void PMString::SetKey	(	ConstCString	key,
		TranslateDuringCall	translate = `kDontTranslateDuringCall`
	)

Set PMString using a ascii key. Caller is responsible for the memory of ConstCString key.

Parameters

key	ascii key string. Need to be null terminated.
translate	using kTranslateDuringCall will put the translation in the string. The key will be lost.

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

Set PMString using a pascal string. Make sure the encoding passed in matchs the encoding of p. Caller is responsible for the memory of ConstPString p. This should be used to set strings that are not keys. Calling Translate on this string will do nothing. If you want to translate the string use SetKey.

RECOMMENDATION - See if the ContPString p came from an API for the Macintosh. See if there is a new version of the API that gives a Unicode buffer or CFString.

Parameters

p	string used to set PMString
encoding	encoding of C string.

void PMString::SetScript ( uint8 script )

OBSOLETE. Use SetEncoding instead

PORTING RECIPE - Encoding (also known as script) should be set when calling a routing that sets or gets a platform string. After the encoding is put at the point of the call this API should be removed.

Returns: uint8 script of string

void PMString::SetString ( const PMString & s )

Set string using PMString s

Parameters

s	string used to set this PMString.

PMString& PMString::SetTranslatable ( bool16 shouldTranslate )

Sets weather the string should be translated. If the string was typed by the user often you want to turn off translation.

RECOMMENDATION - If you need to turn translation off think about using WideString instead. If that cannot be done Try calling constructor with kNoTranslate or SetCString with an encoding (that defaults to an untranslatable string).

Parameters

shouldTranslate kFalse to turn off translation

Returns: PMString& returns this

void PMString::SetTranslated ( )

SetTranslated should not usually be called. It is only used when we get a string the user typed in, so we know it is translated, but it isn't marked that way.

RECOMMENDATION - If you need to turn translation off think about using WideString instead. If that cannot be done Try calling constructor with kNoTranslate or SetCString with an encoding (that sets to an untranslatable string).

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

Sets using a std::string encoded as UTF8. String is marked as not translatable

void PMString::SetXString	(	const UTF16TextChar *	x,
		int32	nDblBytes
	)

Set PMString using a Unicode string.

Parameters

x	Unicode buffer. Does not need to be null terminated as nDblBytes determines what will be read.
nDblBytes	number of UTF16TextChars in x to be read to set PMString. Do not include count of null terminator.

void PMString::SetXString	(	const char *	x,
		int32	nBytes,
		PMString::StringEncoding	encoding = `kUnknownEncoding`
	)

Set PMString using a platform string. Make sure encoding passed in matchs the encoding of x. Caller is responsible for the memory of char* x.

Parameters

x	platform string. Does not need to be null terminated as nBytes determines what will be read.
nBytes	number of bytes in x to be read to set PMString. Do not include count of null terminator
encoding	encoding of C string.

void PMString::StripWhiteSpace ( WhitespaceType wsType = kAllWhiteSpace )

Strip white space from string. This routine only strips kTextChar_Space (U+0020).

Parameters

wsType where to strip white space from

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

Creates a new string based on count characters (not bytes) from this string. The substring begins at pos (0 based). Return nil if selected range is empty.

Parameters

pos	position to get string. 0 based.
count	number of character to get. kMaxInt32 goes to end of string.

Returns: PMString* substring. return nil if selected range is empty.

void PMString::ToLower ( void )

Converts characters to Lower case.

void PMString::ToUpper ( void )

Converts characters to Upper case.

bool16 PMString::Translate ( const PMLocaleId & locale )

translate from key to another locale, over-loaded so that if no locale is specified the current global locale setting is used.

Parameters

locale locale to translate to

Returns: bool16 kTrue if translated. Also kTrue if IsTranslatable is kFalse or HasTranslated if kTrue.

bool16 PMString::Translate ( )

translate from key using current locale.

Returns: bool16 kTrue if translated. Also kTrue if IsTranslatable is kFalse or HasTranslated if kTrue.

void PMString::Truncate ( CharCounter count = 1 )

This routines truncates the final count platform characters (not bytes) from the string.

Parameters

count number of characters to remove from end

int32 PMString::WCharLength ( void ) const

Get the number of UTF16s required to store this string. Same value as returned in numUTF16s by GrabUTF16Buffer.

Returns: int32 number of UTF16s required to store

Friends And Related Function Documentation

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

friend

Appends PMString s2 to PMString s1 and returns it as a PMString

Parameters

s1	string to append to
s2	string to append

Returns: PMString string to set

void swap	(	PMString &	left,
		PMString &	right
	)

friend

Swaps the contents of two strings.

Classes

Public Types

Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation