SFML - Simple and Fast Multimedia Library

SFML 3.0.0

- Main Page
- Topics
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

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>

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

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

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>

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

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}
| inlinestatic

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