text

virtual class text

Provides utility functions for text processing.  All functions are defined as static.

Summary
textProvides utility functions for text processing.
Common Arguments
Functions
capitalizestatic Returns a copy of the given string with the first character uppercased and the remainder lowercased.
centerstatic Returns a string of the specified width with the given string centerted and padded with the specified character.
changestatic Returns a copy of the given string with the characters in the specified range replaced with the specified substring.
chompstatic Returns a copy of the given string with the last newline character removed (if present).
chopstatic Returns the last character of the given string.
colorizestatic Returns a copy of the given string with ANSI escape codes.
containsstatic Returns 1 if the given string contains the specified substring.
contains_strstatic If the given string contains the specified substring, returns that substring.
countstatic Returns the number of non-overlapping occurrences of the specified substring in the given string.
deletestatic Returns a copy of the given string with the specified string removed.
ends_withstatic Returns 1 if the given string ends with one of the specified suffixes.
find_anystatic Returns the lowest index in the given string where each specified substring is found.
hashstatic Returns the hash value of the given string.
indexstatic Returns the index of the first occurrence of the specified substring in the given string within the optionally specified range.
insertstatic Returns a copy of the given string with the specified substring inserted at the specified position.
is_alphastatic Returns 1 if all characters in the given string are alphabetic.
is_digitstatic Returns 1 if all characters in the given string are digits.
is_lowerstatic Returns 1 if all cased characters in the given string are lowercase.
is_printablestatic Returns 1 if all characters in the given string are printable.
is_single_bit_typestatic Returns 1 if the given string is bit, logic, or reg.
is_spacestatic Returns 1 if all characters in the given string are whitespace characters: a space (“ “), a tab (\t), or a newline (\n).
is_upperstatic Returns 1 if all cased characters in the given string are uppercase.
join_strstatic Returns a string by concatenating the strings in the given string queue, separated by the specified separator.
lc_firststatic Returns a copy of the given string with the first character lowercased and the remainder unchanged.
ljuststatic Returns a string of the specified width with the given string left justified and padded with the specified character.
lstripstatic Returns a copy of the given string with leading characters removed.
onlystatic Returns 1 if the given string consists of only the specified set of characters.
partitionstatic Searches the first occurrence of the specified separator in the given string and returns an array of three strings.
replacestatic Returns a copy of the given string with the specified string replaced with a new string.
reversestatic Returns a copy of the given string with the characters in reverse order.
rfind_anystatic Returns the highest index in the given string where each specified substring is found.
rindexstatic Returns the index of the last occurrence of the specified substring in the given string within the optionally specified range.
rjuststatic Returns a string of the specified width with the given string right justified and padded with the specified character.
rpartitionstatic Searches the last occurrence of the specified separator in the given string and returns an array of three strings.
rsplitstatic Returns a queue of substrings by dividing the given string by the specified separator from the right.
rstripstatic Returns a copy of the given string with trailing characters removed.
slicestatic Returns a substring in the specified range.
slice_lenstatic Returns a substring in the specified range.
splitstatic Returns a queue of substrings by dividing the given string by the specified separator.
starts_withstatic Returns 1 if the given string starts with one of the specified prefixes.
stripstatic Returns a copy of the given string with leading and trailing characters removed.
swap_casestatic Returns a copy of the given string with uppercase characters converted to lowercase, and lowercase characters converted to uppercase.
title_casestatic Returns a copy of the given string with the first character of words uppercased and the remainder lowercased.
trimstatic Returns a copy of the given string with the specified numbers of leading and trailing characters removed.
uc_firststatic Returns a copy of the given string with the first character uppercased and the remainder unchanged.
untabifystatic Returns a copy of the given string where all tab characters (\t) are replaced by one or more spaces, depending on the tab positions.

Common Arguments

start_posSpecifies the start position in a string.  The position of the first character is 0, the position of the second character is 1, and so on.  The position can be specified as a negative number.  The position of the last character can be specified as -1, the position of the second to the last character can be specified as -2, and so on.  The default is 0 (the first character).
end_posSpecifies the end position in a string using the same rule as the start_pos.  The default is -1 (the last character).

Example

      ____ position 0 or -26
     /    ____ position 5 or -21
    /    /         ____ position 15 or -11
   /    /         /         ____ position 25 or -1
  /    /         /         /
 V    V         V         V
"How common arguments work."
 |----------------------->| start_pos =   0, end_pos =  25 \
 |----------------------->| start_pos =   0, end_pos =  -1  \ these specify the same range of the string
 |----------------------->| start_pos = -26, end_pos =  25  /
 |----------------------->| start_pos = -26, end_pos =  -1 /
      |-------->|           start_pos =   5, end_pos =  15 \
      |-------->|           start_pos =   5, end_pos = -11  \ these specify the same range of the string
      |-------->|           start_pos = -21, end_pos =  15  /
      |-------->|           start_pos = -21, end_pos = -11 /

Functions

capitalize

static function string capitalize(string s)

static Returns a copy of the given string with the first character uppercased and the remainder lowercased.

Argument

sA string to be capitalized.

Returns

A copy of s with the first character uppercased and the remainder lowercased.

Example

assert( text::capitalize( "capitalize me!" ) == "Capitalize me!" );

See Also

lc_first, swap_case, title_case, uc_first

center

static function string center(string s,  
int width,  
byte fill_char =  " ",
bit trim_ends =  0)

static Returns a string of the specified width with the given string centerted and padded with the specified character.

Arguments

sA string to be centered.
widthThe width of the returned string.
fill_charoptional The character used for padding if width is wider than the length of s.  The default is a space character (“ “).
trim_endsoptional If width is narrower than the length of s and trim_ends is 1, then the head and the tail of s are trimmed to fit within width.  If trim_ends is 0, then width is widened to the length of s.  If width is wider than or equal to the length of s, trim_ends is ignored.  The default is 0.

Returns

A string with s placed at the center and padded with fill_char.

Example

assert( text::center( "center me", 15 )                 == "   center me   " );
assert( text::center( "center me", 15, "-" )            == "---center me---" );
assert( text::center( "center me", 7 )                  ==    "center me"    ); // widened to fit
assert( text::center( "center me", 7, .trim_ends( 1 ) ) ==     "enter m"     ); // trimmed

