ai::UnicodeString Class Reference

UnicodeString objects provide basic string functionality for Unicode-based strings, similar to that provided by the standard C string library. More...

#include <IAIUnicodeString.h>

List of all members.

Public Types
enum	NormalizedForm { kForm_NFD = 0, kForm_NFC, kForm_NFKD, kForm_NFKC, kForm_DummyValue = 0xFFFFFFFF }
	Normalization forms for use with the `normalize()` method. More...
typedef ai::sizediff_t	offset_type
	A numeric relative offset type (signed integer).
typedef size_t	size_type
	A numeric value type (unsigned integer).
typedef ASUInt32	UTF32TextChar
	Value type for a UTF-32 character code.
typedef ASUnicode	UTF16Char
	Value type for a UTF-16 character code.
Public Member Functions
UnicodeString &	append (const UnicodeString &str)
	Appends a string to this string.
UnicodeString &	append (const UnicodeString &str, size_type startOffset, size_type count)
	Appends a substring of a given string to this string.
UnicodeString &	append (size_type count, UTF32TextChar ch)
	Appends a given number of copies of a given character to this string.
UnicodeString &	assign (const UnicodeString &str)
	Replaces the contents of this string with another string.
UnicodeString &	assign (const UnicodeString &str, size_type offset, size_type count)
	Replaces the contents of this string with a substring of another string.
UTF32TextChar	at (size_type offset) const
	Retrieves the UTF32 code point (character) from a string by position index.
void	clear ()
	Erases all characters in this string.
ai::int32	compare (const UnicodeString &str) const
	Compares this string and another string for equality.
ai::int32	compare (size_type pos, size_type num, const UnicodeString &str) const
	Compares this string and a substring of another string for equality.
ai::int32	compare (size_type pos, size_type num, const UnicodeString &str, size_type startOffset, size_type count) const
	Compares a substring of this string and a substring of another string for equality.
size_type	length () const
	Retrieves the number of characters (UTF code points) in this string.
bool	empty () const
	Reports whether this string is an empty string.
UnicodeString &	erase (size_type pos=0, size_type count=npos)
	Removes characters (UTF code points) from this string.
size_type	find (UTF32TextChar ch, size_type startOffset=0) const
	Searches for a character in this string.
size_type	find (const UnicodeString &target, size_type startOffset=0) const
	Searches for a string within a subset of this string.
size_type	find (const UnicodeString &target, size_type startOffset, size_type count) const
	Searches for a substring within a subset of this string.
size_type	caseFind (UTF32TextChar ch, size_type startOffset=0) const
	Searches for a character in this string, performing a caseless compare.
size_type	caseFind (const UnicodeString &target, size_type startOffset=0) const
	Searches for a string within a subset of this string, performing a caseless compare.
size_type	caseFind (const UnicodeString &target, size_type startOffset, size_type count) const
	Searches for a substring within a subset of this string, performing a caseless compare.
size_type	rfind (UTF32TextChar ch, size_type startOffset=npos) const
	Searches for a character in this string, moving backward from a point in this string.
size_type	rfind (const UnicodeString &target, size_type startOffset=npos) const
	Searches for a string within a subset of this string, moving backward from a point in this string.
size_type	rfind (const UnicodeString &target, size_type startOffset, size_type count) const
	Searches for a substring within a subset of this string, moving backward from a point in this string.
size_type	find_first_of (const UnicodeString &target, size_type startOffset=0) const
	Searches for the first character of a string within a subset of this string.
size_type	find_first_of (const UnicodeString &target, size_type startOffset, size_type count) const
	Searches for the first character of a string within a subset of this string.
size_type	find_last_of (const UnicodeString &target, size_type startOffset=npos) const
	Searches for the last character of a string within a subset of this string.
size_type	find_last_of (const UnicodeString &target, size_type startOffset, size_type count) const
	Searches for the last character of a string within a subset of this string.
size_type	find_first_not_of (const UnicodeString &target, size_type startOffset=0) const
	Searches for the first occurrence in this string of a character that is not in a target string.
size_type	find_first_not_of (const UnicodeString &target, size_type startOffset, size_type count) const
	Searches for the first occurrence in a subset of this string of a character that is not in a target string.
size_type	find_last_not_of (const UnicodeString &target, size_type startOffset=npos) const
	Searches for the last occurrence in this string of a character that is not in a target string.
size_type	find_last_not_of (const UnicodeString &target, size_type startOffset, size_type count) const
	Searches for the last occurrence in a subset of this string of a character that is not in a target string.
UnicodeString &	replace (size_type pos, size_type num, const UnicodeString &str)
	Replaces a substring in this string with another string.
UnicodeString &	replace (size_type pos, size_type num, const UnicodeString &str, size_type count)
	Replaces a substring in this string with a substring of another string.
UnicodeString &	replace (size_type pos, size_type num, const UnicodeString &str, size_type startOffset, size_type count)
	Replaces a substring in this string with a substring of another string.
UnicodeString &	insert (size_type insertOffset, const UnicodeString &str)
	Inserts a string into this string, inserting as many characters as will fit.
UnicodeString &	insert (size_type insertOffset, const UnicodeString &str, size_type offset, size_type count)
	Inserts a substring into this string.
UnicodeString &	insert (size_type insertOffset, size_type count, UTF32TextChar ch)
	Inserts repeated characters into this string.
void	push_back (UTF32TextChar ch)
	Appends a character to the end of this string.
void	resize (size_type count, UTF32TextChar ch=UTF32TextChar())
	Resizes this string, truncating it or adding characters as needed.
ai::UnicodeString::size_type	size (void) const
	Retrieves the number of characters (UTF code points) in this string.
UnicodeString	substr (size_type offset=0, size_type count=npos) const
	Creates a copy of a substring of this string.
void	swap (UnicodeString &str)
	Swaps the contents of this string with another string.
UnicodeString &	operator= (const UnicodeString &rhs)
	Assignment operator.
UnicodeString &	operator+= (UTF32TextChar ch)
	Append operator.
UnicodeString &	operator+= (const UnicodeString &rhs)
	Append operator.
UTF32TextChar	operator[] (size_type offset) const
	Retrieves a character from this string.
bool	operator== (const UnicodeString &rhs) const
	Equality operator.
bool	operator!= (const UnicodeString &rhs) const
	Non-equality operator.
bool	operator< (const UnicodeString &rhs) const
	Less-than operator.
UnicodeString &	toLower ()
	Convert the characters in this to lower case following the conventions of the default locale.
UnicodeString &	toUpper ()
	Convert the characters in this to UPPER CASE following the conventions of the default locale.
ai::int32	caseCompare (const UnicodeString &str) const
	Compares this string with another string, doing a caseless code-point-based comparison.
ai::int32	caseCompare (size_type pos, size_type num, const UnicodeString &str) const
	Compares this string with a substring of another string, doing a caseless code-point-based comparison.
ai::int32	caseCompare (size_type pos, size_type num, const UnicodeString &str, size_type startOffset, size_type count) const
	Compares a substring of this string with a substring of another string, doing a caseless code-point-based comparison.
ai::int32	canonicalCompare (const UnicodeString &str) const
	Compares this string with another string for canonical equivalence of their normalized forms (NFD or NFC).
ai::int32	canonicalCaseCompare (const UnicodeString &str) const
	Compares this string with another string for canonical equivalence of their normalized forms (NFD or NFC), performing a caseless compare.
UnicodeString &	normalize (NormalizedForm form)
	Normalizes this string in place into the specified form.
bool	hasSurrogates () const
	Reports whether this string contains surrogate pairs.
size_type	utf_16 (const UTF16Char *&buffer) const
	Creates a UTF-16 string from the contents of this string, in platform byte order.
std::basic_string< ASUnicode >	as_ASUnicode () const
	Creates a 0-terminated UTF-16 string from the contents of this string, in platform byte order.
std::string	as_UTF8 () const
	Creates a UTF-8 string from the contents of this string.
std::string	as_Platform () const
	Creates a platform-encoded version of this string.
std::string	as_Roman () const
	Creates an ISO Latin/Roman-encoded version of this string.
size_type	getToBuffer (char *buffer, size_type bufferMax, AICharacterEncoding encoding) const
	Copies the contents of this string to a provided buffer.
size_type	getToBuffer (const PStr &pascalString, size_type bufferMax, AICharacterEncoding encoding) const
	Copies the contents of this string to a Pascal string in a provided buffer.
size_type	as_ASUnicode (ASUnicode *buffer, size_type bufferMax) const
	Copies the contents of this string to a Unicode string in a provided buffer.
size_type	as_Platform (const PStr &pascalString, size_type bufferMax) const
	Copies the contents of this string to a platform-encoded Pascal string in a provided buffer.
size_type	as_Platform (char *buffer, size_type bufferMax) const
	Copies the contents of this string to a C string in a provided buffer.
size_type	as_Roman (char *buffer, size_type bufferMax) const
	Copies the contents of this string to an ISO Latin/Roman-encoded C string in a provided buffer.
size_type	as_Roman (const PStr &pascalString, size_type bufferMax) const
	Copies the contents of this string to an ISO Latin/Roman-encoded Pascal string in a provided buffer.
std::string	getInStdString (AICharacterEncoding encoding) const
	Creates a `std::string` from the contents of this string.
size_type	getAs (AICharacterEncoding encoding, ai::AutoBuffer< char > &b) const
	Copies the contents of this string to an `ai::AutoBuffer<char>`.
void	deleteImpl ()
Constructors & Destructors

	UnicodeString (void) AINOTHROW
	Empty string constructor.
	UnicodeString (const char *string, offset_type srcByteLen, AICharacterEncoding encoding=kAIPlatformCharacterEncoding)
	Constructs a UnicodeString from an encoded byte array.
	UnicodeString (size_type count, UTF32TextChar ch)
	Constructs a UnicodeString using a copies of a single character.
	UnicodeString (const char *string, AICharacterEncoding encoding=kAIPlatformCharacterEncoding)
	Convenience constructor from a `char` buffer that is known to be 0 terminated.
	UnicodeString (const std::string &string, AICharacterEncoding encoding=kAIPlatformCharacterEncoding)
	Convenience constructor from a `std::string`.
	UnicodeString (const ASUnicode *string)
	Constructor from 0-terminated, platform-byte-ordered, UTF-16 array.
	UnicodeString (const ZRef zStringKey)
	Constructor from the ZString referred to by a ZString key.
	UnicodeString (const ASUnicode *string, size_type srcUTF16Count)
	Constructor from a non-0-terminated platform-byte-ordered, UTF-16 array.
	UnicodeString (const std::basic_string< ASUnicode > &string)
	Constructor from a `std::basic_string` of platform-byte-ordered `ASUnicode` characters.
	UnicodeString (const UnicodeString &s)
	Copy Constructor, creates a copy of a string.
	~UnicodeString (void)
	Destructor.
Mac OS-specific Methods

	UnicodeString (const CFStringRef &cfString)
	Constructs a Unicode string object from a Mac OS `CFString`.
CFStringRef	as_CFString (CFAllocatorRef alloc) const
	Converts the contents of this string to a Mac OS `CFString`.
Windows-specific Methods

	UnicodeString (const WCHARStr &string)
	Constructs a Unicode string object from a Windows `WCHARStr` wrapper object.
WCHARStr	as_WCHARStr () const
	Converts the contents of this string to a `WCHARStr` wrapper object.
size_type	as_WCHARStr (WCHARStr::LPWSTR buffer, size_type bufferMax) const
	Copies the contents of this string to a provided buffer.
Static Public Member Functions
Factory methods

static UnicodeString	FromRoman (const char *string, size_type count)
	Constructs a UnicodeString from a non-zero-terminated `char` array whose encoding is ISO Roman/Latin.
static UnicodeString	FromRoman (const char *string)
	Constructs a UnicodeString from a zero-terminated `char` array whose encoding is ISO Roman/Latin.
static UnicodeString	FromRoman (const std::string &string)
	Constructs a UnicodeString from a `std::string` whose encoding is ISO Roman/Latin.
static UnicodeString	FromRoman (const const_PStr &pascalString)
	Constructs a UnicodeString from a Pascal string whose encoding is ISO Roman/Latin.
static UnicodeString	FromPlatform (const char *string, size_type count)
	Constructs a UnicodeString from a non-zero-terminated `char` array whose encoding is the current platform encoding.
static UnicodeString	FromPlatform (const char *string)
	Constructs a UnicodeString from a zero-terminated `char` array whose encoding is the current platform encoding.
static UnicodeString	FromPlatform (const std::string &string)
	Constructs a UnicodeString from a `std::string` whose encoding is the current platform encoding.
