sf::String Class Reference

Utility string class that automatically handles conversions between types and encodings. More...

#include <String.hpp>

List of all members.

Public Types
typedef std::basic_string < Uint32 >::iterator	Iterator
	Iterator type.
typedef std::basic_string < Uint32 >::const_iterator	ConstIterator
	Constant iterator type.
Public Member Functions
	String ()
	Default constructor.
	String (char ansiChar)
	Construct from a single ANSI character.
	String (char ansiChar, const std::locale &locale)
	Construct from a single ANSI character and a locale.
	String (wchar_t wideChar)
	Construct from single wide character.
	String (Uint32 utf32Char)
	Construct from single UTF-32 character.
	String (const char *ansiString)
	Construct from a null-terminated C-style ANSI string.
	String (const std::string &ansiString)
	Construct from an ANSI string.
	String (const char *ansiString, const std::locale &locale)
	Construct from a null-terminated C-style ANSI string and a locale.
	String (const std::string &ansiString, const std::locale &locale)
	Construct from an ANSI string and a locale.
	String (const wchar_t *wideString)
	Construct from null-terminated C-style wide string.
	String (const std::wstring &wideString)
	Construct from a wide string.
	String (const Uint32 *utf32String)
	Construct from a null-terminated C-style UTF-32 string.
	String (const std::basic_string< Uint32 > &utf32String)
	Construct from an UTF-32 string.
	String (const String &copy)
	Copy constructor.
	operator std::string () const
	Implicit cast operator to std::string (ANSI string).
	operator std::wstring () const
	Implicit cast operator to std::wstring (wide string).
std::string	ToAnsiString () const
	Convert the unicode string to an ANSI string.
std::string	ToAnsiString (const std::locale &locale) const
	Convert the unicode string to an ANSI string.
std::wstring	ToWideString () const
	Convert the unicode string to a wide string.
String &	operator= (const String &right)
	Overload of assignment operator.
String &	operator+= (const String &right)
	Overload of += operator to append an UTF-32 string.
Uint32	operator[] (std::size_t index) const
	Overload of [] operator to access a character by its position.
Uint32 &	operator[] (std::size_t index)
	Overload of [] operator to access a character by its position.
void	Clear ()
	Clear the string.
std::size_t	GetSize () const
	Get the size of the string.
bool	IsEmpty () const
	Check whether the string is empty or not.
void	Erase (std::size_t position, std::size_t count=1)
	Erase one or more characters from the string.
void	Insert (std::size_t position, const String &str)
	Insert one or more characters into the string.
std::size_t	Find (const String &str, std::size_t start=0) const
	Find a sequence of one or more characters in the string.
const Uint32 *	GetData () const
	Get a pointer to the C-style array of characters.
Iterator	Begin ()
	Return an iterator to the beginning of the string.
ConstIterator	Begin () const
	Return an iterator to the beginning of the string.
Iterator	End ()
	Return an iterator to the beginning of the string.
ConstIterator	End () const
	Return an iterator to the beginning of the string.
Static Public Attributes
static const std::size_t	InvalidPos = std::basic_string<Uint32>::npos
	Represents an invalid position in the string.
Friends
SFML_API bool	operator== (const String &left, const String &right)
	Overload of == operator to compare two UTF-32 strings.
SFML_API bool	operator< (const String &left, const String &right)
	Overload of < operator to compare two UTF-32 strings.

---

Detailed Description

Utility string class that automatically handles conversions between types and encodings.

sf::String is a utility string class defined mainly for convenience.

It is a Unicode string (implemented using UTF-32), thus it can store any character in the world (european, chinese, arabic, hebrew, etc.).

It automatically handles conversions from/to ANSI and wide strings, so that you can work with standard string classes and still be compatible with functions taking a sf::String.

 sf::String s;

 std::string s1 = s;  // automatically converted to ANSI string
 std::wstring s2 = s; // automatically converted to wide string
 s = "hello";         // automatically converted from ANSI string
 s = L"hello";        // automatically converted from wide string
 s += 'a';            // automatically converted from ANSI string
 s += L'a';           // automatically converted from wide string

Conversions involving ANSI strings use the default user locale. However it is possible to use a custom locale if necessary:

 std::locale locale;
 sf::String s;
 ...
 std::string s1 = s.ToAnsiString(locale);
 s = sf::String("hello", locale);

sf::String defines the most important functions of the standard std::string class: removing, random access, iterating, appending, comparing, etc. However it is a simple class provided for convenience, and you may have to consider using a more optimized class if your program requires complex string handling. The automatic conversion functions will then take care of converting your string to sf::String whenever SFML requires it.

Please note that SFML also defines a low-level, generic interface for Unicode handling, see the sf::Utf classes.

Definition at line 43 of file String.hpp.

---

Member Typedef Documentation

typedef std::basic_string<Uint32>::const_iterator sf::String::ConstIterator

Constant iterator type.

Definition at line 51 of file String.hpp.

typedef std::basic_string<Uint32>::iterator sf::String::Iterator

Iterator type.

