Merge pull request #6442 from raulsntos/dotnet/string-extensions

C#: Add table with equivalent string methods

tutorials/scripting/c_sharp/c_sharp_differences.rst

@@ -177,42 +177,203 @@ Example:
 String
 ------
 
-Use ``System.String`` (``string``). Most of Godot's String methods are
-provided by the ``StringExtensions`` class as extension methods.
+Use ``System.String`` (``string``). Most of Godot's String methods have an
+equivalent in ``System.String`` or are provided by the ``StringExtensions``
+class as extension methods.
 
 Example:
 
 .. code-block:: csharp
 
-    string upper = "I LIKE SALAD FORKS";
-    string lower = upper.ToLower();
+    string text = "Bigrams";
+    string[] bigrams = text.Bigrams(); // ["Bi", "ig", "gr", "ra", "am", "ms"]
 
-There are a few differences, though:
+Strings are immutable in .NET, so all methods that manipulate a string don't
+modify the original string and return a newly created string with the
+modifications applied. To avoid creating multiple string allocations consider
+using a `StringBuilder`_.
 
-* ``erase``: Strings are immutable in C#, so we cannot modify the string
-  passed to the extension method. For this reason, ``Erase`` was added as an
-  extension method of ``StringBuilder`` instead of string.
-  Alternatively, you can use ``string.Remove``.
-* ``IsSubsequenceOf``/``IsSubsequenceOfi``: An additional method is provided,
-  which is an overload of ``IsSubsequenceOf``, allowing you to explicitly specify
-  case sensitivity:
+List of Godot's String methods and their equivalent in C#:
 
-.. code-block:: csharp
-
-  str.IsSubsequenceOf("ok"); // Case sensitive
-  str.IsSubsequenceOf("ok", true); // Case sensitive
-  str.IsSubsequenceOfi("ok"); // Case insensitive
-  str.IsSubsequenceOf("ok", false); // Case insensitive
-
-* ``Match``/``Matchn``/``ExprMatch``: An additional method is provided besides
-  ``Match`` and ``Matchn``, which allows you to explicitly specify case sensitivity:
-
-.. code-block:: csharp
-
-  str.Match("*.txt"); // Case sensitive
-  str.ExprMatch("*.txt", true); // Case sensitive
-  str.Matchn("*.txt"); // Case insensitive
-  str.ExprMatch("*.txt", false); // Case insensitive
+=======================  ==============================================================
+GDScript                 C#
+=======================  ==============================================================
+begins_with              `string.StartsWith`_
+bigrams                  StringExtensions.Bigrams
+bin_to_int               StringExtensions.BinToInt
+c_escape                 StringExtensions.CEscape
+c_unescape               StringExtensions.CUnescape
+capitalize               StringExtensions.Capitalize
+casecmp_to               StringExtensions.CasecmpTo or StringExtensions.CompareTo (Consider using `string.Equals`_ or `string.Compare`_)
+chr                      N/A
+contains                 `string.Contains`_
+count                    StringExtensions.Count (Consider using `RegEx`_)
+countn                   StringExtensions.CountN (Consider using `RegEx`_)
+dedent                   StringExtensions.Dedent
+ends_with                `string.EndsWith`_
+find                     StringExtensions.Find (Consider using `string.IndexOf`_ or `string.IndexOfAny`_)
+findn                    StringExtensions.FindN (Consider using `string.IndexOf`_ or `string.IndexOfAny`_)
+format                   Use `$ string interpolation`_
+get_base_dir             StringExtensions.GetBaseDir
+get_basename             StringExtensions.GetBaseName
+get_extension            StringExtensions.GetExtension
+get_file                 StringExtensions.GetFile
+get_slice                N/A
+get_slice_count          N/A
+get_slicec               N/A
+hash                     StringExtensions.Hash (Consider using `object.GetHashCode`_ unless you need to guarantee the same behavior as in GDScript)
+hex_to_int               StringExtensions.HexToInt (Consider using `int.Parse`_ or `long.Parse`_ with `System.Globalization.NumberStyles.HexNumber`_)
+humanize_size            N/A
+indent                   StringExtensions.Indent
+insert                   `string.Insert`_ (Consider using `StringBuilder`_ to manipulate strings)
+is_absolute_path         StringExtensions.IsAbsolutePath
+is_empty                 `string.IsNullOrEmpty`_ or `string.IsNullOrWhiteSpace`_
+is_relative_path         StringExtensions.IsRelativePath
+is_subsequence_of        StringExtensions.IsSubsequenceOf
+is_subsequence_ofn       StringExtensions.IsSubsequenceOfN
+is_valid_filename        StringExtensions.IsValidFileName
+is_valid_float           StringExtensions.IsValidFloat (Consider using `float.TryParse`_ or `double.TryParse`_)
+is_valid_hex_number      StringExtensions.IsValidHexNumber
+is_valid_html_color      StringExtensions.IsValidHtmlColor
+is_valid_identifier      StringExtensions.IsValidIdentifier
+is_valid_int             StringExtensions.IsValidInt (Consider using `int.TryParse`_ or `long.TryParse`_)
+is_valid_ip_address      StringExtensions.IsValidIPAddress
+join                     `string.Join`_
+json_escape              StringExtensions.JSONEscape
+left                     StringExtensions.Left (Consider using `string.Substring`_ or `string.AsSpan`_)
+length                   `string.Length`_
+lpad                     `string.PadLeft`_
+lstrip                   `string.TrimStart`_
+match                    StringExtensions.Match (Consider using `RegEx`_)
+matchn                   StringExtensions.MatchN (Consider using `RegEx`_)
+md5_buffer               StringExtensions.MD5Buffer (Consider using `System.Security.Cryptography.MD5.HashData`_)
+md5_text                 StringExtensions.MD5Text (Consider using `System.Security.Cryptography.MD5.HashData`_ with StringExtensions.HexEncode)
+naturalnocasecmp_to      N/A (Consider using `string.Equals`_ or `string.Compare`_)
+nocasecmp_to             StringExtensions.NocasecmpTo or StringExtensions.CompareTo (Consider using `string.Equals`_ or `string.Compare`_)
+num                      `float.ToString`_ or `double.ToString`_
+num_int64                `int.ToString`_ or `long.ToString`_
+num_scientific           `float.ToString`_ or `double.ToString`_
+num_uint64               `uint.ToString`_ or `ulong.ToString`_
+pad_decimals             StringExtensions.PadDecimals
+pad_zeros                StringExtensions.PadZeros
+path_join                StringExtensions.PathJoin
+repeat                   Use `string constructor`_ or a `StringBuilder`_
+replace                  `string.Replace`_ or `RegEx`_
+replacen                 StringExtensions.ReplaceN (Consider using `string.Replace`_ or `RegEx`_)
+rfind                    StringExtensions.RFind (Consider using `string.LastIndexOf`_ or `string.LastIndexOfAny`_)
+rfindn                   StringExtensions.RFindN (Consider using `string.LastIndexOf`_ or `string.LastIndexOfAny`_)
+right                    StringExtensions.Right (Consider using `string.Substring`_ or `string.AsSpan`_)
+rpad                     `string.PadRight`_
+rsplit                   N/A
+rstrip                   `string.TrimEnd`_
+sha1_buffer              StringExtensions.SHA1Buffer (Consider using `System.Security.Cryptography.SHA1.HashData`_)
+sha1_text                StringExtensions.SHA1Text (Consider using `System.Security.Cryptography.SHA1.HashData`_ with StringExtensions.HexEncode)
+sha256_buffer            StringExtensions.SHA256Buffer (Consider using `System.Security.Cryptography.SHA256.HashData`_)
+sha256_text              StringExtensions.SHA256Text (Consider using `System.Security.Cryptography.SHA256.HashData`_ with StringExtensions.HexEncode)
+similarity               StringExtensions.Similarity
+simplify_path            StringExtensions.SimplifyPath
+split                    StringExtensions.Split (Consider using `string.Split`_)
+split_floats             StringExtensions.SplitFloat
+strip_edges              StringExtensions.StripEdges (Consider using `string.Trim`_, `string.TrimStart`_ or `string.TrimEnd`_)
+strip_escapes            StringExtensions.StripEscapes
+substr                   StringExtensions.Substr (Consider using `string.Substring`_ or `string.AsSpan`_)
+to_ascii_buffer          StringExtensions.ToASCIIBuffer (Consider using `System.Text.Encoding.ASCII.GetBytes`_)
+to_camel_case            StringExtensions.ToCamelCase
+to_float                 StringExtensions.ToFloat (Consider using `float.TryParse`_ or `double.TryParse`_)
+to_int                   StringExtensions.ToInt (Consider using `int.TryParse`_ or `long.TryParse`_)
+to_lower                 `string.ToLower`_
+to_pascal_case           StringExtensions.ToPascalCase
+to_snake_case            StringExtensions.ToSnakeCase
+to_upper                 `string.ToUpper`_
+to_utf16_buffer          StringExtensions.ToUTF16Buffer (Consider using `System.Text.Encoding.UTF16.GetBytes`_)
+to_utf32_buffer          StringExtensions.ToUTF32Buffer (Consider using `System.Text.Encoding.UTF32.GetBytes`_)
+to_utf8_buffer           StringExtensions.ToUTF8Buffer (Consider using `System.Text.Encoding.UTF8.GetBytes`_)
+trim_prefix              StringExtensions.TrimPrefix
+trim_suffix              StringExtensions.TrimSuffix
+unicode_at               `string[int]`_ indexer
+uri_decode               StringExtensions.URIDecode (Consider using `System.Uri.UnescapeDataString`_)
+uri_encode               StringExtensions.URIEncode (Consider using `System.Uri.EscapeDataString`_)
+validate_node_name       StringExtensions.ValidateNodeName
+xml_escape               StringExtensions.XMLEscape
+xml_unescape             StringExtensions.XMLUnescape
+=======================  ==============================================================
+
+List of Godot's PackedByteArray methods that create a String and their C# equivalent:
+
+=========================  ==============================================================
+GDScript                   C#
+=========================  ==============================================================
+get_string_from_ascii      StringExtensions.GetStringFromASCII (Consider using `System.Text.Encoding.ASCII.GetString`_)
+get_string_from_utf16      StringExtensions.GetStringFromUTF16 (Consider using `System.Text.Encoding.UTF16.GetString`_)
+get_string_from_utf32      StringExtensions.GetStringFromUTF32 (Consider using `System.Text.Encoding.UTF32.GetString`_)
+get_string_from_utf8       StringExtensions.GetStringFromUTF8 (Consider using `System.Text.Encoding.UTF8.GetString`_)
+hex_encode                 StringExtensions.HexEncode (Consider using `System.Convert.ToHexString`_)
+=========================  ==============================================================
+
+* .NET contains many path utility methods available under the
+  `System.IO.Path`_
+  class that can be used when not dealing with Godot paths (paths that start
+  with ``res://`` or ``user://``)
+
+.. _$ string interpolation: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/tokens/interpolated
+.. _double.ToString: https://learn.microsoft.com/en-us/dotnet/api/system.double.tostring
+.. _double.TryParse: https://learn.microsoft.com/en-us/dotnet/api/system.double.tryparse
+.. _float.ToString: https://learn.microsoft.com/en-us/dotnet/api/system.single.tostring
+.. _float.TryParse: https://learn.microsoft.com/en-us/dotnet/api/system.single.tryparse
+.. _int.Parse: https://learn.microsoft.com/en-us/dotnet/api/system.int32.parse
+.. _int.ToString: https://learn.microsoft.com/en-us/dotnet/api/system.int32.tostring
+.. _int.TryParse: https://learn.microsoft.com/en-us/dotnet/api/system.int32.tryparse
+.. _long.Parse: https://learn.microsoft.com/en-us/dotnet/api/system.int64.parse
+.. _long.ToString: https://learn.microsoft.com/en-us/dotnet/api/system.int64.tostring
+.. _long.TryParse: https://learn.microsoft.com/en-us/dotnet/api/system.int64.tryparse
+.. _uint.ToString: https://learn.microsoft.com/en-us/dotnet/api/system.uint32.tostring
+.. _ulong.ToString: https://learn.microsoft.com/en-us/dotnet/api/system.uint64.tostring
+.. _object.GetHashCode: https://learn.microsoft.com/en-us/dotnet/api/system.object.gethashcode
+.. _RegEx: https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expressions
+.. _string constructor: https://learn.microsoft.com/en-us/dotnet/api/system.string.-ctor
+.. _string[int]: https://learn.microsoft.com/en-us/dotnet/api/system.string.chars
+.. _string.AsSpan: https://learn.microsoft.com/en-us/dotnet/api/system.memoryextensions.asspan
+.. _string.Compare: https://learn.microsoft.com/en-us/dotnet/api/system.string.compare
+.. _string.Contains: https://learn.microsoft.com/en-us/dotnet/api/system.string.contains
+.. _string.EndsWith: https://learn.microsoft.com/en-us/dotnet/api/system.string.endswith
+.. _string.Equals: https://learn.microsoft.com/en-us/dotnet/api/system.string.equals
+.. _string.IndexOf: https://learn.microsoft.com/en-us/dotnet/api/system.string.indexof
+.. _string.IndexOfAny: https://learn.microsoft.com/en-us/dotnet/api/system.string.indexofany
+.. _string.Insert: https://learn.microsoft.com/en-us/dotnet/api/system.string.insert
+.. _string.IsNullOrEmpty: https://learn.microsoft.com/en-us/dotnet/api/system.string.isnullorempty
+.. _string.IsNullOrWhiteSpace: https://learn.microsoft.com/en-us/dotnet/api/system.string.isnullorwhitespace
+.. _string.Join: https://learn.microsoft.com/en-us/dotnet/api/system.string.join
+.. _string.LastIndexOf: https://learn.microsoft.com/en-us/dotnet/api/system.string.lastindexof
+.. _string.LastIndexOfAny: https://learn.microsoft.com/en-us/dotnet/api/system.string.lastindexofany
+.. _string.Length: https://learn.microsoft.com/en-us/dotnet/api/system.string.length
+.. _string.PadLeft: https://learn.microsoft.com/en-us/dotnet/api/system.string.padleft
+.. _string.PadRight: https://learn.microsoft.com/en-us/dotnet/api/system.string.padright
+.. _string.Replace: https://learn.microsoft.com/en-us/dotnet/api/system.string.replace
+.. _string.Split: https://learn.microsoft.com/en-us/dotnet/api/system.string.split
+.. _string.StartsWith: https://learn.microsoft.com/en-us/dotnet/api/system.string.startswith
+.. _string.Substring: https://learn.microsoft.com/en-us/dotnet/api/system.string.substring
+.. _string.Trim: https://learn.microsoft.com/en-us/dotnet/api/system.string.trim
+.. _string.TrimEnd: https://learn.microsoft.com/en-us/dotnet/api/system.string.trimend
+.. _string.TrimStart: https://learn.microsoft.com/en-us/dotnet/api/system.string.trimstart
+.. _string.ToLower: https://learn.microsoft.com/en-us/dotnet/api/system.string.tolower
+.. _string.ToUpper: https://learn.microsoft.com/en-us/dotnet/api/system.string.toupper
+.. _StringBuilder: https://learn.microsoft.com/en-us/dotnet/api/system.text.stringbuilder
+.. _System.Convert.ToHexString: https://learn.microsoft.com/en-us/dotnet/api/system.convert.tohexstring
+.. _System.Globalization.NumberStyles.HexNumber: https://learn.microsoft.com/en-us/dotnet/api/system.globalization.numberstyles#system-globalization-numberstyles-hexnumber
+.. _System.IO.Path: https://learn.microsoft.com/en-us/dotnet/api/system.io.path
+.. _System.Security.Cryptography.MD5.HashData: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.md5.hashdata
+.. _System.Security.Cryptography.SHA1.HashData: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.sha1.hashdata
+.. _System.Security.Cryptography.SHA256.HashData: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.sha256.hashdata
+.. _System.Text.Encoding.ASCII.GetBytes: https://learn.microsoft.com/en-us/dotnet/api/system.text.asciiencoding.getbytes
+.. _System.Text.Encoding.ASCII.GetString: https://learn.microsoft.com/en-us/dotnet/api/system.text.asciiencoding.getstring
+.. _System.Text.Encoding.UTF16.GetBytes: https://learn.microsoft.com/en-us/dotnet/api/system.text.unicodeencoding.getbytes
+.. _System.Text.Encoding.UTF16.GetString: https://learn.microsoft.com/en-us/dotnet/api/system.text.unicodeencoding.getstring
+.. _System.Text.Encoding.UTF32.GetBytes: https://learn.microsoft.com/en-us/dotnet/api/system.text.utf32encoding.getbytes
+.. _System.Text.Encoding.UTF32.GetString: https://learn.microsoft.com/en-us/dotnet/api/system.text.utf32encoding.getstring
+.. _System.Text.Encoding.UTF8.GetBytes: https://learn.microsoft.com/en-us/dotnet/api/system.text.utf8encoding.getbytes
+.. _System.Text.Encoding.UTF8.GetString: https://learn.microsoft.com/en-us/dotnet/api/system.text.utf8encoding.getstring
+.. _System.Uri.EscapeDataString: https://learn.microsoft.com/en-us/dotnet/api/system.uri.escapedatastring
+.. _System.Uri.UnescapeDataString: https://learn.microsoft.com/en-us/dotnet/api/system.uri.unescapedatastring
 
 Basis
 -----