godot-docs/classes/class_string.rst

.. Generated automatically by doc/tools/makerst.py in Godot's source tree.
.. DO NOT EDIT THIS FILE, but the doc/base/classes.xml source instead.

.. _class_String:

String
======

**Category:** Built-In Types

Brief Description
-----------------

Built-in string class.

Member Functions
----------------

+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`basename<class_String_basename>`  **(** **)**                                                                                        |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                | :ref:`begins_with<class_String_begins_with>`  **(** :ref:`String<class_string>` text  **)**                                                |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`c_escape<class_String_c_escape>`  **(** **)**                                                                                        |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`c_unescape<class_String_c_unescape>`  **(** **)**                                                                                    |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`capitalize<class_String_capitalize>`  **(** **)**                                                                                    |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                  | :ref:`casecmp_to<class_String_casecmp_to>`  **(** :ref:`String<class_string>` to  **)**                                                    |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                | :ref:`empty<class_String_empty>`  **(** **)**                                                                                              |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`extension<class_String_extension>`  **(** **)**                                                                                      |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                  | :ref:`find<class_String_find>`  **(** :ref:`String<class_string>` what, :ref:`int<class_int>` from=0  **)**                                |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                  | :ref:`find_last<class_String_find_last>`  **(** :ref:`String<class_string>` what  **)**                                                    |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                  | :ref:`findn<class_String_findn>`  **(** :ref:`String<class_string>` what, :ref:`int<class_int>` from=0  **)**                              |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`get_base_dir<class_String_get_base_dir>`  **(** **)**                                                                                |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`get_file<class_String_get_file>`  **(** **)**                                                                                        |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                  | :ref:`hash<class_String_hash>`  **(** **)**                                                                                                |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                  | :ref:`hex_to_int<class_String_hex_to_int>`  **(** **)**                                                                                    |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`insert<class_String_insert>`  **(** :ref:`int<class_int>` pos, :ref:`String<class_string>` what  **)**                               |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                | :ref:`is_abs_path<class_String_is_abs_path>`  **(** **)**                                                                                  |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                | :ref:`is_rel_path<class_String_is_rel_path>`  **(** **)**                                                                                  |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                | :ref:`is_valid_float<class_String_is_valid_float>`  **(** **)**                                                                            |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                | :ref:`is_valid_html_color<class_String_is_valid_html_color>`  **(** **)**                                                                  |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                | :ref:`is_valid_identifier<class_String_is_valid_identifier>`  **(** **)**                                                                  |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                | :ref:`is_valid_integer<class_String_is_valid_integer>`  **(** **)**                                                                        |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                | :ref:`is_valid_ip_address<class_String_is_valid_ip_address>`  **(** **)**                                                                  |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`json_escape<class_String_json_escape>`  **(** **)**                                                                                  |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`left<class_String_left>`  **(** :ref:`int<class_int>` pos  **)**                                                                     |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                  | :ref:`length<class_String_length>`  **(** **)**                                                                                            |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                | :ref:`match<class_String_match>`  **(** :ref:`String<class_string>` expr  **)**                                                            |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                | :ref:`matchn<class_String_matchn>`  **(** :ref:`String<class_string>` expr  **)**                                                          |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`RawArray<class_rawarray>`        | :ref:`md5_buffer<class_String_md5_buffer>`  **(** **)**                                                                                    |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`md5_text<class_String_md5_text>`  **(** **)**                                                                                        |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                  | :ref:`nocasecmp_to<class_String_nocasecmp_to>`  **(** :ref:`String<class_string>` to  **)**                                                |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`ord_at<class_String_ord_at>`  **(** :ref:`int<class_int>` at  **)**                                                                  |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`pad_decimals<class_String_pad_decimals>`  **(** :ref:`int<class_int>` digits  **)**                                                  |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`pad_zeros<class_String_pad_zeros>`  **(** :ref:`int<class_int>` digits  **)**                                                        |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`percent_decode<class_String_percent_decode>`  **(** **)**                                                                            |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`percent_encode<class_String_percent_encode>`  **(** **)**                                                                            |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`plus_file<class_String_plus_file>`  **(** :ref:`String<class_string>` file  **)**                                                    |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`replace<class_String_replace>`  **(** :ref:`String<class_string>` what, :ref:`String<class_string>` forwhat  **)**                   |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`replacen<class_String_replacen>`  **(** :ref:`String<class_string>` what, :ref:`String<class_string>` forwhat  **)**                 |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                  | :ref:`rfind<class_String_rfind>`  **(** :ref:`String<class_string>` what, :ref:`int<class_int>` from=-1  **)**                             |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                  | :ref:`rfindn<class_String_rfindn>`  **(** :ref:`String<class_string>` what, :ref:`int<class_int>` from=-1  **)**                           |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`right<class_String_right>`  **(** :ref:`int<class_int>` pos  **)**                                                                   |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`StringArray<class_stringarray>`  | :ref:`split<class_String_split>`  **(** :ref:`String<class_string>` divisor, :ref:`bool<class_bool>` allow_empty=True  **)**               |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`RealArray<class_realarray>`      | :ref:`split_floats<class_String_split_floats>`  **(** :ref:`String<class_string>` divisor, :ref:`bool<class_bool>` allow_empty=True  **)** |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`strip_edges<class_String_strip_edges>`  **(** :ref:`bool<class_bool>` left=True, :ref:`bool<class_bool>` right=True  **)**           |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`substr<class_String_substr>`  **(** :ref:`int<class_int>` from, :ref:`int<class_int>` len  **)**                                     |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`RawArray<class_rawarray>`        | :ref:`to_ascii<class_String_to_ascii>`  **(** **)**                                                                                        |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`float<class_float>`              | :ref:`to_float<class_String_to_float>`  **(** **)**                                                                                        |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`                  | :ref:`to_int<class_String_to_int>`  **(** **)**                                                                                            |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`to_lower<class_String_to_lower>`  **(** **)**                                                                                        |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`to_upper<class_String_to_upper>`  **(** **)**                                                                                        |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`RawArray<class_rawarray>`        | :ref:`to_utf8<class_String_to_utf8>`  **(** **)**                                                                                          |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`xml_escape<class_String_xml_escape>`  **(** **)**                                                                                    |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_string>`            | :ref:`xml_unescape<class_String_xml_unescape>`  **(** **)**                                                                                |
+----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+

