Arrays - Petewg/harbour-core GitHub Wiki

🔙 Functions-by-category

• AAdd( <aArray>, <xValue> ) ➜ xValue
  adds an element to the end of <aArray> and assigns the value <xValue> to this new element.

• AClone( <aSource> ) ➜ aDuplicate
  duplicates an array. Works with multidimensional arrays.

• ACopy(<aSource>, <aTarget>, [<nStart>], [<nCount>], [<nTagetPos>]) ➜ aTarget
  copy elements from a source array into a target array. Operates only on one-dimensional arrays.

• ADel(<aArray>, <nPosition>) ➜ aArray
  deletes the element at position <nPosition> from the array <aArray>. All subsequent elements are shifted up by one position so that the last element contains the value NIL.
  See also hb_ADel() (below).

• hb_ADel(<aArray> [, <nPos>, <lAutoSize>]) ➜ aArray
  Deletes the value at position <nPos> of array <aArray> moving all the following values to the previous position. If <lAutoSize> is .T., then the last element is deleted and the size of the array is decreased by one, otherwise NIL will be stored in the last element of the array, as in 'ADel()'. Default values for optional parameters: <nPos> = 1, <lAutoSize> = .F.

• AEval(<aArray>, <bBlock>, [<nStart>], [<nCount>]) ➜ aArray
  Evaluates the <bBlock> for each <aArray> element, starting from <nStart> until <nCount> elements have been reached. Default values for <nStart>/<nCount> optional parameters: <nStart> = 1, <nCount> = Len( aArray ) (i.e. all elements).

• AFill(<aArray>, <xValue>, [<nStart>], [<nCount>]) ➜ aArray
  assigns the value of <xValue> to the <nCount> elements, beginning at position <nStart>. Multi-dimensional arrays cannot be filled using 'AFill()'. Default values for <nStart>/<nCount> optional parameters: <nStart> = 1, <nCount> = Len( aArray ) (i.e. all elements).

• AIns( <aArray>, <nPosition> ) ➜ aArray
  Inserts a new element at <nPosition> into the array <aArray>. All subsequent elements are shifted down by one position so that the last element is lost. The number of elements remain unchanged. See hb_AIns() which allows auto-sizing of array.
  See also hb_AIns() (below).

• hb_AIns(<aArray> [, <nPos>, <uValue>, <lAutoSize>] ) ➜ aArray
  Inserts <uValue> in the <nPos> position of the array, moving all the items to the next position. If <lAutoSize> is .T., a new element will be added, making room for the previous last element, else the size of <aArray> won't change and the last item of <aArray> will be lost. Default values for optional parameters: <nPos> = 1, <uValue> = NIL, <lAutoSize> = .F.

• Array( <nDim1> [, <nDimN,...>] ) ➜ aArray
  returns an array dimensioned according to the passed parameters. All elements of the array contain the value NIL.

• AScan( <aArray>, <xSearch>, [<nStart>], [<nCount>] ) ➜ nStoppedAt
  search into <aArray> for <xSearch> value starting from <nStart> up to <nCount>]. (default values are: nStart=1, nCount=All elements).
  returns the position of element that matches the searched value or 0 if no match is found.
  See also hb_AScan() (below).

• hb_AScan(<aArray>, <uValue> [, <nStart>, <nCount>, <lExact> ]) ➜ nPosition
  Scans (left to right) for <uValue> into <aArray> and returns nPosition of found or zero if nothing found. If <lExact> is given, overrides the _SET_EXACT setting. Case sensitive on string search.
  Note: In hb 3.4 (Viktor's fork) there is a hb_AScanI() which is same as hb_AScan() but with case-insensitive string comparison. See also hb_RAScan() (below).

• hb_RAScan( <aArray>, <uValue> [, <nStart>, <nCount>, <lExact>] ) ➜ nPosition
  scans (right to left) for <uValue> into <aArray> and returns <nPosition> of found or <zero> if nothing found.

• ASize(<aArray>, <nLength>) ➜ aArray
  dynamically increases or decreases the size of <aArray> to <nLength> elements. When the array is enlarged, new elements are added to the end of <aArray> and are initialized with NIL. When the number of elements is decreased, elements are removed from the end of <aArray and their values are lost. returns reference to sized array.

• ASort( <aArray>, [<nStart>], [<nCount>], [<bSort>] ) ➜ aArray
  sorts an array entirely or partially. If the code block <bSort> is omitted, the function expects <aArray> to be a one dimensional array containing simple data types.
  NOTES: 1) Sorting is case sensitive for character elements. 2) Logical value .F. is considered smaller than .T.

