sf::String Class Reference

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

#include <SFML/System/String.hpp>

Public Types
typedef std::basic_string< Uint32 >::iterator	Iterator
	Iterator type.
typedef std::basic_string< Uint32 >::const_iterator	ConstIterator
	Read-only iterator type.

Public Member Functions
	String ()
	Default constructor.
	String (char ansiChar, const std::locale &locale=std::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, const std::locale &locale=std::locale())
	Construct from a null-terminated C-style ANSI string and a locale.
	String (const std::string &ansiString, const std::locale &locale=std::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 conversion operator to std::string (ANSI string)
	operator std::wstring () const
	Implicit conversion operator to std::wstring (wide string)
std::string	toAnsiString (const std::locale &locale=std::locale()) const
	Convert the Unicode string to an ANSI string.
std::wstring	toWideString () const
	Convert the Unicode string to a wide string.
std::basic_string< Uint8 >	toUtf8 () const
	Convert the Unicode string to a UTF-8 string.
std::basic_string< Uint16 >	toUtf16 () const
	Convert the Unicode string to a UTF-16 string.
std::basic_string< Uint32 >	toUtf32 () const
	Convert the Unicode string to a UTF-32 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.
void	replace (std::size_t position, std::size_t length, const String &replaceWith)
	Replace a substring with another string.
void	replace (const String &searchFor, const String &replaceWith)
	Replace all occurrences of a substring with a replacement string.
String	substring (std::size_t position, std::size_t length=InvalidPos) const
	Return a part of 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 end of the string.
ConstIterator	end () const
	Return an iterator to the end of the string.

Static Public Member Functions
template<typename T >
static String	fromUtf8 (T begin, T end)
	Create a new sf::String from a UTF-8 encoded string.
template<typename T >
static String	fromUtf16 (T begin, T end)
	Create a new sf::String from a UTF-16 encoded string.
template<typename T >
static String	fromUtf32 (T begin, T end)
	Create a new sf::String from a UTF-32 encoded string.

Static Public Attributes
static const std::size_t	InvalidPos
	Represents an invalid position in the string.

Friends
bool	operator== (const String &left, const String &right)
bool	operator< (const String &left, const String &right)

Related Functions
(Note that these are not member functions.)
bool	operator== (const String &left, const String &right)
	Overload of == operator to compare two UTF-32 strings.
bool	operator!= (const String &left, const String &right)
	Overload of != operator to compare two UTF-32 strings.
bool	operator< (const String &left, const String &right)
	Overload of < operator to compare two UTF-32 strings.
bool	operator> (const String &left, const String &right)
	Overload of > operator to compare two UTF-32 strings.
bool	operator<= (const String &left, const String &right)
	Overload of <= operator to compare two UTF-32 strings.
bool	operator>= (const String &left, const String &right)
	Overload of >= operator to compare two UTF-32 strings.
String	operator+ (const String &left, const String &right)
	Overload of binary + operator to concatenate two 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 45 of file String.hpp.

Member Typedef Documentation

ConstIterator

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

Read-only iterator type.

Definition at line 53 of file String.hpp.

Iterator

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

Iterator type.

Definition at line 52 of file String.hpp.

Constructor & Destructor Documentation

String() [1/11]

sf::String::String

(

)

Default constructor.

This constructor creates an empty string.

String() [2/11]

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

Construct from a single ANSI character and a locale.

The source character is converted to UTF-32 according to the given locale.

Parameters

ansiChar	ANSI character to convert
locale	Locale to use for conversion

String() [3/11]

sf::String::String

(

wchar_t

wideChar

)

Construct from single wide character.

Parameters

wideChar

Wide character to convert

String() [4/11]

sf::String::String

(

Uint32

utf32Char

)

Construct from single UTF-32 character.

Parameters

utf32Char

UTF-32 character to convert

String() [5/11]

sf::String::String	(	const char *	ansiString,
		const std::locale &	locale = std::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.

Parameters

ansiString	ANSI string to convert
locale	Locale to use for conversion

String() [6/11]

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

Construct from an ANSI string and a locale.

The source string is converted to UTF-32 according to the given locale.

Parameters

ansiString	ANSI string to convert
locale	Locale to use for conversion

String() [7/11]

sf::String::String

(

const wchar_t *

wideString

)

Construct from null-terminated C-style wide string.

Parameters

wideString

Wide string to convert

String() [8/11]

sf::String::String

(

const std::wstring &

wideString

)

Construct from a wide string.

Parameters

wideString

Wide string to convert

String() [9/11]

sf::String::String

(

const Uint32 *

utf32String

)

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

Parameters

utf32String

UTF-32 string to assign

String() [10/11]

sf::String::String

(

const std::basic_string< Uint32 > &

utf32String

)

Construct from an UTF-32 string.

Parameters

utf32String

UTF-32 string to assign

String() [11/11]

sf::String::String

(

const String &

copy

)

Copy constructor.

Parameters

copy	Instance to copy

Member Function Documentation

begin() [1/2]

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

begin() [2/2]

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

clear()

void sf::String::clear

(

)

Clear the string.

This function removes all the characters from the string.

See also

isEmpty, erase

end() [1/2]

Iterator sf::String::end

(

)

Return an iterator to the end 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

end() [2/2]

ConstIterator sf::String::end

(

)

const

Return an iterator to the end 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

erase()

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

find()

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 in 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

fromUtf16()

template<typename T >

static String sf::String::fromUtf16 ( T  begin, T  end  )

static

Create a new sf::String from a UTF-16 encoded string.

Parameters

begin	Forward iterator to the beginning of the UTF-16 sequence
end	Forward iterator to the end of the UTF-16 sequence

Returns

A sf::String containing the source string

See also

fromUtf8, fromUtf32

fromUtf32()

template<typename T >

static String sf::String::fromUtf32 ( T  begin, T  end  )

static

Create a new sf::String from a UTF-32 encoded string.

This function is provided for consistency, it is equivalent to using the constructors that takes a const sf::Uint32* or a std::basic_string<sf::Uint32>.

Parameters

begin	Forward iterator to the beginning of the UTF-32 sequence
end	Forward iterator to the end of the UTF-32 sequence

Returns

A sf::String containing the source string

See also

fromUtf8, fromUtf16

fromUtf8()

template<typename T >

static String sf::String::fromUtf8 ( T  begin, T  end  )

static

Create a new sf::String from a UTF-8 encoded string.

Parameters

begin	Forward iterator to the beginning of the UTF-8 sequence
end	Forward iterator to the end of the UTF-8 sequence

Returns

A sf::String containing the source string

See also

fromUtf16, fromUtf32

getData()

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

getSize()

std::size_t sf::String::getSize

(

)

const

Get the size of the string.

Returns

Number of characters in the string

See also

isEmpty

insert()

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

isEmpty()

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

operator std::string()

sf::String::operator std::string

(

)

const

Implicit conversion operator to std::string (ANSI string)

The current global locale is used for conversion. If you want to explicitly 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

operator std::wstring()

sf::String::operator std::wstring

(

)

const

Implicit conversion 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

operator+=()

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

operator=()

String & sf::String::operator=

(

const String &

right

)

Overload of assignment operator.

Parameters

right

Instance to assign

Returns

Reference to self

operator[]() [1/2]

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: the behavior is undefined if index is out of range.

Parameters

index

Index of the character to get

Returns

Reference to the character at position index

operator[]() [2/2]

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: the behavior is undefined if index is out of range.

Parameters

index

Index of the character to get

Returns

Character at position index

replace() [1/2]

void sf::String::replace	(	const String &	searchFor,
		const String &	replaceWith
	)

Replace all occurrences of a substring with a replacement string.

This function replaces all occurrences of searchFor in this string with the string replaceWith.

Parameters

searchFor	The value being searched for
replaceWith	The value that replaces found searchFor values

replace() [2/2]

void sf::String::replace	(	std::size_t	position,
		std::size_t	length,
		const String &	replaceWith
	)

Replace a substring with another string.

This function replaces the substring that starts at index position and spans length characters with the string replaceWith.

Parameters

position	Index of the first character to be replaced
length	Number of characters to replace. You can pass InvalidPos to replace all characters until the end of the string.
replaceWith	String that replaces the given substring.

substring()

String sf::String::substring	(	std::size_t	position,
		std::size_t	length = InvalidPos
	)		const

Return a part of the string.

This function returns the substring that starts at index position and spans length characters.

Parameters

position	Index of the first character
length	Number of characters to include in the substring (if the string is shorter, as many characters as possible are included). InvalidPos can be used to include all characters until the end of the string.

Returns

String object containing a substring of this object

toAnsiString()

std::string sf::String::toAnsiString

(

const std::locale &

locale = std::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. 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

toUtf16()

std::basic_string< Uint16 > sf::String::toUtf16

(

)

const

Convert the Unicode string to a UTF-16 string.

Returns

Converted UTF-16 string

See also

toUtf8, toUtf32

toUtf32()

std::basic_string< Uint32 > sf::String::toUtf32

(

)

const

Convert the Unicode string to a UTF-32 string.

This function doesn't perform any conversion, since the string is already stored as UTF-32 internally.

Returns

Converted UTF-32 string

See also

toUtf8, toUtf16

toUtf8()

std::basic_string< Uint8 > sf::String::toUtf8

(

)

const

Convert the Unicode string to a UTF-8 string.

Returns

Converted UTF-8 string

See also

toUtf16, toUtf32

toWideString()

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

Friends And Related Function Documentation

operator!=()

bool operator!= ( const String &  left, const String &  right  )

related

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 different

operator+()

String operator+ ( const String &  left, const String &  right  )

related

Overload of binary + operator to concatenate two strings.

Parameters

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

Returns

Concatenated string

operator<()

bool operator< ( const String &  left, const String &  right  )

related

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 lexicographically before right

operator<=()

bool operator<= ( const String &  left, const String &  right  )

related

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 lexicographically before or equivalent to right

operator==()

bool operator== ( const String &  left, const String &  right  )

related

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

operator>()

bool operator> ( const String &  left, const String &  right  )

related

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 lexicographically after right

operator>=()

bool operator>= ( const String &  left, const String &  right  )

related

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 lexicographically after or equivalent to right

Member Data Documentation

InvalidPos

const std::size_t sf::String::InvalidPos

static

Represents an invalid position in the string.

Definition at line 58 of file String.hpp.

---

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

• String.hpp