SFML - Simple and Fast Multimedia Library

SFML

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

#include <String.hpp>

Public Types

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

Public Member Functions

 String ()
 Default constructor. More...
 
 String (char ansiChar, const std::locale &locale=std::locale())
 Construct from a single ANSI character and a locale. More...
 
 String (wchar_t wideChar)
 Construct from single wide character. More...
 
 String (Uint32 utf32Char)
 Construct from single UTF-32 character. More...
 
 String (const char *ansiString, const std::locale &locale=std::locale())
 Construct from a null-terminated C-style ANSI string and a locale. More...
 
 String (const std::string &ansiString, const std::locale &locale=std::locale())
 Construct from an ANSI string and a locale. More...
 
 String (const wchar_t *wideString)
 Construct from null-terminated C-style wide string. More...
 
 String (const std::wstring &wideString)
 Construct from a wide string. More...
 
 String (const Uint32 *utf32String)
 Construct from a null-terminated C-style UTF-32 string. More...
 
 String (const std::basic_string< Uint32 > &utf32String)
 Construct from an UTF-32 string. More...
 
 String (const String &copy)
 Copy constructor. More...
 
 operator std::string () const
 Implicit conversion operator to std::string (ANSI string) More...
 
 operator std::wstring () const
 Implicit conversion operator to std::wstring (wide string) More...
 
std::string toAnsiString (const std::locale &locale=std::locale()) const
 Convert the Unicode string to an ANSI string. More...
 
std::wstring toWideString () const
 Convert the Unicode string to a wide string. More...
 
std::basic_string< Uint8 > toUtf8 () const
 Convert the Unicode string to a UTF-8 string. More...
 
std::basic_string< Uint16 > toUtf16 () const
 Convert the Unicode string to a UTF-16 string. More...
 
std::basic_string< Uint32 > toUtf32 () const
 Convert the Unicode string to a UTF-32 string. More...
 
Stringoperator= (const String &right)
 Overload of assignment operator. More...
 
Stringoperator+= (const String &right)
 Overload of += operator to append an UTF-32 string. More...
 
Uint32 operator[] (std::size_t index) const
 Overload of [] operator to access a character by its position. More...
 
Uint32 & operator[] (std::size_t index)
 Overload of [] operator to access a character by its position. More...
 
void clear ()
 Clear the string. More...
 
std::size_t getSize () const
 Get the size of the string. More...
 
bool isEmpty () const
 Check whether the string is empty or not. More...
 
void erase (std::size_t position, std::size_t count=1)
 Erase one or more characters from the string. More...
 
void insert (std::size_t position, const String &str)
 Insert one or more characters into the string. More...
 
std::size_t find (const String &str, std::size_t start=0) const
 Find a sequence of one or more characters in the string. More...
 
void replace (std::size_t position, std::size_t length, const String &replaceWith)
 Replace a substring with another string. More...
 
void replace (const String &searchFor, const String &replaceWith)
 Replace all occurrences of a substring with a replacement string. More...
 
String substring (std::size_t position, std::size_t length=InvalidPos) const
 Return a part of the string. More...
 
const Uint32 * getData () const
 Get a pointer to the C-style array of characters. More...
 
Iterator begin ()
 Return an iterator to the beginning of the string. More...
 
ConstIterator begin () const
 Return an iterator to the beginning of the string. More...
 
Iterator end ()
 Return an iterator to the end of the string. More...
 
ConstIterator end () const
 Return an iterator to the end of the string. More...
 

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. More...
 
template<typename T >
static String fromUtf16 (T begin, T end)
 Create a new sf::String from a UTF-16 encoded string. More...
 
template<typename T >
static String fromUtf32 (T begin, T end)
 Create a new sf::String from a UTF-32 encoded string. More...
 

Static Public Attributes

static const std::size_t InvalidPos
 Represents an invalid position in the string. More...
 

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. More...
 
bool operator!= (const String &left, const String &right)
 Overload of != operator to compare two UTF-32 strings. More...
 
bool operator< (const String &left, const String &right)
 Overload of < operator to compare two UTF-32 strings. More...
 
bool operator> (const String &left, const String &right)
 Overload of > operator to compare two UTF-32 strings. More...
 
bool operator<= (const String &left, const String &right)
 Overload of <= operator to compare two UTF-32 strings. More...
 
bool operator>= (const String &left, const String &right)
 Overload of >= operator to compare two UTF-32 strings. More...
 
String operator+ (const String &left, const String &right)
 Overload of binary + operator to concatenate two strings. More...
 

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.

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;
...
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

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

Read-only iterator type.

Definition at line 53 of file String.hpp.

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

Iterator type.

Definition at line 52 of file String.hpp.

Constructor & Destructor Documentation

sf::String::String ( )

Default constructor.

This constructor creates an empty string.

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
ansiCharANSI character to convert
localeLocale to use for conversion
sf::String::String ( wchar_t  wideChar)

Construct from single wide character.

Parameters
wideCharWide character to convert
sf::String::String ( Uint32  utf32Char)

Construct from single UTF-32 character.

Parameters
utf32CharUTF-32 character to convert
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
ansiStringANSI string to convert
localeLocale to use for conversion
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
ansiStringANSI string to convert
localeLocale to use for conversion
sf::String::String ( const wchar_t *  wideString)

Construct from null-terminated C-style wide string.

Parameters
wideStringWide string to convert
sf::String::String ( const std::wstring &  wideString)

Construct from a wide string.

Parameters
wideStringWide string to convert
sf::String::String ( const Uint32 *  utf32String)

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

Parameters
utf32StringUTF-32 string to assign
sf::String::String ( const std::basic_string< Uint32 > &  utf32String)

Construct from an UTF-32 string.

Parameters
utf32StringUTF-32 string to assign
sf::String::String ( const String copy)

Copy constructor.

Parameters
copyInstance to copy

Member Function Documentation

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
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
void sf::String::clear ( )

Clear the string.

This function removes all the characters from the string.

See also
isEmpty, erase
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
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
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
positionPosition of the first character to erase
countNumber of characters to erase
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
strCharacters to find
startWhere to begin searching
Returns
Position of str in the string, or String::InvalidPos if not found
template<typename T >
static String sf::String::fromUtf16 ( begin,
end 
)
static

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

Parameters
beginForward iterator to the beginning of the UTF-16 sequence
endForward iterator to the end of the UTF-16 sequence
Returns
A sf::String containing the source string
See also
fromUtf8, fromUtf32
template<typename T >
static String sf::String::fromUtf32 ( begin,
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
beginForward iterator to the beginning of the UTF-32 sequence
endForward iterator to the end of the UTF-32 sequence
Returns
A sf::String containing the source string
See also
fromUtf8, fromUtf16
template<typename T >
static String sf::String::fromUtf8 ( begin,
end 
)
static

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

Parameters
beginForward iterator to the beginning of the UTF-8 sequence
endForward iterator to the end of the UTF-8 sequence
Returns
A sf::String containing the source string
See also
fromUtf16, fromUtf32
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
std::size_t sf::String::getSize ( ) const

Get the size of the string.

Returns
Number of characters in the string
See also
isEmpty
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
positionPosition of insertion
strCharacters to insert
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
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
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
String& sf::String::operator+= ( const String right)

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

Parameters
rightString to append
Returns
Reference to self
String& sf::String::operator= ( const String right)

Overload of assignment operator.

Parameters
rightInstance to assign
Returns
Reference to self
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
indexIndex of the character to get
Returns
Character at position index
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
indexIndex of the character to get
Returns
Reference to the character at position index
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
positionIndex of the first character to be replaced
lengthNumber of characters to replace. You can pass InvalidPos to replace all characters until the end of the string.
replaceWithString that replaces the given substring.
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
searchForThe value being searched for
replaceWithThe value that replaces found searchFor values
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
positionIndex of the first character
lengthNumber 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
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
localeLocale to use for conversion
Returns
Converted ANSI string
See also
toWideString, operator std::string
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
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
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
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

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

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

Parameters
leftLeft operand (a string)
rightRight operand (a string)
Returns
True if both strings are different
String operator+ ( const String left,
const String right 
)
related

Overload of binary + operator to concatenate two strings.

Parameters
leftLeft operand (a string)
rightRight operand (a string)
Returns
Concatenated string
bool operator< ( const String left,
const String right 
)
related

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

Parameters
leftLeft operand (a string)
rightRight operand (a string)
Returns
True if left is lexicographically before right
bool operator<= ( const String left,
const String right 
)
related

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

Parameters
leftLeft operand (a string)
rightRight operand (a string)
Returns
True if left is lexicographically before or equivalent to right
bool operator== ( const String left,
const String right 
)
related

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

Parameters
leftLeft operand (a string)
rightRight operand (a string)
Returns
True if both strings are equal
bool operator> ( const String left,
const String right 
)
related

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

Parameters
leftLeft operand (a string)
rightRight operand (a string)
Returns
True if left is lexicographically after right
bool operator>= ( const String left,
const String right 
)
related

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

Parameters
leftLeft operand (a string)
rightRight operand (a string)
Returns
True if left is lexicographically after or equivalent to right

Member Data Documentation

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: