Metaclass for string items.
Class String from \
BOM( )
This is the set of methods that can be applied to string items.
| Methods | |
| back | Returns the first character in a string. |
| charSize | Returns or changes the size in bytes in this string. |
| cmpi | Performs a lexicographic comparation of two strings, ignoring character case. |
| endsWith | Check if a strings ends with a substring. |
| escape | Escapes all the special characters in the string. |
| esq | Escapes the quotes in this string. |
| fill | Fills a string with a given character or substring. |
| find | Finds a substring. |
| front | Returns the first character in a string. |
| ftrim | Trims front whitespaces in a string. |
| join | Joins the parameters into a new string. |
| lower | Returns a lowercase version of this string. |
| merge | Merges an array of strings into one. |
| ptr | Returns a pointer to raw data contained in this string. |
| replace | Replaces the all the occurrences of a substring with another one. |
| replicate | Returns a new string that is created by replicating this one. |
| rfind | Finds a substring backwards. |
| rtrim | Trims trailing whitespaces in a string. |
| split | Subdivides a string in an array of substrings given a token substring. |
| splittr | Subdivides a string in an array of substrings given a token substring. |
| startsWith | Check if a strings starts with a substring. |
| toMemBuf | Convets this string into a Memory Buffer |
| trim | Trims whitespaces from both ends of a string. |
| unescape | Unescapes all the special characters in the string. |
| unesq | Escapes the quotes in this string. |
| upper | Returns an upper case version of this string. |
| wmatch | Perform an old-style file-like jolly-based wildcard match. |
| Methods inherited from class BOM | |
| __add | Overrides binary addition operand. |
| __call | Overrides call operator "self()". |
| __dec | Overrides decrement unary prefix operand. |
| __decpost | Overrides decrement unary postfix operand. |
| __div | Overrides binary division operand. |
| __getIndex | Overrides array access operator [] |
| __inc | Overrides increment unary prefix operand. |
| __incpost | Overrides increment unary postifx operand. |
| __mod | Overrides modulo operand. |
| __mul | Overrides binary multiplication operand. |
| __pow | Overrides power operand. |
| __setIndex | Overrides array write operator [] |
| __sub | Overrides binary subtraction operand. |
| baseClass | Returns the class item from which an object has been instantiated. |
| bound | Determines if an item is bound or not. |
| className | Returns the name of the class an instance is instantiated from. |
| clone | Performs a deep copy of the item. |
| compare | Performs a lexicographical comparison. |
| derivedFrom | Checks if this item has a given parent. |
| describe | Returns the deep contents of an item on a string representation. |
| isCallable | Determines if an item is callable. |
| len | Retrieves the length of a collection |
| metaclass | Returns the metaclass associated with this item. |
| ptr | Returns a raw memory pointer out of this data (as an integer). |
| serialize | Serialize the item on a stream for persistent storage. |
| toString | Coverts the object to string. |
| typeId | Returns an integer indicating the type of this item. |
Returns the first character in a string.
String.back( [count],[numeric],[remove] )
| count | Number of characters to be taken (defaults to 1). |
| numeric | If true, returns a character value instead of a string. |
| remove | If true, remove also the character. |
| Return | The first element or nil if the string is empty. |
This function returns a string containing one character from the end of this string, or eventually more characters in case a number > 1 is specified in count.
If remove is true, then the character is removed and the string is shrunk.
If numeric is true, the UNICODE value of the string character will be returned, otherwise the caller will receive a string containing the desired character. In this case, count parameter will be ignored and only one UNICODE value will be returned.
See also: strFront.
Returns or changes the size in bytes in this string.
String.charSize( [bpc] )
| bpc | New value for bytes per character (1, 2 or 4). |
| Return | This string if bpc is given, or the current character size value if not given. |
Performs a lexicographic comparation of two strings, ignoring character case.
String.cmpi( string )
| string | Second string to be compared with this one. |
| Return | <0, 0 or >0, respectively if this string is less, equal or greater than the string parameter. |
The two strings are compared ignoring the case of latin characters contained in the strings.
If the first string is greater than the second, the function returns a number less than 0. If it's smaller, it returns a positive number. If the two strings are the same, ignoring the case of the characters, 0 is returned.
Check if a strings ends with a substring.
String.endsWith( token, [icase] )
| token | The substring that will be compared with this string. |
| icase | If true, pefroms a case neutral check |
| Return | True if token matches the end of this string, false otherwise. |
This method performs a comparation check at the end of the string. If this string ends with token, the function returns true. If token is larger than the string, the method will always return false, and if token is an empty string, it will always match.
The optional parameter icase can be provided as true to have this method to perform a case insensitive match.
Escapes all the special characters in the string.
String.escape( [full] )
| full | If true, characters above UNICODE 127 are escaped as well. |
| Return | A new escaped string. |
See also: String, strEsq, strUnescape.
Escapes the quotes in this string.
String.esq( [inplace] )
| inplace | if true, the source string is modified, saving memory. |
| Return | A new escaped string, if inplace is not given, or this same string if inplace is true. |
Fills a string with a given character or substring.
String.fill( chr )
| chr | The character (unicode value) or substring used to refill this string. |
| Return | The string itself. |
This method fills the physical storage of the given string with a single character or a repeated substring. This can be useful to clean a string used repeatedly as input buffer.
Finds a substring.
String.find( needle, [start],[end] )
| needle | Substring to search for. |
| start | Optional position from which to start the search in string. |
| end | Optional position at which to end the search in string. |
| Return | The position where the substring is found, or -1. |
See also: strFind.
Returns the first character in a string.
String.front( [count],[numeric],[remove] )
| count | Number of characters to be returned (1 by default). |
| numeric | If true, returns a character value instead of a string. |
| remove | If true, remove also the character. |
| Return | The first element or nil if the string is empty. |
This method returns a string containing one character from the beginning of the string, or eventually more characters in case a number > 1 is specified in count.
If remove is true, then the character is removed and the string is shrunk.
If numeric is true, the UNICODE value of the string character will be returned, otherwise the caller will receive a string containing the desired character. In this case, count parameter will be ignored and only one UNICODE value will be returned.
See also: strFront.
Trims front whitespaces in a string.
String.ftrim( [trimSet] )
| trimSet | A set of characters that must be removed. | ||
| Return | The trimmed version of the string. | ||
| Raise |
|
A new string, which is a copy of the original one with all characters in trimSet at the beginning of the string removed, is returned. If trimSet is not supplied, it defaults to space, tabulation characters, new lines and carriage returns. The original string is unmodified.
See also: strFrontTrim.
Joins the parameters into a new string.
String.join( ... )
| ... | |
| Return | A new string created joining the parameters, left to right. |
If this string is not empty, it is copied between each joined string.
For example, the next code separates each value with ", "
> ", ".join( "have", "a", "nice", "day" )
If the parameters are not string, a standard toString conversion is tried.
Returns a lowercase version of this string.
String.lower()
| Return | The lowercased string. |
All the Latin characters in the string are turned lowercase. Other characters are left untouched.
Merges an array of strings into one.
String.merge( array )
| array | An array of strings to be merged. |
| Return | This string. |
This method works as strMerge, using this string as separator between the strings in the array.
The function may be used in this way:
a = " ".merge( [ "a", "string", "of", "words" ] ) printl( a ) // prints "a string of words"
If an element of the array is not a string, an error is raised.
Returns a pointer to raw data contained in this string.
String.ptr()
| Return | A string pointer. |
This function returns a pointer value (stored in a Falcon integer) pointing to the raw data in the string. The string is not encoded in any format, and its character size can be 1, 2 or 4 bytes per character depending on the values previusly stored. The string is granted to be terminated by an appropriate "\0" value of the correct size. The value exists and is valid only while the original string (this item) stays unchanged.
Replaces the all the occurrences of a substring with another one.
String.replace( substr, repstr, [start],[end] )
| substr | The substring that will be replaced. |
| repstr | The string that will take the place of substr. |
| start | Optional start position in the string. |
| end | Optional end position in the string. |
| Return | A copy of the string with the occourences of the searched substring replaced. |
See also: strReplace.
Returns a new string that is created by replicating this one.
String.replicate( times )
| times | Number of times the string must be replicated. |
| Return | The new string. |
A nice shortcut. Also, this function performs the work efficiently, preallocating the needed space in one shot and avoiding the need to grow the string while replicating the original value.
Finds a substring backwards.
String.rfind( needle, [start],[end] )
| needle | Substring to search for. |
| start | Optional position from which to start the search in string. |
| end | Optional position at which to end the search in string. |
| Return | The position where the substring is found, or -1. |
See also: strBackFind.
Trims trailing whitespaces in a string.
String.rtrim( [trimSet] )
| trimSet | A set of characters that must be removed. | ||
| Return | The trimmed version of the string. | ||
| Raise |
|
A new string, which is a copy of the original one with all characters in trimSet at the end of the string removed, is returned. If trimSet is not supplied, it defaults to space, tabulation characters, new lines and carriage returns. The original string is unmodified.
Subdivides a string in an array of substrings given a token substring.
String.split( [token],[count] )
| token | The token by which the string should be split. |
| count | Optional maximum split count. |
| Return | An array of strings containing the split string. |
See also: strSplit.
Subdivides a string in an array of substrings given a token substring.
String.splittr( token, [count] )
| token | The token by which the string should be split. |
| count | Optional maximum split count. |
| Return | An array of strings containing the split string. |
See also: strSplitTrimmed.
Check if a strings starts with a substring.
String.startsWith( token, [icase] )
| token | The substring that will be compared with this string. |
| icase | If true, pefroms a case neutral check |
| Return | True if token matches the beginning of this string, false otherwise. |
This method performs a comparation check at the beginning of the string. If this string starts with token, the function returns true. If token is larger than the string, the method will always return false, and if token is an empty string, it will always match.
The optional parameter icase can be provided as true to have this method to perform a case insensitive match.
Convets this string into a Memory Buffer
String.toMemBuf( [wordWidth] )
| wordWidth | The memory buffer word width (defaults to string character size). |
| Return | The resulting membuf. |
This function creates a membuf from a string. The resulting membuf has the same word width of the original string, which may be 1, 2 or 4 byte wide depending on the size needed to store its contents. It is possible to specify a different word width; in that case the function will be much less efficient (each character must be copied).
If wordWidth is set to zero, the resulting memory buffer will have 1 byte long elements, but the content of the string will be copied as-is, bytewise, regardless of its character size.
Trims whitespaces from both ends of a string.
String.trim( [trimSet] )
| trimSet | A set of characters that must be removed. | ||
| Return | The trimmed version of the string. | ||
| Raise |
|
A new string, which is a copy of the original one with all characters in trimSet at both ends of the string removed, is returned. If trimSet is not supplied, it defaults to space, tabulation characters, new lines and carriage returns. The original string is unmodified.
See also: strTrim.
Unescapes all the special characters in the string.
String.unescape( [inplace] )
| inplace | if true, the source string is modified, saving memory. |
| Return | A new unescaped string, if inplace is not given, or the string parameter if inplace is true. |
See also: String, strEsq, strEscape.
Escapes the quotes in this string.
String.unesq( [inplace] )
| inplace | if true, the source string is modified, saving memory. |
| Return | A new escaped string, if inplace is not given, or this same string if inplace is true. |
Returns an upper case version of this string.
String.upper()
| Return | The uppercased string. |
All the Latin characters in the string are turned uppercase. Other characters are left untouched.
Perform an old-style file-like jolly-based wildcard match.
String.wmatch( wildcard, [ignoreCase] )
| wildcard | A wildcard, possibly but not necessarily including a jolly character. |
| ignoreCase | If true, the latin 26 base letters case is ignored in matches. |
| Return | True if the string matches, false otherwise. |
This function matches a wildcard that may contain jolly "*" or "?" characters against a string, eventually ignoring the case of the characters. This is a practical function to match file names against given patterns. A "?" in the wildcard represents any single character, while a "*" represents an arbitrary sequence of characters.
The wildcard must match completely the given string for the function to return true.
For example:
See also: strWildcardMatch.