ASort()

 

ASORT()

Sort an array

Syntax

      ASORT( <aArray>, [<nStart>], [<nCount>], [<bSort>] ) --> aArray

Arguments

<aArray> Array to be sorted.

<nStart> The first element to start the sort from, default is 1.

<nCount> Number of elements starting from <nStart> to sort, default is all elements.

<bSort> Code block for sorting order, default is ascending order {| x, y | x < y }. The code block should accept two parameters and must return .T. if the sort is in order, .F. if not.

Returns

<aArray> reference to the now sorted <aArray> or NIL if the passed <aArray> is not an array.

Description

ASORT() sort all or part of a given array. If <bSort> is omitted, the function expect <aArray> to be one dimensional array containing single data type (one of: Character, Date, Logical, Numeric) and sort this array in ascending order: Character are sorted by their ASCII value, Dates are sorted chronologically, Logical put .F. values before .T., Numeric are sorted by their value.

If <bSort> is specified, it is used to handle the sorting order. With each time the block is evaluate, two array elements are passed to the code block, and <bSort> must return a logical value that state if those elements are in order (.T.) or not (.F.). Using this block you can sort multidimensional array, descending orders or even (but why would you want to do that) sort array that contain different data type.

Examples

      // sort numeric values in ascending order
      ASort( { 3, 1, 4, 42, 5, 9 } )     // result: { 1, 3, 4, 5, 9, 42 }

      // sort character strings in descending lexical order
      aKeys := { "Ctrl", "Alt", "Delete" }
      bSort := {| x, y | Upper( x ) > Upper( y ) }
      ASort( aKeys,,, bSort )      // result: { "Delete", "Ctrl", "Alt" }

      // sort two-dimensional array according to 2nd element of each pair
      aPair := { { "Sun", 8 }, { "Mon", 1 }, { "Tue", 57 }, { "Wed", -6 } }
      ASort( aPair,,, {| x, y | x[ 2 ] < y[ 2 ] } )
      // result: { { "Wed", -6 }, { "Mon", 1 }, { "Sun", 8 }, { "Tue", 57 } }

Compliance

Clipper (arrayblock)

Files

Library is vm

Seealso

ASCAN(), EVAL(), SORT

ASize()

 

ASIZE()

Adjust the size of an array

Syntax

      ASIZE(<aArray>, <nLen>) --> aTarget

Arguments

<aArray> Name of array to be dynamically altered

<nLen> Numeric value representing the new size of <aArray>

Returns

<aTarget> an array pointer reference to <aTarget>.

Description

This function will dynamically increase or decrease the size of <aArray> by adjusting the length of the array to <nLen> subscript positions.

If the length of the array <aArray> is shortened, those former subscript positions are lost. If the length of the array is lengthened a NIL value is assigned to the new subscript position.

Examples

      LOCAL aArray := { 1 }      // Result: aArray is { 1 }
      ASize( aArray, 3 )         // Result: aArray is { 1, NIL, NIL }
      ASize( aArray, 1 )         // Result: aArray is { 1 }

Compliance

If HB_COMPAT_C53 is defined, the function generates an Error, else it will return the array itself.

Files

Library is vm

Seealso

AADD(), ADEL(), AFILL(), AINS()

AScan()

 

ASCAN()

Scan array elements for a specified condition

Syntax

      ASCAN( <aTarget>, <xSearch>, [<nStart>], [<nCount>] ) --> nStoppedAt

Arguments

<aTarget> Array to be scanned.

<xSearch> Expression to search for in <aTarget>

<nStart> Beginning subscript position at which to start the search.

<nCount> Number of elements to scan with <aTarget>.

Returns

<nStoppedAt> A numeric value of subscript position where <xSearch> was found, or 0 if <xSearch> is not found.

Description

This function scan the content of array named <aTarget> for the value of <xSearch>. The return value is the position in the array <aTarget> in which <xSearch> was found. If it was not found, the return value will be 0.

If specified, the beginning subscript position at which to start scanning may be set with the value passed as <nStart>. The default is 1.

If specified, the number of array elements to scan may be set with the value passed as <nCount>. The default is the number of elements in the array <aTarget>.

If <xSearch> is a code block, the operation of the function is slightly different. Each array subscript pointer reference is passed to the code block to be evaluated. The scanning routine will continue until the value obtained from the code block is a logical true (.T.) or until the end of the array has been reached.

Examples

      LOCAL aDir := Directory( "*.prg" )
      AScan( aDir,,, {| x, y | x[ 1 ] := "test.prg" } )

Compliance

This function is not CA-Cl*pper compatible. CA-Cl*pper ASCAN() is affected by the SET EXACT ON/OFF Condition

Files

Library is vm

Seealso

AEVAL()

Array()

 

ARRAY()

Create an uninitialized array of specified length

Syntax

      ARRAY( <nElements> [, <nElements>...] ) --> aArray

Arguments

<nElements> is the number of elements in the specified dimension.

Returns

<aArray> an array of specified dimensions.

Description

This function returns an uninitialized array with the length of <nElements>.

Nested arrays are uninitialized within the same array pointer reference if additional parameters are specified.

Establishing a memory variable with the same name as the array may destroy the original array and release the entire contents of the array. This depends, of course, on the data storage type of either the array or the variable with the same name as the array.

Examples

      PROCEDURE Main()
         LOCAL aArray := Array( 10 )
         LOCAL x
         FOR x := 1 TO Len( aArray )
            aArray[ x ] := Array( x )
         NEXT
         // Result is: { { NIL }, { NIL, NIL }, ... }
         RETURN

Compliance

Clipper (array)

Files

Library is vm

Seealso

AADD(), ADEL(), AFILL(), AINS()

AIns()

 

AINS()

Insert a NIL value at an array subscript position.

Syntax

      AINS( <aArray>, <nPos> ) --> aTarget

Arguments

<aArray> Array name.

<nPos> Subscript position in <aArray>

Returns

<aTarget> an array pointer reference.

Description

This function inserts a NIL value in the array named <aArray> at the <nPos>th position.

All array elements starting with the <nPos>th position will be shifted down one subscript position in the array list and the last item in the array will be removed completely. In other words, if an array element were to be inserted at the fifth subscript position, the element previously in the fifth position would now be located at the sixth position. The length of the array <aArray> will remain unchanged.

Examples

      LOCAL aArray := { "Harbour", "is", "Power!", "!!!" }
      AIns( aArray, 4 )

Compliance

Clipper

Files

Library is vm

Seealso

AADD(), ACOPY(), ADEL(), AEVAL(), AFILL(), ASIZE()

AFill()

 

AFILL()

Fill an array with a specified value

Syntax

      AFILL( <aArray>, <xValue>, [<nStart>], [<nCount>] ) --> aTarget

Arguments

<aArray> Name of array to be filled.

<xValue> Expression to be globally filled in <aArray>

<nStart> Subscript starting position

<nCount> Number of subscript to be filled

Returns

<aTarget> an array pointer.

Description

This function will fill each element of an array named <aArray> with the value <xValue>. If specified, <nStart> denotes the beginning element to be filled and the array elements will continue to be filled for <nCount> positions. If Not specified, the value of <nStart> will be 1, and the value of <nCount> will be the value of LEN(<aArray>); thus, all subscript positions in the array <aArray> will be filled with the value of <xValue>.

This function will work on only a single dimension of <aArray>. If there are array pointer references within a subscript <aArray>, those values will be lost, since this function will overwrite those values with new values.

Examples

      LOCAL aTest := { NIL, 0, 1, 2 }
      AFill( aTest, 5 )

Compliance

Clipper

Files

Library is vm

Seealso

AADD(), AEVAL(), DBSTRUCT(), DIRECTORY()

AEval()

AEVAL()

Evaluates the subscript element of an array

Syntax

      AEVAL(<aArray>, <bBlock>, [<nStart>], [<nCount>]) --> aArray

Arguments

<aArray> Is the array to be evaluated.

<bBlock> Is a code block to evaluate for each element processed.

<nStart> The beginning array element index to evaluate.

<nCount> The number of elements to process.

Returns

<aArray> an array pointer reference.

Description

This function will evaluate and process the subscript elements in <aArray>. A code block passed as <bBlock> defines the operation to be executed on each element of the array. All elements in <aArray> will be evaluated unless specified by a beginning subscript position in <nStart> for <nCount> elements.

Two parameters are passed to the code block <bBlock>. The individual elements in an array are the first parameter and the subscript position is the second.

AEVAL() does not replace a FOR…NEXT loop for processing arrays. If an array is an autonomous unit, AEVAL() is appropriate. If the array is to be altered or if elements are to be reevaluated, a FOR…NEXT loop is more appropriate.

Compliance

Clipper

Files

Library is vm

Seealso

EVAL(), DBEVAL()