namespace String

Provides a set of functions to manipulate strings

namespace attributes [NB. highlighted items are covered in other pages - namespaces or classes]
function length() - Finds the length of a string
function toDouble() - Converts a string to a number stored internally as a double
function toLong() - Converts a string to a number stored internally as a long
function toHex() - Converts a string to a hexadecimal string representation of it
function numToChar() - Converts a number to a character in a string of length one
function charToNum() - Converts the first character of a string to a number
function index() - Finds the first occurance of string b in string a
function isNumber() - Checks whether a string represents a valid number
function toNumber() - Converts a string to a number
function reverse() - Reverses a string
function dissect() - Dissects a string into an array with single character delimiters
function quoteTrim() - Removes quotes from around a string
function toArray() - Splits a string up into an array based on a string delimiter
function trim() - Trims a string (front and back) using the specified delimiters
function preTrim() - Trims the front of a string using the specified delimiters
function postTrim() - Trims the back of a string using the specified delimiters
function toLower() - Translates a string to lower case
function toUpper() - Translates a string to upper case
function compareCase() - Compares two strings
function compareNoCase() - Compares two strings, ignoring the case of alphabetical characters
function nCompareCase() - Compares the initial part of two strings
function nCompareNoCase() - Compares the initial part of two strings, ignoring the case of alphabetical characters
function isalpha() - Tests whether the first character of a string is alphabetic
function islower() - Tests whether the first character of a string is a lower case letter
function isupper() - Tests whether the first character of a string is an upper case letter
function isdigit() - Tests whether the first character of a string is a digit
function isalnum() - Tests whether the first character of a string is alphanumerical
function isxdigit() - Tests whether the first character of a string is a hex digit
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 isgraph() - Tests whether the first character of a string is a graphic character
function isprint() - Tests whether the first character of a string is a printable character
function iscntrl() - Tests whether the first character of a string is a control character
function sprintf() - Prints formatted text to a string
function escape() - Converts various characters in a string to escape sequences
function unescape() - Unescapes strings which contain standard C escape sequences
function pad() - Pads a string
function blocks() - Splits a string into an array of strings of no more than the specified size

Functions
function length Click to go up to the list
Finds the length of a string
Declaration:
    native function length( string str )
Parameters:
    Parameter #1: string str - The string
Returns:
    The number of characters in the string

function toDouble Click to go up to the list
Converts a string to a number stored internally as a double
Declaration:
    native function toDouble( string str )
Description:
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.
Parameters:
    Parameter #1: string str - The string
Returns:
    The number

function toLong Click to go up to the list
Converts a string to a number stored internally as a long
Declaration:
    native function toLong( string str )
Description:
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.
Parameters:
    Parameter #1: string str - The string
Returns:
    The number

function toHex Click to go up to the list
Converts a string to a hexadecimal string representation of it
Declaration:
    native function toHex( string s )
Description:
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.
Parameters:
    Parameter #1: string s - The input string
Returns:
    A string containing the hex representation of the input string

function numToChar Click to go up to the list
Converts a number to a character in a string of length one
Declaration:
    native function numToChar( number n )
Description:
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.
Parameters:
    Parameter #1: number n - The number
Returns:
    A single character string

function charToNum Click to go up to the list
Converts the first character of a string to a number
Declaration:
    native function charToNum( string s )
Description:
This function converts the first character of the specified string into its numerical equivalent.
Parameters:
    Parameter #1: string s - The string containing the character to convert
Returns:
    An integer number in the range 0 to 255 or -1 on error.

function index Click to go up to the list
Finds the first occurance of string b in string a
Declaration:
    native function index( string a, string b )
Parameters:
    Parameter #1: string a - The string to search through
    Parameter #2: string b - The string to search for
Returns:
    The index number of the substring if found, or -1 if not found

function isNumber Click to go up to the list
Checks whether a string represents a valid number
Declaration:
    native function isNumber( string s )
Description:
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.
Parameters:
    Parameter #1: string s - The string
Returns:
    True if the string represents a valid number, false if it doesn't

function toNumber Click to go up to the list
Converts a string to a number
Declaration:
    native function toNumber( string s )
Description:
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.
Parameters:
    Parameter #1: string s - The string
Returns:
    The number

function reverse Click to go up to the list
Reverses a string
Declaration:
    function reverse( string s )
Parameters:
    Parameter #1: string s - The input string
Returns:
    The input string with the order of the characters reversed

function dissect Click to go up to the list
Dissects a string into an array with single character delimiters
Declaration:
    native function dissect(string s, string d, number limit)
Description:
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.
Parameters:
    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
Returns:
    Array of the resulting substrings

function quoteTrim Click to go up to the list
Removes quotes from around a string
Declaration:
    function quoteTrim(string s)
Description:
This function removes a single ' or " character from the beginning and end of the specified string. The current implementation is not very intelligent and will probably be replaced with a better version in the next Ferite release.
Parameters:
    Parameter #1: string s - The input string
