Provides a reference to a UTF-16 character embedded in a UTF-16 string. More...

#include <Utf16CharReference.h>

Public Member Functions
	Utf16CharReference (std::basic_string< UInt16 > &codeUnitString, std::basic_string< UInt16 >::iterator &basicStringIterator, size_t codeUnitCount)
	Initializes an instance of Utf16CharReference using an iterator pointing to some code units and a count of the code units that comprise the character. More...

	Utf16CharReference (const Utf16CharReference &otherCharacterReference)
	This copy constructor initializes an instance of Utf16CharReference that is an exact copy of another Utf16CharReference object. More...

bool	operator== (const Utf16CharReference &otherCharacterReference) const
	Compares the value of this character reference to the value of another character reference and tests whether the two references contain the same character values. More...

bool	operator!= (const Utf16CharReference &otherCharacterReference) const
	Compares the value of this character reference to the value of another character reference and tests whether the two references contain different character values. More...

bool	operator== (const Utf16Char &character) const
	Compares the value of this character reference to the value of a character and tests whether both contain the same character values. More...

bool	operator!= (const Utf16Char &character) const
	Compares the value of this character reference to the value of a character and tests whether both contain different character values. More...

Utf16CharReference &	operator= (const Utf16CharReference &otherCharacterReference)
	Assigns the contents of another Utf16CharReference object to this object. More...

Utf16CharReference &	operator= (const Utf16Char &utf16Char)
	Assigns the contents of a Utf16Char object to this object. More...

UInt16 &	operator[] (const size_t index)
	Returns the code unit found at the specified index. More...

const UInt16 &	operator[] (const size_t index) const
	Returns the code unit found at the specified index. More...

	operator Utf16Char () const
	Converts this object to a Utf16Char object.

	operator Utf8Char () const
	Converts this object to a Utf8Char object. More...

void	assign_reference (const Utf16CharReference &otherCharacterReference)
	Assigns another character reference to this character reference, causing this character reference to refer to the exact same character as the other reference. More...

bool	is_valid () const
	Indicates whether this character is a valid UTF-16 character. More...

bool	reference_equal (const Utf16CharReference &otherCharacterReference)
	Compares this character reference to another character reference and tests whether the two references refer to the exact same character. More...

bool	reference_not_equal (const Utf16CharReference &otherCharacterReference)
	Compares this character reference to another character reference and tests whether the two references refer to different characters. More...

UInt32	to_utf_32 () const
	Converts this character to a UTF-32 code unit. More...

size_t	size () const
	Returns the number of code units in this character.

Friends
std::istream &	operator>> (std::istream &inputStream, Utf16CharReference &utf16CharReference)
	This operator converts a stream of 16-bit values to a UTF-16 character, and assigns it to a character reference. More...

std::ostream &	operator<< (std::ostream &outputStream, const Utf16CharReference &utf16CharReference)
	This operator converts the character referred to by a UTF-16 character reference to a stream of 16-bit values. More...

std::wistream &	operator>> (std::wistream &inputStream, Utf16CharReference &utf16CharReference)
	This operator converts a wide stream of 16-bit values to a UTF-16 character, and assigns it to a character reference. More...

std::wostream &	operator<< (std::wostream &outputStream, const Utf16CharReference &utf16CharReference)
	This operator converts the character referred to by a UTF-16 character reference to a wide stream of 16-bit values. More...

Detailed Description

Provides a reference to a UTF-16 character embedded in a UTF-16 string.

Since a Utf16String provides an interface that hides the individual code units, a character is not directly pulled out of the Utf16String, but is constructed from the underlying code units. This makes it impossible for an string indexer to return a character reference that can be assigned to.

So this class acts as a reference to a character inside a string, so that if this character reference is altered, the contents of the string are altered as well. This allows us to have a read/write indexer in Utf16String instead of a read-only indexer.

Character references may become invalid if the contents of the string being referred to is modified in any way. If a string is modified by adding or removing characters, the associated character reference may then refer to another character or to somewhere outside the string. Attempting to use a character reference that no longer refers to a valid character will most likely cause a runtime error.

The only way code units can be added/subtracted in a character reference is to assign it the value of another character reference (using the assignment operator) or assign it the value of a character. The code units can be individually read and written to, but the number of code units cannot be changed through individual manipulation. Attempting to access a non-existant code unit will result in an assertion failure when a debug build and undefined behavior in a non-debug build.

