Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups

Function set core_array_funcs

Array related functions.


Function list

arrayAdd Adds an element to an array.
arrayBuffer Creates an array filled with nil items.
arrayCopy Adds an element to an array.
arrayDel Deletes the first element matching a given item.
arrayDelAll Deletes all the occurrences of a given item in an array.
arrayFilter Filters an array using a given function.
arrayFind Searches for a given item in an array.
arrayHead Extracts the first element of an array and returns it.
arrayIns Inserts an item into an array.
arrayMap Maps an array using a given function.
arrayMerge Merges two arrays.
arrayRemove Removes one or more elements in the array.
arrayResize Changes the size of the array.
arrayScan Searches an array for an item satisfying arbitrary criteria.
arraySort Sorts an array, possibly using an arbitrary ordering criterion.
arrayTail Extracts the last element of an array and returns it.

Functions

arrayAdd()

Adds an element to an array.

arrayAdd( array, element )
array

The array where to add the new item.

element

The item to be added.

The element will be added at the end of the array, and its size will be increased by one.

arrayBuffer()

Creates an array filled with nil items.

arrayBuffer( size )
size

The length of the returned array.

Returns:

An array filled with size nil elements.

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

arrayCopy()

Adds an element to an array.

arrayCopy( array, [start], [end] )
array

The original array.

start

If given, the first element from where to copy.

end

If given, one-past-last element to be copied.

Returns:

A shallow copy of the array or of part of it.

Actually, this function calls the range-access operator with a complete interval ([:]) if neither start or end are given, an open interval ([start:]) if only start is given and a full range if both start and end are given. This means that the range operation rules apply 1:1 to this function. If end is smaller than start, the copy order is reversed, and if they are the same, an empty array is created. The end parameter, if given, must be one past the last element to be copied; so:

    ret = arrayCopy( source, 5, 6 )

will create an array containing only the element at position 5 in the source array.

arrayDel()

Deletes the first element matching a given item.

arrayDel( array, item )
array

The array that is to be changed.

item

The item that must be deleted.

Returns:

true if at least one item has been removed, false otherwise.

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.

Only the first item matching the given one will be deleted.

arrayDelAll()

Deletes all the occurrences of a given item in an array.

arrayDelAll( array, item )
array

The array that is to be changed.

item

The item that must be deleted.

Returns:

true if at least one item has been removed, false otherwise.

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.

arrayFilter()

Filters an array using a given function.

arrayFilter( array, filterFunc, [start], [end] )
array

The array to be filtered.

filterFunc

A function to filter the array

start

Optional first element to be filtered.

end

Optional last element +1 to be filtered.

Returns:

an array with some of the items removed.

This function perform what is usually defined a “filtering” of the source structure into a target array. The filterFunc parameter is a user-provide callable item that will be called once for each item in the specified array range; if the function returns a true value, the item is copied in the returned array, otherwise it is ignored. The filter function may actually be any kind of callable, including methods, Sigmas and external functions.

In case the function never returns true, an empty array is returned.

A start-end range may optionally be specified to limit the filtering to a part of the array. As for other functions in this module, the range will cause filtering for the items from start to end-1.

The filter 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.

Note: This function is superseeded by filter and may be removed in future versions.

arrayFind()

Searches for a given item in an array.

arrayFind( array, item, [start], [end] )
array

The array that will be searched.

item

The array that will be searched.

start

Optional first element to be searched.

end

Optional last element +1 to be searched.

Returns:

The position of the searched item in the array, or -1 if not found.

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.

An optional range may be specified to limit the search in the interval start included, end excluded.

arrayHead()

Extracts the first element of an array and returns it.

arrayHead( array )
array

The array that will be modified.

Returns:

The extracted item.

This function removes the first item of the array and returns it. If the original array is empty, AccessError is raised.

arrayIns()

Inserts an item into an array.

arrayIns( array, itempos, item )
array

The array where the item should be placed.

itempos

The position where the item should be placed.

item

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.

arrayMap()

Maps an array using a given function.

arrayMap( array, mapFunc, [start], [end] )
array

The array to be mapped.

mapFunc

A function to map the array

start

Optional first element to be filtered.

end

Optional last element +1 to be filtered.

Returns:

An array built mapping each item in array.

This function perform what is usually defined a “mapping” of the source array. The mapFunc parameter is a user-provide callable item that will be called once for each item in the specified array range; The value returned by the function will be appended in the returned array.

A start-end range may optionally be specified to limit the mapping to a part of the array. As for other functions in this module, the range will cause mapping for the items from start to end-1.

The mapping 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.

Note: This function is superseeded by map and may be removed in future versions.

arrayMerge()

Merges two arrays.

arrayMerge( array1, array2, [insertPos], [start], [end] )
array1

Array containing the first half of the merge, that will be modified.

array2

Array containing the second half of the merge, read-only

insertPos

Optional position of array 1 at which to place array2

start

First element of array2 to merge in array1

end

Last element – 1 of array2 to merge in array1

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.

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 objec

arrayRemove()

Removes one or more elements in the array.

arrayRemove( array, itemPos, [lastItemPos] )
array

The array from which items must be removed.

itemPos

The position of the item to be removed, or the first of the items to be removed.

lastItemPos

The last item to be removed + 1

Remove one item or a range of items. The size of the array is shortened accordingly.

arrayResize()

Changes the size of the array.

arrayResize( array, newSize )
array

The array that will be resize.

newSize

The new size for the array.

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.

arrayScan()

Searches an array for an item satisfying arbitrary criteria.

arrayScan( array, scanFunc, [start], [end] )
array

The array that will be searched.

scanFunc

Function that verifies the criterion.

start

Optional first element to be searched.

end

Optional upper end of the range..

Returns:

The position of the searched item in the array, or -1 if not found.

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.

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

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.

arraySort()

Sorts an array, possibly using an arbitrary ordering criterion.

arraySort( array, [sortingFunc], [start], [end] )
array

The array that will be searched.

sortingFunc

A function used to compare two items.

start

Optional first element to be searched.

end

Optional upper end of the range..

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.

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.

arrayTail()

Extracts the last element of an array and returns it.

arrayTail( array )
array

The array that will be modified.

Returns:

The extracted item.

This function removes the last item of the array and returns it. If the original array is empty, AccessError is raised.


Index  |  Related pages  |  Classes  |  Functions  |  Entities  |  Function Sets  |  Groups
Made with Faldoc 1.0.0