Definition at line 50 of file String.hpp.

---

Constructor & Destructor Documentation

sf::String::String

(

)

Default constructor.

This constructor creates an empty string.

Definition at line 43 of file String.cpp.

sf::String::String

(

char

ansiChar

)

Construct from a single ANSI character.

The source character is converted to UTF-32 according to the current locale. See the other constructor for explicitely passing the locale to use.

Parameters:

ansiString

ANSI character to convert

Definition at line 49 of file String.cpp.

sf::String::String	(	char	ansiChar,
		const std::locale &	locale
	)

Construct from a single ANSI character and a locale.

The source character is converted to UTF-32 according to the given locale. If you want to use the current global locale, rather use the other constructor.

Parameters:

	ansiChar	ANSI character to convert
	locale	Locale to use for conversion

Definition at line 56 of file String.cpp.

sf::String::String

(

wchar_t

wideChar

)

Construct from single wide character.

Parameters:

wideChar

Wide character to convert

Definition at line 63 of file String.cpp.

sf::String::String

(

Uint32

utf32Char

)

Construct from single UTF-32 character.

Parameters:

utf32Char

UTF-32 character to convert

Definition at line 70 of file String.cpp.

sf::String::String

(

const char *

ansiString

)

Construct from a null-terminated C-style ANSI string.

The source string is converted to UTF-32 according to the current locale. See the other constructor for explicitely passing the locale to use.

Parameters:

ansiString

ANSI string to convert

Definition at line 77 of file String.cpp.

sf::String::String

(

const std::string &

ansiString

)

Construct from an ANSI string.

The source string is converted to UTF-32 according to the current global locale. See the other constructor for explicitely passing the locale to use.

Parameters:

ansiString

ANSI string to convert

Definition at line 92 of file String.cpp.

sf::String::String	(	const char *	ansiString,
		const std::locale &	locale
	)

Construct from a null-terminated C-style ANSI string and a locale.

The source string is converted to UTF-32 according to the given locale. If you want to use the current global locale, rather use the other constructor.

Parameters:

	ansiString	ANSI string to convert
	locale	Locale to use for conversion

Definition at line 100 of file String.cpp.

sf::String::String	(	const std::string &	ansiString,
		const std::locale &	locale
	)

Construct from an ANSI string and a locale.

The source string is converted to UTF-32 according to the given locale. If you want to use the current global locale, rather use the other constructor.

Parameters:

	ansiString	ANSI string to convert
	locale	Locale to use for conversion

Definition at line 115 of file String.cpp.

sf::String::String

(

const wchar_t *

wideString

)

Construct from null-terminated C-style wide string.

Parameters:

wideString

Wide string to convert

Definition at line 123 of file String.cpp.

sf::String::String

(

const std::wstring &

wideString

)

Construct from a wide string.

Parameters:

wideString

Wide string to convert

Definition at line 138 of file String.cpp.

sf::String::String

(

const Uint32 *

utf32String

)

Construct from a null-terminated C-style UTF-32 string.

Parameters:

utf32String

UTF-32 string to assign

Definition at line 146 of file String.cpp.

sf::String::String

(

const std::basic_string< Uint32 > &

utf32String

)

Construct from an UTF-32 string.

Parameters:

utf32String

UTF-32 string to assign

Definition at line 154 of file String.cpp.

sf::String::String

(

const String &

copy

)

Copy constructor.

Parameters:

other

Instance to copy

Definition at line 161 of file String.cpp.

---

Member Function Documentation

String::ConstIterator sf::String::Begin

(

)

const

Return an iterator to the beginning of the string.

Returns:

Read-only iterator to the beginning of the string characters

See also:

End

Definition at line 310 of file String.cpp.

String::Iterator sf::String::Begin

(

)

Return an iterator to the beginning of the string.

Returns:

Read-write iterator to the beginning of the string characters

See also:

End

Definition at line 303 of file String.cpp.

void sf::String::Clear

(

)

Clear the string.

This function removes all the characters from the string.

See also:

IsEmpty, Erase

Definition at line 254 of file String.cpp.

String::ConstIterator sf::String::End

(

)

const

Return an iterator to the beginning of the string.

The end iterator refers to 1 position past the last character; thus it represents an invalid character and should never be accessed.

Returns:

Read-only iterator to the end of the string characters

See also:

Begin

Definition at line 324 of file String.cpp.

String::Iterator sf::String::End

(

)

Return an iterator to the beginning of the string.

The end iterator refers to 1 position past the last character; thus it represents an invalid character and should never be accessed.

Returns:

Read-write iterator to the end of the string characters

See also:

Begin

Definition at line 317 of file String.cpp.

void sf::String::Erase	(	std::size_t	position,
		std::size_t	count = 1
	)

Erase one or more characters from the string.

This function removes a sequence of count characters starting from position.

Parameters:

	position	Position of the first character to erase
	count	Number of characters to erase

Definition at line 275 of file String.cpp.

std::size_t sf::String::Find	(	const String &	str,
		std::size_t	start = 0
	)			const

Find a sequence of one or more characters in the string.