Utf16Char and Utf16CharReference objects can be assigned to each other or converted from one to the other.

Constructor & Destructor Documentation

UtfString::Utf16CharReference::Utf16CharReference	(	std::basic_string< UInt16 > &	codeUnitString,
		std::basic_string< UInt16 >::iterator &	basicStringIterator,
		size_t	codeUnitCount
	)

Initializes an instance of Utf16CharReference using an iterator pointing to some code units and a count of the code units that comprise the character.

This constructor assumes that codeUnitCount is less than the maximum number of code units allowed by the UTF-16 encoding.

Parameters

[in]	codeUnitString	The string containing the code units being referenced by this character reference
[in]	basicStringIterator	An iterator pointing to the code units to be stored in this character reference
[in]	codeUnitCount	The number of code units that comprise this character

UtfString::Utf16CharReference::Utf16CharReference ( const Utf16CharReference & otherCharacterReference)

This copy constructor initializes an instance of Utf16CharReference that is an exact copy of another Utf16CharReference object.

Parameters

[in] otherCharacterReference The Utf16CharReference object that is to be exactly copied

Member Function Documentation

void UtfString::Utf16CharReference::assign_reference ( const Utf16CharReference & otherCharacterReference)

Assigns another character reference to this character reference, causing this character reference to refer to the exact same character as the other reference.

Note that this function does not copy the value of the other character reference and assign it to the value of this character reference. To do that, use the assignment operator.

Parameters

[in] otherCharacterReference The reference to be assigned to this reference.

bool UtfString::Utf16CharReference::is_valid ( ) const

Indicates whether this character is a valid UTF-16 character.

Returns: true if the code points in this character represent a valid UTF-16 character, otherwise false

UtfString::Utf16CharReference::operator Utf8Char ( ) const

Converts this object to a Utf8Char object.

This operator assumes that this character is a valid UTF-16 character.

See Also: Utf16CharReference::is_valid()

bool UtfString::Utf16CharReference::operator!= ( const Utf16CharReference & otherCharacterReference) const

Compares the value of this character reference to the value of another character reference and tests whether the two references contain different character values.

This type of equality checking checks to see whether the character values of the two references are not equal. This does not check whether the references are different. To test for that type of reference inequality, use the reference_not_equal() function.

Parameters

[in] otherCharacterReference The character reference to be compared with this character reference

Returns: true if the two character values are the same, otherwise false

bool UtfString::Utf16CharReference::operator!= ( const Utf16Char & character) const

Compares the value of this character reference to the value of a character and tests whether both contain different character values.

Parameters

[in] character The character to be compared with this character reference

Returns: true if the two character values are the same, otherwise false

Utf16CharReference& UtfString::Utf16CharReference::operator= ( const Utf16CharReference & otherCharacterReference)

Assigns the contents of another Utf16CharReference object to this object.

The contents of the other reference are assigned to this reference. This does not cause the this reference to refer to the same character as the other reference. To have this reference refer to the exact same character as another reference, use the assign_reference() function.

Note that when the contents of this object are changed, the change is propogated to the referenced Utf16String object.

Parameters

[in] otherCharacterReference The other Utf16CharReference object whose contents are to be assigned to this object

Returns: A reference to this object

Utf16CharReference& UtfString::Utf16CharReference::operator= ( const Utf16Char & utf16Char)

Assigns the contents of a Utf16Char object to this object.

Note that when the contents of this object are changed, the change is propogated to the referenced Utf16String object.

Parameters

[in] utf16Char The Utf16Char object whose contents are to be assigned to this object

Returns: A reference to this object

bool UtfString::Utf16CharReference::operator== ( const Utf16CharReference & otherCharacterReference) const

Compares the value of this character reference to the value of another character reference and tests whether the two references contain the same character values.

This type of equality checking checks to see whether the character values of the two references are equal. This does not check whether the references refer to the same character in the same string. To test for that type of reference equality, use the reference_equal() function.

Parameters

[in] otherCharacterReference The character reference to be compared with this character reference

Returns: true if the two character values are the same, otherwise false

bool UtfString::Utf16CharReference::operator== ( const Utf16Char & character) const

Compares the value of this character reference to the value of a character and tests whether both contain the same character values.

