Utilities

Table specific utilities are in the file Table Utilities.

Summary

Utilities	Table specific utilities are in the file Table Utilities.
otlib
String Utilities
Explode	Split a string by a string.
Trim	Trims leading and tailing whitespace from a string.
LTrim	Exactly like Trim except it only trims the left side.
RTrim	Exactly like Trim except it only trims the right side.
Escape	Makes a string safe for pattern usage, like in string.gsub().
StripComments	Strips comments from a string.
ParseArgs	This is similar to Explode with ( str, “%s+” ) except that it will not split up words within quotation marks.
EditDistance	Finds the edit distance between two strings or tables.
SplitCommentHeader	Splits a comment header in a string.
Numeric Utilities
Round	Rounds a number to a given decimal place.
Other Utilities	Things that don’t fit in any other category.
ToBool	Converts a boolean, nil, string, or number to a boolean value.
StoredExpression	Creates an object that will store an expression.
DataEqualsAnyOf	Checks to see if an argument equals any of the other arguments passed in.

otlib

Summary

String Utilities
Explode	Split a string by a string.
Trim	Trims leading and tailing whitespace from a string.
LTrim	Exactly like Trim except it only trims the left side.
RTrim	Exactly like Trim except it only trims the right side.
Escape	Makes a string safe for pattern usage, like in string.gsub().
StripComments	Strips comments from a string.
ParseArgs	This is similar to Explode with ( str, “%s+” ) except that it will not split up words within quotation marks.
EditDistance	Finds the edit distance between two strings or tables.
SplitCommentHeader	Splits a comment header in a string.
Numeric Utilities
Round	Rounds a number to a given decimal place.
Other Utilities	Things that don’t fit in any other category.
ToBool	Converts a boolean, nil, string, or number to a boolean value.
StoredExpression	Creates an object that will store an expression.
DataEqualsAnyOf	Checks to see if an argument equals any of the other arguments passed in.

String Utilities

Explode

function Explode( str,
separator,
plain,
limit )

Split a string by a string.

Parameters

str	The input string to explode.
separator	An optional string to specify what to split on. Defaults to %s+.
plain	An optional boolean that turns off pattern matching facilities if true. This should make it faster and allows you to specify strings that would otherwise need to be escaped. Defaults to false.
limit	An optional number that if set, the returned table will contain a maximum of limit elements with the last element containing the rest of str. Defaults to no limit.

Returns

A table containing the exploded str.

Example

Explode( "p1 p2 p3" )

returns...

{ "p1", "p2", "p3" }

Notes

If separator is the empty string (“”), this function throws an error.

Revisions

v1.00

Initial.

Trim

function Trim( str )

Trims leading and tailing whitespace from a string.

Parameters

str	The string to trim.

Returns

The stripped string.

Notes

This is ‘trim6’ from http://lua-users.org/wiki/StringTrim.

Revisions

v1.00

Initial.

LTrim

function LTrim( str )

Exactly like Trim except it only trims the left side. Taken from http://lua-users.org/wiki/CommonFunctions

Revisions

v1.00

Initial.

RTrim

function RTrim( str )

Exactly like Trim except it only trims the right side. Taken from http://lua-users.org/wiki/CommonFunctions

Revisions

v1.00

Initial.

Escape

function Escape( str )

Makes a string safe for pattern usage, like in string.gsub(). Basically replaces all keywords with % and the keyword.

Parameters

str	The string to make pattern safe.

Returns

The pattern safe string.

StripComments

function StripComments( str,
line_comment )

Strips comments from a string.

Parameters

str	The input string to strip from.
line_comment	The string of the comment to remove from str. Removes whenever it finds this text until the end of the line.

Returns

A string of str with the comments removed.

Example

StripComments( "Line 1 # My comment\n#Line with only a comment\nLine 2", "#" )

returns...

"Line 1 \n\nLine 2"

Notes

Only handles line comments, no block comments.
Does not parse the document, so it will remove even from inside quotation marks if it finds line_comment inside them.

Revisions

v1.00

Initial.

ParseArgs

function ParseArgs( args )

This is similar to Explode with ( str, “%s+” ) except that it will not split up words within quotation marks.

Parameters

args	The input string to split from.

Returns

1	A table containing the individual arguments.
2	A boolean stating whether or not mismatched quotes were found.

Example

ParseArgs( 'This is a "Cool sentence to" make "split up"' )

returns...

{ "This", "is", "a", "Cool sentence to", "make", "split up" }

Notes

Mismatched quotes will result in having the last quote grouping the remaining input into one argument.
Arguments outside of quotes are trimmed (via Trim), while what’s inside quotes is not trimmed at all.