• ATail(<aArray>) ➜ xValue
  returns the value stored in the last element of <aArray>.

(also known as associative arrays and hash tables)

• hb_Hash([ <Key1>, <Value1> ], [ <KeyN>, <ValueN> ], ...) ➜ hTable
  Creates a hash table and, optionally, populates it with elements (pairs of keys and values).

  • keys can be of type: string, numeric, date, datetime, pointer
  • values can be of type: string, numeric, date/datetime, logical, array, hash table, pointer, block, NIL

  usage: hHash := hb_Hash( xkey1, xValue1, xKey2, xValue2, ..., xKeyN, xValueN )

  An alternative method to create/initialize a hash table, might be to use a direct in-line assignment like below:

     // create an empty hash table
     hHash := {=>}  
     // create & initialize a hash
     hHash := { 1 => "Apples", 2 => "Oranges", "D1" => 0d20180621 }

  This method is, apparently, the most recommended, since it helps out code clarity.

• hb_HAllocate( <hHash>, <nElements>)
  Pre-allocates space (memory) for <nElements> hash items. It's useful when you intend to add a set of new items because you will save time spent in grabbing each new element separately; preallocating elements may improve speed execution of program.
  Note: this function will not "truncate" or release (delete) items, if the <nElements> number is less than the actual item count already into the hash table.

• hb_HAutoAdd(<hHash>, [<lFlag>]) ➜ lPreviousFlag
  Sets the 'auto add' flag for the hash table.

• hb_HBinary(<hHash>, [<lFlag>]) ➜ lPreviousFlag
  Sets the 'binary' flag for the hash table.

• hb_HCaseMatch(<hHash>, [<lFlag>]) ➜ lPreviousFlag
  Sets the 'case match' flag for the hash table.

• hb_HClear(<hHash>) ➜ hHash
  Deletes all the elements in <hHash> leaving an empty hash table.

• hb_HClone(<hHash>) ➜ hsDestination
  Creates a copy of a hash table.

• hb_HCopy(<hsDestination>, <hsSource>, [<nStart>], [<nCount>]) ➜ hsDestination
  Adds entries from the source hash table to the destination hash table.

• hb_HDefault(<hHash>, <DefaultValue>) ➜ OldDefaultValye
  Sets the default value assinged to new keys in a hash table. Returns the previous default value (if any).

• hb_HDel(<hHash>, <xKey>) ➜ hHash
  Deletes the <xKey> key (as well as, its associated value) from the <hHash> hash table. If <xKey> doesn't exist then nothing happens, that is, <hHash> remains (and returned) unaltered.

  Important Note: Unlike a conventional array, after a successful deletion of an item (key/value pair), the hash table automatically shrinks and its total length decrements by one.

• hb_HDelAt(<hHash>, <nPosition>) ➜ hHash
  Removes (deletes) the item ('key,value' pair) found in <nPosition> (ordinal position) of the <hHash> table.
  Valid values for <nPosition> are in range 1 .. Len(hHash), which means that if <nPosition> is zero or greater than the length of hash, an RTE (Bound error: array assign) occurs.

• hb_HEval(<hHash>, <bBlock>, [<nStart>], [<nCount>]) ➜ hHash
  evaluates a code block across the contents of a hash table. It is similar to AEval() function but applied on hashes instead of plain arrays.

• hb_HFill(<hHash>, <Value>) ➜ hHash
  sets the values of all the keys of <hHash> table to <xValue>.

• hb_HGet(<hHash>, <Key>) ➜ xValue
  retrieves the value associated to <Key> key.
  Hint: use hb_HGetDef() instead of this function, to avoid RTE when the <Key> key doesn’t exist/found in <hHash>.

• hb_HGetDef(<hHash>, <Key>, [<DefaultValue>]) ➜ xValue|NIL
  returns either the value associated to the given <Key> key into <hHash> hash table, or the default value <DefaultValue> if the <Key> doesn’t exist.
  It returns NIL when both the <Key> doesn't exist and no <DefaultValue> has specified.

• hb_HGetRef(<hHash>, <xKey>, [ @<xValue> ]) ➜ .T.|.F.
  returns .T. if <xKey> exists.
  Optionally stores its associated key-value to @<xValue> which must be passed by reference.
  If the key is not found, the function returns .F. and the <xValue> becomes NIL.

• hb_HHasKey(<hHash>, <xKey> [, @<nPos> ]) ➜ lExists
  returns .T. if <xKey> exists in the hash table and optionaly stores its ordinal position to @<nPos> which must be passed by reference to retain the stored position.
  If the key doesn’t exists then <nPos> will be the position of the smaller nearest key.

• hb_HKeepOrder(<hHash> [ , <lKeepOrder> ]) ➜ lPrevKeepOrder
  Sets the KEEPORDER flag in a hash and returns the previous state. This flag controls the order by which the elements are stored in the hash table. If the KEEPORDER flag is .T. then the order by which the elements are created or added will be preserved. If it is .F., then the elements of the hash table will be sorted (other flags may affect the order such as the BINARY flag, the CASEMATCH flag, etc). This flag is enabled (.T.) by default.

• hb_HKeyAt(<hHash>, <nPosition>) ➜ xKey
  Retrieves the key at a given position in a hash table. The <nPosition> value must be in the range 1...Len( hHash ). If hash table is empty or <nPosition> is zero or greater than Len( hHash ) then a "Bound error" RTE (runtime error) occurs .

• hb_HKeys(<hHash>) ➜ aKeys
  returns an array with all the keys (but not the associated values) of a hash table.

• hb_HMerge(<hsDestination>, <hsSource>, <bBlock>|<nMethod>) ➜ hsDestination
  Merges <hsSource> hash into <hsDestination> hash. With the 3rd parameter can be optionally specified the merge mode. When source elements copied will substitute those with the same key in the destination hash table.

• hb_HPairAt(<hHash>, <nPosition>) ➜ aKeyValue
  returns a two-dimensional array of the key/value pair entry of the hash table.

• hb_HPos(<hHash>, <Key>) ➜ nPosition
  returns the position of <xKey> in the hash.

• hb_HScan(<hHash>, <uValue>|<bBlock> [, <nStart>, <nCount>], <lExact>) ➜ nPosition
  Scans the hash table values searching for <uValue>, or you can pass a codeblock <bBlock> that receives the key, the value and the position of each element, and should return .T. if a match is found. The range of hash table items to be scanned can be limited by the <nStart> and <nCount> parameters.
  The logical flag <lExact> determines if exact matching (or not) will be applied when searching for strings or datetime or array or hashes.

• hb_HSet(<hHash>, <xKey>, <xValue>) ➜ hHash
  Sets or adds a key/value pair into <hHash> hash table as follows:

  • If the <xKey> exists then its value is replaced by <xValue>, the length of hash remains unchanged.
  • If the <xKey> does not exist then a new pair (key,value) is added to <hHash>, hence it's length increases by one (in this case, function is similar to AAdd() function used on arrays).

• hb_HSort(<hHash>) ➜ hHash
  Marks <hHash> hash for sorting. BINARY and CASEMATCH flags will affect the result.

• hb_HValueAt(<hHash>, <nPosition>, [<xNewValue>]) ➜
  Returns the value associated to the key at a given position in a hash table. Optionally, you can set the new value <xNewValue> associated to the key at that position.

• hb_HValues(<hHash>) ➜ aValues
  returns an array with all the associated values (but not the keys) of a hash table.

Note: For detailed documentation about Harbour hashes see also: Juan Gamero's site

🔙 Functions-by-category