This function searches for the characters of str into the string, starting from start.

Parameters:

	str	Characters to find
	start	Where to begin searching

Returns:

Position of str in the string, or String::InvalidPos if not found

Definition at line 289 of file String.cpp.

const Uint32 * sf::String::GetData

(

)

const

Get a pointer to the C-style array of characters.

This functions provides a read-only access to a null-terminated C-style representation of the string. The returned pointer is temporary and is meant only for immediate use, thus it is not recommended to store it.

Returns:

Read-only pointer to the array of characters

Definition at line 296 of file String.cpp.

std::size_t sf::String::GetSize

(

)

const

Get the size of the string.

Returns:

Number of characters in the string

See also:

IsEmpty

Definition at line 261 of file String.cpp.

void sf::String::Insert	(	std::size_t	position,
		const String &	str
	)

Insert one or more characters into the string.

This function inserts the characters of str into the string, starting from position.

Parameters:

	position	Position of insertion
	str	Characters to insert

Definition at line 282 of file String.cpp.

bool sf::String::IsEmpty

(

)

const

Check whether the string is empty or not.

Returns:

True if the string is empty (i.e. contains no character)

See also:

Clear, GetSize

Definition at line 268 of file String.cpp.

sf::String::operator std::string

(

)

const

Implicit cast operator to std::string (ANSI string).

The current global locale is used for conversion. If you want to explicitely specify a locale, see ToAnsiString. Characters that do not fit in the target encoding are discarded from the returned string. This operator is defined for convenience, and is equivalent to calling ToAnsiString().

Returns:

Converted ANSI string

See also:

ToAnsiString, operator std::wstring

Definition at line 168 of file String.cpp.

sf::String::operator std::wstring

(

)

const

Implicit cast operator to std::wstring (wide string).

Characters that do not fit in the target encoding are discarded from the returned string. This operator is defined for convenience, and is equivalent to calling ToWideString().

Returns:

Converted wide string

See also:

ToWideString, operator std::string

Definition at line 175 of file String.cpp.

String & sf::String::operator+=

(

const String &

right

)

Overload of += operator to append an UTF-32 string.

Parameters:

right

String to append

Returns:

Reference to self

Definition at line 232 of file String.cpp.

String & sf::String::operator=

(

const String &

right

)

Overload of assignment operator.

Parameters:

right

Instance to assign

Returns:

Reference to self

Definition at line 224 of file String.cpp.

Uint32 & sf::String::operator[]

(

std::size_t

index

)

Overload of [] operator to access a character by its position.

This function provides read and write access to characters. Note: this function doesn't throw if index is out of range.

Parameters:

index

Index of the character to get

Returns:

Reference to the character at position index

Definition at line 247 of file String.cpp.

Uint32 sf::String::operator[]

(

std::size_t

index

)

const

Overload of [] operator to access a character by its position.

This function provides read-only access to characters. Note: this function doesn't throw if index is out of range.

Parameters:

index

Index of the character to get

Returns:

Character at position index

Definition at line 240 of file String.cpp.

std::string sf::String::ToAnsiString

(

const std::locale &

locale

)

const

Convert the unicode string to an ANSI string.

The UTF-32 string is converted to an ANSI string in the encoding defined by locale. If you want to use the current global locale, see the other overload of ToAnsiString. Characters that do not fit in the target encoding are discarded from the returned string.

Parameters:

locale

Locale to use for conversion

Returns:

Converted ANSI string

See also:

ToWideString, operator std::string

Definition at line 196 of file String.cpp.

std::string sf::String::ToAnsiString

(

)

const

Convert the unicode string to an ANSI string.

The current global locale is used for conversion. If you want to explicitely specify a locale, see the other overload of ToAnsiString. Characters that do not fit in the target encoding are discarded from the returned string.

Returns:

Converted ANSI string

See also:

ToWideString, operator std::string

Definition at line 182 of file String.cpp.

std::wstring sf::String::ToWideString

(

)

const

Convert the unicode string to a wide string.

Characters that do not fit in the target encoding are discarded from the returned string.

Returns:

Converted wide string

See also:

ToAnsiString, operator std::wstring

Definition at line 210 of file String.cpp.

---

Friends And Related Function Documentation

SFML_API bool operator<	(	const String &	left,
		const String &	right
	)			[friend]

Overload of < operator to compare two UTF-32 strings.

Parameters:

	left	Left operand (a string)
	right	Right operand (a string)

Returns:

True if left is alphabetically lesser than right

Definition at line 345 of file String.cpp.

SFML_API bool operator==	(	const String &	left,
		const String &	right
	)			[friend]

Overload of == operator to compare two UTF-32 strings.

Parameters:

	left	Left operand (a string)
	right	Right operand (a string)

Returns:

True if both strings are equal

Definition at line 331 of file String.cpp.

---

Member Data Documentation

const std::size_t sf::String::InvalidPos = std::basic_string<Uint32>::npos [static]

Represents an invalid position in the string.

Definition at line 56 of file String.hpp.

---

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

• String.hpp
• String.cpp