Revisions

v1.00

Initial.

EditDistance

function EditDistance( s,
t,
lim )

Finds the edit distance between two strings or tables. Edit distance is the minimum number of edits needed to transform one string or table into the other.

Parameters

s	A string or table.
t	Another string or table to compare against s.
lim	An optional number to limit the function to a maximum edit distance. If specified and the function detects that the edit distance is going to be larger than limit, limit is returned immediately.

Returns

A number specifying the minimum edits it takes to transform s into t or vice versa. Will not return a higher number than lim, if specified.

Example

EditDistance( "Tuesday", "Teusday" ) -- One transposition.
EditDistance( "kitten", "sitting" ) -- Two substitutions and a deletion.

returns...

1
3

Notes

Complexity is O( (#t+1) * (#s+1) ) when lim isn’t specified.
This function can be used to compare array-like tables as easily as strings.
The algorithm used is Damerau-Levenshtein distance, which calculates edit distance based off number of subsitutions, additions, deletions, and transpositions.
Source code for this function is based off the Wikipedia article for the algorithm http://en.wikipedia.org/w/index.php?title=Damerau%E2%80%93Levenshtein_distance&oldid=351641537.
This function is case sensitive when comparing strings.
If this function is being used several times a second, you should be taking advantage of the lim parameter.
Using this function to compare against a dictionary of 250,000 words took about 0.6 seconds on my machine for the word “Teusday”, around 10 seconds for very poorly spelled words. Both tests used lim.

Revisions

v1.00

Initial.

SplitCommentHeader

function SplitCommentHeader( str,
comment_prefix )

Splits a comment header in a string. A comment header is defined as a block in a string where every non-blank line starts with a certain prefix, until a non-blank line is reached that doesn’t start with the prefix.

Parameters

str	The string to split the comment from.
comment_prefix	The optional string comment prefix. Defaults to _”;”_.

Returns

1	The comment header.
2	Everything after the comment header.

Example

SplitCommentHeader( ";Comment 1\n;Comment 2\nData 1\nData 2" )

returns...

";Comment 1\n;Comment 2", "Data 1\nData2"

Revisions

v1.00

Initial.

Numeric Utilities

Round

function Round( num,
places )

Rounds a number to a given decimal place.

Parameters

num	The number to round.
places	The optional number of places to round to. 0 rounds to the nearest whole number, 1 rounds to the nearest tenth, 2 rounds to the nearest thousandth, etc. Negative numbers round into the non-fractional places; -1 rounds to the nearest tens, -2 rounds to the nearest hundreds, etc. Defaults to 0.

Returns

The rounded number.

Notes

This is adapted from the ideas at http://lua-users.org/wiki/SimpleRound.

Revisions

v1.00

Initial.

Other Utilities

Things that don’t fit in any other category.

ToBool

function ToBool( value )

Converts a boolean, nil, string, or number to a boolean value.

Parameters

value

The boolean, nil, string, or number to convert.

Returns

The converted boolean value.

Notes

This function favors returning true if it’s not quite sure what to do.
0, strings equating to 0, nil, false, “f”, “false”, “no”, and “n” will all return false.

Revisions

v1.00

Initial.

StoredExpression

function StoredExpression()

Creates an object that will store an expression.

Returns

A table that can be called and accepts any number of arguments, then stores and returns the arguments as given. You can access the arguments in the table by index, or retrieve the total number of aruments from field ‘n’.

A function ‘unpack’ is also defined for the returned table which returns each argument just like regular unpack does.

Example

ex = StoredExpression()
my_list = { "milk", "bread", "cookies", "eggs" }
if ex( HasValue( my_list, "cookies" ) ) then
   print( "cookies are item #" .. ex[ 2 ] .. " on my list" )
end
print( "there were " .. ex.n .. " variables passed back from HasValue" )

prints...

cookies are item #3 on my list
there were 2 variables passed back from HasValue

Notes

This comes from http://lua-users.org/wiki/StatementsInExpressions. See this URL for a more detailed discussion on stored expressions.

Revisions

v1.00

Initial.

DataEqualsAnyOf

function DataEqualsAnyOf( data,
... )

Checks to see if an argument equals any of the other arguments passed in.

Parameters

data	The data to test equality against.
...	All the other arguments, which get tested against data in successive order until a match is found or until we run out of arguments.

Returns

A boolean stating whether or not any of the other arguments equaled the data argument.

Example

This is a conveinence function so that instead of writing this...

if a == b or a == c or a == d then ... end

You can write this...

if DataEqualsAnyOf( a, b, c, d ) then ... end

Revisions

v1.00

Initial.