Description
-----------

This is the built-in string class (and the one used by GDScript). It supports Unicode and provides all necessary means for string handling. Strings are reference counted and use a copy-on-write approach, so passing them around is cheap in resources.

Member Function Description
---------------------------

.. _class_String_basename:

- :ref:`String<class_string>`  **basename**  **(** **)**

If the string is a path to a file, return the path to the file without the extension.

.. _class_String_begins_with:

- :ref:`bool<class_bool>`  **begins_with**  **(** :ref:`String<class_string>` text  **)**

Return true if the strings begins with the given string.

.. _class_String_c_escape:

- :ref:`String<class_string>`  **c_escape**  **(** **)**

.. _class_String_c_unescape:

- :ref:`String<class_string>`  **c_unescape**  **(** **)**

.. _class_String_capitalize:

- :ref:`String<class_string>`  **capitalize**  **(** **)**

Return the string in uppercase.

.. _class_String_casecmp_to:

- :ref:`int<class_int>`  **casecmp_to**  **(** :ref:`String<class_string>` to  **)**

Perform a case-sensitive comparison to another string, return -1 if less, 0 if equal and +1 if greater.

.. _class_String_empty:

- :ref:`bool<class_bool>`  **empty**  **(** **)**

Return true if the string is empty.

.. _class_String_extension:

- :ref:`String<class_string>`  **extension**  **(** **)**

If the string is a path to a file, return the extension.

.. _class_String_find:

- :ref:`int<class_int>`  **find**  **(** :ref:`String<class_string>` what, :ref:`int<class_int>` from=0  **)**

Find the first occurrence of a substring, return the starting position of the substring or -1 if not found. Optionally, the initial search index can be passed.

.. _class_String_find_last:

- :ref:`int<class_int>`  **find_last**  **(** :ref:`String<class_string>` what  **)**

Find the last occurrence of a substring, return the starting position of the substring or -1 if not found. Optionally, the initial search index can be passed.

.. _class_String_findn:

