Synopses, etc for strings.scad

strings.scad

@@ -12,6 +12,9 @@
 // Section: Extracting substrings
 
 // Function: substr()
+// Synopsis: Returns a substring from a string.
+// Topics: Strings
+// See Also: suffix(), str_find(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip()
 // Usage:
 //   newstr = substr(str, [pos], [len]);
 // Description:
@@ -38,6 +41,9 @@ function _substr(str,pos,len,substr="") =
 
 
 // Function: suffix()
+// Synopsis: Returns the last few characters of a string.
+// Topics: Strings
+// See Also: suffix(), str_find(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip()
 // Usage:
 //   newstr = suffix(str,len);
 // Description:
@@ -55,6 +61,9 @@ function suffix(str,len) =
 
 
 // Function: str_find()
+// Synopsis: Finds a substring in a string.
+// Topics: Strings
+// See Also: suffix(), str_find(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip()
 // Usage:
 //   ind = str_find(str,pattern,[last=],[all=],[start=]);
 // Description:
@@ -108,13 +117,16 @@ function _str_find_all(str,pattern) =
     [for(i=[0:1:len(str)-len(pattern)]) if (substr_match(str,i,pattern)) i];
 
 // Function: substr_match()
+// Synopsis: Returns true if the string `pattern` matches the string `str`.
+// Topics: Strings
+// See Also: suffix(), str_find(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip()
 // Usage
 //   bool = substr_match(str,start,pattern);
 // Description:
 //   Returns true if the string `pattern` matches the string `str` starting
 //   at `str[start]`.  If the string is too short for the pattern, or
-//   `start` is out of bounds---either negative or beyond the end of the
+//   `start` is out of bounds – either negative or beyond the end of the
-//   string---then substr_match returns false. 
+//   string – then substr_match returns false.
 // Arguments:
 //   str = String to search
 //   start = Starting index for search in str
@@ -142,6 +154,9 @@ function _substr_match_recurse(str,sindex,pattern,plen,pindex=0,) =
 
 
 // Function: starts_with()
+// Synopsis: Returns true if the string starts with a given substring.
+// Topics: Strings
+// See Also: suffix(), str_find(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip()
 // Usage:
 //    bool = starts_with(str,pattern);
 // Description:
@@ -158,6 +173,9 @@ function starts_with(str,pattern) = substr_match(str,0,pattern);
 
 
 // Function: ends_with()
+// Synopsis: Returns true if the string ends with a given substring.
+// Topics: Strings
+// See Also: suffix(), str_find(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip()
 // Usage:
 //    bool = ends_with(str,pattern);
 // Description:
@@ -175,6 +193,9 @@ function ends_with(str,pattern) = substr_match(str,len(str)-len(pattern),pattern
 
 
 // Function: str_split()
+// Synopsis: Splits a longer string wherever a given substring occurs.
+// Topics: Strings
+// See Also: suffix(), str_find(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip()
 // Usage:
 //   string_list = str_split(str, sep, [keep_nulls]);
 // Description:
@@ -225,6 +246,9 @@ function _remove_empty_strs(list) =
 
 
 // Function: str_join()
+// Synopsis: Joints a list of strings into a single string.
+// Topics: Strings
+// See Also: suffix(), str_find(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip()
 // Usage:
 //   str = str_join(list, [sep]);
 // Description:
@@ -244,6 +268,9 @@ function str_join(list,sep="",_i=0, _result="") =
 
 
 // Function: str_strip()
+// Synopsis: Strips given leading and trailing characters from a string.
+// Topics: Strings
+// See Also: suffix(), str_find(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip()
 // Usage:
 //   str = str_strip(s,c,[start],[end]);
 // Description:
@@ -287,6 +314,9 @@ function str_strip(s,c,start,end) =
 
 
 // Function: str_pad()
+// Synopsis: Pads a string to a given length.
+// Topics: Strings
+// See Also: suffix(), str_find(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip()
 // Usage:
 //   padded = str_pad(str, length, char, [left]);
 // Description:
@@ -311,6 +341,9 @@ function str_pad(str,length,char=" ",left=false) =
 
 
 // Function: str_replace_char()
+// Synopsis: Replace given chars in a string with another substring.
+// Topics: Strings
+// See Also: suffix(), str_find(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip()
 // Usage:
 //   newstr = str_replace_char(str, char, replace);
 // Description:
@@ -324,6 +357,9 @@ function str_replace_char(str,char,replace) =
 
 
 // Function: downcase()
+// Synopsis: Lowercases all characters in a string.
+// Topics: Strings
+// See Also: suffix(), str_find(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip(), upcase(), downcase()
 // Usage:
 //   newstr = downcase(str);
 // Description:
@@ -338,6 +374,9 @@ function downcase(str) =
 
 
 // Function: upcase()
+// Synopsis: Uppercases all characters in a string.
+// Topics: Strings
+// See Also: suffix(), str_find(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip(), upcase(), downcase()
 // Usage:
 //   newstr = upcase(str);
 // Description:
@@ -354,6 +393,9 @@ function upcase(str) =
 // Section: Random strings
 
 // Function: rand_str()
+// Synopsis: Create a randomized string.
+// Topics: Strings
+// See Also: suffix(), str_find(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip(), upcase(), downcase()
 // Usage:
 //    str = rand_str(n, [charset], [seed]);
 // Description:
@@ -371,6 +413,9 @@ function rand_str(n, charset, seed) =
 // Section: Parsing strings into numbers
 
 // Function: parse_int()
+// Synopsis: Parse an integer from a string.
+// Topics: Strings
+// See Also: parse_int(), parse_float(), parse_frac(), parse_num()
 // Usage:
 //   num = parse_int(str, [base])
 // Description:
@@ -407,6 +452,9 @@ function _parse_int_recurse(str,base,i) =
 
 
 // Function: parse_float()
+// Synopsis: Parse a float from a string.
+// Topics: Strings
+// See Also: parse_int(), parse_float(), parse_frac(), parse_num()
 // Usage:
 //   num = parse_float(str);
 // Description:
@@ -435,6 +483,9 @@ function parse_float(str) =
 
 
 // Function: parse_frac()
+// Synopsis: Parse a float from a fraction string.
+// Topics: Strings
+// See Also: parse_int(), parse_float(), parse_frac(), parse_num()
 // Usage:
 //   num = parse_frac(str,[mixed=],[improper=],[signed=]);
 // Description:
@@ -488,6 +539,9 @@ function parse_frac(str,mixed=true,improper=true,signed=true) =
 
 
 // Function: parse_num()
+// Synopsis: Parse a float from a decimal or fraction string.
+// Topics: Strings
+// See Also: parse_int(), parse_float(), parse_frac(), parse_num()
 // Usage:
 //   num = parse_num(str);
 // Description:
@@ -508,6 +562,9 @@ function parse_num(str) =
 // Section: Formatting numbers into strings
 
 // Function: format_int()
+// Synopsis: Formats an integer into a string, with possible leading zeros.
+// Topics: Strings
+// See Also: format_int(), format_fixed(), format_float(), format()
 // Usage:
 //   str = format_int(i, [mindigits]);
 // Description:
@@ -532,6 +589,9 @@ function format_int(i,mindigits=1) =
 
 
 // Function: format_fixed()
+// Synopsis: Formats a float into a string with a fixed number of decimal places.
+// Topics: Strings
+// See Also: format_int(), format_fixed(), format_float(), format()
 // Usage:
 //   s = format_fixed(f, [digits]);
 // Description:
@@ -556,6 +616,9 @@ function format_fixed(f,digits=6) =
 
 
 // Function: format_float()
+// Synopsis: Formats a float into a string with a given number of significant digits.
+// Topics: Strings
+// See Also: format_int(), format_fixed(), format_float(), format()
 // Usage:
 //   str = format_float(f,[sig]);
 // Description:
@@ -655,6 +718,9 @@ function _format_matrix(M, sig=4, sep=1, eps=1e-9) =
 
 
 // Function: format()
+// Synopsis: Formats multiple values into a string with a given format.
+// Topics: Strings
+// See Also: format_int(), format_fixed(), format_float(), format()
 // Usage:
 //   s = format(fmt, vals);
 // Description:
@@ -743,6 +809,9 @@ function format(fmt, vals) =
 // Section: Checking character class
 
 // Function: is_lower()
+// Synopsis: Returns true if all characters in the string are lowercase.
+// Topics: Strings
+// See Also: is_lower(), is_upper(), is_digit(), is_hexdigit(), is_letter()
 // Usage:
 //   x = is_lower(s);
 // Description:
@@ -755,6 +824,9 @@ function is_lower(s) =
 
 
 // Function: is_upper()
+// Synopsis: Returns true if all characters in the string are uppercase.
+// Topics: Strings
+// See Also: is_lower(), is_upper(), is_digit(), is_hexdigit(), is_letter()
 // Usage:
 //   x = is_upper(s);
 // Description:
@@ -767,6 +839,9 @@ function is_upper(s) =
 
 
 // Function: is_digit()
+// Synopsis: Returns true if all characters in the string are decimal digits.
+// Topics: Strings
+// See Also: is_lower(), is_upper(), is_digit(), is_hexdigit(), is_letter()
 // Usage:
 //   x = is_digit(s);
 // Description:
@@ -779,6 +854,9 @@ function is_digit(s) =
 
 
 // Function: is_hexdigit()
+// Synopsis: Returns true if all characters in the string are hexidecimal digits.
+// Topics: Strings
+// See Also: is_lower(), is_upper(), is_digit(), is_hexdigit(), is_letter()
 // Usage:
 //   x = is_hexdigit(s);
 // Description:
@@ -794,6 +872,9 @@ function is_hexdigit(s) =
 
 
 // Function: is_letter()
+// Synopsis: Returns true if all characters in the string are letters.
+// Topics: Strings
+// See Also: is_lower(), is_upper(), is_digit(), is_hexdigit(), is_letter()
 // Usage:
 //   x = is_letter(s);
 // Description: