SFML - Simple and Fast Multimedia Library

SFML 3.1.0
Loading...
Searching...
No Matches
String.hpp
Go to the documentation of this file.
1
2//
3// SFML - Simple and Fast Multimedia Library
4// Copyright (C) 2007-2026 Laurent Gomila (laurent@sfml-dev.org)
5//
6// This software is provided 'as-is', without any express or implied warranty.
7// In no event will the authors be held liable for any damages arising from the use of this software.
8//
9// Permission is granted to anyone to use this software for any purpose,
10// including commercial applications, and to alter it and redistribute it freely,
11// subject to the following restrictions:
12//
13// 1. The origin of this software must not be misrepresented;
14// you must not claim that you wrote the original software.
15// If you use this software in a product, an acknowledgment
16// in the product documentation would be appreciated but is not required.
17//
18// 2. Altered source versions must be plainly marked as such,
19// and must not be misrepresented as being the original software.
20//
21// 3. This notice may not be removed or altered from any source distribution.
22//
24
25#pragma once
26
28// Headers
30#include <SFML/System/Export.hpp>
31
32#include <SFML/System/Utf.hpp>
33
34#include <locale>
35#include <optional>
36#include <string>
37#include <string_view>
38
39#include <cstddef>
40#include <cstdint>
41
42
43namespace sf
44{
49 struct SFML_SYSTEM_API U8StringCharTraits
50{
51 // NOLINTBEGIN(readability-identifier-naming)
52 using char_type = std::uint8_t;
53 using int_type = std::char_traits<char>::int_type;
54 using off_type = std::char_traits<char>::off_type;
55 using pos_type = std::char_traits<char>::pos_type;
56 using state_type = std::char_traits<char>::state_type;
57
58 static void assign(char_type& c1, char_type c2) noexcept;
59 static char_type* assign(char_type* s, std::size_t n, char_type c);
60 static bool eq(char_type c1, char_type c2) noexcept;
61 static bool lt(char_type c1, char_type c2) noexcept;
62 static char_type* move(char_type* s1, const char_type* s2, std::size_t n);
63 static char_type* copy(char_type* s1, const char_type* s2, std::size_t n);
64 static int compare(const char_type* s1, const char_type* s2, std::size_t n);
65 static std::size_t length(const char_type* s);
66 static const char_type* find(const char_type* s, std::size_t n, const char_type& c);
67 static char_type to_char_type(int_type i) noexcept;
68 static int_type to_int_type(char_type c) noexcept;
69 static bool eq_int_type(int_type i1, int_type i2) noexcept;
70 static int_type eof() noexcept;
71 static int_type not_eof(int_type i) noexcept;
72 // NOLINTEND(readability-identifier-naming)
73};
74
83using U8String = std::basic_string<std::uint8_t, U8StringCharTraits>;
84
90class SFML_SYSTEM_API String
91{
92public:
94 // Types
96 using Iterator = std::u32string::iterator;
97 using ConstIterator = std::u32string::const_iterator;
98
100 // Static member data
102 // NOLINTBEGIN(readability-identifier-naming)
104 static inline const std::size_t InvalidPos{std::u32string::npos};
105 // NOLINTEND(readability-identifier-naming)
106
113 String() = default;
114
121 String(std::nullptr_t, const std::locale& = {}) = delete;
122
133 String(char ansiChar, const std::locale& locale = {});
134
141 String(wchar_t wideChar);
142
149 String(char32_t utf32Char);
150
161 String(const char* ansiString, const std::locale& locale = {});
162
173 String(const std::string& ansiString, const std::locale& locale = {});
174
185 String(std::string_view ansiString, const std::locale& locale = {});
186
193 String(const wchar_t* wideString);
194
201 String(const std::wstring& wideString);
202
209 String(std::wstring_view wideString);
210
217 String(const char32_t* utf32String);
218
225 String(std::u32string utf32String);
226
233 String(std::u32string_view utf32String);
234
247 template <typename T>
248 [[nodiscard]] static String fromUtf8(T begin, T end, std::optional<char32_t> replacement = std::nullopt);
249
262 template <typename T>
263 [[nodiscard]] static String fromUtf16(T begin, T end, std::optional<char32_t> replacement = std::nullopt);
264
280 template <typename T>
281 [[nodiscard]] static String fromUtf32(T begin, T end);
282
298 [[deprecated("Use toAnsiString() instead")]] operator std::string() const;
299
313 [[deprecated("Use toWideString() instead")]] operator std::wstring() const;
314
329 [[nodiscard]] std::string toAnsiString(const std::locale& locale = {},
330 std::optional<char> replacement = std::nullopt) const;
331
342 [[nodiscard]] std::wstring toWideString(std::optional<wchar_t> replacement = std::nullopt) const;
343
354 [[nodiscard]] sf::U8String toUtf8(std::optional<std::uint8_t> replacement = std::nullopt) const;
355
366 [[nodiscard]] std::u16string toUtf16(std::optional<std::uint16_t> replacement = std::nullopt) const;
367
379 [[nodiscard]] std::u32string toUtf32() const;
380
389 String& operator+=(const String& right);
390
402 [[nodiscard]] char32_t operator[](std::size_t index) const;
403
415 [[nodiscard]] char32_t& operator[](std::size_t index);
416
425 void clear();
426
435 [[nodiscard]] std::size_t getSize() const;
436
445 [[nodiscard]] bool isEmpty() const;
446
457 void erase(std::size_t position, std::size_t count = 1);
458
469 void insert(std::size_t position, const String& str);
470
483 [[nodiscard]] std::size_t find(const String& str, std::size_t start = 0) const;
484
497 void replace(std::size_t position, std::size_t length, const String& replaceWith);
498
509 void replace(const String& searchFor, const String& replaceWith);
510
526 [[nodiscard]] String substring(std::size_t position, std::size_t length = InvalidPos) const;
527
539 [[nodiscard]] const char32_t* getData() const;
540
549 [[nodiscard]] Iterator begin();
550
559 [[nodiscard]] ConstIterator begin() const;
560
573 [[nodiscard]] Iterator end();
574
587 [[nodiscard]] ConstIterator end() const;
588
608 [[nodiscard]] bool isGraphemeBoundary(std::size_t position) const;
609
626 [[nodiscard]] bool isWordBoundary(std::size_t position) const;
627
641 [[nodiscard]] bool isSentenceBoundary(std::size_t position) const;
642
643private:
644#if defined(SFML_SYSTEM_WINDOWS)
645 friend SFML_SYSTEM_API bool operator==(const String& left, const String& right);
646 friend SFML_SYSTEM_API bool operator<(const String& left, const String& right);
647#else
648 friend bool operator==(const String& left, const String& right);
649 friend bool operator<(const String& left, const String& right);
650#endif
651
653 // Member data
655 std::u32string m_string;
656};
657
668[[nodiscard]] SFML_SYSTEM_API bool operator==(const String& left, const String& right);
669
680[[nodiscard]] SFML_SYSTEM_API bool operator!=(const String& left, const String& right);
681
692[[nodiscard]] SFML_SYSTEM_API bool operator<(const String& left, const String& right);
693
704[[nodiscard]] SFML_SYSTEM_API bool operator>(const String& left, const String& right);
705
716[[nodiscard]] SFML_SYSTEM_API bool operator<=(const String& left, const String& right);
717
728[[nodiscard]] SFML_SYSTEM_API bool operator>=(const String& left, const String& right);
729
740[[nodiscard]] SFML_SYSTEM_API String operator+(const String& left, const String& right);
741
742} // namespace sf
743
744#include <SFML/System/String.inl>
745
746
Export.hpp
SFML_SYSTEM_API
#define SFML_SYSTEM_API
Definition System/Export.hpp:42
Utf.hpp
sf::String::fromUtf16
static String fromUtf16(T begin, T end, std::optional< char32_t > replacement=std::nullopt)
Create a new sf::String from a UTF-16 encoded string.
sf::String::toUtf8
sf::U8String toUtf8(std::optional< std::uint8_t > replacement=std::nullopt) const
Convert the Unicode string to a UTF-8 string.
sf::String::begin
ConstIterator begin() const
Return an iterator to the beginning of the string.
sf::String::getData
const char32_t * getData() const
Get a pointer to the C-style array of characters.
sf::String::String
String(const std::string &ansiString, const std::locale &locale={})
Construct from an ANSI string and a locale.
sf::String::operator>=
bool operator>=(const String &left, const String &right)
Overload of operator>= to compare two UTF-32 strings.
sf::String::String
String()=default
Default constructor.
sf::String::String
String(std::string_view ansiString, const std::locale &locale={})
Construct from an ANSI string view and a locale.
sf::String::toAnsiString
std::string toAnsiString(const std::locale &locale={}, std::optional< char > replacement=std::nullopt) const
Convert the Unicode string to an ANSI string.
sf::String::isEmpty
bool isEmpty() const
Check whether the string is empty or not.
sf::String::String
String(std::wstring_view wideString)
Construct from a wide string view.
sf::String::String
String(std::u32string utf32String)
Construct from an UTF-32 string.
sf::String::clear
void clear()
Clear the string.
sf::String::operator!=
bool operator!=(const String &left, const String &right)
Overload of operator!= to compare two UTF-32 strings.
sf::String::operator==
friend bool operator==(const String &left, const String &right)
sf::String::substring
String substring(std::size_t position, std::size_t length=InvalidPos) const
Return a part of the string.
sf::String::String
String(char ansiChar, const std::locale &locale={})
Construct from a single ANSI character and a locale.
sf::String::toWideString
std::wstring toWideString(std::optional< wchar_t > replacement=std::nullopt) const
Convert the Unicode string to a wide string.
sf::String::operator<
friend bool operator<(const String &left, const String &right)
sf::String::String
String(const wchar_t *wideString)
Construct from null-terminated C-style wide string.
sf::String::toUtf32
std::u32string toUtf32() const
Convert the Unicode string to a UTF-32 string.
sf::String::String
String(const std::wstring &wideString)
Construct from a wide string.
sf::String::operator[]
char32_t operator[](std::size_t index) const
Overload of operator[] to access a character by its position.
sf::String::isSentenceBoundary
bool isSentenceBoundary(std::size_t position) const
Check if the position before a character is a sentence boundary.
sf::String::String
String(const char *ansiString, const std::locale &locale={})
Construct from a null-terminated C-style ANSI string and a locale.
sf::String::replace
void replace(const String &searchFor, const String &replaceWith)
Replace all occurrences of a substring with a replacement string.
sf::String::begin
Iterator begin()
Return an iterator to the beginning of the string.
sf::String::toUtf16
std::u16string toUtf16(std::optional< std::uint16_t > replacement=std::nullopt) const
Convert the Unicode string to a UTF-16 string.
sf::String::find
std::size_t find(const String &str, std::size_t start=0) const
Find a sequence of one or more characters in the string.
sf::String::erase
void erase(std::size_t position, std::size_t count=1)
Erase one or more characters from the string.
sf::String::String
String(char32_t utf32Char)
Construct from single UTF-32 character.
sf::String::fromUtf32
static String fromUtf32(T begin, T end)
Create a new sf::String from a UTF-32 encoded string.
sf::String::InvalidPos
static const std::size_t InvalidPos
Represents an invalid position in the string.
Definition String.hpp:104
sf::String::operator<=
bool operator<=(const String &left, const String &right)
Overload of operator<= to compare two UTF-32 strings.
sf::String::operator[]
char32_t & operator[](std::size_t index)
Overload of operator[] to access a character by its position.
sf::String::ConstIterator
std::u32string::const_iterator ConstIterator
Read-only iterator type.
Definition String.hpp:97
sf::String::end
Iterator end()
Return an iterator to the end of the string.
sf::String::operator>
bool operator>(const String &left, const String &right)
Overload of operator> to compare two UTF-32 strings.
sf::String::String
String(const char32_t *utf32String)
Construct from a null-terminated C-style UTF-32 string.
sf::String::isGraphemeBoundary
bool isGraphemeBoundary(std::size_t position) const
Check if the position before a character is a grapheme boundary.
sf::String::insert
void insert(std::size_t position, const String &str)
Insert one or more characters into the string.
sf::String::isWordBoundary
bool isWordBoundary(std::size_t position) const
Check if the position before a character is a word boundary.
sf::String::String
String(std::u32string_view utf32String)
Construct from an UTF-32 string view.
sf::String::replace
void replace(std::size_t position, std::size_t length, const String &replaceWith)
Replace a substring with another string.
sf::String::fromUtf8
static String fromUtf8(T begin, T end, std::optional< char32_t > replacement=std::nullopt)
Create a new sf::String from a UTF-8 encoded string.
sf::String::getSize
std::size_t getSize() const
Get the size of the string.
sf::String::Iterator
std::u32string::iterator Iterator
Iterator type.
Definition String.hpp:96
sf::String::String
String(wchar_t wideChar)
Construct from single wide character.
sf::String::operator+
String operator+(const String &left, const String &right)
Overload of binary operator+ to concatenate two strings.
sf::String::end
ConstIterator end() const
Return an iterator to the end of the string.
sf::String::String
String(std::nullptr_t, const std::locale &={})=delete
Deleted std::nullptr_t constructor.
sf::String::operator+=
String & operator+=(const String &right)
Overload of operator+= to append an UTF-32 string.
sf
Definition AudioResource.hpp:36
sf::U8String
std::basic_string< std::uint8_t, U8StringCharTraits > U8String
Portable replacement for std::basic_string<std::uint8_t>.
Definition String.hpp:83
sf::U8StringCharTraits
Character traits for std::uint8_t.
Definition String.hpp:50
sf::U8StringCharTraits::eq_int_type
static bool eq_int_type(int_type i1, int_type i2) noexcept
sf::U8StringCharTraits::assign
static void assign(char_type &c1, char_type c2) noexcept
sf::U8StringCharTraits::copy
static char_type * copy(char_type *s1, const char_type *s2, std::size_t n)
sf::U8StringCharTraits::eq
static bool eq(char_type c1, char_type c2) noexcept
sf::U8StringCharTraits::to_int_type
static int_type to_int_type(char_type c) noexcept
sf::U8StringCharTraits::eof
static int_type eof() noexcept
sf::U8StringCharTraits::move
static char_type * move(char_type *s1, const char_type *s2, std::size_t n)
sf::U8StringCharTraits::int_type
std::char_traits< char >::int_type int_type
Definition String.hpp:53
sf::U8StringCharTraits::compare
static int compare(const char_type *s1, const char_type *s2, std::size_t n)
sf::U8StringCharTraits::length
static std::size_t length(const char_type *s)
sf::U8StringCharTraits::state_type
std::char_traits< char >::state_type state_type
Definition String.hpp:56
sf::U8StringCharTraits::lt
static bool lt(char_type c1, char_type c2) noexcept
sf::U8StringCharTraits::not_eof
static int_type not_eof(int_type i) noexcept
sf::U8StringCharTraits::pos_type
std::char_traits< char >::pos_type pos_type
Definition String.hpp:55
sf::U8StringCharTraits::find
static const char_type * find(const char_type *s, std::size_t n, const char_type &c)
sf::U8StringCharTraits::to_char_type
static char_type to_char_type(int_type i) noexcept
sf::U8StringCharTraits::off_type
std::char_traits< char >::off_type off_type
Definition String.hpp:54
sf::U8StringCharTraits::assign
static char_type * assign(char_type *s, std::size_t n, char_type c)
sf::U8StringCharTraits::char_type
std::uint8_t char_type
Definition String.hpp:52