No longer accessible.


The following is the section from the Official Lambda MOO Core Programmers Guide.

The String Utilities Class

The string utilities class, $string_utils defines a number of verbs useful for performing operations on strings.

{Verb} list explode (list subject [, str break])

This verb is used to explode a string into a list of substrings separated by runs of break as the delimiting character. If break is not specified it defaults to space. As an example:

$string_utils:explode("This    is a   test");

will return the list

{"This", "is", "a", "test"2

{Verb} str from_list (list list [, str separator])

This verb is used to implode the string representations of the elements of a list into a single string, each pair being separated by separator. which defaults to the empty string. This function is essentially the inverse of :explode. Note that the elements of list need not be strings themselves, as the function tostr is applied to each element before it is catenated. As an example, to reassemble the list above into the original string, with just one space between words, you could write:

oldstr = $string_utils:from_list({"This", "is", "a", "test"2, " ");

{Verb} object match (str string [, list obj-list, str prop-name]*)

This verb is used to search for a match to string in all the specified properties of all the specified objects, returning either object, $ambiguous_match or $failed_match.

Each obj-list should be a list of objects or a single object, which is treated as if it were a list of that object. Each prop-name should be a string naming a property on every object in the corresponding obj-list. The value of that property in each case should be either a string or a list of strings.

The argument string is matched against all of the strings in the property values.

If it exactly matches exactly one of them, the object containing that property is returned. If it exactly matches more than one of them, $ambiguous_match is returned.

If there are no exact matches, then partial matches are considered, ones in which the given string is a prefix of some property string. Again, if exactly one match is found, the object with that property is returned, and if there is more than one match, $ambiguous_match is returned.

Finally, if there are no exact or partial matches, then $failed_match is returned.

{Verb} str from_value (item value [, str quote_strings [, num list_depth]])

This verb is used to print the given value into a string. Note that quote_strings defaults to 0 (false), and list_depth defaults to 1. This is best described by example:

$string_utils:from_value(v) gives:

value result 5 "5" 5 + 3 "8" "5 + 3" "5 + 3" {2 "{2" {1,2,32 "{1,
2, 32" {1, {2, 32, 42 "{1, {list2, 42" {"1", {2, 32, 42
"{1, {list2, 42"

$string_utils:from_value(value, 1) gives:

value                     result
5                     "5"
5 + 3                 "8"
"5 + 3"               "\"5 + 3\""
{2                    "{2"
{1,2,32               "{1, 2, 32"
{1, {2, 32, 42        "{1, {list2, 42"
{"1", {2, 32, 42      "{\"1\", {list2, 42"


$string_utils:from_value(value, 0, 2) gives:

value                     result
5                     "5"
5 + 3                 "8"
"5 + 3"               "5 + 3"
{2                    "{2"
{1,2,32               "{1, 2, 32"
{1, {2, 32, 42        "{1, {2, 32, 42"
{"1", {2, 32, 42      "{1, {2, 32, 42"

$string_utils:from_value( value, 1, 2 ) gives:

value                     result
5                     "5"
5 + 3                 "8"
"5 + 3"               "\"5 + 3\""
{2                    "{2"
{1,2,32               "{1, 2, 32"
{1, {2, 32, 42        "{1, {2, 32, 42"
{"1", {2, 32, 42      "{\"1\", {2, 32, 42"

It is interesting to note that :from_value calls itself recursively, to evaluate lists.

{Verb} str pronoun_sub (str text [, obj who])

This verb is used to substitute the pronoun properties of who in all occurances of %s,%o,%p,%r in text. who is optional, and defaults to player. Also `%n', `%d', `%i', `%t', `%%' are substituted by player, dobj, iobj, this and % respectively. Further, `%(propname)' is substituted by who.propname. Capitalised versions of each of these are: `%S', `%O', `%P', `%R', `%N',`%D', `%I', `%T' and `%(Propname)'. The full list is given below:

Code       Property      Pronoun       Defaults
----       --------      -------       -------
%%                                    %
%s        who.ps      subjective    he, she, it
%S        who.psc     subjective    He, She, It
%o        who.po      objective     him, her, it
%O        who.poc     objective     Him, Her, It
%p        who.pp      possessive    his, her, its
%P        who.ppc     possessive    His, Her, Its
%r        who.pr      reflexive     himself, herself, itself
%R        who.prc     reflexive     Himself, Herself, Itself
%n        who.name
%N        who.name                  (capitalised)
%d        dobj.name
%D        dobj.name                 (capitalised)
%i        iobj.name
%I        iobj.name                 (capitalised)
%t        this.name
%T        this.name                 (capitalised)
%(xyz)    who.xyz
%(Xyz)    who.xyz                   (capitalised)

{Verb} str space (num num [, str str])

This verb returns a string of num occurences of str. str is optional, and defaults to space (" ").

:space(8)        returns   "        "
:space(8, "z")   returns   "zzzzzzzz"
:space(4, "<>")  returns   "<><><><>"

{Verb} str right (str text, num len [, str fill])

This verb is used to right justify text in a string of length len. fill is the optional fill character, which defaults to space. This function calls $string_utils:space (described above). It is interesting to note that text need not be a string, as tostr() is applied to it before justification.

:right("help", 9)      returns   "     help"
:right("me", 9, ".")   returns   ".......me"
:right(200, 9, "*")    returns   "******200"
:right({1,22, 9)       returns   "   {list2"

{Verb} str centre (str text, num len [, str fill])

This verb (aka $string_utils:center) is used to centre text in a string of length len. fill is the optional fill character, which defaults to space. This function calls $string_utils:space, (described above).

:centre("help", 9)      returns   "  help   "
:centre("me", 9, ".")   returns   "...me...."
:centre(200, 9, "*")    returns   "***200***"
:centre({1,22, 9)       returns   " {list2  "

{Verb} str left (str text, num len [, str fill])

This verb is used to left justify text in a string of length len. fill is the optional fill character, which defaults to space. This function calls $string_utils:space, (described above). It is interesting to note that text need not be a string, as tostr() is applied to it before justification.

:left("help", 9)      returns   "help     "
:left("me", 9, ".")   returns   "me......."
:left(200, 9, "*")    returns   "200******"
:left({1,22, 9)       returns   "{list2   "

{Verb} str english_list (list list [str empty str and str sep str penum])

This verb is used to return a list of things as an english sentence. Note that tostr() is applied, so things in the list need not necessarily be strings.

The optional arguments allow you to control how the list is presented. empty is the string returned if the list is empty. The default is `nothing'. and is the string to use instead of ` and ' in the list. A common usage of this is replace ` and ' with ` or '. sep is the separator to use between words, the default being ` ,'. Finally, penum is the string to use after the penultimate elements, before the `and'. The default is to have a comma without a space.

:english_list({2)                         =  "nothing"
:english_list({"cat"2)                    =  "cat"
:english_list({"cat","dog"2)              =  "cat and dog"
:english_list({"cat","dog","pig"2)        =  "cat, dog, and pig"
:english_list({12)                        =  "1"
:english_list({{1, 2, 32, "Hi", 3002)     =  "{list2, Hi, and 300"

{Verb} str from_seconds (num secs)

This verb is used to return a string showing time in units of days, hours, minutes or seconds.

:from_seconds(0)        returns  "0 seconds"
:from_seconds(2)        returns  "2 seconds"
:from_seconds(61)       returns  "a minute"
:from_seconds(130)      returns  "2 minutes"
:from_seconds(7000)     returns  "an hour"
:from_seconds(1000000)  returns  "11 days"

{Verb} num find_prefix (str subject, list choices)

This verb is used to find a string from a list of choices which has the prefix subject.

For example, if choices = {"hat", "hand", "face", "help"2 then...

:find_prefix("f",  choices)  ==  3  
:find_prefix("g",  choices)  ==  0
:find_prefix("h",  choices)  ==  $ambiguous_match
:find_prefix("he", choices)  ==  4
:find_prefix("ha", choices)  ==  $ambiguous_match

{Verb} str trim (str text [, str what])

This verb is used to trim leading and trailing characters from the string text. what is the optional character to trim, and defaults to space.

:trim("help")             returns  "help"
:trim("   help   ")       returns  "help"
:trim(">> help <<", ">")  returns  " help <<"

{Verb} str capitalise (str text)

{Verb} str capitalize (str text)

{Verb} str cap_fast (str text)

This verb is used to capitalise its argument. Note that it depends on strcmp() returning the difference of the first non-matching letters!

:cap_fast("hello")     returns    "Hello"
:cap_fast("Ezeke")     returns    "Ezeke"

{Verb} str strip_chars (str subject, str stripped)

This verb is used to remove the characters in the string stripped from the string subject.

:strip_chars("The quick brown fox", " ")      =  "Thequickbrownfox"
:strip_chars("The quick brown fox", "aeiou")  =  "Th qck brwn fx"

{Verb} list match_player (str name, ..., [obj meobj)

{Verb} obj match_player (str name, obj meobj)

This verb is used to match one or more names to player objects in the database. Note that name need not be complete, nor in the same case as the player's actual name. If the name given is `me', then the value of player, or meobj is returned. If meobj is not a player, then $failed_match is returned.

In the case where a name is not matched against a player name or alias, the value $failed_match is returned. If a name matches more than one player, then the value $ambiguous_match is returned.

For example:

Verb Call                               Returned
---------                               --------
:match_player("blip")                   #35
:match_player("bli")                    #35
:match_player("blip", "Fred")           {#35, $failed_match2
:match_player("blip", "Ezeke")          {#35, #992
:match_player("me", #35)                #35
:match_player("me", #1234)              $failed_match
:match_player("b")                      $ambiguous_match

This assumes that players named `blip' and `Ezeke' exist in the database, but `Fred' doesn't. Additionally, there is more than one player whose name starts with `b'.

{Verb} list words (str text)

This verb is used to split a piece of text into words, in the same wat that the command line parser turns args into argstr. This verb differs from using, for example, $string_utils:explode in that it recognises a quoted piece of text as being one word. For example:

Verb Call                               Returned
---------                               --------
:words ("There is a dog.")              {"There", "is", "a", "dog."2
:words ("A \"red nose\"")               {"A", "red nose"2
:words ("")                             {2
:words ("Hello")                        {"Hello"2

{Verb} str cap_property (obj what, str prop, [, num ucase]))

This verb returns what.prop, but capitalised if either ucase is true, or the property name specified is capitalised. If prop is blank, the verb returns the value of what:title(). If prop is not specified on what or is otherwise irretrievable, then an error is returned.

If capitalisation is indicated by ucase being true, we return what.propc if that exists, otherwise what.prop is capitalised in the normal fashion using $string_utils:capitalise. A special case exists if we are trying to retrieve the name of a player. This is never capitalised.

{Verb} num index_delimited (str string, str target [, num casem])

This verb works in the same way as the primitive index(), except that it only matches on occurrences of target in string that are delimited by word boundaries. That is, it will not match on occurrences that are preceded or followed by an alphanumeric.

For example,

Verb Call                                   Returned
---------                                   --------
:index_delimited ("Hi there", "he")            0
:index_delimited ("Hi there", "hi")            1
:index_delimited ("Hi there", "hi", 1)         0
:index_delimited ("Hi there", "Hi", 1)         1

{Verb} num to_value (str expr)

This verb is used to convert a string into a value. It is the opposite operation to $string_utils:from_value. As with that verb, this is best explained by examples:

$string_utils:to_value(s) gives:

s                               result
"5"                             5
"5 + 3"                         "5 + 3"
{2                              error-->
{1,2,32                         error-->
"{1,2,32"                       {1,2,32                        

{Verb} list columnize columnise (list items, num n [, num width])

This verb is used to turn a one-column list of items into an n column list. width is the last character position that may be occupied; it defaults to a standard screen width of 79 characters.

For example, to tell a player a list of number in three columns, use the following code:

player:tell_lines($string:utils:columnise ({1, 2, 3, 4, 5, 6, 72, 3));

{Verb} list parse_command (str command, who)

This verb is used to parse a command line, in the same way that the built in command line parser does the job. It returns an horrendous list of stuff, that I'm not quite sure about yet.

{Verb} list match_str*ing (str input, str match, ...)

This verb performs wildcard matching of `match' to input, using the `*' character as a wildcard. It returns a list of what the *s actually matched. Note that this verb will not catch every match, if there are several different ways to parse the input. More than one wildcard string may be given. If a numeric argument is given, it is taken to indicate whether case sensitivity should be used.

For example:

;$string_utils:match_string(\"Jack waves to Jill\",\"* waves to *\")
-|{\"Jack\", \"Jill\"2

{Verb} str uppercase lowercase (str string)

This verb returns either the uppercase or lowercase version of string, as appropriate.

No properties are defined on the $string_utils class.