static UnicodeString	FromPlatform (const const_PStr &pascalString)
	Constructs a UnicodeString from a Pascal string whose encoding is the current platform encoding.
static UnicodeString	FromUTF8 (const char *string)
	Constructs a UnicodeString from a zero-terminated `char` array whose encoding is UTF8.
static UnicodeString	FromUTF8 (const std::string &string)
	Constructs a UnicodeString from a `std::string` whose encoding is UTF8.
static UnicodeString	FromUTF8 (const const_PStr &pascalString)
	Constructs a UnicodeString from a Pascal string whose encoding is UTF8.
Static Public Attributes
static const size_type	npos
	The maximum number of characters possible in a string.
static const ai::UnicodeString	kEmptyString
	The empty unicode string to return as the reference of empty String.
Protected Member Functions
	UnicodeString (class CAIUnicodeStringImpl *impl)

Detailed Description

UnicodeString objects provide basic string functionality for Unicode-based strings, similar to that provided by the standard C string library.

The contents of the string are treated as if all characters are represented as full 32-bit Unicode characters, which means you do not need to know the internal representation of the string, or deal with surrogate pairs during editing or searching operations.

Member Typedef Documentation

typedef ai::sizediff_t ai::UnicodeString::offset_type

A numeric relative offset type (signed integer).

typedef size_t ai::UnicodeString::size_type

A numeric value type (unsigned integer).

typedef ASUnicode ai::UnicodeString::UTF16Char

Value type for a UTF-16 character code.

typedef ASUInt32 ai::UnicodeString::UTF32TextChar

Value type for a UTF-32 character code.

Member Enumeration Documentation

enum ai::UnicodeString::NormalizedForm

Normalization forms for use with the normalize() method.

See http://www.unicode.org/reports/tr15/ for more information.

Enumerator:

kForm_NFD	Canonical Decomposition.
kForm_NFC	Canonical Decomposition, followed by Canonical Composition.
kForm_NFKD	Compatibility Decomposition.
kForm_NFKC	Comparability Decomposition, followed by Canonical Composition.
kForm_DummyValue	Do not use this.

Constructor & Destructor Documentation

ai::UnicodeString::UnicodeString ( void ) [explicit]

Empty string constructor.

Creates a valid, empty string. This method is guaranteed to not throw any exceptions.

Referenced by append(), and insert().

ai::UnicodeString::UnicodeString	(	const char *	string,
		offset_type	srcByteLen,
		AICharacterEncoding	encoding = `kAIPlatformCharacterEncoding`
	)			`[explicit]`

Constructs a UnicodeString from an encoded byte array.

Parameters:

	string	Array of bytes to construct from.
	srcByteLen	Length of the array.
	encoding	Encoding of the contents of the byte array. Default is the current platform encoding

ai::UnicodeString::UnicodeString	(	size_type	count,
		UTF32TextChar	ch
	)			`[explicit]`

Constructs a UnicodeString using a copies of a single character.

Parameters:

	count	Number of characters to insert in this string.
	ch	The UTF32 code point (character) with which to initialize the string.

ai::UnicodeString::UnicodeString	(	const char *	string,
		AICharacterEncoding	encoding = `kAIPlatformCharacterEncoding`
	)			`[explicit]`

Convenience constructor from a char buffer that is known to be 0 terminated.

Parameters:

	string	Initial contents.
	encoding	Encoding of the contents of the byte array.

ai::UnicodeString::UnicodeString	(	const std::string &	string,
		AICharacterEncoding	encoding = `kAIPlatformCharacterEncoding`
	)			`[explicit]`

Convenience constructor from a std::string.

Parameters:

	string	Initial contents.
	encoding	Encoding of the contents of the byte array.

ai::UnicodeString::UnicodeString ( const ASUnicode * string ) [explicit]

Constructor from 0-terminated, platform-byte-ordered, UTF-16 array.

Surrogate pairs are okay. Exception raised if string is malformed.

Parameters:

string Pointer to a valid 0-terminated array of UTF-16 ASUnicode.

ai::UnicodeString::UnicodeString ( const ZRef zStringKey ) [explicit]

Constructor from the ZString referred to by a ZString key.

Parameters:

zStringKey

The ZString key.

ai::UnicodeString::UnicodeString	(	const ASUnicode *	string,
		size_type	srcUTF16Count
	)			`[explicit]`

Constructor from a non-0-terminated platform-byte-ordered, UTF-16 array.

Surrogate pairs are okay. Exception raised if string is malformed.

Parameters:

	string	Pointer to an array of UTF-16 `ASUnicode`.
	srcUTF16Count	The number of UTF-16 code units to be read from string.

ai::UnicodeString::UnicodeString ( const std::basic_string< ASUnicode > & string ) [explicit]

Constructor from a std::basic_string of platform-byte-ordered ASUnicode characters.

Surrogate pairs are okay. Exception raised if string is malformed.

Parameters:

string A std::basic_string<ASUnicode>.

ai::UnicodeString::UnicodeString ( const UnicodeString & s )

Copy Constructor, creates a copy of a string.

Parameters:

s

The string to copy.

ai::UnicodeString::~UnicodeString ( void )

Destructor.

ai::UnicodeString::UnicodeString ( const CFStringRef & cfString ) [explicit]

Constructs a Unicode string object from a Mac OS CFString.

Parameters:

cfString The source CFString.

ai::UnicodeString::UnicodeString ( const WCHARStr & string ) [explicit]

Constructs a Unicode string object from a Windows WCHARStr wrapper object.

Parameters:

string The source WCHARStr.

ai::UnicodeString::UnicodeString ( class CAIUnicodeStringImpl * impl ) [explicit, protected]

Member Function Documentation

UnicodeString& ai::UnicodeString::append	(	size_type	count,
		UTF32TextChar	ch
	)			`[inline]`

Appends a given number of copies of a given character to this string.

Parameters:

	count	The number of characters to append.
	ch	The character to append.

Returns:: A reference to this Unicode string object.

References append(), and UnicodeString().

Referenced by append().

UnicodeString& ai::UnicodeString::append	(	const UnicodeString &	str,
		size_type	startOffset,
		size_type	count
	)

Appends a substring of a given string to this string.

Parameters:

	str	The source string of the substring.
	startOffset	The 0-based index of the first character in the substring.
	count	The maximum number of characters in the substring.

Returns:: A reference to this Unicode string object.

UnicodeString& ai::UnicodeString::append ( const UnicodeString & str )

Appends a string to this string.

Parameters:

str

The string to append.

Returns:: A reference to this Unicode string object.

Referenced by AIFileDialogFilters::AddFilter(), insert(), ASUserInteractionChecker::logInfo(), operator+=(), and push_back().

UnicodeString::size_type ai::UnicodeString::as_ASUnicode	(	ASUnicode *	buffer,
		size_type	bufferMax
	)			const `[inline]`

Copies the contents of this string to a Unicode string in a provided buffer.

Parameters:

	buffer	A pointer to a Unicode string in which to return the 0-terminated copy.
	bufferMax	The maximum count of UTF-16 code units (`ASUnicode`) to write to the buffer including a 0 terminator. Or, pass 0 to request the required buffer size.

Returns:: The size needed to write the entire string contents to a buffer, including a 0 terminator.

References utf_16().

std::basic_string<ASUnicode> ai::UnicodeString::as_ASUnicode ( ) const

Creates a 0-terminated UTF-16 string from the contents of this string, in platform byte order.

Returns:: The contents of this string as UTF-16 code units.

Referenced by as_WCHARStr().

CFStringRef ai::UnicodeString::as_CFString ( CFAllocatorRef alloc ) const

Converts the contents of this string to a Mac OS CFString.

Parameters:

alloc A valid CFAllocatorRef for allocating the CFString.

Returns:: An immutable CFString object containing chars, or NULL if there was a problem creating the object. You must dispose of this object when it is no longer needed.

UnicodeString::size_type ai::UnicodeString::as_Platform	(	char *	buffer,
		size_type	bufferMax
	)			const `[inline]`

Copies the contents of this string to a C string in a provided buffer.

Parameters:

	buffer	A pointer to a C string in which to return the 0-terminated copy.
	bufferMax	The maximum byte count to write to the buffer, including the 0 terminator, or `NULL` to return the required size.

Returns:: The size needed to write the entire string contents to a buffer, including a 0 terminator.

References getToBuffer(), and kAIPlatformCharacterEncoding.

UnicodeString::size_type ai::UnicodeString::as_Platform	(	const PStr &	pascalString,
		size_type	bufferMax
	)			const `[inline]`

Copies the contents of this string to a platform-encoded Pascal string in a provided buffer.

Parameters:

	pascalString	A pointer to a Pascal string in which to return the 0-terminated copy.
	bufferMax	The maximum byte count to write to the buffer, including the 0 terminator, or `NULL` to return the required size.

Returns:: The size needed to write the entire string contents to a buffer, including a 0 terminator.

References getToBuffer(), and kAIPlatformCharacterEncoding.

std::string ai::UnicodeString::as_Platform ( ) const [inline]

Creates a platform-encoded version of this string.

Returns:: The contents of this string as a UTF-8 encoded std::string.

References getInStdString(), and kAIPlatformCharacterEncoding.

UnicodeString::size_type ai::UnicodeString::as_Roman	(	const PStr &	pascalString,
		size_type	bufferMax
	)			const `[inline]`

Copies the contents of this string to an ISO Latin/Roman-encoded Pascal string in a provided buffer.

Parameters:

	pascalString	A pointer to a Pascal string in which to return the 0-terminated copy.
	bufferMax	The maximum byte count to write to the buffer, including the 0 terminator, or `NULL` to return the required size.

Returns:: The size needed to write the entire string contents to a buffer, including a 0 terminator.

References getToBuffer(), and kAIRomanCharacterEncoding.

UnicodeString::size_type ai::UnicodeString::as_Roman	(	char *	buffer,
		size_type	bufferMax
	)			const `[inline]`

Copies the contents of this string to an ISO Latin/Roman-encoded C string in a provided buffer.

Parameters:

	buffer	A pointer to a C string in which to return the 0-terminated copy.
	bufferMax	The maximum byte count to write to the buffer, including the 0 terminator, or `NULL` to return the required size.

Returns:: The size needed to write the entire string contents to a buffer, including a 0 terminator.

References getToBuffer(), and kAIRomanCharacterEncoding.

std::string ai::UnicodeString::as_Roman ( ) const [inline]

Creates an ISO Latin/Roman-encoded version of this string.

Returns:: The contents of this string as a UTF-8 encoded std::string.

References getInStdString(), and kAIRomanCharacterEncoding.

std::string ai::UnicodeString::as_UTF8 ( ) const [inline]

Creates a UTF-8 string from the contents of this string.

Returns:: The contents of this string as a UTF-8 encoded std::string.

References getInStdString(), and kAIUTF8CharacterEncoding.

Referenced by ASUserInteractionChecker::logInfo().

UnicodeString::size_type ai::UnicodeString::as_WCHARStr	(	WCHARStr::LPWSTR	buffer,
		size_type	bufferMax
	)			const `[inline]`

Copies the contents of this string to a provided buffer.

Parameters:

	buffer	A pointer to a buffer of `WCHARStr::LPWSTR` in which to return the 0-terminated copy.
	bufferMax	The maximum count of `WCHARStr::LPWSTR` to write to the buffer.

Returns:: The size needed to write the entire string contents to a buffer, including a 0 terminator. Returned size is the count of WCHARStr::LPWSTR needed.

References AI_STATIC_CHECK, and as_ASUnicode().

WCHARStr ai::UnicodeString::as_WCHARStr ( ) const

Converts the contents of this string to a WCHARStr wrapper object.

Returns:: The WCHARStr object. Contents are UTF-16 encoded.

UnicodeString& ai::UnicodeString::assign	(	const UnicodeString &	str,
		size_type	offset,
		size_type	count
	)			`[inline]`

Replaces the contents of this string with a substring of another string.

Parameters:

	str	The source of the substring.
	offset	The 0-based index of the first character in the substring.
	count	The maximum number of characters in the substring.

Returns:: A reference to this Unicode string object.

References assign(), and substr().

Referenced by assign().

UnicodeString& ai::UnicodeString::assign ( const UnicodeString & str )

Replaces the contents of this string with another string.

Parameters:

str

The new contents.

Returns:: A reference to this Unicode string object.

UTF32TextChar ai::UnicodeString::at ( size_type offset ) const

Retrieves the UTF32 code point (character) from a string by position index.

Raises kUnicodeStringBadIndex exception if offset is out of range.

Parameters:

offset

The 0-based index of the character.

Returns:: The UTF32 value of the character.

ai::int32 ai::UnicodeString::canonicalCaseCompare ( const UnicodeString & str ) const

Compares this string with another string for canonical equivalence of their normalized forms (NFD or NFC), performing a caseless compare.

This requires temporary allocation of memory, and can throw out-of-memory errors.

Uninitialized strings are equal to other uninitialized strings and empty strings. Uninitialized and empty strings are less than initialized, non-empty strings.

Parameters:

str

The comparison string (right side of compare).

Returns:: 0 if the strings are equal.
Positive if this string is greater than the comparison string.
Negative if this string is less than the comparison string.

Note:: Substring comparison of non-normalized strings is not directly available. You can create substrings and pass them to this method.

ai::int32 ai::UnicodeString::canonicalCompare ( const UnicodeString & str ) const

Compares this string with another string for canonical equivalence of their normalized forms (NFD or NFC).

This requires temporary allocation of memory, and can throw out-of-memory errors.

Uninitialized strings are equal to other uninitialized strings and empty strings. Uninitialized and empty strings are less than initialized, non-empty strings.

Parameters:

str

The comparison string (right side of compare).

Returns:: 0 if the strings are equal.
Positive if this string is greater than the comparison string.
Negative if this string is less than the comparison string.

Note:: Substring comparison of non-normalized strings is not directly available. You can create substrings and pass them to this method.

ai::int32 ai::UnicodeString::caseCompare	(	size_type	pos,
		size_type	num,
		const UnicodeString &	str,
		size_type	startOffset,
		size_type	count
	)			const

Compares a substring of this string with a substring of another string, doing a caseless code-point-based comparison.

Uninitialized strings are equal to other uninitialized strings and empty strings. Uninitialized and empty strings are less than initialized, non-empty strings.

Parameters:

	pos	The 0-based position index of the first character of the substring of this string.
	num	The number of characters in the substring of this string.
	str	The comparison string (right side of compare).
	startOffset	The 0-based position index of the first character of the substring of the comparison string.
	count	The number of characters in the substring of the comparison string.

Returns:: 0 if this substring and the comparison substring are equal.
Positive if this substring is greater than the comparison substring.
Negative if this substring is less than the comparison substring.

ai::int32 ai::UnicodeString::caseCompare	(	size_type	pos,
		size_type	num,
		const UnicodeString &	str
	)			const `[inline]`

Compares this string with a substring of another string, doing a caseless code-point-based comparison.

Uninitialized strings are equal to other uninitialized strings and empty strings. Uninitialized and empty strings are less than initialized, non-empty strings.

Parameters:

	pos	The 0-based position index of the first character of the substring.
	num	The number of characters to compare.
	str	The comparison string (right side of compare).

Returns:: 0 if this string and the substring are equal.
Positive if this string is greater than the substring.
Negative if this string is less than the substring.

References caseCompare(), and npos.

Referenced by caseCompare().

ai::int32 ai::UnicodeString::caseCompare ( const UnicodeString & str ) const [inline]

Compares this string with another string, doing a caseless code-point-based comparison.

Uninitialized strings are equal to other uninitialized strings and empty strings. Uninitialized and empty strings are less than initialized, non-empty strings.

Parameters:

str

The comparison string (right side of compare).

Returns:: 0 if the strings are equal.
Positive if this string is greater than the comparison string.
Negative if this string is less than the comparison string.

References caseCompare(), and npos.

Referenced by caseCompare().

size_type ai::UnicodeString::caseFind	(	const UnicodeString &	target,
		size_type	startOffset,
		size_type	count
	)			const

Searches for a substring within a subset of this string, performing a caseless compare.

Parameters:

	target	The string to search for.
	startOffset	The 0-based position index in this string at which to start the search.
	count	The number of characters in the target string to search for.

Returns:: The 0-based position index of the first character of the target substring within this string, if found, or (npos) if the target substring is not found.

size_type ai::UnicodeString::caseFind	(	const UnicodeString &	target,
		size_type	startOffset = `0`
	)			const `[inline]`

Searches for a string within a subset of this string, performing a caseless compare.

Parameters:

	target	The string to search for.
	startOffset	The 0-based position index in this string at which to start the search.

Returns:: The 0-based position index of the first character of the target string within this string, if found, or (npos) if the target string is not found.

References caseFind(), and length().

Referenced by caseFind().

size_type ai::UnicodeString::caseFind	(	UTF32TextChar	ch,
		size_type	startOffset = `0`
	)			const `[inline]`

Searches for a character in this string, performing a caseless compare.

Parameters:

	ch	The character to search for.
	startOffset	The 0-based position index in this string at which to start the search.

Returns:: The 0-based position index of the found character, or (npos) if the character is not found.

References caseFind().

Referenced by caseFind().

void ai::UnicodeString::clear ( )

Erases all characters in this string.

Same as erase(0, npos). Uninitialized strings remain unchanged.

Returns:: Nothing.

See also:: erase()

ai::int32 ai::UnicodeString::compare	(	size_type	pos,
		size_type	num,
		const UnicodeString &	str,
		size_type	startOffset,
		size_type	count
	)			const

Compares a substring of this string and a substring of another string for equality.

Uninitialized strings are equal to other uninitialized strings and to empty strings.Uninitialized and empty strings are less than initialized, non-empty strings.

Parameters:

	pos	The 0-based index of the first character of the substring in this string.
	num	The number of characters to compare in this string.
	str	The source of the substring to compare against (right side of compare)..
	startOffset	The 0-based index of the first character of the substring of `str`.
	count	The number of characters from `str` to compare.

Returns:: Zero if the two substrings are equal.
Negative if the substring of this string is less than the substring of str.
Positive if the substring of this string is greater than the substring of str.

ai::int32 ai::UnicodeString::compare	(	size_type	pos,
		size_type	num,
		const UnicodeString &	str
	)			const

Compares this string and a substring of another string for equality.

Uninitialized strings are equal to other uninitialized strings and to empty strings.Uninitialized and empty strings are less than initialized, non-empty strings.

Parameters:

	pos	The 0-based index of the first character of the substring.
	num	The number of characters to compare.
	str	The source of the substring to compare against (right side of compare)..

Returns:: Zero if this string and the substring are equal.
Negative if this string is less than the substring of str.
Positive if this string is greater than the substring of str.

ai::int32 ai::UnicodeString::compare ( const UnicodeString & str ) const

Compares this string and another string for equality.

Uninitialized strings are equal to other uninitialized strings and to empty strings.Uninitialized and empty strings are less than initialized, non-empty strings.

Parameters:

str

The string to compare against (right side of compare)..

Returns:: Zero if the two strings are equal.
Negative if this string is less than str.
Positive if this string is greater than str.

Referenced by operator<(), and operator==().

void ai::UnicodeString::deleteImpl ( )

bool ai::UnicodeString::empty ( ) const

Reports whether this string is an empty string.

Returns:: True if the string is empty.

Referenced by AIFileDialogFilters::AddFilter().

UnicodeString& ai::UnicodeString::erase	(	size_type	pos = `0`,
		size_type	count = `npos`
	)

Removes characters (UTF code points) from this string.

Parameters:

	pos	The 0-based position index of the first character to remove.
	count	The number of characters to remove.

Returns:: A reference to this Unicode string object.

Referenced by AIFileDialogFilters::AddFilter(), and replace().

size_type ai::UnicodeString::find	(	const UnicodeString &	target,
		size_type	startOffset,
		size_type	count
	)			const

Searches for a substring within a subset of this string.

Parameters:

	target	The string to search for.
	startOffset	The 0-based position index in this string at which to start the search.
	count	The number of characters in the target string to search for.

Returns:: The 0-based position index of the first character of the target substring within this string, if found, or (npos) if the target substring is not found.

size_type ai::UnicodeString::find	(	const UnicodeString &	target,
		size_type	startOffset = `0`
	)			const

Searches for a string within a subset of this string.

Parameters:

	target	The string to search for.
	startOffset	The 0-based position index in this string at which to start the search.

Returns:: The 0-based position index of the first character of the target string within this string, if found, or the number of characters in this string (npos) if the target string is not found.

size_type ai::UnicodeString::find	(	UTF32TextChar	ch,
		size_type	startOffset = `0`
	)			const

Searches for a character in this string.

Parameters:

	ch	The character to search for.
	startOffset	The 0-based position index in this string at which to start the search.

Returns:: The 0-based position index of the found character, or the number of characters in this string (npos) if the character is not found.

size_type ai::UnicodeString::find_first_not_of	(	const UnicodeString &	target,
		size_type	startOffset,
		size_type	count
	)			const

Searches for the first occurrence in a subset of this string of a character that is not in a target string.

Parameters:

	target	The target string.
	startOffset	The 0-based position index in this string at which to start the search.
	count	The number of characters in this string to search.

Returns:: The 0-based position index of the character within this string, if found, or (npos) if the character is not found.

size_type ai::UnicodeString::find_first_not_of	(	const UnicodeString &	target,
		size_type	startOffset = `0`
	)			const `[inline]`

Searches for the first occurrence in this string of a character that is not in a target string.

Parameters:

	target	The target string.
	startOffset	The 0-based position index in this string at which to start the search.

Returns:: The 0-based position index of the character within this string, if found, or (npos) if the character is not found.

References find_first_not_of(), and npos.

Referenced by find_first_not_of().

size_type ai::UnicodeString::find_first_of	(	const UnicodeString &	target,
		size_type	startOffset,
		size_type	count
	)			const

Searches for the first character of a string within a subset of this string.

Parameters:

	target	The string to search for.
	startOffset	The 0-based position index in this string at which to start the search.
	count	The number of characters in the substring to search.

Returns:: The 0-based position index of the first character of the target string within this string, if found, or (npos) if the character is not found.

size_type ai::UnicodeString::find_first_of	(	const UnicodeString &	target,
		size_type	startOffset = `0`
	)			const `[inline]`

Searches for the first character of a string within a subset of this string.

Parameters:

	target	The string to search for.
	startOffset	The 0-based position index in this string at which to start the search.

Returns:: The 0-based position index of the first character of the target string within this string, if found, or (npos) if the first character of the target string is not found.

References find_first_of(), and npos.

Referenced by find_first_of().

size_type ai::UnicodeString::find_last_not_of	(	const UnicodeString &	target,
		size_type	startOffset,
		size_type	count
	)			const

Searches for the last occurrence in a subset of this string of a character that is not in a target string.

Parameters:

	target	The target string.
	startOffset	The 0-based position index in this string at which to start the search.
	count	The number of characters in this string to search.

Returns:: The 0-based position index of the character within this string, if found, or (npos) if the character is not found.

size_type ai::UnicodeString::find_last_not_of	(	const UnicodeString &	target,
		size_type	startOffset = `npos`
	)			const `[inline]`

Searches for the last occurrence in this string of a character that is not in a target string.

Parameters:

	target	The target string.
	startOffset	The 0-based position index in this string at which to start the search.

Returns:: The 0-based position index of the character within this string, if found, or (npos) if the character is not found.

References find_last_not_of(), and npos.

Referenced by find_last_not_of().

size_type ai::UnicodeString::find_last_of	(	const UnicodeString &	target,
		size_type	startOffset,
		size_type	count
	)			const

Searches for the last character of a string within a subset of this string.

Parameters:

	target	The string containing the character to search for.
	startOffset	The 0-based position index in this string at which to start the search.
	count	The number of characters in this string in which to search.

Returns:: The 0-based position index of the last character of the target string within this string, if found, or (npos) if the character is not found.

size_type ai::UnicodeString::find_last_of	(	const UnicodeString &	target,
		size_type	startOffset = `npos`
	)			const `[inline]`

Searches for the last character of a string within a subset of this string.

Parameters:

	target	The string containing the character to search for.
	startOffset	The 0-based position index in this string at which to start the search.

Returns:: The 0-based position index of the last character of the target string within this string, if found, or (npos) if the character is not found.

References find_last_of(), and npos.

Referenced by find_last_of().

static UnicodeString ai::UnicodeString::FromPlatform ( const const_PStr & pascalString ) [static]

Constructs a UnicodeString from a Pascal string whose encoding is the current platform encoding.

Parameters:

pascalString

The Pascal string.

Returns:: The Unicode string object.

static UnicodeString ai::UnicodeString::FromPlatform ( const std::string & string ) [static]

Constructs a UnicodeString from a std::string whose encoding is the current platform encoding.

Parameters:

string

The string.

Returns:: The Unicode string object.

static UnicodeString ai::UnicodeString::FromPlatform ( const char * string ) [static]

Constructs a UnicodeString from a zero-terminated char array whose encoding is the current platform encoding.

Parameters:

string The char array.

Returns:: The Unicode string object.

static UnicodeString ai::UnicodeString::FromPlatform	(	const char *	string,
		size_type	count
	)			`[static]`

Constructs a UnicodeString from a non-zero-terminated char array whose encoding is the current platform encoding.

Parameters:

	string	The `char` array.
	count	The number of bytes (chars) in the string.

Returns:: The Unicode string object.

static UnicodeString ai::UnicodeString::FromRoman ( const const_PStr & pascalString ) [static]

Constructs a UnicodeString from a Pascal string whose encoding is ISO Roman/Latin.

Parameters:

pascalString

The Pascal string.

Returns:: The Unicode string object.

static UnicodeString ai::UnicodeString::FromRoman ( const std::string & string ) [static]

Constructs a UnicodeString from a std::string whose encoding is ISO Roman/Latin.

Parameters:

string

The string.

Returns:: The Unicode string object.

static UnicodeString ai::UnicodeString::FromRoman ( const char * string ) [static]

Constructs a UnicodeString from a zero-terminated char array whose encoding is ISO Roman/Latin.

Parameters:

string The char array.

Returns:: The Unicode string object.

static UnicodeString ai::UnicodeString::FromRoman	(	const char *	string,
		size_type	count
	)			`[static]`

Constructs a UnicodeString from a non-zero-terminated char array whose encoding is ISO Roman/Latin.

Parameters:

	string	The `char` array.
	count	the number of bytes (chars) in the string.

Returns:: The Unicode string object.

static UnicodeString ai::UnicodeString::FromUTF8 ( const const_PStr & pascalString ) [static]

Constructs a UnicodeString from a Pascal string whose encoding is UTF8.

Parameters:

pascalString

The Pascal string.

Returns:: The Unicode string object.

static UnicodeString ai::UnicodeString::FromUTF8 ( const std::string & string ) [static]

Constructs a UnicodeString from a std::string whose encoding is UTF8.

Parameters:

string

The string.

Returns:: The Unicode string object.

static UnicodeString ai::UnicodeString::FromUTF8 ( const char * string ) [static]

Constructs a UnicodeString from a zero-terminated char array whose encoding is UTF8.

Parameters:

string The char array.

Returns:: The Unicode string object.

size_type ai::UnicodeString::getAs	(	AICharacterEncoding	encoding,
		ai::AutoBuffer< char > &	b
	)			const

Copies the contents of this string to an ai::AutoBuffer<char>.

Parameters:

	encoding	The encoding for the result.
	b	The buffer in which to return the result. The resulting contents might not be 0 terminated.

Returns:: The number of characters (bytes) returned in the buffer.

std::string ai::UnicodeString::getInStdString ( AICharacterEncoding encoding ) const

Creates a std::string from the contents of this string.

Can throw an out-of-memory error.

Parameters:

encoding

The encoding for the result.

Returns:: The string result.

Referenced by as_Platform(), as_Roman(), and as_UTF8().

size_type ai::UnicodeString::getToBuffer	(	const PStr &	pascalString,
		size_type	bufferMax,
		AICharacterEncoding	encoding
	)			const

Copies the contents of this string to a Pascal string in a provided buffer.

Parameters:

	pascalString	A pointer to a Pascal string in which to return the 0-terminated copy.
	bufferMax	The maximum byte count to write to the buffer, including the 0 terminator, or `NULL` to return the required size.
	encoding	The encoding for the result.

Returns:: The size needed to write the entire string contents to a buffer, including a 0 terminator.

size_type ai::UnicodeString::getToBuffer	(	char *	buffer,
		size_type	bufferMax,
		AICharacterEncoding	encoding
	)			const

Copies the contents of this string to a provided buffer.

This method follows the strlcpy paradigm.

Parameters:

	buffer	A pointer to a byte array in which to return the 0-terminated copy.
	bufferMax	The maximum byte count to write to the buffer, including the 0 terminator, or `NULL` to return the required size.
	encoding	The encoding for the result.

Returns:: The size needed to write the entire string contents to a buffer, including a 0 terminator.

Referenced by as_Platform(), and as_Roman().

bool ai::UnicodeString::hasSurrogates ( ) const

Reports whether this string contains surrogate pairs.

Returns:: True if there are surrogate pairs in this string.

UnicodeString& ai::UnicodeString::insert	(	size_type	insertOffset,
		size_type	count,
		UTF32TextChar	ch
	)			`[inline]`

Inserts repeated characters into this string.

Parameters:

	insertOffset	The 0-based position index in this string after which to start the insertion.
	count	The number of copies of the character to insert.
	ch	The character to insert.

Returns:: This string object.

References insert(), and UnicodeString().

Referenced by insert().

UnicodeString & ai::UnicodeString::insert	(	size_type	insertOffset,
		const UnicodeString &	str,
		size_type	offset,
		size_type	count
	)			`[inline]`

Inserts a substring into this string.

Parameters:

	insertOffset	The 0-based position index in this string after which to start the insertion.
	str	The source string of the substring to insert.
	offset	he 0-based position index of the first character of the substring to insert.
	count	The number of characters to insert.

Returns:: This string object.

References append(), kUnicodeStringBadIndex, length(), and substr().

UnicodeString& ai::UnicodeString::insert	(	size_type	insertOffset,
		const UnicodeString &	str
	)			`[inline]`

Inserts a string into this string, inserting as many characters as will fit.

Parameters:

	insertOffset	The 0-based position index in this string after which to start the insertion.
	str	The string to be partially or wholly inserted.

Returns:: This string object.

References insert(), and npos.

Referenced by insert(), and replace().

size_type ai::UnicodeString::length ( ) const

Retrieves the number of characters (UTF code points) in this string.

Returns:: The number of UTF code points in this string.

Referenced by AIFileDialogFilters::AddFilter(), caseFind(), insert(), replace(), and size().

UnicodeString& ai::UnicodeString::normalize ( NormalizedForm form )

Normalizes this string in place into the specified form.

Normalization may require re-allocation of the string. If this happens, the method can throw out-of-memory errors. On failure, this string remains unmodified.

Parameters:

form

The form with which to normalize the string.

Returns:: A reference to this string.

bool ai::UnicodeString::operator!= ( const UnicodeString & rhs ) const [inline]

Non-equality operator.

Does a simple, direct, code-point-based comparison.

Parameters:

rhs

The string with which to compare this string.

