Class String

Metaclass for string items.

class String \ from BOM

more...

Summary

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.

Inherited methods

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.

Detailed description

Metaclass for string items.

This is the set of methods that can be applied to string items.

Methods

back()

Returns the first character in a string.

String.back( [count], [numeric], [remove] )

countNumber of characters to be taken (defaults to 1).
numericIf true, returns a character value instead of a string.
removeIf 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.

charSize()

Returns or changes the size in bytes in this string.

String.charSize( [bpc] )

bpcNew 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.

cmpi()

Performs a lexicographic comparation of two strings, ignoring character case.

String.cmpi( string )

stringSecond 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.

endsWith()

Check if a strings ends with a substring.

String.endsWith( token, [icase] )

tokenThe substring that will be compared with this string.
icaseIf 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.

fill()

Fills a string with a given character or substring.

String.fill( chr )

chrThe 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.

find()

Finds a substring.

String.find( needle, [start], [end] )

needleSubstring to search for.
startOptional position from which to start the search in string.
endOptional position at which to end the search in string.
Returns:The position where the substring is found, or -1.

front()

Returns the first character in a string.

String.front( [count], [numeric], [remove] )

countNumber of characters to be returned (1 by default).
numericIf true, returns a character value instead of a string.
removeIf 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.

ftrim()

Trims front whitespaces in a string.

String.ftrim( [trimSet] )

trimSetA set of characters that must be removed.
Returns:The trimmed version of the string.
Raises:
AccessErrorif the given item is not a string.

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.

join()

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.

lower()

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.

merge()

Merges an array of strings into one.

String.merge( array )

arrayAn 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.

ptr()

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.

replace()

Replaces the all the occurrences of a substring with another one.

String.replace( substr, repstr, [start], [end] )

substrThe substring that will be replaced.
repstrThe string that will take the place of substr.
startOptional start position in the string.
endOptional end position in the string.
Returns:A copy of the string with the occourences of the searched substring replaced.

replicate()

Returns a new string that is created by replicating this one.

String.replicate( times )

timesNumber 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.

rfind()

Finds a substring bakwards.

String.rfind( needle, [start], [end] )

needleSubstring to search for.
startOptional position from which to start the search in string.
endOptional position at which to end the search in string.
Returns:The position where the substring is found, or -1.

rtrim()

Trims trailing whitespaces in a string.

String.rtrim( [trimSet] )

trimSetA set of characters that must be removed.
Returns:The trimmed version of the string.
Raises:
AccessErrorif the given item is not a string.

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.

split()

Subdivides a string in an array of substrings given a token substring.

String.split( token, [count] )

tokenThe token by which the string should be splitted.
countOptional maximum split count.
Returns:An array of strings containing the splitted string.

splittr()

Subdivides a string in an array of substrings given a token substring.

String.splittr( token, [count] )

tokenThe token by which the string should be splitted.
countOptional maximum split count.
Returns:An array of strings containing the splitted string.

startsWith()

Check if a strings starts with a substring.

String.startsWith( token, [icase] )

tokenThe substring that will be compared with this string.
icaseIf 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.

toMemBuf()

Convets this string into a Memory Buffer

String.toMemBuf( [wordWidth] )

wordWidthThe 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.

trim()

Trims whitespaces from both ends of a string.

String.trim( [trimSet] )

trimSetA set of characters that must be removed.
Returns:The trimmed version of the string.
Raises:
AccessErrorif the given item is not a string.

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.

upper()

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.

wmatch()

Perform an old-style file-like jolly-based wildcard match.

String.wmatch( wildcard, [ignoreCase] )

wildcardA wildcard, possibly but not necessarily including a jolly character.
ignoreCaseIf 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:


Made with faldoc 2.1.0