Parameters

[in] character The character to be compared with this character reference

Returns: true if the two character values are the same, otherwise false

UInt16& UtfString::Utf16CharReference::operator[] ( const size_t index)

Returns the code unit found at the specified index.

This operator does not check for the validity of the index, so it assumes that index is less than the maximum number of code units allowed by the UTF-16 encoding, and that index < size().

Parameters

[in] index The index identifying the code unit to be retrieved

Returns: The code unit found at the specified index

const UInt16& UtfString::Utf16CharReference::operator[] ( const size_t index) const

Returns the code unit found at the specified index.

This operator does not check for the validity of the index, so it assumes that index is less than the maximum number of code units allowed by the UTF-16 encoding, and that index < size().

Parameters

[in] index The index identifying the code unit to be retrieved

Returns: The code unit found at the specified index

bool UtfString::Utf16CharReference::reference_equal ( const Utf16CharReference & otherCharacterReference)

Compares this character reference to another character reference and tests whether the two references refer to the exact same character.

This type of equality checking checks to see whether the two references refer to the exact same character in the same Utf16String. This does not check whether the character values are equal. To test for that type of equality, use the == operator.

Parameters

[in] otherCharacterReference The character reference to be compared with this character reference

Returns: true if this character reference refers to the exact same character as the other reference

bool UtfString::Utf16CharReference::reference_not_equal ( const Utf16CharReference & otherCharacterReference)

Compares this character reference to another character reference and tests whether the two references refer to different characters.

This type of equality checking checks to see whether the two references refer to different characters. This does not check whether the character values are not equal, but rather their references. To test for value inequality, use the != operator.

Parameters

[in] otherCharacterReference The character reference to be compared with this character reference

Returns: true if this character reference refers to a differemt character as the other reference

UInt32 UtfString::Utf16CharReference::to_utf_32 ( ) const

Converts this character to a UTF-32 code unit.

This function assumes that size() is 1 or 2.

Returns: This character as a UTF-32 code unit

Friends And Related Function Documentation

std::ostream& operator<<	(	std::ostream &	outputStream,
		const Utf16CharReference &	utf16CharReference
	)

friend

This operator converts the character referred to by a UTF-16 character reference to a stream of 16-bit values.

No checks for validity are done, so the resulting UTF-16 stream may or may contain a valid UTF-16 character.

Parameters

[in]	outputStream	The output stream to which the contents of the UTF-16 character are to be written
[in]	utf16CharReference	A reference to the UTF-16 character to be written to the output stream

std::wostream& operator<<	(	std::wostream &	outputStream,
		const Utf16CharReference &	utf16CharReference
	)

friend

This operator converts the character referred to by a UTF-16 character reference to a wide stream of 16-bit values.

No checks for validity are done, so the resulting UTF-16 stream may or may contain a valid UTF-16 character.

Parameters

[in]	outputStream	The wide output stream to which the contents of the UTF-16 character are to be written
[in]	utf16CharReference	A reference to the UTF-16 character to be written to the output stream

std::istream& operator>>	(	std::istream &	inputStream,
		Utf16CharReference &	utf16CharReference
	)

friend

This operator converts a stream of 16-bit values to a UTF-16 character, and assigns it to a character reference.

This function clears the contents of utf16CharReference before the stream is converted. In addition this function assumes that the stream being converted is of the same endianness as the machine on which this function was compiled.

Parameters

[in]	inputStream	The input stream containing 16-bit values to be converted to a UTF-16 string
[in]	utf16CharReference	The character reference object to which the converted UTF-16 character will be assigned

std::wistream& operator>>	(	std::wistream &	inputStream,
		Utf16CharReference &	utf16CharReference
	)

friend

This operator converts a wide stream of 16-bit values to a UTF-16 character, and assigns it to a character reference.

This function clears the contents of utf16CharReference before the stream is converted. In addition this function assumes that the stream being converted is of the same endianness as the machine on which this function was compiled.

Parameters

[in]	inputStream	The wide input stream containing 16-bit values to be converted to a UTF-16 string
[in]	utf16CharReference	The character reference object to which the converted UTF-16 character will be assigned

The documentation for this class was generated from the following file:

C:/Development/Libraries/UtfString/include/utfstring/Utf16CharReference.h

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation