String manipulation and formatting functions.

To use, add the following lines to the beginning of your file:

include <BOSL2/std.scad>

1. Section: Extracting substrings

   • substr() – Returns a substring from a string.
   • suffix() – Returns the last few characters of a string.

2. Section: String Searching

   • str_find() – Finds a substring in a string.
   • substr_match() – Returns true if the string pattern matches the string str.
   • starts_with() – Returns true if the string starts with a given substring.
   • ends_with() – Returns true if the string ends with a given substring.
   • str_split() – Splits a longer string wherever a given substring occurs.

3. Section: String modification

   • str_join() – Joints a list of strings into a single string.
   • str_strip() – Strips given leading and trailing characters from a string.
   • str_pad() – Pads a string to a given length.
   • str_replace_char() – Replace given chars in a string with another substring.
   • downcase() – Lowercases all characters in a string.
   • upcase() – Uppercases all characters in a string.

4. Section: Random strings

   • rand_str() – Create a randomized string.

5. Section: Parsing strings into numbers

   • parse_int() – Parse an integer from a string.
   • parse_float() – Parse a float from a string.
   • parse_frac() – Parse a float from a fraction string.
   • parse_num() – Parse a float from a decimal or fraction string.

6. Section: Formatting numbers into strings

   • format_int() – Formats an integer into a string, with possible leading zeros.
   • format_fixed() – Formats a float into a string with a fixed number of decimal places.
   • format_float() – Formats a float into a string with a given number of significant digits.
   • format() – Formats multiple values into a string with a given format.

7. Section: Checking character class

   • is_lower() – Returns true if all characters in the string are lowercase.
   • is_upper() – Returns true if all characters in the string are uppercase.
   • is_digit() – Returns true if all characters in the string are decimal digits.
   • is_hexdigit() – Returns true if all characters in the string are hexidecimal digits.
   • is_letter() – Returns true if all characters in the string are letters.

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:

Returns a substring from a string start at position pos with length len, or if len isn't given, the rest of the string.

Arguments:

Example 1:

include <BOSL2/std.scad>
substr("abcdefg",3,3);     // Returns "def"
substr("abcdefg",2);       // Returns "cdefg"
substr("abcdefg",len=3);   // Returns "abc"
substr("abcdefg",[2,4]);   // Returns "cde"
substr("abcdefg",len=-2);  // Returns ""

Synopsis: Returns the last few characters of a string.

Topics: Strings

See Also: str_find(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip()

Usage:

• newstr = suffix(str,len);

Description:

Returns the last len characters from the input string str. If len is longer than the length of str, then the entirety of str is returned.

Arguments:

Synopsis: Finds a substring in a string.

Topics: Strings

See Also: suffix(), substr_match(), starts_with(), ends_with(), str_split(), str_join(), str_strip()

Usage:

• ind = str_find(str,pattern,[last=],[all=],[start=]);

Description:

Searches input string str for the string pattern and returns the index or indices of the matches in str. By default str_find() returns the index of the first match in str. If last is true then it returns the index of the last match. If the pattern is the empty string the first match is at zero and the last match is the last character of the str. If start is set then the search begins at index start, working either forward and backward from that position. If you set start and last is true then the search will find the pattern if it begins at index start. If no match exists, returns undef. If you set all to true then str_find() returns all of the matches in a list, or an empty list if there are no matches.

Arguments:

Example 1:

include <BOSL2/std.scad>
str_find("abc123def123abc","123");   // Returns 3
str_find("abc123def123abc","b");     // Returns 1
str_find("abc123def123abc","1234");  // Returns undef
str_find("abc","");                  // Returns 0
str_find("abc123def123", "123", start=4);     // Returns 9
str_find("abc123def123abc","123",last=true);  // Returns 9
str_find("abc123def123abc","b",last=true);    // Returns 13
str_find("abc123def123abc","1234",last=true); // Returns undef
str_find("abc","",last=true);                 // Returns 3
str_find("abc123def123", "123", start=8, last=true));  // Returns 3
str_find("abc123def123abc","123",all=true);   // Returns [3,9]
str_find("abc123def123abc","b",all=true);     // Returns [1,13]
str_find("abc123def123abc","1234",all=true);  // Returns []
str_find("abc","",all=true);                  // Returns [0,1,2]

Synopsis: Returns true if the string pattern matches the string str.

Topics: Strings

See Also: suffix(), str_find(), starts_with(), ends_with(), str_split(), str_join(), str_strip()

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 string – then substr_match returns false.

Arguments:

Example 1:

include <BOSL2/std.scad>
substr_match("abcde",2,"cd");   // Returns true

Example 2:

include <BOSL2/std.scad>
substr_match("abcde",2,"cx");   // Returns false

Example 3:

include <BOSL2/std.scad>
substr_match("abcde",2,"cdef"); // Returns false

Example 4:

include <BOSL2/std.scad>
substr_match("abcde",-2,"cd");  // Returns false

Example 5:

include <BOSL2/std.scad>
substr_match("abcde",19,"cd");  // Returns false

Example 6:

include <BOSL2/std.scad>
substr_match("abc",1,"");       // Returns true

Synopsis: Returns true if the string starts with a given substring.

Topics: Strings

See Also: suffix(), str_find(), substr_match(), ends_with(), str_split(), str_join(), str_strip()

Usage:

• bool = starts_with(str,pattern);

Description:

Returns true if the input string str starts with the specified string pattern, pattern. Otherwise returns false.

Arguments:

Example 1:

include <BOSL2/std.scad>
starts_with("abcdef","abc");  // Returns true
starts_with("abcdef","def");  // Returns false
starts_with("abcdef","");     // Returns true

Synopsis: Returns true if the string ends with a given substring.

Topics: Strings

See Also: suffix(), str_find(), substr_match(), starts_with(), str_split(), str_join(), str_strip()

Usage:

• bool = ends_with(str,pattern);

Description:

Returns true if the input string str ends with the specified string pattern, pattern. Otherwise returns false.

Arguments:

Example 1:

include <BOSL2/std.scad>
ends_with("abcdef","def");  // Returns true
ends_with("abcdef","de");   // Returns false
ends_with("abcdef","");     // Returns true

Synopsis: Splits a longer string wherever a given substring occurs.

Topics: Strings

See Also: suffix(), str_find(), substr_match(), starts_with(), ends_with(), str_join(), str_strip()

Usage:

• string_list = str_split(str, sep, [keep_nulls]);

Description:

Breaks an input string into substrings using a separator or list of separators. If keep_nulls is true then two sequential separator characters produce an empty string in the output list. If keep_nulls is false then no empty strings are included in the output list.

If sep is a single string then each character in sep is treated as a delimiting character and the input string is split at every delimiting character. Empty strings can occur whenever two delimiting characters are sequential. If sep is a list of strings then the input string is split sequentially using each string from the list in order. If keep_nulls is true then the output will have length equal to len(sep)+1, possibly with trailing null strings if the string runs out before the separator list.

Arguments:

Example 1:

include <BOSL2/std.scad>
str_split("abc+def-qrs*iop","*-+");     // Returns ["abc", "def", "qrs", "iop"]
str_split("abc+*def---qrs**iop+","*-+");// Returns ["abc", "", "def", "", "", "qrs", "", "iop", ""]
str_split("abc      def"," ");          // Returns ["abc", "", "", "", "", "", "def"]
str_split("abc      def"," ",keep_nulls=false);  // Returns ["abc", "def"]
str_split("abc+def-qrs*iop",["+","-","*"]);     // Returns ["abc", "def", "qrs", "iop"]
str_split("abc+def-qrs*iop",["-","+","*"]);     // Returns ["abc+def", "qrs*iop", "", ""]

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_strip()

Usage:

• str = str_join(list, [sep]);

Description:

Returns the concatenation of a list of strings, optionally with a separator string inserted between each string on the list.

Arguments:

Example 1:

include <BOSL2/std.scad>
str_join(["abc","def","ghi"]);        // Returns "abcdefghi"
str_join(["abc","def","ghi"], " + ");  // Returns "abc + def + ghi"

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()

Usage:

• str = str_strip(s,c,[start],[end]);

Description:

Takes a string s and strips off all leading and/or trailing characters that exist in string c. By default strips both leading and trailing characters. If you set start or end to true then it will strip only the leading or trailing characters respectively. If you set start or end to false then it will strip only lthe trailing or leading characters.

Arguments:

Example 1:

include <BOSL2/std.scad>
str_strip("--##--123--##--","#-");  // Returns: "123"
str_strip("--##--123--##--","-");   // Returns: "##--123--##"
str_strip("--##--123--##--","#");   // Returns: "--##--123--##--"
str_strip("--##--123--##--","#-",end=true);  // Returns: "--##--123"
str_strip("--##--123--##--","-",end=true);   // Returns: "--##--123--##"
str_strip("--##--123--##--","#",end=true);   // Returns: "--##--123--##--"
str_strip("--##--123--##--","#-",start=true); // Returns: "123--##--"
str_strip("--##--123--##--","-",start=true);  // Returns: "##--123--##--"
str_strip("--##--123--##--","#",start=true);  // Returns: "--##--123--##--"

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:

Pad the given string str with to length length with the specified character, which must be a length 1 string. If left is true then pad on the left, otherwise pad on the right. If the string is longer than the specified length the full string is returned unchanged.

Arguments:

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:

Replace every occurence of char in the input string with the string replace which can be any string.

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()

Usage:

• newstr = downcase(str);

Description:

Returns the string with the standard ASCII upper case letters A-Z replaced by their lower case versions.

Arguments:

Example 1:

include <BOSL2/std.scad>
downcase("ABCdef");   // Returns "abcdef"

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(), downcase()

Usage:

• newstr = upcase(str);

Description:

Returns the string with the standard ASCII lower case letters a-z replaced by their upper case versions.

Arguments:

Example 1:

include <BOSL2/std.scad>
upcase("ABCdef");   // Returns "ABCDEF"

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:

Produce a random string of length n. If you give a string charset then the characters of the random string are drawn from that list, weighted by the number of times each character appears in the list. If you do not give a character set then the string is generated with characters ranging from 0 to z (based on character code).

Synopsis: Parse an integer from a string.

Topics: Strings

See Also: parse_float(), parse_frac(), parse_num()

Usage:

• num = parse_int(str, [base])

Description:

Converts a string into an integer with any base up to 16. Returns NaN if conversion fails. Digits above 9 are represented using letters A-F in either upper case or lower case.

Arguments:

Example 1:

include <BOSL2/std.scad>
parse_int("349");        // Returns 349
parse_int("-37");        // Returns -37
parse_int("+97");        // Returns 97
parse_int("43.9");       // Returns nan
parse_int("1011010",2);  // Returns 90
parse_int("13",2);       // Returns nan
parse_int("dead",16);    // Returns 57005
parse_int("CEDE", 16);   // Returns 52958
parse_int("");           // Returns 0

Synopsis: Parse a float from a string.

Topics: Strings

See Also: parse_int(), parse_frac(), parse_num()

Usage:

• num = parse_float(str);

Description:

Converts a string to a floating point number. Returns NaN if the conversion fails.

Arguments:

Example 1:

include <BOSL2/std.scad>
parse_float("44");       // Returns 44
parse_float("3.4");      // Returns 3.4
parse_float("-99.3332"); // Returns -99.3332
parse_float("3.483e2");  // Returns 348.3
parse_float("-44.9E2");  // Returns -4490
parse_float("7.342e-4"); // Returns 0.0007342
parse_float("");         // Returns 0

Synopsis: Parse a float from a fraction string.

Topics: Strings

See Also: parse_int(), parse_float(), parse_num()

Usage:

• num = parse_frac(str,[mixed=],[improper=],[signed=]);

Description:

Converts a string fraction to a floating point number. A string fraction has the form [-][# ][#/#] where each # is one or more of the digits 0-9, and there is an optional sign character at the beginning. The full form is a sign character and an integer, followed by exactly one space, followed by two more integers separated by a "/" character. The leading integer and space can be omitted or the trailing fractional part can be omitted. If you set mixed to false then the leading integer part is not accepted and the input must include a slash. If you set improper to false then the fractional part must be a proper fraction, where the numerator is smaller than the denominator. If you set signed to false then the leading sign character is not permitted. The empty string evaluates to zero. Any invalid string evaluates to NaN.

Arguments:

Example 1:

include <BOSL2/std.scad>
parse_frac("3/4");     // Returns 0.75
parse_frac("-77/9");   // Returns -8.55556
parse_frac("+1/3");    // Returns 0.33333
parse_frac("19");      // Returns 19
parse_frac("2 3/4");   // Returns 2.75
parse_frac("-2 12/4"); // Returns -5
parse_frac("");        // Returns 0
parse_frac("3/0");     // Returns inf
parse_frac("0/0");     // Returns nan
parse_frac("-77/9",improper=false);   // Returns nan
parse_frac("-2 12/4",improper=false); // Returns nan
parse_frac("-2 12/4",signed=false);   // Returns nan
parse_frac("-2 12/4",mixed=false);    // Returns nan
parse_frac("2 1/4",mixed=false);      // Returns nan

Synopsis: Parse a float from a decimal or fraction string.

Topics: Strings

See Also: parse_int(), parse_float(), parse_frac()

Usage:

• num = parse_num(str);

Description:

Converts a string to a number. The string can be either a fraction (two integers separated by a "/") or a floating point number. Returns NaN if the conversion fails.

Example 1:

include <BOSL2/std.scad>
parse_num("3/4");    // Returns 0.75
parse_num("3.4e-2"); // Returns 0.034

Synopsis: Formats an integer into a string, with possible leading zeros.

Topics: Strings

See Also: format_fixed(), format_float(), format()

Usage:

• str = format_int(i, [mindigits]);

Description:

Formats an integer number into a string. This can handle larger numbers than str().

Arguments:

Example 1:

include <BOSL2/std.scad>
str(123456789012345);  // Returns "1.23457e+14"
format_int(123456789012345);  // Returns "123456789012345"
format_int(-123456789012345);  // Returns "-123456789012345"

Synopsis: Formats a float into a string with a fixed number of decimal places.

Topics: Strings

See Also: format_int(), format_float(), format()

Usage:

• s = format_fixed(f, [digits]);

Description:

Given a floating point number, formats it into a string with the given number of digits after the decimal point.

Arguments:

Synopsis: Formats a float into a string with a given number of significant digits.

Topics: Strings

See Also: format_int(), format_fixed(), format()

Usage:

• str = format_float(f,[sig]);

Description:

Formats the given floating point number f into a string with sig significant digits. Strips trailing 0s after the decimal point. Strips trailing decimal point. If the number can be represented in sig significant digits without a mantissa, it will be. If given a list of numbers, recursively prints each item in the list, returning a string like [3,4,5]

Arguments:

Example 1:

include <BOSL2/std.scad>
format_float(PI,12);  // Returns: "3.14159265359"
format_float([PI,-16.75],12);  // Returns: "[3.14159265359, -16.75]"

Synopsis: Formats multiple values into a string with a given format.

Topics: Strings

See Also: format_int(), format_fixed(), format_float()

Usage:

• s = format(fmt, vals);

Description:

Given a format string and a list of values, inserts the values into the placeholders in the format string and returns it. Formatting placeholders have the following syntax:

• A leading { character to show the start of the placeholder.
• An integer index into the vals list to specify which value should be formatted at that place. If not given, the first placeholder will use index 0, the second will use index 1, etc.
• An optional : separator to indicate that what follows if a formatting specifier. If not given, no formatting info follows.
• An optional - character to indicate that the value should be left justified if the value needs field width padding. If not given, right justification is used.
• An optional 0 character to indicate that the field should be padded with 0s. If not given, spaces will be used for padding.
• An optional integer field width, which the value should be padded to. If not given, no padding will be performed.
• An optional . followed by an integer precision length, for specifying how many digits to display in numeric formats. If not give, 6 digits is assumed.
• An optional letter to indicate the formatting style to use. If not given, s is assumed, which will do it's generic best to format any data type.
• A trailing } character to show the end of the placeholder.

Formatting styles, and their effects are as follows:

• s: Converts the value to a string with str() to display. This is very generic.
• i or d: Formats numeric values as integers.
• f: Formats numeric values with the precision number of digits after the decimal point. NaN and Inf are shown as nan and inf.
• F: Formats numeric values with the precision number of digits after the decimal point. NaN and Inf are shown as NAN and INF.
• g: Formats numeric values with the precision number of total significant digits. NaN and Inf are shown as nan and inf. Mantissas are demarked by e.
• G: Formats numeric values with the precision number of total significant digits. NaN and Inf are shown as NAN and INF. Mantissas are demarked by E.
• b: If the value logically evaluates as true, it shows as true, otherwise false.
• B: If the value logically evaluates as true, it shows as TRUE, otherwise FALSE.

Arguments:

Example 1:

include <BOSL2/std.scad>
format("The value of {} is {:.14f}.", ["pi", PI]);  // Returns: "The value of pi is 3.14159265358979."
format("The value {1:f} is known as {0}.", ["pi", PI]);  // Returns: "The value 3.141593 is known as pi."
format("We use a very small value {1:.6g} as {0}.", ["EPSILON", EPSILON]);  // Returns: "We use a very small value 1e-9 as EPSILON."
format("{:-5s}{:i}{:b}", ["foo", 12e3, 5]);  // Returns: "foo  12000true"
format("{:-10s}{:.3f}", ["plecostamus",27.43982]);  // Returns: "plecostamus27.440"
format("{:-10.9s}{:.3f}", ["plecostamus",27.43982]);  // Returns: "plecostam 27.440"

Synopsis: Returns true if all characters in the string are lowercase.

Topics: Strings

See Also: is_upper(), is_digit(), is_hexdigit(), is_letter()

Usage:

• x = is_lower(s);

Description:

Returns true if all the characters in the given string are lowercase letters. (a-z)

Synopsis: Returns true if all characters in the string are uppercase.

Topics: Strings

See Also: is_lower(), is_digit(), is_hexdigit(), is_letter()

Usage:

• x = is_upper(s);

Description:

Returns true if all the characters in the given string are uppercase letters. (A-Z)

Synopsis: Returns true if all characters in the string are decimal digits.

Topics: Strings

See Also: is_lower(), is_upper(), is_hexdigit(), is_letter()

Usage:

• x = is_digit(s);

Description:

Returns true if all the characters in the given string are digits. (0-9)

Synopsis: Returns true if all characters in the string are hexidecimal digits.

Topics: Strings

See Also: is_lower(), is_upper(), is_digit(), is_letter()

Usage:

• x = is_hexdigit(s);

Description:

Returns true if all the characters in the given string are valid hexadecimal digits. (0-9 or a-f or A-F))

Synopsis: Returns true if all characters in the string are letters.

Topics: Strings

See Also: is_lower(), is_upper(), is_digit(), is_hexdigit()

Usage:

• x = is_letter(s);

Description:

Returns true if all the characters in the given string are standard ASCII letters. (A-Z or a-z)