Provides a copy of a UTF-16 character embedded in a UTF-16 string. More...

#include <Utf16Char.h>

Public Member Functions
	Utf16Char ()
	Initializes an empty Utf16Char.

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

	Utf16Char (const std::basic_string< UInt16 >::const_iterator &basicStringIterator, size_t codeUnitCount)
	Initializes an instance of Utf16Char using an const_iterator pointing to some code units and a count of the code units that comprise the character. More...

	Utf16Char (const wchar_t wideCharacter)
	Initializes an instance of Utf16Char using a wide character. More...

	Utf16Char (const char character)
	Initializes an instance of Utf16Char using an 8-bit ASCII character. More...

	Utf16Char (const wchar_t *wideCharacter)
	Initializes an instance of Utf16Char using a variable-code-unit wide character. More...

	Utf16Char (const Utf16Char &character)
	Initializes an instance of Utf16Char using another instance of Utf16Char. More...

virtual	~Utf16Char ()
	The class destructor.

bool	operator== (const Utf16Char &otherCharacter) const
	Compares the value of this character to the value of another character and tests whether the two character values are the same. More...

bool	operator!= (const Utf16Char &otherCharacter) const
	Compares the value of this character to the value of another character and tests whether the two character values are the different. More...

bool	operator== (const Utf16CharReference &characterReference) const
	Compares the value of this character to the value of a character reference and tests whether the two character values are the same. More...

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

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

Utf16Char &	operator= (const Utf16CharReference &characterReference)
	Assigns the contents of a Utf16CharReference 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 Utf8Char () const
	Converts this object to a Utf8Char object. More...

const UInt16 *	c_str () const
	Returns c-style version of this character as an array of 16-bit code units. More...

void	clear ()
	Clears the contents of the character, making it an empty character.

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

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

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

Friends
std::istream &	operator>> (std::istream &inputStream, Utf16Char &utf16Char)
	This operator converts a stream of 16-bit values to a UTF-16 character. More...

std::ostream &	operator<< (std::ostream &outputStream, const Utf16Char &utf16Char)
	This operator converts a UTF-16 character to a stream of 16-bit values. More...

std::wistream &	operator>> (std::wistream &inputStream, Utf16Char &utf16Char)
	This operator converts a wide stream of 16-bit values to a UTF-16 character. More...

std::wostream &	operator<< (std::wostream &outputStream, const Utf16Char &utf16Char)
	This operator converts a UTF-16 character to a wide stream of 16-bit values. More...

Detailed Description

Provides a copy of 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 class holds a copy of those code units as a single character. Changing the value of a Utf16Char will not cause anything to be changed anywhere else.

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

Constructor & Destructor Documentation

UtfString::Utf16Char::Utf16Char	(	const std::basic_string< UInt16 >::iterator &	basicStringIterator,
		size_t	codeUnitCount
	)

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

This constructor assumes that index is less than the maximum number of code units allowed by the UTF-16 encoding. This constructor also assumes that there are at least codeUnitCount code units available in the string from the location of the iterator. If the iterator is pointing to the last one-code-unit character, and a codeUnitCount of 2 is passed in, this constructor will read past the end of the string and a crash will result.

Parameters

[in]	basicStringIterator	An iterator pointing to the code units to be stored in this character
[in]	codeUnitCount	The number of code units that comprise this character

UtfString::Utf16Char::Utf16Char	(	const std::basic_string< UInt16 >::const_iterator &	basicStringIterator,
		size_t	codeUnitCount
	)

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

This constructor assumes that index is less than the maximum number of code units allowed by the UTF-16 encoding. This constructor also assumes that there are at least codeUnitCount code units available in the string from the location of the iterator. If the iterator is pointing to the last one-code-unit character, and a codeUnitCount of 2 is passed in, this constructor will read past the end of the string and a crash will result.

Parameters

[in]	basicStringIterator	An iterator pointing to the code units to be stored in this character
[in]	codeUnitCount	The number of code units that comprise this character

UtfString::Utf16Char::Utf16Char ( const wchar_t wideCharacter)

Initializes an instance of Utf16Char using a wide character.

The wide character passed into this constructor can contain only one code unit, so this constructor can only be used to initialize one-code-unit characters

Parameters

[in] wideCharacter The wide character to use in initializing this character

UtfString::Utf16Char::Utf16Char ( const char character)

Initializes an instance of Utf16Char using an 8-bit ASCII character.

