1.2.15Class String

Metaclass for string items.

Class String from \
                 BOM( )

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

Methods
backReturns the first character in a string.
charSizeReturns or changes the size in bytes in this string.
cmpiPerforms a lexicographic comparation of two strings, ignoring character case.
endsWithCheck if a strings ends with a substring.
escapeEscapes all the special characters in the string.
esqEscapes the quotes in this string.
fillFills a string with a given character or substring.
findFinds a substring.
frontReturns the first character in a string.
ftrimTrims front whitespaces in a string.
joinJoins the parameters into a new string.
lowerReturns a lowercase version of this string.
mergeMerges an array of strings into one.
ptrReturns a pointer to raw data contained in this string.
replaceReplaces the all the occurrences of a substring with another one.
replicateReturns a new string that is created by replicating this one.
rfindFinds a substring backwards.
rtrimTrims trailing whitespaces in a string.
splitSubdivides a string in an array of substrings given a token substring.
splittrSubdivides a string in an array of substrings given a token substring.
startsWithCheck if a strings starts with a substring.
toMemBufConvets this string into a Memory Buffer
trimTrims whitespaces from both ends of a string.
unescapeUnescapes all the special characters in the string.
unesqEscapes the quotes in this string.
upperReturns an upper case version of this string.
wmatchPerform an old-style file-like jolly-based wildcard match.
Methods inherited from class BOM
__addOverrides binary addition operand.
__callOverrides call operator "self()".
__decOverrides decrement unary prefix operand.
__decpostOverrides decrement unary postfix operand.
__divOverrides binary division operand.
__getIndexOverrides array access operator []
__incOverrides increment unary prefix operand.
__incpostOverrides increment unary postifx operand.
__modOverrides modulo operand.
__mulOverrides binary multiplication operand.
__powOverrides power operand.
__setIndexOverrides array write operator []
__subOverrides binary subtraction operand.
baseClassReturns the class item from which an object has been instantiated.
boundDetermines if an item is bound or not.
classNameReturns the name of the class an instance is instantiated from.
clonePerforms a deep copy of the item.
comparePerforms a lexicographical comparison.
derivedFromChecks if this item has a given parent.
describeReturns the deep contents of an item on a string representation.
isCallableDetermines if an item is callable.
lenRetrieves the length of a collection
metaclassReturns the metaclass associated with this item.
ptrReturns a raw memory pointer out of this data (as an integer).
serializeSerialize the item on a stream for persistent storage.
toStringCoverts the object to string.
typeIdReturns an integer indicating the type of this item.

Methods

back

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

charSize

Returns or changes the size in bytes in this string.

String.charSize( [bpc] )
bpc New value for bytes per character (1, 2 or 4).
ReturnThis 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 )
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.

endsWith

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

escape

Escapes all the special characters in the string.

String.escape( [full] )
full If true, characters above UNICODE 127 are escaped as well.
ReturnA new escaped string.

See also: String, strEsq, strUnescape.

esq

Escapes the quotes in this string.

String.esq( [inplace] )
inplace if true, the source string is modified, saving memory.
ReturnA new escaped string, if inplace is not given, or this same string if inplace is true.

See also: String, strEsq.

fill

Fills a string with a given character or substring.

String.fill( chr )
chr The character (unicode value) or substring used to refill this string.
ReturnThe 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] )
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.
ReturnThe position where the substring is found, or -1.

See also: strFind.

front

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

ftrim

Trims front whitespaces in a string.

String.ftrim( [trimSet] )
trimSet A set of characters that must be removed.
ReturnThe trimmed version of the string.
Raise
AccessError if 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.

See also: strFrontTrim.

join

Joins the parameters into a new string.

String.join( ... )
...
ReturnA 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()
ReturnThe 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 )
array An array of strings to be merged.
ReturnThis 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()
ReturnA 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] )
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.
ReturnA copy of the string with the occourences of the searched substring replaced.

See also: strReplace.

replicate

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

String.replicate( times )
times Number of times the string must be replicated.
ReturnThe 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 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.
ReturnThe position where the substring is found, or -1.

See also: strBackFind.

rtrim

Trims trailing whitespaces in a string.

String.rtrim( [trimSet] )
trimSet A set of characters that must be removed.
ReturnThe trimmed version of the string.
Raise
AccessError if 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] )
token The token by which the string should be split.
count Optional maximum split count.
ReturnAn array of strings containing the split string.

See also: strSplit.

splittr

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.
ReturnAn array of strings containing the split string.

See also: strSplitTrimmed.

startsWith

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
ReturnTrue 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] )
wordWidth The memory buffer word width (defaults to string character size).
ReturnThe 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] )
trimSet A set of characters that must be removed.
ReturnThe trimmed version of the string.
Raise
AccessError if 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.

See also: strTrim.

unescape

Unescapes all the special characters in the string.

String.unescape( [inplace] )
inplace if true, the source string is modified, saving memory.
ReturnA new unescaped string, if inplace is not given, or the string parameter if inplace is true.

See also: String, strEsq, strEscape.

unesq

Escapes the quotes in this string.

String.unesq( [inplace] )
inplace if true, the source string is modified, saving memory.
ReturnA new escaped string, if inplace is not given, or this same string if inplace is true.

See also: String, strUnesq.

upper

Returns an upper case version of this string.

String.upper()
ReturnThe 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] )
wildcard A wildcard, possibly but not necessarily including a jolly character.
ignoreCase If true, the latin 26 base letters case is ignored in matches.
ReturnTrue 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.

Made with http://www.falconpl.org