- :ref:`int<class_int>`  **findn**  **(** :ref:`String<class_string>` what, :ref:`int<class_int>` from=0  **)**

Find the first occurrence of a substring but search as case-insensitive, return the starting position of the substring or -1 if not found. Optionally, the initial search index can be passed.

.. _class_String_get_base_dir:

- :ref:`String<class_string>`  **get_base_dir**  **(** **)**

If the string is a path to a file, return the base directory.

.. _class_String_get_file:

- :ref:`String<class_string>`  **get_file**  **(** **)**

If the string is a path to a file, return the file and ignore the base directory.

.. _class_String_hash:

- :ref:`int<class_int>`  **hash**  **(** **)**

Hash the string and return a 32 bits integer.

.. _class_String_hex_to_int:

- :ref:`int<class_int>`  **hex_to_int**  **(** **)**

Convert a string containing an hexadecimal number into an int.

.. _class_String_insert:

- :ref:`String<class_string>`  **insert**  **(** :ref:`int<class_int>` pos, :ref:`String<class_string>` what  **)**

Insert a substring at a given position.

.. _class_String_is_abs_path:

- :ref:`bool<class_bool>`  **is_abs_path**  **(** **)**

If the string is a path to a file or directory, return true if the path is absolute.

.. _class_String_is_rel_path:

- :ref:`bool<class_bool>`  **is_rel_path**  **(** **)**

If the string is a path to a file or directory, return true if the path is relative.

.. _class_String_is_valid_float:

- :ref:`bool<class_bool>`  **is_valid_float**  **(** **)**

Check whether the string contains a valid float.

.. _class_String_is_valid_html_color:

- :ref:`bool<class_bool>`  **is_valid_html_color**  **(** **)**

Check whether the string contains a valid color in HTML notation.

.. _class_String_is_valid_identifier:

- :ref:`bool<class_bool>`  **is_valid_identifier**  **(** **)**

.. _class_String_is_valid_integer:

- :ref:`bool<class_bool>`  **is_valid_integer**  **(** **)**

Check whether the string contains a valid integer.

.. _class_String_is_valid_ip_address:

- :ref:`bool<class_bool>`  **is_valid_ip_address**  **(** **)**

Check whether the string contains a valid IP address.

.. _class_String_json_escape:

- :ref:`String<class_string>`  **json_escape**  **(** **)**

.. _class_String_left:

- :ref:`String<class_string>`  **left**  **(** :ref:`int<class_int>` pos  **)**

Return an amount of characters from the left of the string.

.. _class_String_length:

- :ref:`int<class_int>`  **length**  **(** **)**

Return the length of the string in characters.

.. _class_String_match:

- :ref:`bool<class_bool>`  **match**  **(** :ref:`String<class_string>` expr  **)**

Do a simple expression match, where '\*' matches zero or more arbitrary characters and '?' matches any single character except '.'.

.. _class_String_matchn:

- :ref:`bool<class_bool>`  **matchn**  **(** :ref:`String<class_string>` expr  **)**

Do a simple case insensitive expression match, using ? and \* wildcards (see :ref:`match<class_String_match>`).

.. _class_String_md5_buffer:

- :ref:`RawArray<class_rawarray>`  **md5_buffer**  **(** **)**

.. _class_String_md5_text:

- :ref:`String<class_string>`  **md5_text**  **(** **)**

.. _class_String_nocasecmp_to:

- :ref:`int<class_int>`  **nocasecmp_to**  **(** :ref:`String<class_string>` to  **)**

Perform a case-insensitive comparison to another string, return -1 if less, 0 if equal and +1 if greater.

.. _class_String_ord_at:

- :ref:`String<class_string>`  **ord_at**  **(** :ref:`int<class_int>` at  **)**

Return the character code at position "at".

.. _class_String_pad_decimals:

- :ref:`String<class_string>`  **pad_decimals**  **(** :ref:`int<class_int>` digits  **)**

.. _class_String_pad_zeros:

- :ref:`String<class_string>`  **pad_zeros**  **(** :ref:`int<class_int>` digits  **)**

.. _class_String_percent_decode:

- :ref:`String<class_string>`  **percent_decode**  **(** **)**