See Also

ljust, rjust

change

static function string change(string s,  
string sub,  
int start_pos =  0,
int end_pos =  -1)

static Returns a copy of the given string with the characters in the specified range replaced with the specified substring.

Arguments

sA string to be changed.
subA substring.
start_posoptional Specifies the left-most position in s to be replaced.  See Common Arguments.
end_posoptional Specifies the right-most position in s to be replaced.  See Common Arguments.

Returns

A copy of s with the characters in the specified range replaced with sub.  If the specified range is invalid, s is returned without a change.  If s is an empty string (“”), no change is made.

Example

assert( text::change( "a primary library", "function", .start_pos( 10 ) ) == "a primary function" );
//                               |---->|
//                              10

See Also

replace

chomp

static function string chomp(string s)

static Returns a copy of the given string with the last newline character removed (if present).  Returns the given string as is if the given string does not end in a newline character.

Argument

sA string to be chomped

Returns

Returns a copy of s with the last newline character removed (if present).  Returns s as is if the given string does not end in a newline character.

Example

assert( text::chomp( "abc"     ) == "abc" );
assert( text::chomp( "abc\n"   ) == "abc" );
assert( text::chomp( "abc\n\n" ) == "abc\n" );

See Also

chop, delete, lstrip, rstrip, strip, trim

chop

static function byte chop(string s)

static Returns the last character of the given string.

Arguments

sAn input string.

Returns

Returns the last character of s.  If s is empty, 0 is returned.

Example

assert( text::chop( "abc" ) == "c" );
assert( text::chop( "abc\n" ) == "\n" );

See Also

chomp, delete, lstrip, rstrip, strip, trim

colorize

static function string colorize(string s,  
fg_color_e fg =  FG_BLACK,
bg_color_e bg =  BG_WHITE,
bit bold =  0,
bit underline =  0,
bit blink =  0,
bit reverse =  0)

static Returns a copy of the given string with ANSI escape codes.

Arguments

sA string to be colorized.
fgoptional The foreground color of s.  See fg_color_e for available colors.  The default is black.
bgoptional The background color of s.  See bg_color_e for available colors.  The default is white.
boldoptional If 1, s is boldfaced.  The default is 0.
underlineoptional If 1, s is underlined.  The default is 0.
blinkoptional If 1, s is blinked.  The default is 0.
reverseoptional If 1, the foreground and the background colors of s are reversed.  The default is 0.

Returns

A copy of s with ANSI escape codes.

Example

$display( text::colorize( "display me in red", FG_RED ) );

contains

static function bit contains(string s,  
string sub,  
int start_pos =  0,
int end_pos =  -1)

static Returns 1 if the given string contains the specified substring.

Arguments

sAn input string.
subA substring to search.  An empty substring (“”) matches no input string.
start_posoptional Specifies the position in s to begin the search.  See Common Arguments.
end_posoptional Specifies the position in s to end the search.  See Common Arguments.

Returns

If s contains sub, 1 is returned.  Otherwise, 0 is returned.

Example

assert( text::contains( "a primary library", "primary" )                  == 1 );
assert( text::contains( "a primary library", "primary", .start_pos( 3 ) ) == 0 );
//                          |----------->|
//                          3
assert( text::contains( "a primary library", "primary", .end_pos(  7 ) )  == 0 );
//                       |----->|
//                              7
assert( text::contains( "a primary library", "primary", .end_pos( -9 ) )  == 1 );
//                       |------>|
//                              -9

See Also

contains_str, count, ends_with, find_any, index, only, rfind_any, rindex, starts_with

contains_str

static function string contains_str(string s,  
string sub,  
int start_pos =  0,
int end_pos =  -1)

static If the given string contains the specified substring, returns that substring.

Arguments

sAn input string.
subA substring to search.  An empty substring (“”) matches no input string.
start_posoptional Specifies the position in s to begin the search.  See Common Arguments.
end_posoptional Specifies the position in s to end the search.  See Common Arguments.

Returns

If s contains sub, sub is returned.  Otherwise, an empty string (“”) is returned.

Example

assert( text::contains_str( "a primary library", "primary" )                  == "primary" );
assert( text::contains_str( "a primary library", "primary", .start_pos( 3 ) ) == "" );
//                              |----------->|
//                              3
assert( text::contains_str( "a primary library", "primary", .end_pos(  7 ) )  == "" );
//                           |----->|
//                                  7
assert( text::contains_str( "a primary library", "primary", .end_pos( -9 ) )  == "primary" );
//                           |------>|
//                                  -9

See Also

contains, count, ends_with, find_any, index, only, rfind_any, rindex, starts_with

count

static function int unsigned count(string s,  
string sub,  
int start_pos =  0,
int end_pos =  -1)

static Returns the number of non-overlapping occurrences of the specified substring in the given string.

Arguments

sAn input string.
subA substring to search.  An empty substring (“”) matches no input string.
start_posoptional Specifies the position in s to begin the search.  See Common Arguments.
end_posoptional Specifies the position in s to end the search.  See Common Arguments.

Returns

The number of non-overlapping occurrences of sub in s.

Example

assert( text::count( "a primary library", "ary" )                  == 2 );
assert( text::count( "a primary library", "ary", .start_pos( 3 ) ) == 2 );
//                       |----------->|
//                       3
assert( text::count( "a primary library", "ary", .end_pos(  7 ) )  == 0 );
//                    |----->|
//                           7
assert( text::count( "a primary library", "ary", .end_pos( -9 ) )  == 1 );
//                    |------>|
//                           -9

See Also

contains, contains_str, ends_with, find_any, index, only, rfind_any, rindex, starts_with

delete

static function string delete(string s,  
string sub,  
int count =  -1)

static Returns a copy of the given string with the specified string removed.

Arguments

sAn input string.
subA substring to remove.  An empty substring (“”) matches no input string.
countoptional The number of substrings to remove.  If specified, only the first count occurrences are removed.  By default, all occurrences are removed.

Returns

A copy of s with the first count occurrences of sub removed.

Example

