EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2026-06-02 08:58:14
0001 //////////////////////////////////////////////////////////// 0002 // 0003 // SFML - Simple and Fast Multimedia Library 0004 // Copyright (C) 2007-2023 Laurent Gomila (laurent@sfml-dev.org) 0005 // 0006 // This software is provided 'as-is', without any express or implied warranty. 0007 // In no event will the authors be held liable for any damages arising from the use of this software. 0008 // 0009 // Permission is granted to anyone to use this software for any purpose, 0010 // including commercial applications, and to alter it and redistribute it freely, 0011 // subject to the following restrictions: 0012 // 0013 // 1. The origin of this software must not be misrepresented; 0014 // you must not claim that you wrote the original software. 0015 // If you use this software in a product, an acknowledgment 0016 // in the product documentation would be appreciated but is not required. 0017 // 0018 // 2. Altered source versions must be plainly marked as such, 0019 // and must not be misrepresented as being the original software. 0020 // 0021 // 3. This notice may not be removed or altered from any source distribution. 0022 // 0023 //////////////////////////////////////////////////////////// 0024 0025 #ifndef SFML_STRING_HPP 0026 #define SFML_STRING_HPP 0027 0028 //////////////////////////////////////////////////////////// 0029 // Headers 0030 //////////////////////////////////////////////////////////// 0031 #include <SFML/System/Export.hpp> 0032 #include <SFML/System/Utf.hpp> 0033 #include <iterator> 0034 #include <locale> 0035 #include <string> 0036 0037 0038 namespace sf 0039 { 0040 //////////////////////////////////////////////////////////// 0041 /// \brief Utility string class that automatically handles 0042 /// conversions between types and encodings 0043 /// 0044 //////////////////////////////////////////////////////////// 0045 class SFML_SYSTEM_API String 0046 { 0047 public: 0048 0049 //////////////////////////////////////////////////////////// 0050 // Types 0051 //////////////////////////////////////////////////////////// 0052 typedef std::basic_string<Uint32>::iterator Iterator; //!< Iterator type 0053 typedef std::basic_string<Uint32>::const_iterator ConstIterator; //!< Read-only iterator type 0054 0055 //////////////////////////////////////////////////////////// 0056 // Static member data 0057 //////////////////////////////////////////////////////////// 0058 static const std::size_t InvalidPos; //!< Represents an invalid position in the string 0059 0060 //////////////////////////////////////////////////////////// 0061 /// \brief Default constructor 0062 /// 0063 /// This constructor creates an empty string. 0064 /// 0065 //////////////////////////////////////////////////////////// 0066 String(); 0067 0068 //////////////////////////////////////////////////////////// 0069 /// \brief Construct from a single ANSI character and a locale 0070 /// 0071 /// The source character is converted to UTF-32 according 0072 /// to the given locale. 0073 /// 0074 /// \param ansiChar ANSI character to convert 0075 /// \param locale Locale to use for conversion 0076 /// 0077 //////////////////////////////////////////////////////////// 0078 String(char ansiChar, const std::locale& locale = std::locale()); 0079 0080 //////////////////////////////////////////////////////////// 0081 /// \brief Construct from single wide character 0082 /// 0083 /// \param wideChar Wide character to convert 0084 /// 0085 //////////////////////////////////////////////////////////// 0086 String(wchar_t wideChar); 0087 0088 //////////////////////////////////////////////////////////// 0089 /// \brief Construct from single UTF-32 character 0090 /// 0091 /// \param utf32Char UTF-32 character to convert 0092 /// 0093 //////////////////////////////////////////////////////////// 0094 String(Uint32 utf32Char); 0095 0096 //////////////////////////////////////////////////////////// 0097 /// \brief Construct from a null-terminated C-style ANSI string and a locale 0098 /// 0099 /// The source string is converted to UTF-32 according 0100 /// to the given locale. 0101 /// 0102 /// \param ansiString ANSI string to convert 0103 /// \param locale Locale to use for conversion 0104 /// 0105 //////////////////////////////////////////////////////////// 0106 String(const char* ansiString, const std::locale& locale = std::locale()); 0107 0108 //////////////////////////////////////////////////////////// 0109 /// \brief Construct from an ANSI string and a locale 0110 /// 0111 /// The source string is converted to UTF-32 according 0112 /// to the given locale. 0113 /// 0114 /// \param ansiString ANSI string to convert 0115 /// \param locale Locale to use for conversion 0116 /// 0117 //////////////////////////////////////////////////////////// 0118 String(const std::string& ansiString, const std::locale& locale = std::locale()); 0119 0120 //////////////////////////////////////////////////////////// 0121 /// \brief Construct from null-terminated C-style wide string 0122 /// 0123 /// \param wideString Wide string to convert 0124 /// 0125 //////////////////////////////////////////////////////////// 0126 String(const wchar_t* wideString); 0127 0128 //////////////////////////////////////////////////////////// 0129 /// \brief Construct from a wide string 0130 /// 0131 /// \param wideString Wide string to convert 0132 /// 0133 //////////////////////////////////////////////////////////// 0134 String(const std::wstring& wideString); 0135 0136 //////////////////////////////////////////////////////////// 0137 /// \brief Construct from a null-terminated C-style UTF-32 string 0138 /// 0139 /// \param utf32String UTF-32 string to assign 0140 /// 0141 //////////////////////////////////////////////////////////// 0142 String(const Uint32* utf32String); 0143 0144 //////////////////////////////////////////////////////////// 0145 /// \brief Construct from an UTF-32 string 0146 /// 0147 /// \param utf32String UTF-32 string to assign 0148 /// 0149 //////////////////////////////////////////////////////////// 0150 String(const std::basic_string<Uint32>& utf32String); 0151 0152 //////////////////////////////////////////////////////////// 0153 /// \brief Copy constructor 0154 /// 0155 /// \param copy Instance to copy 0156 /// 0157 //////////////////////////////////////////////////////////// 0158 String(const String& copy); 0159 0160 //////////////////////////////////////////////////////////// 0161 /// \brief Create a new sf::String from a UTF-8 encoded string 0162 /// 0163 /// \param begin Forward iterator to the beginning of the UTF-8 sequence 0164 /// \param end Forward iterator to the end of the UTF-8 sequence 0165 /// 0166 /// \return A sf::String containing the source string 0167 /// 0168 /// \see fromUtf16, fromUtf32 0169 /// 0170 //////////////////////////////////////////////////////////// 0171 template <typename T> 0172 static String fromUtf8(T begin, T end); 0173 0174 //////////////////////////////////////////////////////////// 0175 /// \brief Create a new sf::String from a UTF-16 encoded string 0176 /// 0177 /// \param begin Forward iterator to the beginning of the UTF-16 sequence 0178 /// \param end Forward iterator to the end of the UTF-16 sequence 0179 /// 0180 /// \return A sf::String containing the source string 0181 /// 0182 /// \see fromUtf8, fromUtf32 0183 /// 0184 //////////////////////////////////////////////////////////// 0185 template <typename T> 0186 static String fromUtf16(T begin, T end); 0187 0188 //////////////////////////////////////////////////////////// 0189 /// \brief Create a new sf::String from a UTF-32 encoded string 0190 /// 0191 /// This function is provided for consistency, it is equivalent to 0192 /// using the constructors that takes a const sf::Uint32* or 0193 /// a std::basic_string<sf::Uint32>. 0194 /// 0195 /// \param begin Forward iterator to the beginning of the UTF-32 sequence 0196 /// \param end Forward iterator to the end of the UTF-32 sequence 0197 /// 0198 /// \return A sf::String containing the source string 0199 /// 0200 /// \see fromUtf8, fromUtf16 0201 /// 0202 //////////////////////////////////////////////////////////// 0203 template <typename T> 0204 static String fromUtf32(T begin, T end); 0205 0206 //////////////////////////////////////////////////////////// 0207 /// \brief Implicit conversion operator to std::string (ANSI string) 0208 /// 0209 /// The current global locale is used for conversion. If you 0210 /// want to explicitly specify a locale, see toAnsiString. 0211 /// Characters that do not fit in the target encoding are 0212 /// discarded from the returned string. 0213 /// This operator is defined for convenience, and is equivalent 0214 /// to calling toAnsiString(). 0215 /// 0216 /// \return Converted ANSI string 0217 /// 0218 /// \see toAnsiString, operator std::wstring 0219 /// 0220 //////////////////////////////////////////////////////////// 0221 operator std::string() const; 0222 0223 //////////////////////////////////////////////////////////// 0224 /// \brief Implicit conversion operator to std::wstring (wide string) 0225 /// 0226 /// Characters that do not fit in the target encoding are 0227 /// discarded from the returned string. 0228 /// This operator is defined for convenience, and is equivalent 0229 /// to calling toWideString(). 0230 /// 0231 /// \return Converted wide string 0232 /// 0233 /// \see toWideString, operator std::string 0234 /// 0235 //////////////////////////////////////////////////////////// 0236 operator std::wstring() const; 0237 0238 //////////////////////////////////////////////////////////// 0239 /// \brief Convert the Unicode string to an ANSI string 0240 /// 0241 /// The UTF-32 string is converted to an ANSI string in 0242 /// the encoding defined by \a locale. 0243 /// Characters that do not fit in the target encoding are 0244 /// discarded from the returned string. 0245 /// 0246 /// \param locale Locale to use for conversion 0247 /// 0248 /// \return Converted ANSI string 0249 /// 0250 /// \see toWideString, operator std::string 0251 /// 0252 //////////////////////////////////////////////////////////// 0253 std::string toAnsiString(const std::locale& locale = std::locale()) const; 0254 0255 //////////////////////////////////////////////////////////// 0256 /// \brief Convert the Unicode string to a wide string 0257 /// 0258 /// Characters that do not fit in the target encoding are 0259 /// discarded from the returned string. 0260 /// 0261 /// \return Converted wide string 0262 /// 0263 /// \see toAnsiString, operator std::wstring 0264 /// 0265 //////////////////////////////////////////////////////////// 0266 std::wstring toWideString() const; 0267 0268 //////////////////////////////////////////////////////////// 0269 /// \brief Convert the Unicode string to a UTF-8 string 0270 /// 0271 /// \return Converted UTF-8 string 0272 /// 0273 /// \see toUtf16, toUtf32 0274 /// 0275 //////////////////////////////////////////////////////////// 0276 std::basic_string<Uint8> toUtf8() const; 0277 0278 //////////////////////////////////////////////////////////// 0279 /// \brief Convert the Unicode string to a UTF-16 string 0280 /// 0281 /// \return Converted UTF-16 string 0282 /// 0283 /// \see toUtf8, toUtf32 0284 /// 0285 //////////////////////////////////////////////////////////// 0286 std::basic_string<Uint16> toUtf16() const; 0287 0288 //////////////////////////////////////////////////////////// 0289 /// \brief Convert the Unicode string to a UTF-32 string 0290 /// 0291 /// This function doesn't perform any conversion, since the 0292 /// string is already stored as UTF-32 internally. 0293 /// 0294 /// \return Converted UTF-32 string 0295 /// 0296 /// \see toUtf8, toUtf16 0297 /// 0298 //////////////////////////////////////////////////////////// 0299 std::basic_string<Uint32> toUtf32() const; 0300 0301 //////////////////////////////////////////////////////////// 0302 /// \brief Overload of assignment operator 0303 /// 0304 /// \param right Instance to assign 0305 /// 0306 /// \return Reference to self 0307 /// 0308 //////////////////////////////////////////////////////////// 0309 String& operator =(const String& right); 0310 0311 //////////////////////////////////////////////////////////// 0312 /// \brief Overload of += operator to append an UTF-32 string 0313 /// 0314 /// \param right String to append 0315 /// 0316 /// \return Reference to self 0317 /// 0318 //////////////////////////////////////////////////////////// 0319 String& operator +=(const String& right); 0320 0321 //////////////////////////////////////////////////////////// 0322 /// \brief Overload of [] operator to access a character by its position 0323 /// 0324 /// This function provides read-only access to characters. 0325 /// Note: the behavior is undefined if \a index is out of range. 0326 /// 0327 /// \param index Index of the character to get 0328 /// 0329 /// \return Character at position \a index 0330 /// 0331 //////////////////////////////////////////////////////////// 0332 Uint32 operator [](std::size_t index) const; 0333 0334 //////////////////////////////////////////////////////////// 0335 /// \brief Overload of [] operator to access a character by its position 0336 /// 0337 /// This function provides read and write access to characters. 0338 /// Note: the behavior is undefined if \a index is out of range. 0339 /// 0340 /// \param index Index of the character to get 0341 /// 0342 /// \return Reference to the character at position \a index 0343 /// 0344 //////////////////////////////////////////////////////////// 0345 Uint32& operator [](std::size_t index); 0346 0347 //////////////////////////////////////////////////////////// 0348 /// \brief Clear the string 0349 /// 0350 /// This function removes all the characters from the string. 0351 /// 0352 /// \see isEmpty, erase 0353 /// 0354 //////////////////////////////////////////////////////////// 0355 void clear(); 0356 0357 //////////////////////////////////////////////////////////// 0358 /// \brief Get the size of the string 0359 /// 0360 /// \return Number of characters in the string 0361 /// 0362 /// \see isEmpty 0363 /// 0364 //////////////////////////////////////////////////////////// 0365 std::size_t getSize() const; 0366 0367 //////////////////////////////////////////////////////////// 0368 /// \brief Check whether the string is empty or not 0369 /// 0370 /// \return True if the string is empty (i.e. contains no character) 0371 /// 0372 /// \see clear, getSize 0373 /// 0374 //////////////////////////////////////////////////////////// 0375 bool isEmpty() const; 0376 0377 //////////////////////////////////////////////////////////// 0378 /// \brief Erase one or more characters from the string 0379 /// 0380 /// This function removes a sequence of \a count characters 0381 /// starting from \a position. 0382 /// 0383 /// \param position Position of the first character to erase 0384 /// \param count Number of characters to erase 0385 /// 0386 //////////////////////////////////////////////////////////// 0387 void erase(std::size_t position, std::size_t count = 1); 0388 0389 //////////////////////////////////////////////////////////// 0390 /// \brief Insert one or more characters into the string 0391 /// 0392 /// This function inserts the characters of \a str 0393 /// into the string, starting from \a position. 0394 /// 0395 /// \param position Position of insertion 0396 /// \param str Characters to insert 0397 /// 0398 //////////////////////////////////////////////////////////// 0399 void insert(std::size_t position, const String& str); 0400 0401 //////////////////////////////////////////////////////////// 0402 /// \brief Find a sequence of one or more characters in the string 0403 /// 0404 /// This function searches for the characters of \a str 0405 /// in the string, starting from \a start. 0406 /// 0407 /// \param str Characters to find 0408 /// \param start Where to begin searching 0409 /// 0410 /// \return Position of \a str in the string, or String::InvalidPos if not found 0411 /// 0412 //////////////////////////////////////////////////////////// 0413 std::size_t find(const String& str, std::size_t start = 0) const; 0414 0415 //////////////////////////////////////////////////////////// 0416 /// \brief Replace a substring with another string 0417 /// 0418 /// This function replaces the substring that starts at index \a position 0419 /// and spans \a length characters with the string \a replaceWith. 0420 /// 0421 /// \param position Index of the first character to be replaced 0422 /// \param length Number of characters to replace. You can pass InvalidPos to 0423 /// replace all characters until the end of the string. 0424 /// \param replaceWith String that replaces the given substring. 0425 /// 0426 //////////////////////////////////////////////////////////// 0427 void replace(std::size_t position, std::size_t length, const String& replaceWith); 0428 0429 //////////////////////////////////////////////////////////// 0430 /// \brief Replace all occurrences of a substring with a replacement string 0431 /// 0432 /// This function replaces all occurrences of \a searchFor in this string 0433 /// with the string \a replaceWith. 0434 /// 0435 /// \param searchFor The value being searched for 0436 /// \param replaceWith The value that replaces found \a searchFor values 0437 /// 0438 //////////////////////////////////////////////////////////// 0439 void replace(const String& searchFor, const String& replaceWith); 0440 0441 //////////////////////////////////////////////////////////// 0442 /// \brief Return a part of the string 0443 /// 0444 /// This function returns the substring that starts at index \a position 0445 /// and spans \a length characters. 0446 /// 0447 /// \param position Index of the first character 0448 /// \param length Number of characters to include in the substring (if 0449 /// the string is shorter, as many characters as possible 0450 /// are included). \ref InvalidPos can be used to include all 0451 /// characters until the end of the string. 0452 /// 0453 /// \return String object containing a substring of this object 0454 /// 0455 //////////////////////////////////////////////////////////// 0456 String substring(std::size_t position, std::size_t length = InvalidPos) const; 0457 0458 //////////////////////////////////////////////////////////// 0459 /// \brief Get a pointer to the C-style array of characters 0460 /// 0461 /// This functions provides a read-only access to a 0462 /// null-terminated C-style representation of the string. 0463 /// The returned pointer is temporary and is meant only for 0464 /// immediate use, thus it is not recommended to store it. 0465 /// 0466 /// \return Read-only pointer to the array of characters 0467 /// 0468 //////////////////////////////////////////////////////////// 0469 const Uint32* getData() const; 0470 0471 //////////////////////////////////////////////////////////// 0472 /// \brief Return an iterator to the beginning of the string 0473 /// 0474 /// \return Read-write iterator to the beginning of the string characters 0475 /// 0476 /// \see end 0477 /// 0478 //////////////////////////////////////////////////////////// 0479 Iterator begin(); 0480 0481 //////////////////////////////////////////////////////////// 0482 /// \brief Return an iterator to the beginning of the string 0483 /// 0484 /// \return Read-only iterator to the beginning of the string characters 0485 /// 0486 /// \see end 0487 /// 0488 //////////////////////////////////////////////////////////// 0489 ConstIterator begin() const; 0490 0491 //////////////////////////////////////////////////////////// 0492 /// \brief Return an iterator to the end of the string 0493 /// 0494 /// The end iterator refers to 1 position past the last character; 0495 /// thus it represents an invalid character and should never be 0496 /// accessed. 0497 /// 0498 /// \return Read-write iterator to the end of the string characters 0499 /// 0500 /// \see begin 0501 /// 0502 //////////////////////////////////////////////////////////// 0503 Iterator end(); 0504 0505 //////////////////////////////////////////////////////////// 0506 /// \brief Return an iterator to the end of the string 0507 /// 0508 /// The end iterator refers to 1 position past the last character; 0509 /// thus it represents an invalid character and should never be 0510 /// accessed. 0511 /// 0512 /// \return Read-only iterator to the end of the string characters 0513 /// 0514 /// \see begin 0515 /// 0516 //////////////////////////////////////////////////////////// 0517 ConstIterator end() const; 0518 0519 private: 0520 0521 friend SFML_SYSTEM_API bool operator ==(const String& left, const String& right); 0522 friend SFML_SYSTEM_API bool operator <(const String& left, const String& right); 0523 0524 //////////////////////////////////////////////////////////// 0525 // Member data 0526 //////////////////////////////////////////////////////////// 0527 std::basic_string<Uint32> m_string; //!< Internal string of UTF-32 characters 0528 }; 0529 0530 //////////////////////////////////////////////////////////// 0531 /// \relates String 0532 /// \brief Overload of == operator to compare two UTF-32 strings 0533 /// 0534 /// \param left Left operand (a string) 0535 /// \param right Right operand (a string) 0536 /// 0537 /// \return True if both strings are equal 0538 /// 0539 //////////////////////////////////////////////////////////// 0540 SFML_SYSTEM_API bool operator ==(const String& left, const String& right); 0541 0542 //////////////////////////////////////////////////////////// 0543 /// \relates String 0544 /// \brief Overload of != operator to compare two UTF-32 strings 0545 /// 0546 /// \param left Left operand (a string) 0547 /// \param right Right operand (a string) 0548 /// 0549 /// \return True if both strings are different 0550 /// 0551 //////////////////////////////////////////////////////////// 0552 SFML_SYSTEM_API bool operator !=(const String& left, const String& right); 0553 0554 //////////////////////////////////////////////////////////// 0555 /// \relates String 0556 /// \brief Overload of < operator to compare two UTF-32 strings 0557 /// 0558 /// \param left Left operand (a string) 0559 /// \param right Right operand (a string) 0560 /// 0561 /// \return True if \a left is lexicographically before \a right 0562 /// 0563 //////////////////////////////////////////////////////////// 0564 SFML_SYSTEM_API bool operator <(const String& left, const String& right); 0565 0566 //////////////////////////////////////////////////////////// 0567 /// \relates String 0568 /// \brief Overload of > operator to compare two UTF-32 strings 0569 /// 0570 /// \param left Left operand (a string) 0571 /// \param right Right operand (a string) 0572 /// 0573 /// \return True if \a left is lexicographically after \a right 0574 /// 0575 //////////////////////////////////////////////////////////// 0576 SFML_SYSTEM_API bool operator >(const String& left, const String& right); 0577 0578 //////////////////////////////////////////////////////////// 0579 /// \relates String 0580 /// \brief Overload of <= operator to compare two UTF-32 strings 0581 /// 0582 /// \param left Left operand (a string) 0583 /// \param right Right operand (a string) 0584 /// 0585 /// \return True if \a left is lexicographically before or equivalent to \a right 0586 /// 0587 //////////////////////////////////////////////////////////// 0588 SFML_SYSTEM_API bool operator <=(const String& left, const String& right); 0589 0590 //////////////////////////////////////////////////////////// 0591 /// \relates String 0592 /// \brief Overload of >= operator to compare two UTF-32 strings 0593 /// 0594 /// \param left Left operand (a string) 0595 /// \param right Right operand (a string) 0596 /// 0597 /// \return True if \a left is lexicographically after or equivalent to \a right 0598 /// 0599 //////////////////////////////////////////////////////////// 0600 SFML_SYSTEM_API bool operator >=(const String& left, const String& right); 0601 0602 //////////////////////////////////////////////////////////// 0603 /// \relates String 0604 /// \brief Overload of binary + operator to concatenate two strings 0605 /// 0606 /// \param left Left operand (a string) 0607 /// \param right Right operand (a string) 0608 /// 0609 /// \return Concatenated string 0610 /// 0611 //////////////////////////////////////////////////////////// 0612 SFML_SYSTEM_API String operator +(const String& left, const String& right); 0613 0614 #include <SFML/System/String.inl> 0615 0616 } // namespace sf 0617 0618 0619 #endif // SFML_STRING_HPP 0620 0621 0622 //////////////////////////////////////////////////////////// 0623 /// \class sf::String 0624 /// \ingroup system 0625 /// 0626 /// sf::String is a utility string class defined mainly for 0627 /// convenience. It is a Unicode string (implemented using 0628 /// UTF-32), thus it can store any character in the world 0629 /// (European, Chinese, Arabic, Hebrew, etc.). 0630 /// 0631 /// It automatically handles conversions from/to ANSI and 0632 /// wide strings, so that you can work with standard string 0633 /// classes and still be compatible with functions taking a 0634 /// sf::String. 0635 /// 0636 /// \code 0637 /// sf::String s; 0638 /// 0639 /// std::string s1 = s; // automatically converted to ANSI string 0640 /// std::wstring s2 = s; // automatically converted to wide string 0641 /// s = "hello"; // automatically converted from ANSI string 0642 /// s = L"hello"; // automatically converted from wide string 0643 /// s += 'a'; // automatically converted from ANSI string 0644 /// s += L'a'; // automatically converted from wide string 0645 /// \endcode 0646 /// 0647 /// Conversions involving ANSI strings use the default user locale. However 0648 /// it is possible to use a custom locale if necessary: 0649 /// \code 0650 /// std::locale locale; 0651 /// sf::String s; 0652 /// ... 0653 /// std::string s1 = s.toAnsiString(locale); 0654 /// s = sf::String("hello", locale); 0655 /// \endcode 0656 /// 0657 /// sf::String defines the most important functions of the 0658 /// standard std::string class: removing, random access, iterating, 0659 /// appending, comparing, etc. However it is a simple class 0660 /// provided for convenience, and you may have to consider using 0661 /// a more optimized class if your program requires complex string 0662 /// handling. The automatic conversion functions will then take 0663 /// care of converting your string to sf::String whenever SFML 0664 /// requires it. 0665 /// 0666 /// Please note that SFML also defines a low-level, generic 0667 /// interface for Unicode handling, see the sf::Utf classes. 0668 /// 0669 ////////////////////////////////////////////////////////////
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|