Metaclass for string items.
class String \ from BOM
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. |
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 bakwards. |
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. |
upper() | Returns an upper case version of this string. |
wmatch() | Perform an old-style file-like jolly-based wildcard match. |
add__ from BOM | Overrides binary addition operand. |
baseClass from BOM | Returns the class item from which an object has been instantiated. |
call__ from BOM | Overrides call operator "self()". |
className from BOM | Returns the name of the class an instance is instantiated from. |
clone from BOM | Performs a deep copy of the item. |
compare from BOM | Performs a lexicographical comparison. |
dec__ from BOM | Overrides decrement unary prefix operand. |
decpost__ from BOM | Overrides decrement unary postfix operand. |
derivedFrom from BOM | Checks if this item has a given parent. |
describe from BOM | Returns the deep contents of an item on a string representation. |
div__ from BOM | Overrides binary division operand. |
getIndex__ from BOM | Overrides array access operator [] |
inc__ from BOM | Overrides increment unary prefix operand. |
incpost__ from BOM | Overrides increment unary postifx operand. |
isCallable from BOM | Determines if an item is callable. |
len from BOM | Retreives the lenght of a collection |
metaclass from BOM | Returns the metaclass associated with this item. |
mod__ from BOM | Overrides modulo operand. |
mul__ from BOM | Overrides binary multiplication operand. |
pow__ from BOM | Overrides power operand. |
ptr from BOM | Returns a raw memory pointer out of this data (as an integer). |
serialize from BOM | Serialize the item on a stream for persistent storage. |
setIndex__ from BOM | Overrides array write operator [] |
sub__ from BOM | Overrides binary subtraction operand. |
toString from BOM | Coverts the object to string. |
typeId from BOM | Returns an integer indicating the type of this item. |
Metaclass for string items.
This is the set of methods that can be applied to string items.
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. |
Returns: | 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 shrinked.
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.
Returns or changes the size in bytes in this string.
String.charSize( [bpc] )
bpc | New value for bytes per character (1, 2 or 4). |
Returns: | 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. |
Returns: | <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 |
Returns: | 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.
Fills a string with a given character or substring.
String.fill( chr )
chr | The character (unicode value) or substring used to refill this string. |
Returns: | 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. |
Returns: | The position where the substring is found, or -1. |
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. |
Returns: | 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 shrinked.
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.
Trims front whitespaces in a string.
String.ftrim( [trimSet] )
trimSet | A set of characters that must be removed. | ||
Returns: | The trimmed version of the string. | ||
Raises: |
|
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.
Joins the parameters into a new string.
String.join( .. )
.. | . |
Returns: | 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( )
Returns: | 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. |
Returns: | 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( )
Returns: | 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. |
Returns: | A copy of the string with the occourences of the searched substring replaced. |
Returns a new string that is created by replicating this one.
String.replicate( times )
times | Number of times the string must be replicated. |
Returns: | 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 bakwards.
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. |
Returns: | The position where the substring is found, or -1. |
Trims trailing whitespaces in a string.
String.rtrim( [trimSet] )
trimSet | A set of characters that must be removed. | ||
Returns: | The trimmed version of the string. | ||
Raises: |
|
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 splitted. |
count | Optional maximum split count. |
Returns: | An array of strings containing the splitted string. |
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 splitted. |
count | Optional maximum split count. |
Returns: | An array of strings containing the splitted string. |
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 |
Returns: | 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). |
Returns: | 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. | ||
Returns: | The trimmed version of the string. | ||
Raises: |
|
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.
Returns an upper case version of this string.
String.upper( )
Returns: | 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. |
Returns: | 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: