<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Function set "String functions" - Function set "String functions"</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./funset.html"><span>Function sets</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Function set "String functions"</h1>
<p class="faldoc_brief">Functions manipulating strings </p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#strBack">strBack()</a></td><td>Returns the last character(s) in a string. </td></tr>
<tr><td><a href="#strBackFind">strBackFind()</a></td><td>Finds a substring bakwards. </td></tr>
<tr><td><a href="#strBackTrim">strBackTrim()</a></td><td>Removes white spaces at both the beginning and the end of the string. </td></tr>
<tr><td><a href="#strBuffer">strBuffer()</a></td><td>Pre-allocates an empty string. </td></tr>
<tr><td><a href="#strCmpIgnoreCase">strCmpIgnoreCase()</a></td><td>Performs a lexicographic comparation of two strings, ignoring character case. </td></tr>
<tr><td><a href="#strEndsWith">strEndsWith()</a></td><td>Check if a strings ends with a substring. </td></tr>
<tr><td><a href="#strEscape">strEscape()</a></td><td>Escape quotes and special characters in the string </td></tr>
<tr><td><a href="#strEsq">strEsq()</a></td><td>Escape quotes in the given string. </td></tr>
<tr><td><a href="#strFill">strFill()</a></td><td>Fills a string with a given character or substring. </td></tr>
<tr><td><a href="#strFind">strFind()</a></td><td>Finds a substring. </td></tr>
<tr><td><a href="#strFromMemBuf">strFromMemBuf()</a></td><td>Convets a MemBuf to a string. </td></tr>
<tr><td><a href="#strFront">strFront()</a></td><td>Returns the first character in a string. </td></tr>
<tr><td><a href="#strFrontTrim">strFrontTrim()</a></td><td>Removes white spaces from the front of the string. </td></tr>
<tr><td><a href="#strLower">strLower()</a></td><td>Returns a lowercase version of the given string. </td></tr>
<tr><td><a href="#strMerge">strMerge()</a></td><td>Merges an array of strings into a string. </td></tr>
<tr><td><a href="#strReplace">strReplace()</a></td><td>Replaces the all the occurrences of a substring with another one. </td></tr>
<tr><td><a href="#strReplicate">strReplicate()</a></td><td>Returns a new string that is created by replicating the original one. </td></tr>
<tr><td><a href="#strSplit">strSplit()</a></td><td>Subdivides a string in an array of substrings given a token substring. </td></tr>
<tr><td><a href="#strSplitTrimmed">strSplitTrimmed()</a></td><td>Subdivides a string in an array of substrings given a token substring. </td></tr>
<tr><td><a href="#strStartsWith">strStartsWith()</a></td><td>Check if a strings starts with a substring. </td></tr>
<tr><td><a href="#strToMemBuf">strToMemBuf()</a></td><td>Convets a string into a Memory Buffer </td></tr>
<tr><td><a href="#strTrim">strTrim()</a></td><td>Removes the white spaces at the beginning and at the end of a string. </td></tr>
<tr><td><a href="#strUnescape">strUnescape()</a></td><td>Unescape quotes and special characters in the string </td></tr>
<tr><td><a href="#strUnesq">strUnesq()</a></td><td>Unescape the quotes in given string. </td></tr>
<tr><td><a href="#strUpper">strUpper()</a></td><td>Returns an upper case version of the string. </td></tr>
<tr><td><a href="#strWildcardMatch">strWildcardMatch()</a></td><td>Perform an old-style file-like jolly-based wildcard match. </td></tr>
</table>
<h2 class="faldoc_title">Members</h2>
<h3 class="faldoc_funcname"><a name="strBack">strBack()</a></h3>
<p class="item_brief">Returns the last character(s) in a string. </p>
<p class="faldoc_funcdecl">strBack( str, [count], [remove], [numeric] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">str</td><td class="faldoc_paramdesc">The string on which to operate. </td></tr>
<tr><td class="faldoc_optparam">count</td><td class="faldoc_optparamdesc">Number of characters to be taken (defaults to 1). </td></tr><tr><td class="faldoc_optparam">remove</td><td class="faldoc_optparamdesc">If true, remove also the character. </td></tr><tr><td class="faldoc_optparam">numeric</td><td class="faldoc_optparamdesc">If true, returns a character value instead of a string. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The first element or nil if the string is empty. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function returns a string containing one character from the end of <b>str</b>, or eventually more characters in case a number > 1 is specified in <b>count</b>. </p>
<p class="faldoc_text"> If <b>remove</b> is true, then the characters are removed and the string is shrinked. </p>
<p class="faldoc_text"> If <b>numeric</b> 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, <b>count</b> parameter will be ignored and only one UNICODE value will be returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="strBackFind">strBackFind()</a></h3>
<p class="item_brief">Finds a substring bakwards. </p>
<p class="faldoc_funcdecl">strBackFind( string, needle, [start], [end] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">String where the search will take place. </td></tr><tr><td class="faldoc_param">needle</td><td class="faldoc_paramdesc">Substring to search for. </td></tr>
<tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">Optional position from which to start the search in string. </td></tr><tr><td class="faldoc_optparam">end</td><td class="faldoc_optparamdesc">Optional position at which to end the search in string. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The position where the substring is found, or -1. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Works exactly as <a href="./functions.html#strFind">strFind</a>, except for the fact that the last match in the string (or in the specified interval) is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="strBackTrim">strBackTrim()</a></h3>
<p class="item_brief">Removes white spaces at both the beginning and the end of the string. </p>
<p class="faldoc_funcdecl">strBackTrim( string, [trimSet] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string to be trimmed. </td></tr>
<tr><td class="faldoc_optparam">trimSet</td><td class="faldoc_optparamdesc">A set of characters that must be removed. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The trimmed substring. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> A new string, which is a copy of the original one with all characters in <b>trimSet</b> at the beginning and at the end of the string removed, is returned. If <b>trimSet</b> is not supplied, it defaults to space, tabulation characters, new lines and carriage returns. The original string is unmodified. </p>
</p>
<h3 class="faldoc_funcname"><a name="strBuffer">strBuffer()</a></h3>
<p class="item_brief">Pre-allocates an empty string. </p>
<p class="faldoc_funcdecl">strBuffer( size )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">size</td><td class="faldoc_paramdesc">Size of the pre-allocated string. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The new string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned string is an empty string, and equals to "". However, the required size is pre-allocated, and addition to this string (i.e. += operators) takes place in a fraction of the time otherwise required, up tho the filling of the pre-allocated buffer. Also, this string can be fed into file functions, the pre-allocation size being used as the input read size. </p>
</p>
<h3 class="faldoc_funcname"><a name="strCmpIgnoreCase">strCmpIgnoreCase()</a></h3>
<p class="item_brief">Performs a lexicographic comparation of two strings, ignoring character case. </p>
<p class="faldoc_funcdecl">strCmpIgnoreCase( string1, string2 )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string1</td><td class="faldoc_paramdesc">First string to be compared. </td></tr><tr><td class="faldoc_param">string2</td><td class="faldoc_paramdesc">Second string to be compared. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">-1, 0 or 1. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The two strings are compared ignoring the case of latin characters contained in the strings. </p>
<p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="strEndsWith">strEndsWith()</a></h3>
<p class="item_brief">Check if a strings ends with a substring. </p>
<p class="faldoc_funcdecl">strEndsWith( string, token, [icase] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string that is going to be tested for the given token. </td></tr><tr><td class="faldoc_param">token</td><td class="faldoc_paramdesc">The substring that will be compared with this string. </td></tr>
<tr><td class="faldoc_optparam">icase</td><td class="faldoc_optparamdesc">If true, pefroms a case neutral check </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> True if <b>token</b> matches the end of <b>string</b>, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This functioin performs a comparation check at the end of the <b>string</b>. If this string ends with <b>token</b>, the function returns true. If <b>token</b> is larger than the string, the function will always return false, and if <b>token</b> is an empty string, it will always match. </p>
<p class="faldoc_text"> The optional parameter <b>icase</b> can be provided as true to have this function to perform a case insensitive match. </p>
</p>
<h3 class="faldoc_funcname"><a name="strEscape">strEscape()</a></h3>
<p class="item_brief">Escape quotes and special characters in the string </p>
<p class="faldoc_funcdecl">strEscape( string, [full] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">the String to be escaped. </td></tr>
<tr><td class="faldoc_optparam">full</td><td class="faldoc_optparamdesc">If true, characters above UNICODE 127 are escaped as well. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A new escaped string. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="strEsq">strEsq()</a></h3>
<p class="item_brief">Escape quotes in the given string. </p>
<p class="faldoc_funcdecl">strEsq( string, [inplace] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">the String to be escaped. </td></tr>
<tr><td class="faldoc_optparam">inplace</td><td class="faldoc_optparamdesc">if true, the source string is modified, saving memory. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new escaped string, if <b>inplace</b> is not given, or the <b>string</b> parameter if <b>inplace</b> is true. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="strFill">strFill()</a></h3>
<p class="item_brief">Fills a string with a given character or substring. </p>
<p class="faldoc_funcdecl">strFill( string, chr )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string to be filled. </td></tr><tr><td class="faldoc_param">chr</td><td class="faldoc_paramdesc"> The character (unicode value) or substring used to refill the <b>string</b>. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The string itself. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function 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. </p>
<p class="faldoc_text">The function returns the same string that has been passed as the parameter. </p>
</p>
<h3 class="faldoc_funcname"><a name="strFind">strFind()</a></h3>
<p class="item_brief">Finds a substring. </p>
<p class="faldoc_funcdecl">strFind( string, needle, [start], [end] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">String where the search will take place. </td></tr><tr><td class="faldoc_param">needle</td><td class="faldoc_paramdesc">Substring to search for. </td></tr>
<tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">Optional position from which to start the search in string. </td></tr><tr><td class="faldoc_optparam">end</td><td class="faldoc_optparamdesc">Optional position at which to end the search in string. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The position where the substring is found, or -1. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns the index in string were needle begins, or -1 if not present. Giving a start parameter will cause the search to start from the given position up to the end of the string; if a match can be made at start position, then the the returned value will be the same as start, so when repeating searches in a string for all the possible matches, repeat until the result is -1 by adding one to the returned value and using it as start position for the next search. </p>
<p class="faldoc_text">If an end position is given, it is used as upper limit for the search, so that the search is in the interval [start, end-1]. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This function is equivalent to the fbom method String.find </p>
</p>
<h3 class="faldoc_funcname"><a name="strFromMemBuf">strFromMemBuf()</a></h3>
<p class="item_brief">Convets a MemBuf to a string. </p>
<p class="faldoc_funcdecl">strFromMemBuf( membuf )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">membuf</td><td class="faldoc_paramdesc">A MemBuf that will be converted to a string. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The resulting string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This string takes each element of the membuf and converts it into a character in the final string. The contents of the buffer are not transcoded. It is appropriate to say that this function considers each element in the MemBuf as an Unicode value for the character in the final string. </p>
<p class="faldoc_text">To create a string from a buffer that may come from an encoded source (i.e. a file), use directly Transcode functions. </p>
</p>
<h3 class="faldoc_funcname"><a name="strFront">strFront()</a></h3>
<p class="item_brief">Returns the first character in a string. </p>
<p class="faldoc_funcdecl">strFront( str, [count], [remove], [numeric] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">str</td><td class="faldoc_paramdesc">The string on which to operate. </td></tr>
<tr><td class="faldoc_optparam">count</td><td class="faldoc_optparamdesc">Number of characters to be taken (defaults to 1). </td></tr><tr><td class="faldoc_optparam">remove</td><td class="faldoc_optparamdesc">If true, remove also the character. </td></tr><tr><td class="faldoc_optparam">numeric</td><td class="faldoc_optparamdesc">If true, returns a character value instead of a string. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The first element or nil if the string is empty. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function returns a string containing one character from the beginning of <b>str</b>, or eventually more characters in case a number > 1 is specified in <b>count</b>. </p>
<p class="faldoc_text"> If <b>remove</b> is true, then the character is removed and the string is shrinked. </p>
<p class="faldoc_text"> If <b>numeric</b> 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, <b>count</b> parameter will be ignored and only one UNICODE value will be returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="strFrontTrim">strFrontTrim()</a></h3>
<p class="item_brief">Removes white spaces from the front of the string. </p>
<p class="faldoc_funcdecl">strFrontTrim( string, [trimSet] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string to be trimmed. </td></tr>
<tr><td class="faldoc_optparam">trimSet</td><td class="faldoc_optparamdesc">A set of characters that must be removed. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The trimmed substring. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> A new string, which is a copy of the original one with all characters in <b>trimSet</b> at the beginning of the string removed, is returned. If <b>trimSet</b> is not supplied, it defaults to space, tabulation characters, new lines and carriage returns. The original string is unmodified. </p>
</p>
<h3 class="faldoc_funcname"><a name="strLower">strLower()</a></h3>
<p class="item_brief">Returns a lowercase version of the given string. </p>
<p class="faldoc_funcdecl">strLower( string )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">String that must be lowercased. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The lowercased string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">All the Latin characters in the string are turned lowercase. Other characters are left untouched. </p>
</p>
<h3 class="faldoc_funcname"><a name="strMerge">strMerge()</a></h3>
<p class="item_brief">Merges an array of strings into a string. </p>
<p class="faldoc_funcdecl">strMerge( array, [mergeStr], [count] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">An array of strings to be merged. </td></tr>
<tr><td class="faldoc_optparam">mergeStr</td><td class="faldoc_optparamdesc">A string placed between each merge. </td></tr><tr><td class="faldoc_optparam">count</td><td class="faldoc_optparamdesc">Maximum count of merges. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The merged string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function will return a new string containing the concatenation of the strings inside the array parameter. If the array is empty, an empty string is returned. If a mergeStr parameter is given, it is added to each pair of string merged; mergeStr is never added at the end of the new string. A count parameter may be specified to limit the number of elements merged in the array. </p>
<p class="faldoc_text">The function may be used in this way: </p>
<pre class="faldoc_code">
a = strMerge( [ "a", "string", "of", "words" ], " " )
printl( a ) // prints "a string of words"
</pre>
<p class="faldoc_text">If an element of the array is not a string, an error is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="strReplace">strReplace()</a></h3>
<p class="item_brief">Replaces the all the occurrences of a substring with another one. </p>
<p class="faldoc_funcdecl">strReplace( string, substr, repstr, [start], [end] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string where the replace will take place. </td></tr><tr><td class="faldoc_param">substr</td><td class="faldoc_paramdesc">The substring that will be replaced. </td></tr><tr><td class="faldoc_param">repstr</td><td class="faldoc_paramdesc">The string that will take the place of substr. </td></tr>
<tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">Optional start position in the string. </td></tr><tr><td class="faldoc_optparam">end</td><td class="faldoc_optparamdesc">Optional end position in the string. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A copy of the string with the occourences of the searched substring replaced. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This is a flexible function that allows to alter a string by changing all the occurrences of a substring into another one. If the start parameter is given, the search and replacement will take place only starting at the specified position up to the end of the string, and if the end parameter is also provided, the search will take place in the interval [start, end-1]. </p>
</p>
<h3 class="faldoc_funcname"><a name="strReplicate">strReplicate()</a></h3>
<p class="item_brief">Returns a new string that is created by replicating the original one. </p>
<p class="faldoc_funcdecl">strReplicate( string, times )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string to be replicaeted. </td></tr><tr><td class="faldoc_param">times</td><td class="faldoc_paramdesc">Number of times the string must be replicated. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The new string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="strSplit">strSplit()</a></h3>
<p class="item_brief">Subdivides a string in an array of substrings given a token substring. </p>
<p class="faldoc_funcdecl">strSplit( string, token, [count] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string that must be splitted </td></tr><tr><td class="faldoc_param">token</td><td class="faldoc_paramdesc">The token by which the string should be splitted. </td></tr>
<tr><td class="faldoc_optparam">count</td><td class="faldoc_optparamdesc">Optional maximum split count. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array of strings containing the splitted string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns an array of strings extracted from the given parameter. The array is filled with strings extracted from the first parameter, by dividing it based on the occurrences of the token substring. A count parameter may be provided to limit the splitting, so to take into consideration only the first relevant tokens. Adjacent matching tokens will cause the returned array to contains empty strings. If no matches are possible, the returned array contains at worst a single element containing a copy of the whole string passed as a parameter. </p>
<p class="faldoc_text">For example, the following may be useful to parse a INI file where keys are separated from values by "=" signs: </p>
<pre class="faldoc_code">
key, value = strSplit( string, "=", 2 )
</pre>
<p class="faldoc_text">This code would return an array of 2 items at maximum; if no "=" signs are found in string, the above code would throw an error because of unpacking size, a thing that may be desirable in a parsing code. If there are more than one "=" in the string, only the first starting from left is considered, while the others are returned in the second item, unparsed. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This function is equivalent to the fbom method <a href="./class_String.html#split">String.split</a>. The above example can be rewritten as: </p>
<pre class="faldoc_code">
key, value = string.split( "=", 2 )
</pre>
</p>
<h3 class="faldoc_funcname"><a name="strSplitTrimmed">strSplitTrimmed()</a></h3>
<p class="item_brief">Subdivides a string in an array of substrings given a token substring. </p>
<p class="faldoc_funcdecl">strSplitTrimmed( string, token, [count] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string that must be splitted </td></tr><tr><td class="faldoc_param">token</td><td class="faldoc_paramdesc">The token by which the string should be splitted. </td></tr>
<tr><td class="faldoc_optparam">count</td><td class="faldoc_optparamdesc">Optional maximum split count. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array of strings containing the splitted string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns an array of strings extracted from the given parameter. The array is filled with strings extracted from the first parameter, by dividing it based on the occurrences of the token substring. A count parameter may be provided to limit the splitting, so to take into consideration only the first relevant tokens. Adjacent matching tokens will be ignored. If no matches are possible, the returned array contains at worst a single element containing a copy of the whole string passed as a parameter. </p>
<p class="faldoc_text"> Contrarily to <a href="./functions.html#strSplit">strSplit</a>, this function will "eat up" adjacent tokens. While <a href="./functions.html#strSplit">strSplit</a> is more adequate to parse field-oriented strings (as i.e. colon separated fields in configuration files) this function is best employed in word extraction. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> this function is equivalent to the FBOM method String.splittr </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> See <a href="./class_Tokenizer.html">Tokenizer</a> for a more adequate function to scan extensively wide strings. </p>
</p>
<h3 class="faldoc_funcname"><a name="strStartsWith">strStartsWith()</a></h3>
<p class="item_brief">Check if a strings starts with a substring. </p>
<p class="faldoc_funcdecl">strStartsWith( string, token, [icase] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string that is going to be tested for the given token. </td></tr><tr><td class="faldoc_param">token</td><td class="faldoc_paramdesc">The substring that will be compared with this string. </td></tr>
<tr><td class="faldoc_optparam">icase</td><td class="faldoc_optparamdesc">If true, pefroms a case neutral check </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> True if <b>token</b> matches the beginning of <b>string</b>, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This functioin performs a comparation check at the beginning of the <b>string</b>. If this string starts with <b>token</b>, the function returns true. If <b>token</b> is larger than the string, the function will always return false, and if <b>token</b> is an empty string, it will always match. </p>
<p class="faldoc_text"> The optional parameter <b>icase</b> can be provided as true to have this function to perform a case insensitive match. </p>
</p>
<h3 class="faldoc_funcname"><a name="strToMemBuf">strToMemBuf()</a></h3>
<p class="item_brief">Convets a string into a Memory Buffer </p>
<p class="faldoc_funcdecl">strToMemBuf( string, [wordWidth] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">String to be converted in a membuf. </td></tr>
<tr><td class="faldoc_optparam">wordWidth</td><td class="faldoc_optparamdesc">The memory buffer word width (defaults to string character size). </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The resulting membuf. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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). </p>
<p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="strTrim">strTrim()</a></h3>
<p class="item_brief">Removes the white spaces at the beginning and at the end of a string. </p>
<p class="faldoc_funcdecl">strTrim( string, [trimSet] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The string to be trimmed. </td></tr>
<tr><td class="faldoc_optparam">trimSet</td><td class="faldoc_optparamdesc">A set of characters that must be removed. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The trimmed substring. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> A new string, which is a copy of the original one with all characters in <b>trimSet</b> at the end of the string removed, is returned. If <b>trimSet</b> is not supplied, it defaults to space, tabulation characters, new lines and carriage returns. The original string is unmodified. </p>
</p>
<h3 class="faldoc_funcname"><a name="strUnescape">strUnescape()</a></h3>
<p class="item_brief">Unescape quotes and special characters in the string </p>
<p class="faldoc_funcdecl">strUnescape( string, [inplace] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">the String to be escaped. </td></tr>
<tr><td class="faldoc_optparam">inplace</td><td class="faldoc_optparamdesc">if true, the source string is modified, saving memory. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new unescaped string, if <b>inplace</b> is not given, or the <b>string</b> parameter if <b>inplace</b> is true. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="strUnesq">strUnesq()</a></h3>
<p class="item_brief">Unescape the quotes in given string. </p>
<p class="faldoc_funcdecl">strUnesq( string, [inplace] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">the String to be unescaped. </td></tr>
<tr><td class="faldoc_optparam">inplace</td><td class="faldoc_optparamdesc">if true, the source string is modified, saving memory. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new unescaped string, if <b>inplace</b> is not given, or the <b>string</b> parameter if <b>inplace</b> is true. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function transforms all the occourences of '\\"' and '\\'' into a double or single quote, leaving all the other special escape sequences untouched. </p>
</p>
<h3 class="faldoc_funcname"><a name="strUpper">strUpper()</a></h3>
<p class="item_brief">Returns an upper case version of the string. </p>
<p class="faldoc_funcdecl">strUpper( string )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">String that must be uppercased. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The uppercased string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">All the Latin characters in the string are turned uppercase. Other characters are left untouched. </p>
</p>
<h3 class="faldoc_funcname"><a name="strWildcardMatch">strWildcardMatch()</a></h3>
<p class="item_brief">Perform an old-style file-like jolly-based wildcard match. </p>
<p class="faldoc_funcdecl">strWildcardMatch( string, wildcard, [ignoreCase] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">String that must match the wildcard. </td></tr><tr><td class="faldoc_param">wildcard</td><td class="faldoc_paramdesc">A wildcard, possibly but not necessarily including a jolly character. </td></tr>
<tr><td class="faldoc_optparam">ignoreCase</td><td class="faldoc_optparamdesc">If true, the latin 26 base letters case is ignored in matches. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the string matches, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
<p class="faldoc_text">The wildcard must match completely the given string for the function to return true. </p>
<p class="faldoc_text">For example: </p>
<ul>
<li>"*" matches everything </li><li>"a?b" matches "aab", "adb" and so on </li><li>"a*b" matches "ab", "annnb" and so on </li>
</ul>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./funset.html">Function sets</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./globals.html">Globals</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