assert( text::delete( "abcabc", "abc"    ) == "" );
assert( text::delete( "abcabc", "abc", 1 ) == "abc" );

See Also

chop, chomp, insert, lstrip, rstrip, strip, trim

ends_with

static function bit ends_with(string s,  
string_q suffixes,  
int start_pos =  0,
int end_pos =  -1)

static Returns 1 if the given string ends with one of the specified suffixes.

Arguments

sAn input string.
suffixesA queue of suffix strings.  The suffixes can be specified using an array literal.  An empty string (“”) matches no input string.
start_posoptional Specifies the position in s to begin the search.  See Common Arguments.
end_posoptional Specifies the position in s to end the search.  See Common Arguments.

Returns

If s ends with one of the specified suffixes, 1 is returned.  Otherwise, 0 is returned.

Example

assert( text::ends_with( "a primary library", { "primary", "library" } )                  == 1 );
assert( text::ends_with( "a primary library", { "primary", "library" }, .start_pos( 3 ) ) == 1 );
//                           |----------->|
//                           3
assert( text::ends_with( "a primary library", { "primary", "library" }, .end_pos(  7 ) )  == 0 );
//                        |----->|
//                               7
assert( text::ends_with( "a primary library", { "primary", "library" }, .end_pos( -9 ) )  == 1 );
//                        |------>|
//                               -9

See Also

contains, contains_str, count, find_any, index, only, rfind_any, rindex, starts_with

find_any

static function int find_any(string s,  
string_q subs,  
int start_pos =  0,
int end_pos =  -1)

static Returns the lowest index in the given string where each specified substring is found.

Arguments

sAn input string.
subsA queue of substrings.  The substrings can be specified using an array literal.  An empty substring (“”) matches no input string.
start_posoptional Specifies the position in s to begin the search.  See Common Arguments.
end_posoptional Specifies the position in s to end the search.  See Common Arguments.

Returns

The lowest index in s where each substring in subs is found.  If no substring is found, -1 is returned.

Example

assert( text::find_any( "a primary library", { "primary", "library" } ) ==  2 );
assert( text::find_any( "a primary library", { "primary", "library" }, .start_pos( 3 ) ) == 10 );
//                          |----------->|
//                          3
assert( text::find_any( "a primary library", { "primary", "library" }, .end_pos(  7 ) ) == -1 );
//                       |----->|
//                              7
assert( text::find_any( "a primary library", { "primary", "library" }, .end_pos( -9 ) ) ==  2 );
//                       |------>|
//                              -9

See Also

contains, contains_str, count, ends_with, index, only, rfind_any, rindex, starts_with

hash

static function int hash(string s)

static Returns the hash value of the given string.  The hash value is calculated by:

(see hash.png)

where N is the length of the given string.

Argument

sAn input string.

Returns

The hash value of s.

Example

assert( text::hash( "my hash value is" ) == 32'he4260597 );

index

static function int index(string s,  
string sub,  
int start_pos =  0,
int end_pos =  -1)

static Returns the index of the first occurrence of the specified substring in the given string within the optionally specified range.

Arguments

sAn input string.
subA substring to search.  An empty substring (“”) matches no input string.
start_posoptional Specifies the position in s to begin the search.  See Common Arguments.
end_posoptional Specifies the position in s to end the search.  See Common Arguments.

Returns

The index of the first occurrence of sub in s.  If sub is not found, -1 is returned.

Example

assert( text::index( "a primary library", "ary" )                  ==  6 );
assert( text::index( "a primary library", "ary", .start_pos( 3 ) ) ==  6 );
//                       |----------->|
//                       3
assert( text::index( "a primary library", "ary", .end_pos(  7 ) )  == -1 );
//                    |----->|
//                           7
assert( text::index( "a primary library", "ary", .end_pos( -9 ) )  ==  6 );
//                    |------>|
//                           -9

See Also

contains, contains_str, count, ends_with, find_any, only, rfind_any, rindex, starts_with

insert

static function string insert(string s,  
string sub,  
int start_pos =  0)

static Returns a copy of the given string with the specified substring inserted at the specified position.

Arguments

sAn input string.
subA substring to insert.
start_posoptional Specifies the position where sub is inserted.  See Common Arguments.  The default is 0 (inserting sub before s).

Returns

A copy of s with sub inserted at start_pos.

Example

assert( text::insert( "abc", "XYZ"     ) == "XYZabc" ); // insert "XYZ" before the first character ("a")
assert( text::insert( "abc", "XYZ",  1 ) == "aXYZbc" ); // insert "XYZ" before the character index 1 ("b")
assert( text::insert( "abc", "XYZ", -1 ) == "abXYZc" ); // insert "XYZ" before the last character ("c")

See Also

chop, chomp, delete, lstrip, rstrip, strip, trim

is_alpha

static function bit is_alpha(string s)

static Returns 1 if all characters in the given string are alphabetic.  Alphabetic characters are [a-zA-Z].

Argument

sAn input string.

Returns

If all characters in s are alphabetic, 1 is returned.  Otherwise, 0 is returned.  If s is an empty string, 0 is returned.

Example

assert( text::is_alpha( "abc"  ) == 1 );
assert( text::is_alpha( "abc_" ) == 0 );

See Also

is_digit, is_lower, is_printable, is_space, is_upper

is_digit

static function bit is_digit(string s)

static Returns 1 if all characters in the given string are digits.  Digits are [0-9].

Argument

sAn input string.

Returns

If all characters in s are digits, 1 is returned.  Otherwise, 0 is returned.  If s is an empty string, 0 is returned.

Example

assert( text::is_digit( "123"  ) == 1 );
assert( text::is_digit( "123X" ) == 0 );

See Also

is_alpha, is_lower, is_printable, is_space, is_upper

is_lower

static function bit is_lower(string s)

static Returns 1 if all cased characters in the given string are lowercase.  Lowercase characters are [a-z].

Argument

sAn input string.

Returns

If all cased characters in s are lowercase, 1 is returned.  Otherwise, 0 is returned.  If s is an empty string, 0 is returned.

Example

assert( text::is_lower( "abc"   ) == 1 );
assert( text::is_lower( "abcX"  ) == 0 );
assert( text::is_lower( "abc!?" ) == 1 ); // all cased characters are lowercase

See Also

is_alpha, is_digit, is_printable, is_space, is_upper

is_printable

static function bit is_printable(string s)

static Returns 1 if all characters in the given string are printable.  Printable characters are the ones whose ASCII code are between ‘h20 (“ “) and ‘h7F (“~”).

Argument

sAn input string.

Returns

If all characters in s are printable, 1 is returned.  Otherwise, 0 is returned.  If s is an empty string, 0 is returned.

Example

assert( text::is_printable( "!@#$" ) == 1 );
assert( text::is_printable( "\200" ) == 0 ); // ASCII 'h80 is not printable

See Also

is_alpha, is_digit, is_lower, is_space, is_upper

is_single_bit_type

static function bit is_single_bit_type(string s)

static Returns 1 if the given string is bit, logic, or reg.

Argument

sAn input string.

Returns

If s is bit, logic, or reg, 1 is returned.  Othewise, 0 is returned.

Example

assert( text::is_single_bit_type( "bit" ) == 1 );
assert( text::is_single_bit_type( "int" ) == 0 );

is_space

static function bit is_space(string s)

static Returns 1 if all characters in the given string are whitespace characters: a space (“ “), a tab (\t), or a newline (\n).

Argument

sAn input string.

Returns

If all characters in s are whitespace characters, 1 is returned.  Otherwise, 0 is returned.  If s is an empty string, 0 is returned.

Example

assert( text::is_space( " \t\n" ) == 1 );
assert( text::is_space( "X\t\n" ) == 0 );

See Also

is_alpha, is_digit, is_lower, is_printable, is_upper

is_upper

static function bit is_upper(string s)

static Returns 1 if all cased characters in the given string are uppercase.  Uppercase characters are [A-Z].

Argument

sAn input string.

Returns

If all cased characters in s are uppercase, 1 is returned.  Otherwise, 0 is returned.  If s is an empty string, 0 is returned.

Example

assert( text::is_upper( "ABC"   ) == 1 );
assert( text::is_upper( "ABCx"  ) == 0 );
assert( text::is_upper( "ABC!?" ) == 1 ); // all cased characters are uppercase

See Also

is_alpha, is_digit, is_lower, is_printable, is_space

join_str

static function string join_str(string_q strings,  
string separator =  "")

static Returns a string by concatenating the strings in the given string queue, separated by the specified separator.

Arguments

stringsA queue of strings.  The strings can be specified using an array literal.
separatoroptional A separator between strings.  The default is an empty string (“”).

Returns

A string by concatenating the strings in strings, separated by separator.

Example

assert( text::join_str( { "abc", "XYZ" }        ) == "abcXYZ"    );
assert( text::join_str( { "abc", "XYZ" }, "---" ) == "abc---XYZ" );

lc_first

static function string lc_first(string s)

static Returns a copy of the given string with the first character lowercased and the remainder unchanged.

Argument

sAn input string.

Returns

A copy of s with the first character lowercased and the remainder unchanged.

Example

assert( text::lc_first( "Lower CASE first" ) == "lower CASE first" );

See Also

capitalize, swap_case, title_case, uc_first

ljust

static function string ljust(string s,  
int width,  
byte fill_char =  " ",
bit trim_right =  0)

static Returns a string of the specified width with the given string left justified and padded with the specified character.

Arguments

sA string to left-justify.
widthThe width of the returned string.
fill_charoptional A character used for padding if width is wider than the length of s.  The default is a space character (“ “).
trim_rightoptional If width is narrower than the length of s and trim_right is 1, then the tail of s is trimmed to fit within width.  If trim_right is 0, then width is widened to the length of s.  If width is wider than or equal to the length of s, trim_right is ignored.  The default is 0.

Returns

A string with s left-justified and padded with fill_char.

Example

assert( text::ljust( "ljust me", 15 )                  == "ljust me       " );
assert( text::ljust( "ljust me", 15, "-" )             == "ljust me-------" );
assert( text::ljust( "ljust me", 7 )                   == "ljust me"        ); // widened to fit
assert( text::ljust( "ljust me", 7, .trim_right( 1 ) ) == "ljust m"         ); // trimmed

See Also

center, rjust

lstrip

static function string lstrip(string s,  
string chars =  " \t\n")

static Returns a copy of the given string with leading characters removed.

Arguments

sA string to be stripped.
charsoptional A string specifying the set of characters to be removed.  The default is whitespace characters: a space (“ “), a tab (\t), or a newline (\n).  Note that the chars string is not a prefix.  All combinations of its characters are stripped.

Returns

A copy of s with leading characters removed.

Example

assert( text::lstrip( "      abc" ) == "abc" );
assert( text::lstrip( "  \t\nabc" ) == "abc" );
assert( text::lstrip( "aabbcc", "a"  ) == "bbcc" );
assert( text::lstrip( "aabbcc", "ab" ) == "cc"   );
assert( text::lstrip( "aabbcc", "ba" ) == "cc"   ); // "b"s and "a"s are stripped

See Also

chop, chomp, delete, rstrip, strip, trim

only

static function bit only(string s,
string chars)

static Returns 1 if the given string consists of only the specified set of characters.

Arguments

sAn input string.
charsA string specifying the set of characters to be checked.  An empty string (“”) matches no input string.

Returns

If s consists of only the characters in chars, 1 is returned.  Othewise, 0 is returned.

Example

assert( text::only( "abc", "abcXYZ" ) == 1 );
assert( text::only( "abcXYZ", "abc" ) == 0 );

See Also

contains, contains_str, count, ends_with, find_any, index, rfind_any, rindex, starts_with

partition

static function three_strings partition(string s,
string sep)

static Searches the first occurrence of the specified separator in the given string and returns an array of three strings.  The returned array consists of: the string before the separator, the separator itself, and the string after the separator.  If the separator is not found, the given string and two empty strings are returned.

Arguments

sAn input string.
sepA separator.

Returns

An array that consists of the part before sep, the sep, and the part after sep.  If sep is not found, returns s and two empty strings.

Example

three_strings s, t1, t2, t3, t4;

s = '{ "abc", "-", "XYZ" };
assert( text::partition( "abc-XYZ", "-" ) == s );

t1 = '{ "", "a", "bcabc" };
t2 = '{ "a", "b", "cabc" };
t3 = '{ "ab", "c", "abc" };
t4 = '{ "abcabc", "", "" };
assert( text::partition( "abcabc", "a" ) == t1 );
assert( text::partition( "abcabc", "b" ) == t2 );
assert( text::partition( "abcabc", "c" ) == t3 );
assert( text::partition( "abcabc", "X" ) == t4 );

See Also

rpartition, rsplit, split

replace

static function string replace(string s,  
string old_str,  
string new_str,  
int count =  -1)

static Returns a copy of the given string with the specified string replaced with a new string.

Arguments

sAn input string.
old_strAn old string.  An empty string (“”) matches no input string.
new_strA new string.
countoptional The number of strings to replace.  If specified, only the first count occurrences are replaced.  By default, all occurrences are replaced.

Returns

A copy of s with the first count occurrences of old_str replaced with new_str.

Example

assert( text::replace( "abcabc", "abc", "XYZ"    ) == "XYZXYZ" );
assert( text::replace( "abcabc", "abc", "XYZ", 1 ) == "XYZabc" );

See Also

change

reverse

static function string reverse(string s)

static Returns a copy of the given string with the characters in reverse order.

Argument

sAn input string.

Returns

A copy of s with the characters in reverse order.

Example

assert( text::reverse( "reverse me!" ) == "!em esrever" );
assert( text::reverse( "wonton? not now" ) == "won ton ?notnow" );

rfind_any

static function int rfind_any(string s,  
string_q subs,  
int start_pos =  0,
int end_pos =  -1)

static Returns the highest index in the given string where each specified substring is found.

Arguments

sAn input string.
subsA queue of substrings.  The substrings can be specified using an array literal.  An empty substring (“”) matches no input string.
start_posoptional Specifies the position in s to begin the search.  See Common Arguments.
end_posoptional Specifies the position in s to end the search.  See Common Arguments.

Returns

The highest index in s where each substring in subs is found.  If no substring is found, -1 is returned.

Example

assert( text::rfind_any( "a primary library", { "primary", "library" } )                  == 10 );
assert( text::rfind_any( "a primary library", { "primary", "library" }, .start_pos( 3 ) ) == 10 );
//                           |----------->|
//                           3
assert( text::rfind_any( "a primary library", { "primary", "library" }, .end_pos(  7 ) )  == -1 );
//                        |----->|
//                               7
assert( text::rfind_any( "a primary library", { "primary", "library" }, .end_pos( -9 ) )  ==  2 );
//                        |------>|
//                               -9

See Also

contains, contains_str, count, ends_with, find_any, index, only, rindex, starts_with

rindex

static function int rindex(string s,  
string sub,  
int start_pos =  0,
int end_pos =  -1)

static Returns the index of the last occurrence of the specified substring in the given string within the optionally specified range.

Arguments

sAn input string.
subA substring to search.  An empty substring (“”) matches no input string.
start_posoptional Specifies the position in s to begin the search.  See Common Arguments.
end_posoptional Specifies the position in s to end the search.  See Common Arguments.

Returns

The index of the last occurrence of sub in s.  If sub is not found, -1 is returned.

Example

assert( text::rindex( "a primary library", "ary" )                  == 14 );
assert( text::rindex( "a primary library", "ary", .start_pos( 3 ) ) == 14 );
//                        |----------->|
//                        3
assert( text::rindex( "a primary library", "ary", .end_pos(  7 ) )  == -1 );
//                     |----->|
//                            7
assert( text::rindex( "a primary library", "ary", .end_pos( -9 ) )  ==  6 );
//                     |------>|
//                            -9

See Also

contains, contains_str, count, ends_with, find_any, index, only, rfind_any, starts_with

rjust

static function string rjust(string s,  
int width,  
byte fill_char =  " ",
bit trim_left =  0)

static Returns a string of the specified width with the given string right justified and padded with the specified character.

Arguments

sA string to right-justify.
widthThe width of the returned string.
fill_charoptional A character used for padding if width is wider than the length of s.  The default is a space character (“ “).
trim_leftoptional If width is narrower than the length of s and trim_left is 1, then the head of s is trimmed to fit within width.  If trim_left is 0, then width is widened to the length of s.  If width is wider than or equal to the length of s, trim_left is ignored.  The default is 0.

Returns

A string with s right justified and padded with fill_char.

Example

assert( text::rjust( "rjust me", 15 )                 == "       rjust me" );
assert( text::rjust( "rjust me", 15, "-" )            == "-------rjust me" );
assert( text::rjust( "rjust me", 7 )                  ==        "rjust me" ); // widened to fit
assert( text::rjust( "rjust me", 7, .trim_left( 1 ) ) ==         "just me" ); // trimmed

See Also

center, ljust

rpartition

static function three_strings rpartition(string s,
string sep)

static Searches the last occurrence of the specified separator in the given string and returns an array of three strings.  The returned array consists of: the string before the separator, the separator itself, and the string after the separator.  If the separator is not found, the given string and two empty strings are returned.

Arguments

sAn input string.
sepA separator.

Returns

An array that consists of the part before sep, the sep, and the part after sep.  If sep is not found, returns s and two empty strings.

Example

three_strings s, t1, t2, t3, t4;

s = '{ "abc", "-", "XYZ" };
assert( text::rpartition( "abc-XYZ", "-" ) == s );

t1 = '{ "abc", "a", "bc" };
t2 = '{ "abca", "b", "c" };
t3 = '{ "abcab", "c", "" };
t4 = '{ "abcabc", "", "" };
assert( text::rpartition( "abcabc", "a" ) == t1 );
assert( text::rpartition( "abcabc", "b" ) == t2 );
assert( text::rpartition( "abcabc", "c" ) == t3 );
assert( text::rpartition( "abcabc", "X" ) == t4 );

See Also

partition, rsplit, split

rsplit

static function string_q rsplit(string s,  
string sep =  "",
int max_split =  -1)

static Returns a queue of substrings by dividing the given string by the specified separator from the right.

Arguments

sAn input string.  If s is empty, an empty queue is returned.
sepoptional A separator.  If specified, sep is used as the delimiter.  The sep itself is not returned as an element of the queue.  If not specified, whitespace characters (a space (“ “), a tab (\t), or a newline (\n)) are used.  If sep is not specified, the contiguous whitespaces and the trailing whitespaces are ignored.
max_splitoptional If specified, at most max_split splits are done from the right and the remaining substring is returned as the first element of the queue.  If not specified or -1, there is no limit to the number of splits.

Returns

A queue of substrings (string_q).

Example

string_q s1, s2, s3, s4, t1, t2, t3, t4, t5;

s1 = '{ "abc", "pqr", "xyz" };
s2 = '{ "  abc  pqr", "xyz" };
s3 = '{ "  abc", "pqr", "xyz" };
s4 = '{ "abc", "pqr", "xyz" };
assert( text::rsplit( "  abc  pqr  xyz  "                  ) == s1 );
assert( text::rsplit( "  abc  pqr  xyz  ", .max_split( 1 ) ) == s2 );
assert( text::rsplit( "  abc  pqr  xyz  ", .max_split( 2 ) ) == s3 );
assert( text::rsplit( "  abc  pqr  xyz  ", .max_split( 3 ) ) == s4 );

t1 = '{ "", "abc", "pqr", "xyz", "" };
t2 = '{ "--abc--pqr--xyz", "" };
t3 = '{ "--abc--pqr", "xyz", "" };
t4 = '{ "--abc", "pqr", "xyz", "" };
t5 = '{ "", "abc", "pqr", "xyz", "" };
assert( text::rsplit( "--abc--pqr--xyz--", "--"                  ) == t1 );
assert( text::rsplit( "--abc--pqr--xyz--", "--", .max_split( 1 ) ) == t2 );
assert( text::rsplit( "--abc--pqr--xyz--", "--", .max_split( 2 ) ) == t3 );
assert( text::rsplit( "--abc--pqr--xyz--", "--", .max_split( 3 ) ) == t4 );
assert( text::rsplit( "--abc--pqr--xyz--", "--", .max_split( 4 ) ) == t5 );

See Also

partition, rpartition, split

rstrip

static function string rstrip(string s,  
string chars =  " \t\n")

static Returns a copy of the given string with trailing characters removed.

Arguments

sA string to be stripped.
charsoptional A string specifying the set of characters to be removed.  The default is whitespace characters: a space (“ “), a tab (\t), or a newline (\n).  Note that the chars string is not a suffix.  All combinations of its characters are stripped.

Returns

A copy of s with trailing characters removed.

Example

assert( text::rstrip( "abc      " ) == "abc" );
assert( text::rstrip( "abc  \t\n" ) == "abc" );
assert( text::rstrip( "aabbcc", "c"  ) == "aabb" );
assert( text::rstrip( "aabbcc", "bc" ) == "aa"   );
assert( text::rstrip( "aabbcc", "cb" ) == "aa"   ); // "c"s and "b"s are stripped

See Also

chop, chomp, delete, lstrip, strip, trim

slice

static function string slice(string s,  
int start_pos =  0,
int end_pos =  - 1)

static Returns a substring in the specified range.  This function is similar to the substr function in native SystemVerilog, but one can specify negative numbers to specify the range with this function.

Arguments

sAn input string.
start_posoptional Specifies the position in s to begin the substring.  See Common Arguments.
end_posoptional Specifies the position in s to end the substring.  See Common Arguments.

Returns

Returns a substring in the specified range.

Example

assert( text::slice( "slice me",  2,  6 ) == "ice m" );
assert( text::slice( "slice me", -6, -2 ) == "ice m" );

See Also

slice_len

slice_len

static function string slice_len(string s,  
int start_pos =  0,
int unsigned length =  s.len())

static Returns a substring in the specified range.  Unlike slice, this function takes the length to extract instead of the end position.

Arguments

sAn input string.
start_posoptional Specifies the position in s to begin the substring.  See Common Arguments.
lengthoptional The number of characters to extract.  The default is the length of s.

Returns

Returns a substring in the specified range.

Example

assert( text::slice_len( "slice me",  2, 5 ) == "ice m" );
assert( text::slice_len( "slice me", -6, 5 ) == "ice m" );

See Also

slice

split

static function string_q split(string s,  
string sep =  "",
int max_split =  -1)

static Returns a queue of substrings by dividing the given string by the specified separator.

Arguments

sAn input string.  If s is empty, an empty queue is returned.
sepoptional A separator.  If specified, sep is used as the delimiter.  The sep itself is not returned as an element of the queue.  If not specified, whitespace characters (a space (“ “), a tab (\t), or a newline (\n)) are used.  If sep is not specified, the leading whitespaces and the contiguous whitespaces are ignored.
max_splitoptional If specified, at most max_split splits are done and the remaining substring is returned as the last element of the queue.  If not specified or -1, there is no limit to the number of splits.

Returns

A queue of substrings (string_q).

Example

string_q s1, s2, s3, s4, t1, t2, t3, t4, t5;

s1 = '{ "abc", "pqr", "xyz" };
s2 = '{ "abc", "pqr  xyz  " };
s3 = '{ "abc", "pqr", "xyz  " };
s4 = '{ "abc", "pqr", "xyz" };
assert( text::split( "  abc  pqr  xyz  "                  ) == s1 );
assert( text::split( "  abc  pqr  xyz  ", .max_split( 1 ) ) == s2 );
assert( text::split( "  abc  pqr  xyz  ", .max_split( 2 ) ) == s3 );
assert( text::split( "  abc  pqr  xyz  ", .max_split( 3 ) ) == s4 );

t1 = '{ "", "abc", "pqr", "xyz", "" };
t2 = '{ "", "abc--pqr--xyz--" };
t3 = '{ "", "abc", "pqr--xyz--" };
t4 = '{ "", "abc", "pqr", "xyz--" };
t5 = '{ "", "abc", "pqr", "xyz", "" };
assert( text::split( "--abc--pqr--xyz--", "--"                  ) == t1 );
assert( text::split( "--abc--pqr--xyz--", "--", .max_split( 1 ) ) == t2 );
assert( text::split( "--abc--pqr--xyz--", "--", .max_split( 2 ) ) == t3 );
assert( text::split( "--abc--pqr--xyz--", "--", .max_split( 3 ) ) == t4 );
assert( text::split( "--abc--pqr--xyz--", "--", .max_split( 4 ) ) == t5 );

See Also

partition, rpartition, rsplit

starts_with

static function bit starts_with(string s,  
string_q prefixes,  
int start_pos =  0,
int end_pos =  -1)

static Returns 1 if the given string starts with one of the specified prefixes.

Arguments

sAn input string.
prefixesA queue of prefix strings.  The prefixes can be specified using an array literal.  An empty string (“”) matches no input string.
start_posoptional Specifies the position in s to begin the search.  See Common Arguments.
end_posoptional Specifies the position in s to end the search.  See Common Arguments.

Returns

If s starts with one of the specified prefixes, 1 is returned.  Otherwise, 0 is returned.

Example

assert( text::starts_with( "a primary library", { "a primary", "library" } )                   == 1 );
assert( text::starts_with( "a primary library", { "a primary", "library" }, .start_pos( 10 ) ) == 1 );
//                                    |---->|
//                                   10
assert( text::starts_with( "a primary library", { "a primary", "library" }, .end_pos(  7 ) )  == 0 );
//                          |----->|
//                                 7
assert( text::starts_with( "a primary library", { "a primary", "library" }, .end_pos( -9 ) )  == 1 );
//                          |------>|
//                                 -9

See Also

contains, contains_str, count, ends_with, find_any, index, only, rfind_any, rindex

strip

static function string strip(string s,  
string chars =  " \t\n")

static Returns a copy of the given string with leading and trailing characters removed.

Arguments

sA string to be stripped.
charsoptional A string specifying the set of characters to be removed.  The default is whitespace characters: a space (“ “), a tab (\t), or a newline (\n).  Note that the chars string is not a prefix or suffix.  All combinations of its characters are stripped.

Returns

A copy of s with leading and trailing characters removed.

Example

assert( text::strip( "   abc    " ) == "abc" );
assert( text::strip( " \t\nabc\n" ) == "abc" );
assert( text::strip( "aabbcc", "a"  ) == "bbcc" );
assert( text::strip( "aabbcc", "ab" ) == "cc"   );
assert( text::strip( "aabbcc", "ac" ) == "bb"   );

See Also

chop, chomp, delete, lstrip, rstrip, trim

swap_case

static function string swap_case(string s)

static Returns a copy of the given string with uppercase characters converted to lowercase, and lowercase characters converted to uppercase.

Argument

sA string to be swap-cased.

Returns

A copy of s with uppercase characters converted to lowercase, and lowercase characters converted to uppercase.

Example

assert( text::swap_case( "Swap Case Me!" ) == "sWAP cASE mE!" );

See Also

capitalize, lc_first, title_case, uc_first

title_case

static function string title_case(string s)

static Returns a copy of the given string with the first character of words uppercased and the remainder lowercased.

Argument

sA string to be title-cased.

Returns

A copy of s with the first character of words uppercased and the remainder lowercased.

Example

assert( text::title_case( "title case me!" ) == "Title Case Me!" );

See Also

capitalize, lc_first, swap_case, uc_first

trim

static function string trim(string s,  
int unsigned left =  0,
int unsigned right =  0)

static Returns a copy of the given string with the specified numbers of leading and trailing characters removed.

Arguments

sA string to be trimmed.
leftoptional The number of leading characters to remove.  The default is 0.
rightoptional The number of trailing characters to remove.  The default is 0.

Returns

A copy of s with leading left characters and trailing right characters removed.

Example

assert( text::trim( "trim me!"       ) == "trim me!" );
assert( text::trim( "trim me!", 1, 2 ) ==  "rim m"   );
assert( text::trim( "trim me!", 3, 4 ) ==    "m"     );

See Also

chop, chomp, delete, lstrip, rstrip, strip

uc_first

static function string uc_first(string s)

static Returns a copy of the given string with the first character uppercased and the remainder unchanged.

Argument

sAn input string.

Returns

A copy of s with the first character uppercased and the remainder unchanged.

Example

assert( text::uc_first( "upper CASE first" ) == "Upper CASE first" );

See Also

capitalize, lc_first, swap_case, title_case

untabify

static function string untabify(string s,  
int unsigned tab_size =  8)

static Returns a copy of the given string where all tab characters (\t) are replaced by one or more spaces, depending on the tab positions.  If a newline (\n) is found, it is copied and the tab position is reset.

Arguments

sA string to untabify.
tab_sizeoptional Tab positions occur every tab_size characters.  The default is 8.

Returns

A copy of s where all tab characters are replaced by one or more spaces, depending on the tab positions.

Example

assert( text::untabify( "AB\tCDE\tFGHI\tJKLMN" ) == "AB      CDE     FGHI    JKLMN" );
                                   // tab positions: ^       ^       ^       ^
assert( text::untabify( "AB\tCDE\tFGHI\tJKLMN", 4 ) == "AB  CDE FGHI    JKLMN" );
                                   // tab positions:    ^   ^   ^   ^   ^   ^
assert( text::untabify( "AB\nCDE\tFGHI\tJKLMN", 4 ) == "AB\nCDE FGHI    JKLMN" );
                                   // tab positions:    ^   ^   ^   ^   ^   ^
virtual class text
Provides utility functions for text processing.
static function string capitalize(string s)
static Returns a copy of the given string with the first character uppercased and the remainder lowercased.
static function string center(string s,  
int width,  
byte fill_char =  " ",
bit trim_ends =  0)
static Returns a string of the specified width with the given string centerted and padded with the specified character.
static function string change(string s,  
string sub,  
int start_pos =  0,
int end_pos =  -1)
static Returns a copy of the given string with the characters in the specified range replaced with the specified substring.
static function string chomp(string s)
static Returns a copy of the given string with the last newline character removed (if present).
static function byte chop(string s)
static Returns the last character of the given string.
static function string colorize(string s,  
fg_color_e fg =  FG_BLACK,
bg_color_e bg =  BG_WHITE,
bit bold =  0,
bit underline =  0,
bit blink =  0,
bit reverse =  0)
static Returns a copy of the given string with ANSI escape codes.
static function bit contains(string s,  
string sub,  
int start_pos =  0,
int end_pos =  -1)
static Returns 1 if the given string contains the specified substring.
static function string contains_str(string s,  
string sub,  
int start_pos =  0,
int end_pos =  -1)
static If the given string contains the specified substring, returns that substring.
static function int unsigned count(string s,  
string sub,  
int start_pos =  0,
int end_pos =  -1)
static Returns the number of non-overlapping occurrences of the specified substring in the given string.
static function string delete(string s,  
string sub,  
int count =  -1)
static Returns a copy of the given string with the specified string removed.
static function bit ends_with(string s,  
string_q suffixes,  
int start_pos =  0,
int end_pos =  -1)
static Returns 1 if the given string ends with one of the specified suffixes.
static function int find_any(string s,  
string_q subs,  
int start_pos =  0,
int end_pos =  -1)
static Returns the lowest index in the given string where each specified substring is found.
static function int hash(string s)
static Returns the hash value of the given string.
static function int index(string s,  
string sub,  
int start_pos =  0,
int end_pos =  -1)
static Returns the index of the first occurrence of the specified substring in the given string within the optionally specified range.
static function string insert(string s,  
string sub,  
int start_pos =  0)
static Returns a copy of the given string with the specified substring inserted at the specified position.
static function bit is_alpha(string s)
static Returns 1 if all characters in the given string are alphabetic.
static function bit is_digit(string s)
static Returns 1 if all characters in the given string are digits.
static function bit is_lower(string s)
static Returns 1 if all cased characters in the given string are lowercase.
static function bit is_printable(string s)
static Returns 1 if all characters in the given string are printable.
static function bit is_single_bit_type(string s)
static Returns 1 if the given string is bit, logic, or reg.
static function bit is_space(string s)
static Returns 1 if all characters in the given string are whitespace characters: a space (“ “), a tab (\t), or a newline (\n).
static function bit is_upper(string s)
static Returns 1 if all cased characters in the given string are uppercase.
static function string join_str(string_q strings,  
string separator =  "")
static Returns a string by concatenating the strings in the given string queue, separated by the specified separator.
static function string lc_first(string s)
static Returns a copy of the given string with the first character lowercased and the remainder unchanged.
static function string ljust(string s,  
int width,  
byte fill_char =  " ",
bit trim_right =  0)
static Returns a string of the specified width with the given string left justified and padded with the specified character.
static function string lstrip(string s,  
string chars =  " \t\n")
static Returns a copy of the given string with leading characters removed.
static function bit only(string s,
string chars)
static Returns 1 if the given string consists of only the specified set of characters.
static function three_strings partition(string s,
string sep)
static Searches the first occurrence of the specified separator in the given string and returns an array of three strings.
static function string replace(string s,  
string old_str,  
string new_str,  
int count =  -1)
static Returns a copy of the given string with the specified string replaced with a new string.
static function string reverse(string s)
static Returns a copy of the given string with the characters in reverse order.
static function int rfind_any(string s,  
string_q subs,  
int start_pos =  0,
int end_pos =  -1)
static Returns the highest index in the given string where each specified substring is found.
static function int rindex(string s,  
string sub,  
int start_pos =  0,
int end_pos =  -1)
static Returns the index of the last occurrence of the specified substring in the given string within the optionally specified range.
static function string rjust(string s,  
int width,  
byte fill_char =  " ",
bit trim_left =  0)
static Returns a string of the specified width with the given string right justified and padded with the specified character.
static function three_strings rpartition(string s,
string sep)
static Searches the last occurrence of the specified separator in the given string and returns an array of three strings.
static function string_q rsplit(string s,  
string sep =  "",
int max_split =  -1)
static Returns a queue of substrings by dividing the given string by the specified separator from the right.
static function string rstrip(string s,  
string chars =  " \t\n")
static Returns a copy of the given string with trailing characters removed.
static function string slice(string s,  
int start_pos =  0,
int end_pos =  - 1)
static Returns a substring in the specified range.
static function string slice_len(string s,  
int start_pos =  0,
int unsigned length =  s.len())
static Returns a substring in the specified range.
static function string_q split(string s,  
string sep =  "",
int max_split =  -1)
static Returns a queue of substrings by dividing the given string by the specified separator.
static function bit starts_with(string s,  
string_q prefixes,  
int start_pos =  0,
int end_pos =  -1)
static Returns 1 if the given string starts with one of the specified prefixes.
static function string strip(string s,  
string chars =  " \t\n")
static Returns a copy of the given string with leading and trailing characters removed.
static function string swap_case(string s)
static Returns a copy of the given string with uppercase characters converted to lowercase, and lowercase characters converted to uppercase.
static function string title_case(string s)
static Returns a copy of the given string with the first character of words uppercased and the remainder lowercased.
static function string trim(string s,  
int unsigned left =  0,
int unsigned right =  0)
static Returns a copy of the given string with the specified numbers of leading and trailing characters removed.
static function string uc_first(string s)
static Returns a copy of the given string with the first character uppercased and the remainder unchanged.
static function string untabify(string s,  
int unsigned tab_size =  8)
static Returns a copy of the given string where all tab characters (\t) are replaced by one or more spaces, depending on the tab positions.
typedef enum { FG_BLACK = 30, FG_RED = 31, FG_GREEN = 32, FG_YELLOW = 33, FG_BLUE = 34, FG_MAGENTA = 35, FG_CYAN = 36, FG_WHITE = 37 } fg_color_e
The enumerated type of foreground colors.
typedef enum { BG_BLACK = 40, BG_RED = 41, BG_GREEN = 42, BG_YELLOW = 43, BG_BLUE = 44, BG_MAGENTA = 45, BG_CYAN = 46, BG_WHITE = 47 } bg_color_e
The enumerated type of background colors.
typedef string string_q[$]
The queue of strings.