SFML 3.0.2
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Friends | Related Symbols | List of all members
sf::String Class Reference
System module

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

`#include <SFML/System/String.hpp>`

## Public Types
using | Iterator = std::u32string::iterator
| Iterator type.
using | ConstIterator = std::u32string::const_iterator
| Read-only iterator type.

## Public Member Functions
| String ()=default
| Default constructor.
| String (std::nullptr_t, const std::locale &={})=delete
| Deleted std::nullptr_t constructor.
| 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 (char32_t utf32Char)
| Construct from single UTF-32 character.
| 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 char32_t *utf32String)
| Construct from a null-terminated C-style UTF-32 string.
| String (std::u32string utf32String)
| Construct from an UTF-32 string.
| 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={}) const
| Convert the Unicode string to an ANSI string.
std::wstring | toWideString () const
| Convert the Unicode string to a wide string.
sf::U8String | toUtf8 () const
| Convert the Unicode string to a UTF-8 string.
std::u16string | toUtf16 () const
| Convert the Unicode string to a UTF-16 string.
std::u32string | toUtf32 () const
| Convert the Unicode string to a UTF-32 string.
String & | operator+= (const String &right)
| Overload of operator+= to append an UTF-32 string.
char32_t | operator[] (std::size_t index) const
| Overload of operator[] to access a character by its position.
char32_t & | 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 char32_t * | 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 {std::u32string::npos}
| 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 Symbols
(Note that these are not member symbols.)
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
sf::String
Utility string class that automatically handles conversions between types and encodings.
Definition String.hpp:89

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::toAnsiString
std::string toAnsiString(const std::locale &locale={}) const
Convert the Unicode string to an ANSI string.

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 88 of file String.hpp.

## Member Typedef Documentation

## ◆ ConstIterator

using sf::String::ConstIterator = std::u32string::const_iterator

Read-only iterator type.

Definition at line 95 of file String.hpp.

## ◆ Iterator

using sf::String::Iterator = std::u32string::iterator

Iterator type.

Definition at line 94 of file String.hpp.

## Constructor & Destructor Documentation

## ◆ String() [1/11]

sf::String::String | ( |  | ) |
| default

Default constructor.

This constructor creates an empty string.

## ◆ String() [2/11]

sf::String::String | ( | std::nullptr_t | ,
|  | const std::locale & | = {} )
| delete

Deleted std::nullptr_t constructor.

Disallow construction from nullptr literal

## ◆ String() [3/11]

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.

Parameters

  ansiChar | ANSI character to convert
  locale | Locale to use for conversion

## ◆ String() [4/11]

sf::String::String | ( | wchar_t | wideChar | ) |

Construct from single wide character.

Parameters

  wideChar | Wide character to convert

## ◆ String() [5/11]

sf::String::String | ( | char32_t | utf32Char | ) |

Construct from single UTF-32 character.

Parameters

  utf32Char | UTF-32 character to convert

## ◆ String() [6/11]

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.

Parameters

  ansiString | ANSI string to convert
  locale | Locale to use for conversion

## ◆ String() [7/11]

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.

Parameters

  ansiString | ANSI string to convert
  locale | Locale to use for conversion

## ◆ String() [8/11]

sf::String::String | ( | const wchar_t * | wideString | ) |

Construct from null-terminated C-style wide string.

Parameters

  wideString | Wide string to convert

## ◆ String() [9/11]

sf::String::String | ( | const std::wstring & | wideString | ) |

Construct from a wide string.

Parameters

  wideString | Wide string to convert

## ◆ String() [10/11]

sf::String::String | ( | const char32_t * | utf32String | ) |

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

Parameters

  utf32String | UTF-32 string to assign

## ◆ String() [11/11]

sf::String::String | ( | std::u32string | utf32String | ) |

Construct from an UTF-32 string.

Parameters

  utf32String | UTF-32 string to assign

## Member Function Documentation

## ◆ begin() [1/2]

Iterator sf::String::begin | ( |  | ) |
| nodiscard

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

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 | ( |  | ) |
| nodiscard

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

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

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>

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

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>

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

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 char32_t* or a std::u32string.

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>

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

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 char32_t * sf::String::getData | ( |  | ) | const
| nodiscard

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

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

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[]() [1/2]

char32_t & sf::String::operator[] | ( | std::size_t | index | ) |
| nodiscard

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]

char32_t sf::String::operator[] | ( | std::size_t | index | ) | const
| nodiscard

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

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 = {} | ) | const
| nodiscard

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::u16string sf::String::toUtf16 | ( |  | ) | const
| nodiscard

Convert the Unicode string to a UTF-16 string.

Returns
  Converted UTF-16 string

See also
  toUtf8, toUtf32

## ◆ toUtf32()

std::u32string sf::String::toUtf32 | ( |  | ) | const
| nodiscard

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()

sf::U8String sf::String::toUtf8 | ( |  | ) | const
| nodiscard

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

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 Symbol 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< [1/2]

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

## ◆ operator<() [2/2]

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== [1/2]

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

## ◆ operator==() [2/2]

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 {std::u32string::npos}
| inline static

Represents an invalid position in the string.

Definition at line 102 of file String.hpp.

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

- String.hpp