Returns:
    The trimmed string

function toArray Click to go up to the list
Splits a string up into an array based on a string delimiter
Declaration:
    native function toArray(string s, string d, number limit)
Description:
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.
Parameters:
    Parameter #1: string str - The string to split
    Parameter #2: string delims - The string to use as the delimiter

function trim Click to go up to the list
Trims a string (front and back) using the specified delimiters
Declaration:
    native function trim( string str, string delims )
Description:
This function removes all occurrences of any of the characters in the delims string from the front and back of the specified string.
Parameters:
    Parameter #1: string str - The string to trim
    Parameter #2: string delims - The list of delimiters
Returns:
    The trimmed string

function preTrim Click to go up to the list
Trims the front of a string using the specified delimiters
Declaration:
    native function preTrim( string str, string delims )
Description:
This function removes all occurrences of any of the chararacters in the delims string from the front of the specified string.
Parameters:
    Parameter #1: string str - The string to trim
    Parameter #2: string delims - The list of delmimiters
Returns:
    The trimmed string

function postTrim Click to go up to the list
Trims the back of a string using the specified delimiters
Declaration:
    native function postTrim( string str, string delims )
Description:
This function removes all occurrences of any of the characters in the delims string from the back of the specified string.
Parameters:
    Parameter #1: string str - The string to trim
    Parameter #2: string delims - The list of delimiters
Returns:
    The trimmed string

function toLower Click to go up to the list
Translates a string to lower case
Declaration:
    native function toLower( string str )
Description:
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.
Parameters:
    Parameter #1: string str - The input string
Returns:
    A copy of the input string translated to lower case

function toUpper Click to go up to the list
Translates a string to upper case
Declaration:
    native function toUpper( string str )
Description:
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.
Parameters:
    Parameter #1: string str - The input string
Returns:
    A copy of the input string translated to upper case

function compareCase Click to go up to the list
Compares two strings
Declaration:
    native function compareCase( string a, string b )
Description:
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.
Parameters:
    Parameter #1: string a - The first string
    Parameter #2: string b - The second string
Returns:
    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
Declaration:
    native function compareNoCase( string a, string b )
Description:
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.
Parameters:
    Parameter #1: string a - The first string
    Parameter #2: string b - The second string
Returns:
    True if they match, false if they do not

function nCompareCase Click to go up to the list
Compares the initial part of two strings
Declaration:
    native function nCompareCase( string a, string b, number max )
Description:
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.
Parameters:
    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
Returns:
    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
Declaration:
    native function nCompareCase( string a, string b, number max )
Description:
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.
Parameters:
    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
Returns:
    True if the first "max" characters match, false if they do not

function isalpha Click to go up to the list
Tests whether the first character of a string is alphabetic
Description:
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 islower Click to go up to the list
Tests whether the first character of a string is a lower case letter
Description:
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 isupper Click to go up to the list
Tests whether the first character of a string is an upper case letter
Description:
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 isdigit Click to go up to the list
Tests whether the first character of a string is a digit
Description:
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 isalnum Click to go up to the list
Tests whether the first character of a string is alphanumerical
Description:
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 isxdigit Click to go up to the list
Tests whether the first character of a string is a hex digit
Description:
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 ispunct Click to go up to the list
Tests whether the first character of a string is a punctuation character
Description:
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
Description:
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 isgraph Click to go up to the list
Tests whether the first character of a string is a graphic character
Description:
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 isprint Click to go up to the list
Tests whether the first character of a string is a printable character
Description:
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 iscntrl Click to go up to the list
Tests whether the first character of a string is a control character
Description:
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 sprintf Click to go up to the list
Prints formatted text to a string
Declaration:
    function sprintf( string fmt, ... )
Description:
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).
Parameters:
    Parameter #1: string fmt - The format string
    Parameter #2: void ... - The variables

function escape Click to go up to the list
Converts various characters in a string to escape sequences
Declaration:
    native function escape( string str )
Description:
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.
Parameters:
    Parameter #1: string str - The string
Returns:
    A copy of the string after escaping some characters

function unescape Click to go up to the list
Unescapes strings which contain standard C escape sequences
Declaration:
    native function unescape( string str )
Parameters:
    Parameter #1: string str - The string
Returns:
    A copy of the string after unescaping it

function pad Click to go up to the list
Pads a string
Declaration:
    native function pad( string str, number pad, string padstr )
Description:
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.
Parameters:
    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
Returns:
    A copy of the string, padded to the specified length

function blocks Click to go up to the list
Splits a string into an array of strings of no more than the specified size
Declaration:
    native function blocks( string str, number size )
Description:
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" ].
Parameters:
    Parameter #1: string str - The string
    Parameter #2: number size - The maximum size of the output strings
Returns:
    The array of output strings

Automatically generated at 8:45pm, Wednesday 08 January 2003 by feritedoc.