From ba99387bf380122afcd59263f1a3b1cf30db9d0f Mon Sep 17 00:00:00 2001 From: Raul Santos Date: Sat, 24 Jul 2021 22:38:39 +0200 Subject: [PATCH] Fix documentation in StringExtensions --- .../GodotSharp/Core/StringExtensions.cs | 357 ++++++++++-------- 1 file changed, 192 insertions(+), 165 deletions(-) diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/StringExtensions.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/StringExtensions.cs index aefad2c8cf5..b182f1f15ee 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/StringExtensions.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/StringExtensions.cs @@ -61,9 +61,9 @@ namespace Godot return string.Empty; } - // - // If the string is a path to a file, return the path to the file without the extension. - // + /// + /// If the string is a path to a file, return the path to the file without the extension. + /// public static string BaseName(this string instance) { int index = instance.LastIndexOf('.'); @@ -74,17 +74,17 @@ namespace Godot return instance; } - // - // Return true if the strings begins with the given string. - // + /// + /// Return if the strings begins with the given string. + /// public static bool BeginsWith(this string instance, string text) { return instance.StartsWith(text); } - // - // Return the bigrams (pairs of consecutive letters) of this string. - // + /// + /// Return the bigrams (pairs of consecutive letters) of this string. + /// public static string[] Bigrams(this string instance) { var b = new string[instance.Length - 1]; @@ -127,9 +127,9 @@ namespace Godot return sign * Convert.ToInt32(instance, 2); } - // - // Return the amount of substrings in string. - // + /// + /// Return the amount of substrings in string. + /// public static int Count(this string instance, string what, bool caseSensitive = true, int from = 0, int to = 0) { if (what.Length == 0) @@ -187,9 +187,9 @@ namespace Godot return c; } - // - // Return a copy of the string with special characters escaped using the C language standard. - // + /// + /// Return a copy of the string with special characters escaped using the C language standard. + /// public static string CEscape(this string instance) { var sb = new StringBuilder(string.Copy(instance)); @@ -209,9 +209,10 @@ namespace Godot return sb.ToString(); } - // - // Return a copy of the string with escaped characters replaced by their meanings according to the C language standard. - // + /// + /// Return a copy of the string with escaped characters replaced by their meanings + /// according to the C language standard. + /// public static string CUnescape(this string instance) { var sb = new StringBuilder(string.Copy(instance)); @@ -231,9 +232,12 @@ namespace Godot return sb.ToString(); } - // - // Change the case of some letters. Replace underscores with spaces, convert all letters to lowercase then capitalize first and every letter following the space character. For [code]capitalize camelCase mixed_with_underscores[/code] it will return [code]Capitalize Camelcase Mixed With Underscores[/code]. - // + /// + /// Change the case of some letters. Replace underscores with spaces, convert all letters + /// to lowercase then capitalize first and every letter following the space character. + /// For capitalize camelCase mixed_with_underscores it will return + /// Capitalize Camelcase Mixed With Underscores. + /// public static string Capitalize(this string instance) { string aux = instance.Replace("_", " ").ToLower(); @@ -254,17 +258,17 @@ namespace Godot return cap; } - // - // Perform a case-sensitive comparison to another string, return -1 if less, 0 if equal and +1 if greater. - // + /// + /// Perform a case-sensitive comparison to another string, return -1 if less, 0 if equal and +1 if greater. + /// public static int CasecmpTo(this string instance, string to) { return instance.CompareTo(to, caseSensitive: true); } - // - // Perform a comparison to another string, return -1 if less, 0 if equal and +1 if greater. - // + /// + /// Perform a comparison to another string, return -1 if less, 0 if equal and +1 if greater. + /// public static int CompareTo(this string instance, string to, bool caseSensitive = true) { if (string.IsNullOrEmpty(instance)) @@ -316,25 +320,25 @@ namespace Godot } } - // - // Return true if the strings ends with the given string. - // + /// + /// Return if the strings ends with the given string. + /// public static bool EndsWith(this string instance, string text) { return instance.EndsWith(text); } - // - // Erase [code]chars[/code] characters from the string starting from [code]pos[/code]. - // + /// + /// Erase characters from the string starting from . + /// public static void Erase(this StringBuilder instance, int pos, int chars) { instance.Remove(pos, chars); } - // - // If the string is a path to a file, return the extension. - // + /// + /// If the string is a path to a file, return the extension. + /// public static string Extension(this string instance) { int pos = instance.FindLast("."); @@ -345,14 +349,18 @@ namespace Godot return instance.Substring(pos + 1); } - /// Find the first occurrence of a substring. Optionally, the search starting position can be passed. + /// + /// Find the first occurrence of a substring. Optionally, the search starting position can be passed. + /// /// The starting position of the substring, or -1 if not found. public static int Find(this string instance, string what, int from = 0, bool caseSensitive = true) { return instance.IndexOf(what, from, caseSensitive ? StringComparison.Ordinal : StringComparison.OrdinalIgnoreCase); } - /// Find the first occurrence of a char. Optionally, the search starting position can be passed. + /// + /// Find the first occurrence of a char. Optionally, the search starting position can be passed. + /// /// The first instance of the char, or -1 if not found. public static int Find(this string instance, char what, int from = 0, bool caseSensitive = true) { @@ -375,16 +383,19 @@ namespace Godot return instance.LastIndexOf(what, from, caseSensitive ? StringComparison.Ordinal : StringComparison.OrdinalIgnoreCase); } - /// Find the first occurrence of a substring but search as case-insensitive. Optionally, the search starting position can be passed. + /// + /// Find the first occurrence of a substring but search as case-insensitive. + /// Optionally, the search starting position can be passed. + /// /// The starting position of the substring, or -1 if not found. public static int FindN(this string instance, string what, int from = 0) { return instance.IndexOf(what, from, StringComparison.OrdinalIgnoreCase); } - // - // If the string is a path to a file, return the base directory. - // + /// + /// If the string is a path to a file, return the base directory. + /// public static string GetBaseDir(this string instance) { int basepos = instance.Find("://"); @@ -419,9 +430,9 @@ namespace Godot return @base + rs.Substr(0, sep); } - // - // If the string is a path to a file, return the file and ignore the base directory. - // + /// + /// If the string is a path to a file, return the file and ignore the base directory. + /// public static string GetFile(this string instance) { int sep = Mathf.Max(instance.FindLast("/"), instance.FindLast("\\")); @@ -461,9 +472,9 @@ namespace Godot return Encoding.UTF8.GetString(bytes); } - // - // Hash the string and return a 32 bits unsigned integer. - // + /// + /// Hash the string and return a 32 bits unsigned integer. + /// public static uint Hash(this string instance) { uint hash = 5381; @@ -553,17 +564,17 @@ namespace Godot return sign * int.Parse(instance, NumberStyles.HexNumber); } - // - // Insert a substring at a given position. - // + /// + /// Insert a substring at a given position. + /// public static string Insert(this string instance, int pos, string what) { return instance.Insert(pos, what); } - // - // If the string is a path to a file or directory, return true if the path is absolute. - // + /// + /// If the string is a path to a file or directory, return if the path is absolute. + /// public static bool IsAbsPath(this string instance) { if (string.IsNullOrEmpty(instance)) @@ -574,17 +585,17 @@ namespace Godot return instance[0] == '/' || instance[0] == '\\'; } - // - // If the string is a path to a file or directory, return true if the path is relative. - // + /// + /// If the string is a path to a file or directory, return if the path is relative. + /// public static bool IsRelPath(this string instance) { return !IsAbsPath(instance); } - // - // Check whether this string is a subsequence of the given string. - // + /// + /// Check whether this string is a subsequence of the given string. + /// public static bool IsSubsequenceOf(this string instance, string text, bool caseSensitive = true) { int len = instance.Length; @@ -625,34 +636,36 @@ namespace Godot return false; } - // - // Check whether this string is a subsequence of the given string, ignoring case differences. - // + /// + /// Check whether this string is a subsequence of the given string, ignoring case differences. + /// public static bool IsSubsequenceOfI(this string instance, string text) { return instance.IsSubsequenceOf(text, caseSensitive: false); } - // - // Check whether the string contains a valid float. - // + /// + /// Check whether the string contains a valid . + /// public static bool IsValidFloat(this string instance) { float f; return float.TryParse(instance, out f); } - // - // Check whether the string contains a valid color in HTML notation. - // + /// + /// Check whether the string contains a valid color in HTML notation. + /// public static bool IsValidHtmlColor(this string instance) { return Color.HtmlIsValid(instance); } - // - // Check whether the string is a valid identifier. As is common in programming languages, a valid identifier may contain only letters, digits and underscores (_) and the first character may not be a digit. - // + /// + /// Check whether the string is a valid identifier. As is common in + /// programming languages, a valid identifier may contain only letters, + /// digits and underscores (_) and the first character may not be a digit. + /// public static bool IsValidIdentifier(this string instance) { int len = instance.Length; @@ -680,18 +693,18 @@ namespace Godot return true; } - // - // Check whether the string contains a valid integer. - // + /// + /// Check whether the string contains a valid integer. + /// public static bool IsValidInteger(this string instance) { int f; return int.TryParse(instance, out f); } - // - // Check whether the string contains a valid IP address. - // + /// + /// Check whether the string contains a valid IP address. + /// public static bool IsValidIPAddress(this string instance) { // TODO: Support IPv6 addresses @@ -714,9 +727,9 @@ namespace Godot return true; } - // - // Return a copy of the string with special characters escaped using the JSON standard. - // + /// + /// Return a copy of the string with special characters escaped using the JSON standard. + /// public static string JSONEscape(this string instance) { var sb = new StringBuilder(string.Copy(instance)); @@ -733,9 +746,9 @@ namespace Godot return sb.ToString(); } - // - // Return an amount of characters from the left of the string. - // + /// + /// Return an amount of characters from the left of the string. + /// public static string Left(this string instance, int pos) { if (pos <= 0) @@ -783,7 +796,8 @@ namespace Godot } /// - /// Do a simple expression match, where '*' matches zero or more arbitrary characters and '?' matches any single character except '.'. + /// Do a simple expression match, where '*' matches zero or more + /// arbitrary characters and '?' matches any single character except '.'. /// private static bool ExprMatch(this string instance, string expr, bool caseSensitive) { @@ -807,7 +821,8 @@ namespace Godot } /// - /// Do a simple case sensitive expression match, using ? and * wildcards (see [method expr_match]). + /// Do a simple case sensitive expression match, using ? and * wildcards + /// (see ). /// public static bool Match(this string instance, string expr, bool caseSensitive = true) { @@ -818,7 +833,8 @@ namespace Godot } /// - /// Do a simple case insensitive expression match, using ? and * wildcards (see [method expr_match]). + /// Do a simple case insensitive expression match, using ? and * wildcards + /// (see ). /// public static bool MatchN(this string instance, string expr) { @@ -828,9 +844,9 @@ namespace Godot return instance.ExprMatch(expr, caseSensitive: false); } - // - // Return the MD5 hash of the string as an array of bytes. - // + /// + /// Return the MD5 hash of the string as an array of bytes. + /// public static byte[] MD5Buffer(this string instance) { return godot_icall_String_md5_buffer(instance); @@ -839,9 +855,9 @@ namespace Godot [MethodImpl(MethodImplOptions.InternalCall)] internal extern static byte[] godot_icall_String_md5_buffer(string str); - // - // Return the MD5 hash of the string as a string. - // + /// + /// Return the MD5 hash of the string as a string. + /// public static string MD5Text(this string instance) { return godot_icall_String_md5_text(instance); @@ -850,25 +866,25 @@ namespace Godot [MethodImpl(MethodImplOptions.InternalCall)] internal extern static string godot_icall_String_md5_text(string str); - // - // Perform a case-insensitive comparison to another string, return -1 if less, 0 if equal and +1 if greater. - // + /// + /// Perform a case-insensitive comparison to another string, return -1 if less, 0 if equal and +1 if greater. + /// public static int NocasecmpTo(this string instance, string to) { return instance.CompareTo(to, caseSensitive: false); } - // - // Return the character code at position [code]at[/code]. - // + /// + /// Return the character code at position . + /// public static int OrdAt(this string instance, int at) { return instance[at]; } - // - // Format a number to have an exact number of [code]digits[/code] after the decimal point. - // + /// + /// Format a number to have an exact number of after the decimal point. + /// public static string PadDecimals(this string instance, int digits) { int c = instance.Find("."); @@ -902,9 +918,9 @@ namespace Godot return instance; } - // - // Format a number to have an exact number of [code]digits[/code] before the decimal point. - // + /// + /// Format a number to have an exact number of before the decimal point. + /// public static string PadZeros(this string instance, int digits) { string s = instance; @@ -935,9 +951,10 @@ namespace Godot return s; } - // - // If the string is a path, this concatenates [code]file[/code] at the end of the string as a subpath. E.g. [code]"this/is".plus_file("path") == "this/is/path"[/code]. - // + /// + /// If the string is a path, this concatenates at the end of the string as a subpath. + /// E.g. "this/is".PlusFile("path") == "this/is/path". + /// public static string PlusFile(this string instance, string file) { if (instance.Length > 0 && instance[instance.Length - 1] == '/') @@ -945,25 +962,25 @@ namespace Godot return instance + "/" + file; } - // - // Replace occurrences of a substring for different ones inside the string. - // + /// + /// Replace occurrences of a substring for different ones inside the string. + /// public static string Replace(this string instance, string what, string forwhat) { return instance.Replace(what, forwhat); } - // - // Replace occurrences of a substring for different ones inside the string, but search case-insensitive. - // + /// + /// Replace occurrences of a substring for different ones inside the string, but search case-insensitive. + /// public static string ReplaceN(this string instance, string what, string forwhat) { return Regex.Replace(instance, what, forwhat, RegexOptions.IgnoreCase); } - // - // Perform a search for a substring, but start from the end of the string instead of the beginning. - // + /// + /// Perform a search for a substring, but start from the end of the string instead of the beginning. + /// public static int RFind(this string instance, string what, int from = -1) { return godot_icall_String_rfind(instance, what, from); @@ -972,9 +989,10 @@ namespace Godot [MethodImpl(MethodImplOptions.InternalCall)] internal extern static int godot_icall_String_rfind(string str, string what, int from); - // - // Perform a search for a substring, but start from the end of the string instead of the beginning. Also search case-insensitive. - // + /// + /// Perform a search for a substring, but start from the end of the string instead of the beginning. + /// Also search case-insensitive. + /// public static int RFindN(this string instance, string what, int from = -1) { return godot_icall_String_rfindn(instance, what, from); @@ -983,9 +1001,9 @@ namespace Godot [MethodImpl(MethodImplOptions.InternalCall)] internal extern static int godot_icall_String_rfindn(string str, string what, int from); - // - // Return the right side of the string from a given position. - // + /// + /// Return the right side of the string from a given position. + /// public static string Right(this string instance, int pos) { if (pos >= instance.Length) @@ -1032,9 +1050,9 @@ namespace Godot [MethodImpl(MethodImplOptions.InternalCall)] internal extern static byte[] godot_icall_String_sha256_buffer(string str); - // - // Return the SHA-256 hash of the string as a string. - // + /// + /// Return the SHA-256 hash of the string as a string. + /// public static string SHA256Text(this string instance) { return godot_icall_String_sha256_text(instance); @@ -1043,9 +1061,10 @@ namespace Godot [MethodImpl(MethodImplOptions.InternalCall)] internal extern static string godot_icall_String_sha256_text(string str); - // - // Return the similarity index of the text compared to this string. 1 means totally similar and 0 means totally dissimilar. - // + /// + /// Return the similarity index of the text compared to this string. + /// 1 means totally similar and 0 means totally dissimilar. + /// public static float Similarity(this string instance, string text) { if (instance == text) @@ -1083,17 +1102,19 @@ namespace Godot return 2.0f * inter / sum; } - // - // Split the string by a divisor string, return an array of the substrings. Example "One,Two,Three" will return ["One","Two","Three"] if split by ",". - // + /// + /// Split the string by a divisor string, return an array of the substrings. + /// Example "One,Two,Three" will return ["One","Two","Three"] if split by ",". + /// public static string[] Split(this string instance, string divisor, bool allowEmpty = true) { return instance.Split(new[] { divisor }, StringSplitOptions.RemoveEmptyEntries); } - // - // Split the string in floats by using a divisor string, return an array of the substrings. Example "1,2.5,3" will return [1,2.5,3] if split by ",". - // + /// + /// Split the string in floats by using a divisor string, return an array of the substrings. + /// Example "1,2.5,3" will return [1,2.5,3] if split by ",". + /// public static float[] SplitFloats(this string instance, string divisor, bool allowEmpty = true) { var ret = new List(); @@ -1125,9 +1146,10 @@ namespace Godot (char)30, (char)31, (char)32 }; - // - // 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. - // + /// + /// 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. + /// public static string StripEdges(this string instance, bool left = true, bool right = true) { if (left) @@ -1140,58 +1162,62 @@ namespace Godot return instance.TrimEnd(_nonPrintable); } - // - // Return part of the string from the position [code]from[/code], with length [code]len[/code]. - // + /// + /// Return part of the string from the position , with length . + /// public static string Substr(this string instance, int from, int len) { int max = instance.Length - from; return instance.Substring(from, len > max ? max : len); } - // - // Convert the String (which is a character array) to PackedByteArray (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. - // + /// + /// Convert the String (which is a character array) to PackedByteArray (which is an array of bytes). + /// The conversion is speeded up in comparison to with the assumption + /// that all the characters the String contains are only ASCII characters. + /// public static byte[] ToAscii(this string instance) { return Encoding.ASCII.GetBytes(instance); } - // - // Convert a string, containing a decimal number, into a [code]float[/code]. - // + /// + /// Convert a string, containing a decimal number, into a . + /// public static float ToFloat(this string instance) { return float.Parse(instance); } - // - // Convert a string, containing an integer number, into an [code]int[/code]. - // + /// + /// Convert a string, containing an integer number, into an . + /// public static int ToInt(this string instance) { return int.Parse(instance); } - // - // Return the string converted to lowercase. - // + /// + /// Return the string converted to lowercase. + /// public static string ToLower(this string instance) { return instance.ToLower(); } - // - // Return the string converted to uppercase. - // + /// + /// Return the string converted to uppercase. + /// public static string ToUpper(this string instance) { return instance.ToUpper(); } - // - // Convert the String (which is an array of characters) to PackedByteArray (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(). - // + /// + /// Convert the String (which is an array of characters) to PackedByteArray (which is an array of bytes). + /// The conversion is a bit slower than , but supports all UTF-8 characters. + /// Therefore, you should prefer this function over . + /// public static byte[] ToUTF8(this string instance) { return Encoding.UTF8.GetBytes(instance); @@ -1224,17 +1250,18 @@ namespace Godot return Uri.EscapeDataString(instance); } - // - // Return a copy of the string with special characters escaped using the XML standard. - // + /// + /// Return a copy of the string with special characters escaped using the XML standard. + /// public static string XMLEscape(this string instance) { return SecurityElement.Escape(instance); } - // - // Return a copy of the string with escaped characters replaced by their meanings according to the XML standard. - // + /// + /// Return a copy of the string with escaped characters replaced by their meanings + /// according to the XML standard. + /// public static string XMLUnescape(this string instance) { return SecurityElement.FromString(instance).Text;