.. _class_String_percent_encode:

- :ref:`String<class_string>`  **percent_encode**  **(** **)**

.. _class_String_plus_file:

- :ref:`String<class_string>`  **plus_file**  **(** :ref:`String<class_string>` file  **)**

.. _class_String_replace:

- :ref:`String<class_string>`  **replace**  **(** :ref:`String<class_string>` what, :ref:`String<class_string>` forwhat  **)**

Replace occurrences of a substring for different ones inside the string.

.. _class_String_replacen:

- :ref:`String<class_string>`  **replacen**  **(** :ref:`String<class_string>` what, :ref:`String<class_string>` forwhat  **)**

Replace occurrences of a substring for different ones inside the string, but search case-insensitive.

.. _class_String_rfind:

- :ref:`int<class_int>`  **rfind**  **(** :ref:`String<class_string>` what, :ref:`int<class_int>` from=-1  **)**

Perform a search for a substring, but start from the end of the string instead of the beginning.

.. _class_String_rfindn:

- :ref:`int<class_int>`  **rfindn**  **(** :ref:`String<class_string>` what, :ref:`int<class_int>` from=-1  **)**

Perform a search for a substring, but start from the end of the string instead of the beginning. Also search case-insensitive.

.. _class_String_right:

- :ref:`String<class_string>`  **right**  **(** :ref:`int<class_int>` pos  **)**

Return the right side of the string from a given position.

.. _class_String_split:

- :ref:`StringArray<class_stringarray>`  **split**  **(** :ref:`String<class_string>` divisor, :ref:`bool<class_bool>` allow_empty=True  **)**

Split the string by a divisor string, return an array of the substrings. Example "One,Two,Three" will return \:ref:`"One","Two","Three"\<class_"one","two","three"\>` if split by ",".

.. _class_String_split_floats:

- :ref:`RealArray<class_realarray>`  **split_floats**  **(** :ref:`String<class_string>` divisor, :ref:`bool<class_bool>` allow_empty=True  **)**

Split the string in floats by using a divisor string, return an array of the substrings. Example "1,2.5,3" will return \:ref:`1,2.5,3\<class_1,2.5,3\>` if split by ",".

.. _class_String_strip_edges:

- :ref:`String<class_string>`  **strip_edges**  **(** :ref:`bool<class_bool>` left=True, :ref:`bool<class_bool>` right=True  **)**

Return a copy of the string stripped of any non-printable character at the beginning and the end. The optional arguments are used to toggle stripping on the left and right edges respectively.

.. _class_String_substr:

- :ref:`String<class_string>`  **substr**  **(** :ref:`int<class_int>` from, :ref:`int<class_int>` len  **)**

Return part of the string from "from", with length "len".

.. _class_String_to_ascii:

- :ref:`RawArray<class_rawarray>`  **to_ascii**  **(** **)**

Convert the String (which is a character array) to RawArray (which is an array of bytes). The conversion is speeded up in comparison to to_utf8() with the assumption that all the characters the String contains are only ASCII characters.

.. _class_String_to_float:

- :ref:`float<class_float>`  **to_float**  **(** **)**

Convert a string, containing a decimal number, into a float.

.. _class_String_to_int:

- :ref:`int<class_int>`  **to_int**  **(** **)**

Convert a string, containing an integer number, into an int.

.. _class_String_to_lower:

- :ref:`String<class_string>`  **to_lower**  **(** **)**

Return the string converted to lowercase.

.. _class_String_to_upper:

- :ref:`String<class_string>`  **to_upper**  **(** **)**

Return the string converted to uppercase.

.. _class_String_to_utf8:

- :ref:`RawArray<class_rawarray>`  **to_utf8**  **(** **)**

Convert the String (which is an array of characters) to RawArray (which is an array of bytes). The conversion is a bit slower than to_ascii(), but supports all UTF-8 characters. Therefore, you should prefer this function over to_ascii().

.. _class_String_xml_escape:

- :ref:`String<class_string>`  **xml_escape**  **(** **)**

Perform XML escaping on the string.

.. _class_String_xml_unescape:

- :ref:`String<class_string>`  **xml_unescape**  **(** **)**

Perform XML un-escaping of the string.