The character passed into this constructor is assumed to be a complete 8-bit ASCII character, and not a code unit that comprises some UTF-8 character. Note that this constructor only handles basic ASCII, the characters that match the first 128 code points in Unicode. Extended ASCII, which varies from platform to platform, will be converted to whatever code point happens to have the same value as the extended ASCII character.

Parameters

[in] character The 8-bit ASCII character to use in initializing this character

UtfString::Utf16Char::Utf16Char ( const wchar_t * wideCharacter)

Initializes an instance of Utf16Char using a variable-code-unit wide character.

The wide character passed into this constructor is in the form of a wide character string, which can contain one or more code units. The wideCharacter parameter is assumed to be a valid pointer to a null-terminated wide character string. If the length of wideCharacter is 0, this character will be initialized as an empty character. If the length of wideCharacter is 1 or 2, the code units will be used to initialize this character, whether those code units represent a valid UTF-16 character or not (validity can be checked using the is_valid() function). If the length of wideCharacter is more than 2, only the first two code units will be used, and the rest will be ignored.

Parameters

[in] wideCharacter A wide character string containing code units to use in initializing this character

UtfString::Utf16Char::Utf16Char ( const Utf16Char & character)

Initializes an instance of Utf16Char using another instance of Utf16Char.

This is a copy constructor, and sets the constructed instance to be the same as the Utf16Char instance passed in as a parameter

Parameters

[in] character A character to use in initializing this character

Member Function Documentation

const UInt16* UtfString::Utf16Char::c_str ( ) const

Returns c-style version of this character as an array of 16-bit code units.

The c-style array is owned by this object, and the pointer returned by this function is invalidated if any non-const functions are called on this object.

Returns: A pointer to a null-terminated array of 16-bit code units

bool UtfString::Utf16Char::is_valid ( ) const

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

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

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

UtfString::Utf16Char::operator Utf8Char ( ) const

Converts this object to a Utf8Char object.

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

See Also: Utf16Char::is_valid()

bool UtfString::Utf16Char::operator!= ( const Utf16Char & otherCharacter) const

Compares the value of this character to the value of another character and tests whether the two character values are the different.

Parameters

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

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

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

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

Parameters

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

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

Utf16Char& UtfString::Utf16Char::operator= ( const Utf16Char & anotherCharacter)

Assigns the contents of another Utf16Char object to this object.

Parameters

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

Returns: A reference to this object

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

Assigns the contents of a Utf16CharReference object to this object.

Parameters

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

Returns: A reference to this object

bool UtfString::Utf16Char::operator== ( const Utf16Char & otherCharacter) const

Compares the value of this character to the value of another character and tests whether the two character values are the same.

Parameters

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

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

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

Compares the value of this character to the value of a character reference and tests whether the two character values are the same.

Parameters

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

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

UInt16& UtfString::Utf16Char::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.

Note that if the given index isn't within the bounds of the character (whether the index is valid or not), the character will be resized to allow that index to be read and written to.

Parameters

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

Returns: The code unit found at the specified index

const UInt16& UtfString::Utf16Char::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.

Note that if the given index isn't within the bounds of the character (whether the index is valid or not), the character will be not be resized, as this function can only be called on a constant.

Parameters

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

Returns: The code unit found at the specified index

UInt32 UtfString::Utf16Char::to_utf_32 ( ) const

Converts this character to a UTF-32 code point.

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 Utf16Char &	utf16Char
	)

friend

This operator converts a UTF-16 character to a stream of 16-bit values.

No checks for validity are done, so the resulting UTF-16 stream may or may not contain a valid UTF-16 character. The endianness of the bytes in stream is the same as the endiannes of them machine on which this function is compiled.

Parameters

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

std::wostream& operator<<	(	std::wostream &	outputStream,
		const Utf16Char &	utf16Char
	)

friend

This operator converts a UTF-16 character to a wide stream of 16-bit values.

No checks for validity are done, so the resulting UTF-16 stream may or may not contain a valid UTF-16 character. The endianness of the bytes in stream is the same as the endiannes of them machine on which this function is compiled.

Parameters

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

std::istream& operator>>	(	std::istream &	inputStream,
		Utf16Char &	utf16Char
	)

friend

This operator converts a stream of 16-bit values to a UTF-16 character.

This function clears the contents of utf16Char 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 character
[in]	utf16Char	The character object into which the converted UTF-16 character will be stored

std::wistream& operator>>	(	std::wistream &	inputStream,
		Utf16Char &	utf16Char
	)

friend

This operator converts a wide stream of 16-bit values to a UTF-16 character.

This function clears the contents of utf16Char 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 character
[in]	utf16Char	The character object into which the converted UTF-16 character will be stored

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

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

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation