crypt()
STRING crypt(STRING str[, STRING salt])
This function performs one-way encryption on str, using the SHA encryption routine. If salt is not specified, it is chosen randomly. The return value is the encrypted string.
The encryption performed by this function has the property that it is very difficult to find a string which will produce a given result; however, a given string and a given salt will always yield the same encrypted string.
crypt("str", "salt")
=> "$2$salt$AIK1GjWYixJe84m.O2sxSFrVPv7"
When matching an encrypted string versus a non-encrypted string, the function match_crypted() should be used, as it will take into consideration any possible future changes to the crypt() implementation.
explode()
LIST explode(STRING str[, STRING sep[, INTEGER want_blanks]])
This function breaks str into a list of strings, using the string sep as the delimiter. If sep is unspecified it uses spaces as the delimiter. If want_blanks is specified and is true, zero-length strings will be included in the final list, otherwise they will not. The function split() is similar, but uses a regular expression as the delimiter.
explode(" foo bar baz")
=> ["foo", "bar", "baz"]
explode("foo:bar::baz", ":")
=> ["foo", "bar", "baz"]
explode("foo:bar::baz", ":", 1)
=> ["foo", "bar", "", "baz"]
lowercase()
STRING lowercase(STRING str)
This function changes each character in str to its lowercase value and returns the result.
lowercase("FoO bAr")
=> "foo bar"
match_begin()
INTEGER match_begin(STRING str, STRING search[, STRING sep])
This function looks for the string search at the beginning of each word in str. The word separator is given by the string sep if it is specified; otherwise, a space is used. The return value is 1 (true) if search was found at the beginning of a word in str, or 0 (false) if not.
match_begin("foo:bar:baz", "fo", ":")
=> 1
match_begin("foo bar baz", "ar")
=> 0
match_crypted()
LIST match_crypted(STRING crypted, STRING matchwith)
This function is used to match strings encrypted with the crypt() function. This function should be used instead of directly comparing the result, as it will take into account possible older encryption methods. It returns 1 (true) if there is a correct match, or 0 (false) if there is not.
match_crypted("$2$salt$AIK1GjWYixJe84m.O2sxSFrVPv7", "str")
=> 1
match_pattern()
LIST match_pattern(STRING str, STRING pattern)
This function matches the wildcard pattern pattern against str. A wildcard pattern is a string with asterisks (*) signifying wildcards. A regular character matches itself, while a wildcard matches any number of arbitrary characters. The return value is a list of the substrings of str which match the wildcards in pattern, or 0 (zero) if the match fails.
match_pattern("foobar", "*")
=> ["foobar"]
match_pattern("foo quux bar quuux baz", "foo * bar * baz")
=> ["quux", "quuux"]
match_pattern("narf:fnord", "narf:*")
=> ["fnord"]
match_pattern("foo baz", "foo * bar")
=> 0
match_regexp()
LIST match_regexp(STRING str, STRING regexp[, INTEGER cs])
This function matches the regular expression argument regexp against the argument str. If cs is specified and is true, the match is case-sensitive; otherwise, it is case-insensitive. If the match succeeds, a ten-element list is returned giving the substitutions for the match (see below); otherwise, a 0 (zero) is returned. If the argument regexp is not a valid regular expression, the error ~regexp is thrown.
This function is often used when all that is desired is whether a match was made or not. The function regexp() is better for handling the full results of a regexp match. See Regular Expressions for more information.
The substitutions are the text in str which match the parenthesized subexpressions in regexp. The first substitution is the text in str which matches the whole regexp. Thus, a regular expression can contain no more than nine parenthesized subexpressions. Substitutions are returned as two-element lists [start, len] giving the index of the matching text in str and the length of the text.
match_regexp("fooBAR", "bar")
=> [[4, 3], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0],
[0, 0]]
match_regexp("Greg says, 'Hello.'", "^([^ ]+) says, '(.*)'$")
=> [[1, 19], [1, 4], [13, 6], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0],
[0, 0]]
match_regexp(" 300 100 200 ", "[0-9]+")
=> [[2, 3], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0], [0, 0],
[0, 0]]
match_regexp("foo", "bar")
=> 0
match_regexp("Foo", "foo", 1)
=> 0
match_template()
LIST match_template(STRING str, STRING template)
This function matches the template template against the command str. The return value is a list of fields resulting from the template match, or 0 (zero) if the match fails or if template is an invalid template.
Templates are composed of word-patterns and wildcards. Word-patterns may contain a partial-match operator (?) and/or pipe characters ( | ).
A word-pattern is any sequence of characters bounded by spaces, or the beginning or end of the string. The result from a word-pattern match is the string which matched the word-pattern.
The partial-match operator is used to indicate that partial matches that extend at least as far as the question mark are okay. For instance, the word-pattern "ex?am" matches any of the words "ex", "exa", and "exam".
The pipe character is used to group more than one word where any of the words in the group can be matched as one word. For instance, the template "this|that|there" would match "this", "that", or "there".
Wildcards can be either simple or coupled. A simple wildcard is represented by an asterisk (*). A simple wildcard matches any number of words in str, and must be bounded by spaces or the beginning or end of the template. If the wildcard is followed in the template by a word-pattern, then it can also match a quoted wildcard match.
A quoted wildcard match is just like a ColdC string literal: it begins and ends with a double quote ("), and can include a literal double quote or backslash by preceding the character with a backslash (\). If the simple wildcard is followed by a word-pattern, and the words in str that the wildcard would match begin with a double quote, then the match must be a quoted wildcard match or the match fails, even if the match would have succeeded if the words were not treated as a quoted wildcard match. However, if the words that the wildcard would match begin with a backslash followed by a double quote, then the backslash is ignored and the double quote and the text following it are treated as regular words.
The following template using a simple wildcard "* bar" matches any of the following strings:
- "foo bar"
- "foo baz bar"
- "\"foo bar \" baz\" bar"
- "\"foo baz bar"
Matching against a simple wildcard produces one result per wildcard—the words that the simple wildcard matched. If the wildcard matches a quoted wildcard match, then the beginning and ending double quotes are stripped out of the result, as well as any backslashes used to escape characters inside the double quotes.
A coupled wildcard is represented by the three-character sequence '*=*'. It matches any sequence of words containing an equal sign (=), and results in two strings, the text before the equal sign and the text after it. Any spaces surrounding the equal sign in the matched string are ignored and do not show up in the results. The text before the equal sign can be a quoted wildcard match (as before, if it begins with a double quote, then it must be a quoted wildcard match or the match fails, unless the initial double quote is escaped by a backslash). If the coupled wildcard is followed by a word pattern, then the text after the equal sign can also be a quoted wildcard match. The coupled wildcard is a special feature intended for parsing TinyMUD command formats.
match_template("@descr me as foobar", "@desc?ribe * as *")
=> ["@descr", "me", "as", "foobar"]
match_template("@desc \"as is\" as foobar", "@desc?ribe * as *")
=> ["@desc", "as is", "as", "foobar"]
match_template("@desc \"as\" is as foobar", "@desc?ribe * as *")
=> 0
match_template("@desc \\\"as\" is as foobar", "@desc?ribe * as *")
=> ["@desc", "\"as\" is", "as", "foobar"]
match_template("@descr me =foobar", "@desc?ribe *=*")
=> ["@descr", "me", "foobar"]
match_template("@desc \"2+2=4\"= an equation", "@desc?ribe *=*")
=> ["@desc", "2+2=4", "an equation"]
match_template("look at rose", "l?ook|ex?amine *")
=> ["look", "at rose"]
pad()
STRING pad(STRING str, INTEGER length[, STRING filler])
This function pads or truncates the argument str to the length given by the argument length. If the argument filler is specified, then it is used to pad the string, otherwise a space is used. If length is greater than the length of str, then pad adds filler characters on the right. If the length is a negative number, filler will be added on the left instead. The function strfmt() may also be used for string padding.
pad("foo", 6)
=> "foo "
pad("foobar", 3)
=> "foo"
pad(tostr(29), -4, "0")
=> "0029"
pad("what", 20, "!?!")
=> "what!?!!?!!?!!?!!?!!"
regexp()
LIST regexp(STRING str, STRING regexp[, INTEGER cs])
This function matches the regular expression argument regexp against the argument str. If cs is specified and is true, the match is case-sensitive; otherwise, it is case-insensitive. If the match succeeds, a list of the matches in str is returned; otherwise the function returns 0 (zero). If regexp is not a valid regular expression the error ~regexp is thrown. For more information, see Regular Expressions.
The function match_regexp() is similar and is more suitable when all that is desired is whether the regexp matches or not.
regexp("fooBAR", "bar")
=> ["BAR"]
regexp("Greg says, 'Hello.'", "^([^ ]+) says, '(.*)'$")
=> ["Greg", "Hello."]
regexp(" 300 100 200 ", "[0-9]+")
=> ["300"]
regexp("bar", "foo")
=> 0
regexp("Foo", "foo", 1)
=> 0
split()
LIST split(STRING str, STRING regexp[, STRING regexp_args])
This function breaks str into a list of strings, using the second argument regexp (a regular expression) as a delimiter. The third argument is optional, and is a string containing character flags which can change the behaviour the function. Flags can be any:
- b - Keep blank entries (default is to ignore).
- c - Case sensitive match.
- i - Case insensitive match (default).
split(" foo bar baz", " +")
=> ["foo", "bar", "baz"]
split("foo:bar::baz", ":", "b")
=> ["foo", "bar", "", "baz"]
split("fobibobIbidilly", "i")
=> ["fob", "bob", "b", "d", "lly"]
split("fobIbobibidIlly", "i", "cb")
=> ["fobIbob", "b", "dIlly"]
strcmp()
INTEGER strcmp(STRING str1, STRING str2)
This function compares str1 against str2 and returns 0 (zero) if they are equal, a positive number if str1 is lexically greater than str2, and a negative number if str1 is lexically less than str2. The comparison performed by strcmp() is case-sensitive.
strcmp("Foo", "bar")
=> -28
strcmp("cashmir", "cashmiR")
=> 32
strcmp("foo", "foo")
=> 0
strfmt()
STRING strfmt(STRING format, ANY arg, ...)
This function formats its arguments and returns the result. How the arguments are formatted depends upon the argument format. The format contains two types of sequences: plain characters, which are simply copied to the new string, and format specifications, each of which causes printing of the next successive argument. The format begins with a percent character (%), followed by:
- Pad Length
- The pad length is an integer which specifies the length of characters to pad the argument in. Pad length is optional. Specifying a zero pad length will be ignored, and is equivalent to not specifying a pad length.
- Precision
- A period (.), followed by an integer specifies the precision, the number of digits to appear after the decimal point when printing float arguments. Precision is optional, and does not have to be specified. If it is specified it must come after the pad length (if specified), and before the filler (if specified) or format type.
- Filler
- Filler specifies what is used when padding a string within the pad length. Filler is specified within curly braces ({}). To include a curly brace in the filler, prefix it with a backslash. The filler must come after pad length or precision, if they are specified, and before format type.
- Format Type
- Format type must be specified last and is not optional. Format type
specifies how the argument is to be handled. It is one of the following
characters:
- d or D
- literal data
- s or S or l or L
- any data, align left
- r or R
- any data, align right
- c or C
- any data, align centered
- e
- any data, align left with an ellipse
strfmt("%r", "test")
=> "test"
strfmt("%l", "test")
=> "test"
strfmt("%c", "test")
=> "test"
strfmt("%d", "test")
=> "\"test\""
strfmt("%10r", "test")
=> " test"
strfmt("%10l", "test")
=> "test "
strfmt("%10c", "test")
=> " test "
strfmt("%10{|>}r", "test")
=> "|>|>|>test"
strfmt("%10{|>}l", "test")
=> "test|>|>|>"
strfmt("%10{|>}c", "test")
=> "|>|test|>|"
strfmt("%.2l", 1.1214)
=> "1.12"
strfmt("%10.3{0}r", 1.1214)
=> "000001.121"
strfmt("%10.3{0}l", 1.1214)
=> "1.12100000"
strfmt("%5e", "testing")
=> "te..."
strfmt("%s parents: %15e", "$container", $container.parents())
=> "$container parents: [$location, ..."
NOTE: There is a bug in the driver code for strfmt() in Genesis-1.1.12 which can result in the driver getting caught in an infinite loop. Please see the Genesis Bug Fixes documentation for the necessary fix.
strgraft()
STRING strgraft(STRING str, INTEGER pos, STRING str2)
This function grafts a string into another string. It will take the string specified by str2 and insert it into str, starting at the position specified by pos.
strgraft("this string", 6, "is a ")
=> "this is a string"
stridx()
INTEGER stridx(STRING str, STRING what[, INTEGER origin])
This function returns the position in str where what exists, starting from origin. A 0 (zero) is returned if what cannot be found. If origin is not specified it will default to 1. The origin is the position in the string from which the search begins. If it is a positive number, the search starts that many elements into the string. If it is a negative number, the search starts that many elements from the end of the string and searches backwards.
stridx("this test ok", "e")
=> 7
stridx("this test ok", "t", -1)
=> 9
stridx("this test ok", "t", -5)
=> 6
stridx("this test ok", "alf")
=> 0
strlen()
INTEGER strlen(STRING str)
This function returns the length of str.
strlen("this is a test")
=> 14
strsed()
STRING strsed(STRING rx, STRING str, STRING repl[, STRING flags[, INTEGER count]])
This functions similar to sed in many unix systems. It searches for any occurrences of rx in str, replaces them with repl, and returns the result. The optional fourth argument is used to specify flags. Flags are any of the following characters within a string:
- g - Match the regular expression globally througout the string.
- s - Single match—match the first occurrence only (default).
- c - Perform case-sensitive matching.
- i - Perform case-insensitive matching (default).
For more information, see Regular Expressions.
The fifth argument count is intended to optimize the use of this function, and is generally not used. It is simply an optimizing guideline which specifies how many occurrences of the regular expression are expected in the string. This value is used, when computing the initial size of the resulting string, to lower the number of memory allocations which may have to be performed.
strsed("foObar", "o+", "X")
=> "fXbar"
strsed("foObar", "o+", "X", "c")
=> "fXObar"
strsub()
STRING strsub(STRING str, STRING what, STRING replace[, STRING flags])
This function searches for occurrences of the string what within the string str and replaces them with replace. By default it will replace any occurrence and will do case-insensitive comparisons. The optional fourth argument can be any of the following characters within the string:
- g - Match globally througout the string (default).
- s - Single match—match the first occurrence only.
- c - Perform case-sensitive matching.
- i - Perform case-insensitive matching (default).
strsub("fooBar", "bar", "baz")
=> "foobaz"
strsub("fooBar", "bar", "baz", "c")
=> "fooBar"
substr()
STRING substr(STRING str, INTEGER start[, INTEGER length])
This function returns a subrange of str. The subrange starts at the character specified by start and continues for length characters. If length is unspecified it continues to the end of the string. If start is less than 1 or is greater than strlen(str) + 1, or if length will extend past the end of the string, the error ~range is thrown.
substr("foobar", 2, 3)
=> "oob"
substr("foobar", 3)
=> "obar"
substr("foobar", 7)
=> ""
uppercase()
STRING uppercase(STRING str)
This function changes each character in str to its uppercase value and returns the result.
uppercase("foo bar")
=> "FOO BAR"