Returns:: True if the strings are not equal.

References operator==().

UnicodeString& ai::UnicodeString::operator+= ( const UnicodeString & rhs ) [inline]

Append operator.

Parameters:

rhs

The Unicode string object to append to this one.

Returns:: A reference to this string.

References append().

UnicodeString& ai::UnicodeString::operator+= ( UTF32TextChar ch ) [inline]

Append operator.

Parameters:

ch

The character to append to this string.

Returns:: A reference to this string.

References append().

bool ai::UnicodeString::operator< ( const UnicodeString & rhs ) const [inline]

Less-than operator.

Does a simple, direct, code-point-based comparison.

Parameters:

rhs

The string with which to compare this string.

Returns:: True if this string is less than the comparison string.

References compare().

UnicodeString& ai::UnicodeString::operator= ( const UnicodeString & rhs )

Assignment operator.

Parameters:

rhs

The Unicode string object to assign into this one.

Returns:: A reference to this string.

bool ai::UnicodeString::operator== ( const UnicodeString & rhs ) const [inline]

Equality operator.

Does a simple, direct, code-point-based comparison.

Parameters:

rhs

The string with which to compare this string.

Returns:: True if the strings are equal.

References compare().

Referenced by operator!=().

UTF32TextChar ai::UnicodeString::operator[] ( size_type offset ) const

Retrieves a character from this string.

Parameters:

offset

The 0-based position index of the character.

Returns:: The character.

Note:: This behavior differs from std::basic_string operator[]. This method returns the character at the given offset. std::basic_string::operator[] returns a writeable reference to the elopement at the given offset.

void ai::UnicodeString::push_back ( UTF32TextChar ch ) [inline]

Appends a character to the end of this string.

Parameters:

ch

The character to append.

Returns:: Nothing.

References append().

UnicodeString & ai::UnicodeString::replace	(	size_type	pos,
		size_type	num,
		const UnicodeString &	str,
		size_type	startOffset,
		size_type	count
	)			`[inline]`

Replaces a substring in this string with a substring of another string.

Parameters:

	pos	The 0-based position index in this string at which to start the replacement.
	num	The number of characters in this string to replace.
	str	The replacement string.
	startOffset	The 0-based position index of the first character of the replacement substring.
	count	The number of characters in the replacement substring, starting at the offset.

Returns:: This string object.

References erase(), insert(), kUnicodeStringBadIndex, and length().

UnicodeString& ai::UnicodeString::replace	(	size_type	pos,
		size_type	num,
		const UnicodeString &	str,
		size_type	count
	)			`[inline]`

Replaces a substring in this string with a substring of another string.

Parameters:

	pos	The 0-based position index in this string at which to start the replacement.
	num	The number of characters in this string to replace.
	str	The replacement string.
	count	The number of characters in the replacement substring, starting at the first character.

Returns:: This string object.

References replace().

Referenced by replace().

UnicodeString& ai::UnicodeString::replace	(	size_type	pos,
		size_type	num,
		const UnicodeString &	str
	)			`[inline]`

Replaces a substring in this string with another string.

Parameters:

	pos	The 0-based position index in this string at which to start the replacement.
	num	The number of characters in this string to replace.
	str	The replacement string.

Returns:: This string object.

References npos, and replace().

Referenced by replace().

void ai::UnicodeString::resize	(	size_type	count,
		UTF32TextChar	ch = `UTF32TextChar()`
	)

Resizes this string, truncating it or adding characters as needed.

Parameters:

	count	The new number of characters.
	ch	The UTF code point value with which to initialize new elements, if the size of the string is increased.

Returns:: Nothing.

size_type ai::UnicodeString::rfind	(	const UnicodeString &	target,
		size_type	startOffset,
		size_type	count
	)			const

Searches for a substring within a subset of this string, moving backward from a point in this string.

Parameters:

	target	The string to search for.
	startOffset	The 0-based position index in this string at which to start the search.
	count	The number of characters in the target string to search for.

Returns:: The 0-based position index of the first character of the target substring within this string, if found, or (npos) if the target substring is not found.

size_type ai::UnicodeString::rfind	(	const UnicodeString &	target,
		size_type	startOffset = `npos`
	)			const

Searches for a string within a subset of this string, moving backward from a point in this string.

Parameters:

	target	The string to search for.
	startOffset	The 0-based position index in this string at which to start the search.

Returns:: The 0-based position index of the first character of the target string within this string, if found, or (npos) if the target string is not found.

size_type ai::UnicodeString::rfind	(	UTF32TextChar	ch,
		size_type	startOffset = `npos`
	)			const

Searches for a character in this string, moving backward from a point in this string.

Parameters:

	ch	The character to search for.
	startOffset	The 0-based position index in this string at which to start the search.

Returns:: The 0-based position index of the found character, or (npos) if the character is not found.

ai::UnicodeString::size_type ai::UnicodeString::size ( void ) const [inline]

Retrieves the number of characters (UTF code points) in this string.

This is the same as length().

Returns:: The number of UTF code points in this string.

References length().

UnicodeString ai::UnicodeString::substr	(	size_type	offset = `0`,
		size_type	count = `npos`
	)			const

Creates a copy of a substring of this string.

Parameters:

	offset	The 0-based position index of the first character to be copied to the substring.
	count	The maximum number of characters to copy to the new substring.

Returns:: A UnicodeString object containing the requested substring.

Referenced by assign(), and insert().

void ai::UnicodeString::swap ( UnicodeString & str )

Swaps the contents of this string with another string.

Parameters:

str

The string to swap.

Returns:: Nothing.

UnicodeString& ai::UnicodeString::toLower ( )

Convert the characters in this to lower case following the conventions of the default locale.

Returns:: A reference to this.

UnicodeString& ai::UnicodeString::toUpper ( )

Convert the characters in this to UPPER CASE following the conventions of the default locale.

Returns:: A reference to this.

size_type ai::UnicodeString::utf_16 ( const UTF16Char *& buffer ) const

Creates a UTF-16 string from the contents of this string, in platform byte order.

This method does not allocate any memory, and returns in constant time.

Parameters:

buffer A reference to a const pointer to UTF16Char in which to return the contents of this string as UTF-16 code units. Can be 0 if this string is empty. This buffer pointer is only valid at most for the lifetime of this string. The buffer is not guaranteed to be 0 terminated. Use as_ASUnicode() to guarantee a 0-terminated buffer.