<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Function set "Array support" - Function set "Array support"</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 "Array support"</h1>
<p class="faldoc_brief">Array related functions. </p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#arrayAdd">arrayAdd()</a></td><td>Adds an element to an array. </td></tr>
<tr><td><a href="#arrayBuffer">arrayBuffer()</a></td><td>Creates an array filled with nil items. </td></tr>
<tr><td><a href="#arrayCompact">arrayCompact()</a></td><td>Reduces the memory used by an array. </td></tr>
<tr><td><a href="#arrayDel">arrayDel()</a></td><td>Deletes the first element matching a given item. </td></tr>
<tr><td><a href="#arrayDelAll">arrayDelAll()</a></td><td>Deletes all the occurrences of a given item in an array. </td></tr>
<tr><td><a href="#arrayFill">arrayFill()</a></td><td>Fills the array with the given element. </td></tr>
<tr><td><a href="#arrayFind">arrayFind()</a></td><td>Searches for a given item in an array. </td></tr>
<tr><td><a href="#arrayHead">arrayHead()</a></td><td>Extracts the first element of an array and returns it. </td></tr>
<tr><td><a href="#arrayIns">arrayIns()</a></td><td>Inserts an item into an array. </td></tr>
<tr><td><a href="#arrayMerge">arrayMerge()</a></td><td>Merges two arrays. </td></tr>
<tr><td><a href="#arrayNM">arrayNM()</a></td><td>Force an array to be non-method. </td></tr>
<tr><td><a href="#arrayRemove">arrayRemove()</a></td><td>Removes one or more elements in the array. </td></tr>
<tr><td><a href="#arrayResize">arrayResize()</a></td><td>Changes the size of the array. </td></tr>
<tr><td><a href="#arrayScan">arrayScan()</a></td><td>Searches an array for an item satisfying arbitrary criteria. </td></tr>
<tr><td><a href="#arraySort">arraySort()</a></td><td>Sorts an array, possibly using an arbitrary ordering criterion. </td></tr>
<tr><td><a href="#arrayTail">arrayTail()</a></td><td>Extracts the last element of an array and returns it. </td></tr>
</table>
<h2 class="faldoc_title">Members</h2>
<h3 class="faldoc_funcname"><a name="arrayAdd">arrayAdd()</a></h3>
<p class="item_brief">Adds an element to an array. </p>
<p class="faldoc_funcdecl">arrayAdd( array, item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array where to add the new item. </td></tr><tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be added. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The element will be added at the end of the array, and its size will be increased by one. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayBuffer">arrayBuffer()</a></h3>
<p class="item_brief">Creates an array filled with nil items. </p>
<p class="faldoc_funcdecl">arrayBuffer( size, [defItem] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">size</td><td class="faldoc_paramdesc">The length of the returned array. </td></tr>
<tr><td class="faldoc_optparam">defItem</td><td class="faldoc_optparamdesc">The default item to be that will fill the array. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> An array filled with <b>size</b> nil elements. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function is useful when the caller knows the number of needed items. In this way, it is just necessary to set the various elements to their values, rather than adding them to the array. This will result in faster operations. </p>
<p class="faldoc_text"> If <b>defItem</b> is not given, the elements in the returned array will be set to nil, otherwise each element will be a flat copy of <b>item</b>. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayCompact">arrayCompact()</a></h3>
<p class="item_brief">Reduces the memory used by an array. </p>
<p class="faldoc_funcdecl">arrayCompact( array )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array itself. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Itself </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Normally, array operations, as insertions, additions and so on cause the array to grow to accommodate items that may come in the future. also, reducing the size of an array doesn't automatically dispose of the memory held by the array to store its elements. </p>
<p class="faldoc_text">This function grants that the memory used by the array is strictly the memory needed to store its data. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayDel">arrayDel()</a></h3>
<p class="item_brief">Deletes the first element matching a given item. </p>
<p class="faldoc_funcdecl">arrayDel( array, item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that is to be changed. </td></tr><tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item that must be deleted. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if at least one item has been removed, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function scans the array searching for an item that is considered equal to the given one. If such an item can be found, it is removed and the function returns true. If the item cannot be found, false is returned. </p>
<p class="faldoc_text">Only the first item matching the given one will be deleted. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayDelAll">arrayDelAll()</a></h3>
<p class="item_brief">Deletes all the occurrences of a given item in an array. </p>
<p class="faldoc_funcdecl">arrayDelAll( array, item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that is to be changed. </td></tr><tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item that must be deleted. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if at least one item has been removed, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function removes all the elements of the given array that are considered equivalent to the given item. If one or more elements have been found and deleted, the function will return true, else it will return false. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayFill">arrayFill()</a></h3>
<p class="item_brief">Fills the array with the given element. </p>
<p class="faldoc_funcdecl">arrayFill( array, item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array where to add the new item. </td></tr><tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be replicated. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> The same <b>array</b> passed as parameter. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method allows to clear a whole array, resetting all the elements to a default value. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayFind">arrayFind()</a></h3>
<p class="item_brief">Searches for a given item in an array. </p>
<p class="faldoc_funcdecl">arrayFind( array, item, [start], [end] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that will be searched. </td></tr><tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The array that will be searched. </td></tr>
<tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">Optional first element to be searched. </td></tr><tr><td class="faldoc_optparam">end</td><td class="faldoc_optparamdesc">Optional last element +1 to be searched. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The position of the searched item in the array, or -1 if not found. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function searches the array for a given item (or for an item considered equivalent to the given one). If that item is found, the item position is returned, else -1 is returned. </p>
<p class="faldoc_text">An optional range may be specified to limit the search in the interval start included, end excluded. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayHead">arrayHead()</a></h3>
<p class="item_brief">Extracts the first element of an array and returns it. </p>
<p class="faldoc_funcdecl">arrayHead( array )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that will be modified. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The extracted item. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">if the array is empty. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function removes the first item of the array and returns it. If the original array is empty, AccessError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayIns">arrayIns()</a></h3>
<p class="item_brief">Inserts an item into an array. </p>
<p class="faldoc_funcdecl">arrayIns( array, itempos, item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array where the item should be placed. </td></tr><tr><td class="faldoc_param">itempos</td><td class="faldoc_paramdesc">The position where the item should be placed. </td></tr><tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be inserted. The item is inserted before the given position. If pos is 0, the item is inserted in the very first position, while if it's equal to the array length, it is appended at the array tail. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="arrayMerge">arrayMerge()</a></h3>
<p class="item_brief">Merges two arrays. </p>
<p class="faldoc_funcdecl">arrayMerge( array1, array2, [insertPos], [start], [end] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array1</td><td class="faldoc_paramdesc">Array containing the first half of the merge, that will be modified. </td></tr><tr><td class="faldoc_param">array2</td><td class="faldoc_paramdesc">Array containing the second half of the merge, read-only </td></tr>
<tr><td class="faldoc_optparam">insertPos</td><td class="faldoc_optparamdesc">Optional position of array 1 at which to place array2 </td></tr><tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">First element of array2 to merge in array1 </td></tr><tr><td class="faldoc_optparam">end</td><td class="faldoc_optparamdesc">Last element – 1 of array2 to merge in array1 </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The items in array2 are appended to the end of array1, or in case an mergePos is specified, they are inserted at the given position. If mergePos is 0, they are inserted at beginning of array1, while if it's equal to array1 size they are appended at the end. An optional start parameter may be used to specify the first element in the array2 that must be copied in array1; if given, the parameter end will specify the last element that must be copied plus 1; that is elements are copied from array2 in array1 from start to end excluded. </p>
<p class="faldoc_text">The items are copied shallowly. This means that if an object is in array2 and it's modified thereafter, both array2 and array1 will grant access to the modified object. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayNM">arrayNM()</a></h3>
<p class="item_brief">Force an array to be non-method. </p>
<p class="faldoc_funcdecl">arrayNM( array )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">the array that should not be transformed into a method. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The same array passed as parameter. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Callable arrays stored in objects become methods when they are accessed. At times, this is not desirable. Suppose it is necessary to store a list of items, possibly functions, in an object, and that random access is needed. </p>
<p class="faldoc_text">In this case, an array is a good storage, but it's useful to tell Falcon that this array is never to be considered a method for the host object. Consider the following case: </p>
<pre class="faldoc_code">
class WithArrays( a )
asMethod = a
asArray= arrayNM( a.clone() ) // or a.clone().NM()
end
wa = WithArrays( [ printl, 'hello' ] )
// this is ok
for item in wa.asArray: > "Item in this array: ", item
// this will raise an error
for item in wa.asMethod: > "Item in this array: ", item
</pre>
<p class="faldoc_text">The array is cloned in this example as the function modifies the array itself, which becomes non-methodic, and returns it without copying it. So, if not copied, in this example also asMethod would have been non-methodic. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayRemove">arrayRemove()</a></h3>
<p class="item_brief">Removes one or more elements in the array. </p>
<p class="faldoc_funcdecl">arrayRemove( array, itemPos, [lastItemPos] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array from which items must be removed. </td></tr><tr><td class="faldoc_param">itemPos</td><td class="faldoc_paramdesc">The position of the item to be removed, or the first of the items to be removed. </td></tr>
<tr><td class="faldoc_optparam">lastItemPos</td><td class="faldoc_optparamdesc">The last item to be removed, in range semantic. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Remove one item or a range of items. The size of the array is shortened accordingly. The semantic of <b>lastItemPos</b> is the same as ranged access to the array. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayResize">arrayResize()</a></h3>
<p class="item_brief">Changes the size of the array. </p>
<p class="faldoc_funcdecl">arrayResize( array, newSize )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that will be resize. </td></tr><tr><td class="faldoc_param">newSize</td><td class="faldoc_paramdesc">The new size for the array. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the given size is smaller than the current size, the array is shortened. If it's larger, the array is grown up to the desired size, and the missing elements are filled by adding nil values. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayScan">arrayScan()</a></h3>
<p class="item_brief">Searches an array for an item satisfying arbitrary criteria. </p>
<p class="faldoc_funcdecl">arrayScan( array, func, [start], [end] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that will be searched. </td></tr><tr><td class="faldoc_param">func</td><td class="faldoc_paramdesc">Function that verifies the criterion. </td></tr>
<tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">Optional first element to be searched. </td></tr><tr><td class="faldoc_optparam">end</td><td class="faldoc_optparamdesc">Optional upper end of the range.. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The position of the searched item in the array, or -1 if not found. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">With this function, it is possible to specify an arbitrary search criterion. The items in the array are fed one after another as the single parameter to the provided scanFunc, which may be any Falcon callable item, including a method. If the scanFunc returns true, the scan is interrupted and the index of the item is returned. If the search is unsuccesful, -1 is returned. </p>
<p class="faldoc_text">An optional start parameter may be provided to begin searching from a certain point on. If also an end parameter is given, the search is taken between start included and end excluded (that is, the search terminates when at the element before the position indicated by end). </p>
<p class="faldoc_text">Scan function is called in atomic mode. The called function cannot be interrupted by external kind requests, and it cannot sleep or yield the execution to other coroutines. </p>
</p>
<h3 class="faldoc_funcname"><a name="arraySort">arraySort()</a></h3>
<p class="item_brief">Sorts an array, possibly using an arbitrary ordering criterion. </p>
<p class="faldoc_funcdecl">arraySort( array, [sortingFunc] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that will be searched. </td></tr>
<tr><td class="faldoc_optparam">sortingFunc</td><td class="faldoc_optparamdesc">A function used to compare two items. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function sorts the contents of the array so that the first element is the smaller one, and the last element is the bigger one. String sorting is performed lexicographically. To sort the data based on an arbitrary criterion, or to sort complex items, or objects, based on some of their contents, the caller may provide a sortFunc that will receive two parameters. The sortFunc must return -1 if the first parameter is to be considered smaller than the second, 0 if they are the same and 1 if the second parameter is considered greater. </p>
<p class="faldoc_text">Sort function is called in atomic mode. The called function cannot be interrupted by external kind requests, and it cannot sleep or yield the execution to other coroutines. </p>
</p>
<h3 class="faldoc_funcname"><a name="arrayTail">arrayTail()</a></h3>
<p class="item_brief">Extracts the last element of an array and returns it. </p>
<p class="faldoc_funcdecl">arrayTail( array )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">array</td><td class="faldoc_paramdesc">The array that will be modified. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The extracted item. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function removes the last item of the array and returns it. If the original array is empty, AccessError is raised. </p>
</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>
