namespace String

namespace String

Provides a set of functions to manipulate strings

namespace contents

function

base64decode(string) - Convert a string from base64 encoding to normal.

function

base64encode(string) - Convert a string to base64 encoding.

function

blocks(string,number) - Splits a string into an array of strings of no more than the specified size

function

charToNum(string) - Converts the first character of a string to a number

function

compareCase(string,string) - Compares two strings

function

compareNoCase(string,string) - Compares two strings, ignoring the case of alphabetical characters

function

dissect(string,string,number) - Dissects a string into an array with single character delimiters

function

escape(string) - Converts various characters in a string to escape sequences

function

index(string,string) - Finds the first occurance of string b in string a

function

isalnum() - Tests whether the first character of a string is alphanumerical

function

isalpha() - Tests whether the first character of a string is alphabetic

function

iscntrl() - Tests whether the first character of a string is a control character

function

isdigit() - Tests whether the first character of a string is a digit

function

isgraph() - Tests whether the first character of a string is a graphic character

function

islower() - Tests whether the first character of a string is a lower case letter

function

isNumber(string) - Checks whether a string represents a valid number

function

isprint() - Tests whether the first character of a string is a printable character

function

ispunct() - Tests whether the first character of a string is a punctuation character

function

isspace() - Tests whether the first character of a string is a whitespace character

function

isupper() - Tests whether the first character of a string is an upper case letter

function

isxdigit() - Tests whether the first character of a string is a hex digit

function

length(string) - Finds the length of a string

function

lines(string) - Itterate through the lines within a string or create an array containing the lines.

function

nCompareCase(string,string,number) - Compares the initial part of two strings

function

nCompareNoCase(string,string,number) - Compares the initial part of two strings, ignoring the case of alphabetical characters

function

numToChar(number) - Converts a number to a character in a string of length one

function

pad(string,number) - Pads a string

function

pad(string,number,number) - Pads a string

function

pad(string,number,string) - Pads a string

function

postTrim(string,string) - Trims the back of a string using the specified delimiters

function

preTrim(string,string) - Trims the front of a string using the specified delimiters

function

reverse(string) - Reverses a string

function

sprintf(string,void) - Prints formatted text to a string

function

toArray(string,string) - Splits a string up into an array based on a string delimiter

function

toDouble(string) - Converts a string to a number stored internally as a double

function

toHex(string) - Interprets a string as a number and converts it to a hexadecimal string representation of it

function

toLong(string) - Converts a string to a number stored internally as a long

function

toLower(string) - Translates a string to lower case

function

toNumber(string) - Converts a string to a number

function

toUpper(string) - Translates a string to upper case

function

trim(string,string) - Trims a string (front and back) using the specified delimiters

function

unescape(string) - Unescapes strings which contain standard C escape sequences

Functions

function base64decode

Click to go up to the list

Convert a string from base64 encoding to normal.

The base64 encoding makes it possible to transport binary information within an ascii system such as email.

Parameter #1: string source - The string to decode

The decoded version of source.

function base64encode

Click to go up to the list

Convert a string to base64 encoding.

The base64 encoding makes it possible to transport binary information within an ascii system such as email.

Parameter #1: string source - The string to encode

The encoded version of source.

function blocks

Click to go up to the list

Splits a string into an array of strings of no more than the specified size

function blocks( string str, number size )

This function converts the specified string into an array of strings. Each string in the array will contain "size" characters of the input string, except for the last string which may be smaller if it runs out of characters in the input string. For example, String.blocks("hello world", 3) will produce the output [ "hel", "lo ", "wor", "ld" ].

Parameter #1: string str - The string

Parameter #2: number size - The maximum size of the output strings

The array of output strings

function charToNum

Click to go up to the list

Converts the first character of a string to a number

function charToNum( string s )

This function converts the first character of the specified string into its numerical equivalent.

Parameter #1: string s - The string containing the character to convert

An integer number in the range 0 to 255 or -1 on error.

number space = String.numToChar(" "); » space = 32

function compareCase

Click to go up to the list

Compares two strings

function compareCase( string a, string b )

This function compares the two strings and returns true if they match or false if they do not. The case of alphabetical characters is not ignored.

Parameter #1: string a - The first string

Parameter #2: string b - The second string

True if they match, false if they do not

function compareNoCase

Click to go up to the list

Compares two strings, ignoring the case of alphabetical characters

function compareNoCase( string a, string b )

This function compares the two strings and returns true if they match or false if they do not. The case of alphabetical characters is ignored, eg. if you compare "hello" and "HELLO" with this function, they will match.

Parameter #1: string a - The first string

Parameter #2: string b - The second string

True if they match, false if they do not

function dissect

Click to go up to the list

Dissects a string into an array with single character delimiters

function dissect(string s, string d, number limit)

This function dissects string s into an array of substrings delimited by the characters in string d. It is similar to String.toArray() except that it expects a list of single character delimiters instead of a single delimiting string. For example, if s contains "aaa1bbbb2ccc3dddd" and d contains "123" the result will be ["aaa", "bbbb", "ccc", "dddd"]. If none of the delimiting characters are present in the string, the result array will contain a single string which is an exact copy of the input string. If limit is 0, dissect() will cut the string every time it encounters a delimiting character. If it is greater than 0, it will not cut the string more than limit times. If the limit parameter is omitted, there is no limit to the number of times the string will be cut.

Parameter #1: string s - The string to dissect

Parameter #2: string d - The list of single delimiting characters

Parameter #3: number limit - If greater than zero, limits the number of cuts

Array of the resulting substrings

function escape

Click to go up to the list

Converts various characters in a string to escape sequences

function escape( string str )

This function encodes a binary string using standard C escape sequences which can be used in many places where arbitrary binary data is not allowed.

Parameter #1: string str - The string

A copy of the string after escaping some characters

function index

Click to go up to the list

Finds the first occurance of string b in string a

function index( string a, string b )

Parameter #1: string a - The string to search through

Parameter #2: string b - The string to search for

The index number of the substring if found, or -1 if not found

number space = String.index("Hello World", "World"); » space = 6

function isalnum

Click to go up to the list

Tests whether the first character of a string is alphanumerical

This function returns true if the first letter of the string is one of [a-z], [A-Z], or [0-9]. False is returned if it is not alphanumerical or if the string is empty.

function isalpha

Click to go up to the list

Tests whether the first character of a string is alphabetic

This function returns true if the first letter of the string is one of [a-z] or [A-Z]. False is returned if it is not alphabetic or if the string is empty.

function iscntrl

Click to go up to the list

Tests whether the first character of a string is a control character

This function returns true if the first letter of the string is a control character, ie. any character which is not printable. False is returned if it is not a control character or if the string is empty.

function isdigit

Click to go up to the list

Tests whether the first character of a string is a digit

This function returns true if the first letter of the string is one of [0-9]. False is returned if it is not a digit or if the string is empty.

function isgraph

Click to go up to the list

Tests whether the first character of a string is a graphic character

This function returns true if the first letter of the string is a graphic character, ie. one which has a glyph associated with it. Whitespace characters are not considered to be graphic characters. False is returned if it is not a graphic character or if the string is empty.

function islower

Click to go up to the list

Tests whether the first character of a string is a lower case letter

This function returns true if the first letter of the string is one of [a-z]. False is returned if it is not a lower case letter or if the string is empty.

function isNumber

Click to go up to the list

Checks whether a string represents a valid number

function isNumber( string s )

This function is used to discover whether String.toNumber() will fail when called with a particular string or not. A string which causes isNumber() to return true won't necessarily work with String.toDouble() or String.toLong() because String.toNumber() copes with many cases which the above functions do not. An alternative to calling this function before String.toNumber() is to check err.number for failure after the String.toNumber() call.

Parameter #1: string s - The string

True if the string represents a valid number, false if it doesn't

number space = 0;
if( String.isNumber("32") ) {
space = String.toNumber("32");
} » space = 32

function isprint

Click to go up to the list

Tests whether the first character of a string is a printable character

This function returns true if the first letter of the string is a printable character. isprint() returns true for all the characters that isgraph() does, and for the space character as well. False is returned if it is not a printable character or if the string is empty.

function ispunct

Click to go up to the list

Tests whether the first character of a string is a punctuation character

This function returns true if the first letter of the string is any non alphanumerical printable character. False is returned if it is not a punctuation character or if the string is empty.

function isspace

Click to go up to the list

Tests whether the first character of a string is a whitespace character

This function returns true if the first letter of the string is one of ' ', '\f', '\n', '\r', '\t', or '\v'. False is returned if it is not a whitespace character or if the string is empty.

function isupper

Click to go up to the list

Tests whether the first character of a string is an upper case letter

This function returns true if the first letter of the string is one of [A-Z]. False is returned if it is not an upper case letter or if the string is empty.

function isxdigit

Click to go up to the list

Tests whether the first character of a string is a hex digit

This function returns true if the first letter of the string is one of [0-9], [a-f], or [A-F]. False is returned if it is not a hex digit or if the string is empty.

function length

Click to go up to the list

Finds the length of a string

function length( string str )

Parameter #1: string str - The string

The number of characters in the string

function lines

Click to go up to the list

Itterate through the lines within a string or create an array containing the lines.

function lines( string str )

If you pass this function a closure, it will call it with each line.

Parameter #1: string str - The string

The array containing the lines.

array lines = String.lines( "line1\nline2\nline3\n" );
String.lines( "line1\nline2\nline3\n" ) using ( line ) {
Console.println( line );
}

function nCompareCase

Click to go up to the list

Compares the initial part of two strings

function nCompareCase( string a, string b, number max )

This function compares the first "max" characters of the two strings and returns true if they match or false if they do not. The case of alphabetical characters is not ignored.

Parameter #1: string a - The first string

Parameter #2: string b - The second string

Parameter #3: number max - The maximum number of characters to compare

True if the first "max" characters match, false if they do not

function nCompareNoCase

Click to go up to the list

Compares the initial part of two strings, ignoring the case of alphabetical characters

function nCompareCase( string a, string b, number max )

This function compares the first "max" characters of the two strings and returns true if they match or false if they do not. The case of alphabetical characters is ignored, eg. if you compare "hello" and "HELLO" with this function, they will match.

Parameter #1: string a - The first string

Parameter #2: string b - The second string

Parameter #3: number max - The maximum number of characters to compare

True if the first "max" characters match, false if they do not

function numToChar

Click to go up to the list

Converts a number to a character in a string of length one

function numToChar( number n )

Converts the ASCII number n into a character and returns it as a string one character long. The number should be a positive integer less than 255. If it is not, a zero length string will be returned.

Parameter #1: number n - The number

A single character string

string space = String.numToChar(32); » space = " "

function pad

Click to go up to the list

function pad( string str, number pad )

If the specified string is less than "pad" characters long, copies of the first character of padchar are added to the end of the string to make it up to the specified length. The string is not truncated if it is already longer than the specified length. The character to pad will be a space.

Parameter #1: string str - The string

Parameter #2: number pad - The total length the string should be

A copy of the string, padded to the specified length

string s = String.pad("fnar",10); » s = "fnar "

function pad

Click to go up to the list

function pad( string str, number pad, number ch )

If the specified string is less than "pad" characters long, copies of the first character of padchar are added to the end of the string to make it up to the specified length. The string is not truncated if it is already longer than the specified length. The character to pad will be the value ch.

Parameter #1: string str - The string

Parameter #2: number pad - The total length the string should be

Parameter #3: number ch - The ASCII value to use.

A copy of the string, padded to the specified length

string s = String.pad("fnar",10,32); » s = "fnar "

function pad

Click to go up to the list

function pad( string str, number pad, string padstr )

If the specified string is less than "pad" characters long, copies of the first character of padchar are added to the end of the string to make it up to the specified length. The string is not truncated if it is already longer than the specified length. If the padchar parameter is omitted or is an empty string, spaces are used. If a number between 0 and 255 is specified instead of the padchar, the string is padded with the ASCII character which that number represents.

Parameter #1: string str - The string

Parameter #2: number pad - The total length the string should be

Parameter #3: string padchar - The character to pad the extra space with

A copy of the string, padded to the specified length

string s = String.pad("fnar",10,"."); » s = "fnar......"

function postTrim

Click to go up to the list

Trims the back of a string using the specified delimiters

function postTrim( string str, string delims )

This function removes all occurrences of any of the characters in the delims string from the back of the specified string.

Parameter #1: string str - The string to trim

Parameter #2: string delims - The list of delimiters

The trimmed string

function preTrim

Click to go up to the list

Trims the front of a string using the specified delimiters

function preTrim( string str, string delims )

This function removes all occurrences of any of the chararacters in the delims string from the front of the specified string.

Parameter #1: string str - The string to trim

Parameter #2: string delims - The list of delmimiters

The trimmed string

function reverse

Click to go up to the list

Reverses a string

function reverse( string s )

Parameter #1: string s - The input string

The input string with the order of the characters reversed

string s = String.reverse("gninnuc"); » s = "cunning"

function sprintf

Click to go up to the list

Prints formatted text to a string

function sprintf( string fmt, ... )

This function is analagous to the libc sprintf() function. You should read your system libc manual for full details on the different output formats you can use. Printing of objects and arrays is not currently supported and various extensions such as %m are not supported (but may be in the future).

Parameter #1: string fmt - The format string

Parameter #2: void ... - The variables

string s = String.sprintf("fnar:%s:%d","Yes",32); » s = "fnar:Yes:32"

function toArray

Click to go up to the list

Splits a string up into an array based on a string delimiter

function toArray(string s, string d, number limit)

This function splits string s into an array of substrings delimited by string d. It is similar to String.dissect() except that it expects a string as a delimiter instead of a list of single characters. For example, if s contains "foo equals bar" and d contains " equals " then the result will be ["foo", "bar"]. If d is not present in s, then the returned array will contain a single string which is an exact copy of s. If limit is greater than 0, toArray() will not break the string more than limit times. Otherwise, it will break the string every time it encounters the delimiting string. Note: it is possible to omit the limit parameter, and it will default to 0.

Parameter #1: string str - The string to split

Parameter #2: string delims - The string to use as the delimiter

function toDouble

Click to go up to the list

Converts a string to a number stored internally as a double

function toDouble( string str )

This function converts the specified string to a number, which will be internally represented as a double. Note that it does not perform any error checking at all. Use String.toNumber() instead on new projects.

Parameter #1: string str - The string

function toHex

Click to go up to the list

Interprets a string as a number and converts it to a hexadecimal string representation of it

function toHex( string s )

This function performs a similar function to the standard Unix utility, hexdump. It is useful for converting a block of binary data into a printable hexadecimal string.

Parameter #1: string s - The input string

A string containing the hex representation of the input string

function toLong

Click to go up to the list

Converts a string to a number stored internally as a long

function toLong( string str )

This function converts the specified string to a number, which will be internally represented as a long. Note that it does not perform any error checking at all. Use String.toNumber(), and if necessary round it to an integer instead on new projects.

Parameter #1: string str - The string

function toLower

Click to go up to the list

Translates a string to lower case

function toLower( string str )

This function translates all occurrences of upper case alphabetical characters (A, B, C, etc.) in the input string to their lower case equivalents (a, b, c, etc.) and returns the result in a new string.

Parameter #1: string str - The input string

A copy of the input string translated to lower case

string s = String.toLower("FNAR"); » s = "fnar"

function toNumber

Click to go up to the list

Converts a string to a number

function toNumber( string s )

This function attempts to convert a string to a number. If the number is too large to be represented by a double, (note that this requires a very large number indeed) it returns HUGE_VAL or -HUGE_VAL and sets err.number to ERANGE. The actual value of HUGE_VAL depends on your C library (on some systems it is a special value which means infinity). If the string doesn't represent a valid number, 0 is returned and err.number is set to Sys.EINVAL. If the conversion is successful, the result is returned as a number and err.number is set to 0. Note that this function is much more powerful and not significantly slower than String.toLong() and String.toDouble(), so it should always be used in preference to them in new projects.

Parameter #1: string s - The string

number space = 0;
if( String.isNumber("32") ) {
space = String.toNumber("32");
} » space = 32

function toUpper

Click to go up to the list

Translates a string to upper case

function toUpper( string str )

This function translates all occurrences of lower case alphabetical characters (a, b, c, etc.) in the input string to their upper case equivalents (A, B, C, etc.) and returns the result in a new string.

Parameter #1: string str - The input string

A copy of the input string translated to upper case

string s = String.toUpper("fnar"); » s = "FNAR"

function trim

Click to go up to the list

Trims a string (front and back) using the specified delimiters

function trim( string str, string delims )

This function removes all occurrences of any of the characters in the delims string from the front and back of the specified string.

Parameter #1: string str - The string to trim

Parameter #2: string delims - The list of delimiters

The trimmed string

string s = String.trim(" FNAR ", " "); » s = "FNAR"

function unescape

Click to go up to the list

Unescapes strings which contain standard C escape sequences

function unescape( string str )

Parameter #1: string str - The string

A copy of the string after unescaping it

Automatically generated at 12:08PM, Wednesday 25 May 2005 by feritedoc.