String

Functions dealing with strings.

Capitalize
Capitalizes the first letter of a string.
ColumnFormat
Formats an array of strings into columns of specified widths.
DateAsPoint3
Takes a date returned by the "localTime" global variable or external file date functions and returns a point3 in the form [dd,mm,yyyy].
DateAsSeconds
Takes a date returned by the "localTime" global variable or external file date functions and returns the number of seconds past midnight.
FindString2
Similar to findString(), but with three new optional parameters (from, to, and caseSensitive).
GetPadNum
Returns a number as a string, padded out with zeros to a minimum of characters.
GetTag
Searches for the first tag in a string, surrounded by <* and *>
IsCharInt
Checks if a single character can be converted to an int.
PrintColor
Prints a string in the color specified to the listener.
ReplaceTags
Replaces tags in a string with specified values.
SearchReplace
Search for text "searchText" in "str", and replace it with "replaceText".
SnipString
Shorten a string to n characters, removing characters from the middle and inserting a single "~" in place.
StringCount
Counts how many times a string is found in another string.
ToLower
Convert a string to all lower case.
ToUpper
Convert a string to all upper case.
Trunc
Truncate a string to n characters.

Capitalize:

Capitalizes the first letter of a string.

Returns:

A new string with the first letter capitalized.

Arguments:
<str>
A string to capitalize.

Back to top...


ColumnFormat:

Formats an array of strings into columns of specified widths. ie:
ColumnFormat "%%%\n" #("One","Two","Three") #(2,4,1)
will print:
OnTwo T

Returns:

OK.

Arguments:
<formatString>
A format string, the form of which is the same as one passed to the standard Format() function.
<args>
An array of arguments to print into the formatString. The count of this array must match the number of "%" wildcards in the formatString.
<argsCnt>
An array of integers, one for each item in the args array. Each args[x] will be expanded or shortened to argsCnt[x] number of characters.

Back to top...


DateAsPoint3:

Takes a date returned by the "localTime" global variable or external file date functions and returns a point3 in the form [dd,mm,yyyy].

Returns:

A point3 in the form [dd,mm,yyyy].

Arguments:
<localTimeString>
A string returned by the "localTime" global variable.

Back to top...


DateAsSeconds:

Takes a date returned by the "localTime" global variable or external file date functions and returns the number of seconds past midnight.

Returns:

The number of seconds past midnight for the given day in the passed date string, as an integer.

Arguments:
<localTimeString>
A string returned by the "localTime" global variable.

Back to top...


FindString2:

Similar to findString(), but with three new optional parameters (from, to, and caseSensitive).
Leaving the new parameters off will cause findString2() to work just like findString().

Returns:

The index of the first letter of the found string, or undefined if not found.

Arguments:
<str>
The string to search.
<searchString>
The string to search for in str.
[fromIndex:1]
The index in the string where you start searching.
[lengthIndex:0]
The length of the substring you want to search. The default 0 will search the rest of the string.
[caseSensitive:false]
Only return exact case matches.

Back to top...


GetPadNum:

Returns a number as a string, padded out with zeros to a minimum of characters.

Returns:

The original number padded out with leading zeros, or the original number as a string if the size is already greater than the minimum.

Arguments:
<num>
The number to pad.
<minSize>
The minimum size the padded number will be.

Back to top...


GetTag:

Searches for the first tag in a string, surrounded by <* and *>.

Returns:

An array containing #(int,int,string)
array[1] is the starting character of the tag (including the starting <*)
array[2] is the length of the tag (including the start <* and end *>)
array[3] is the tag name, not including the <* *>)
example: getTag "this is a test <*TAGHERE*> string" returns: #(16,11,"TAGHERE")

Arguments:
<str>
The string to search for a tag within.
<startIdx>
The starting index to start search from.

Back to top...


IsCharInt:

Checks if a single character can be converted to an int.

Returns:

True if the character can be converted to an int, otherwise false.

Arguments:
<char>
A single character string to be checked.

Back to top...


PrintColor:

Prints a string in the color specified to the listener.
Note: This function is fairly limited.

Returns:

The string printed.

Arguments:
<str>
The string to be printed.
<colorValue>
The color the string should be printed in.

Back to top...


ReplaceTags:

Replaces tags in a string with specified values.
Allows batches of tags to be replaced quickly within text. ie:
replacetags "This is <*aTag*> <*bTag*>" #(#aTag,#bTag) #("foo","bar")
returns:
"This is foo bar"

Returns:

The passed string with the tags replaced. Any unknown tags are replaced with the string "UNKNOWNTAG".

Arguments:
<str>
The string containing the tags to be replaced.
<tagArray>
An array containing the possible tags that will be in str. The tags should be name values.
<tagValArray>
An array containing the values for the tags in the tagArray. These should be strings, or convertable to strings.

Back to top...


SearchReplace:

Replaces parts of a string with a new string.

Returns:

The passed string with any matching parts replaced.

Arguments:
<str>
The string to search through.
<searchString>
The string to search for in the passed string.
<replaceString>
If the searchString is found, it will be replaced with this string.
[fromIndex:1]
The start index in the string to start searching from.
[lengthIndex:0]
The length of the string to search in, from the fromIndex. If zero, the rest of the string will be searched.
[caseSensitive:false]
If true, the search will be case sensitive.

Back to top...


SnipString:

Shorten a string to n characters, removing characters from the middle and inserting a single "~" in place. ie:
SnipString "ThisIsAReallyLongName" 10
returns:
"ThisI~Name"

Returns:

The passed string shortened to "maxLength" characters.

Arguments:
<str>
A string to shorten.
<maxLength>
The maximum length the string can be before it is shortened.

Back to top...


StringCount:

Counts how many times a string is found in another string.

Returns:

An integer count of how many times the string was found, or 0 if not found.

Arguments:
<str>
A string to search in.
<findStr>
A string to find in the first string.

Back to top...


ToLower:

Convert a string to all lower case.

Returns:

The passed string converted to all lower case letters.

Arguments:
<str>
The string to convert.

Back to top...


ToUpper:

Convert a string to all upper case.

Returns:

The passed string converted to all lower upper case letters.

Arguments:
<str>
The string to convert.

Back to top...


Trunc:

Truncate a string to n characters.

Returns:

The passed string with the trailing characters snipped off.

Arguments:
<str>
The string to truncate.
<maxLength>
The maximum length the string can be before it is truncated.

Back to top...