ASort()

Posted on January 7, 2014 by vivaclipper

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

Posted on January 7, 2014 by vivaclipper

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

Posted on January 7, 2014 by vivaclipper

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

Posted on January 7, 2014 by vivaclipper

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

Posted on January 7, 2014 by vivaclipper

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

Posted on January 7, 2014 by vivaclipper

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

Posted on January 7, 2014 by vivaclipper

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

ADel()

Posted on January 7, 2014 by vivaclipper

ADEL()

Delete an element form an array.

Syntax

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

Arguments

<aArray> Name of array from which an element is to be removed.

<nPos> Subscript of the element to be removed.

Returns

<aTarget> an array pointer reference.

Description

This function deletes the element found at <nPos> subscript position in the array <aArray>. All elements in the array <aArray> below the given subscript position <nPos> will move up one position in the array. In other words, what was formerly the sixth subscript position will become the fifth subscript position. The length of the array <aArray> will remain unchanged, as the last element in the array will become a NIL data type.

Examples

      LOCAL aArray := { "Harbour", "is", "Power" }
      ADel( aArray, 2 ) // Result: aArray is { "Harbour", "Power" }

Compliance

Clipper

Files

Library is vm

Seealso

ACOPY(), AINS(), AFILL()

ACopy()

Posted on January 7, 2014 by vivaclipper

ACOPY()

Copy elements from one array to another

Syntax

      ACOPY( <aSource>, <aTarget>, [<nStart>], [<nCount>], [<nTargetPos>] ) --> aTarget

Arguments

<aSource> is the array to copy elements from.

<aTarget> is the array to copy elements to.

<nStart> is the beginning subscript position to copy from <aSource>

<nCount> the number of subscript elements to copy from <aSource>.

<nTargetPos> the starting subscript position in <aTarget> to copy elements to.

Returns

<aTarget> an array pointer reference

Description

This function copies array elements from <aSource> to <aTarget>.

<nStart> is the beginning element to be copied from <aSource>; the default is 1.

<nCount> is the number of elements to be copied from <aSource>; the default is the entire array.

<nTargetPos> is the subscript number in the target array, <aTarget>, to which array elements are to be copied; the default is 1

This function will copy all data types in <aSource> to <aTarget>.

If an array element in <aSource> is a pointer reference to another array, that array pointer will be copied to <aTarget>; not all subdimensions will be copied from one array to the next. This must be accomplished via the ACLONE() function.

Note: If array <aSource> is larger then <aTarget>, array elements will start copying at <nTargetPos> and continue copying until the end of array <aTarget> is reached. The ACOPY() function doesn’t append subscript positions to the target array, the size of the target array <aTarget> remains constant.

Examples

      LOCAL nCount := 2, nStart := 1, aOne, aTwo
      aOne := { "HARBOUR", " is ", "POWER"}
      aTwo := { "CLIPPER", " was ", "POWER"}
      ACopy( aOne, aTwo, nStart, nCount )

Compliance

Clipper

Files

Library is vm

Seealso

ACLONE(), ADEL(), AEVAL(), AFILL(), AINS(), ASORT()

AClone()

Posted on January 7, 2014 by vivaclipper

ACLONE()

Duplicate a multidimensional array

Syntax

      ACLONE(<aSource>) --> aDuplicate

Arguments

<aSource> Name of the array to be cloned.

Returns

<aDuplicate> A new array pointer reference complete with nested array values.

Description

This function makes a complete copy of the array expressed as <aSource> and return a cloned set of array values. This provides a complete set of arrays values for all dimensions within the original array <aSource>

Examples

      LOCAL aOne, aTwo
      aOne := { "Harbour"," is ","POWER" }
      aTwo := AClone( aOne )       // Result: aTwo is {"Harbour"," is ","POWER"}
      aOne[ 1 ] := "The Harbour Compiler"
      // Result:
      // aOne is { "The Harbour Compiler", " is ", "POWER" }
      // aTwo is { "Harbour"," is ","POWER" }

Compliance

CA-Cl*pper will return NIL if the parameter is not an array.

Files

Library is vm

Seealso

ACOPY(), ADEL(), AINS(), ASIZE()

M	T	W	T	F	S	S
		1	2	3	4	5
6	7	8	9	10	11	12
13	14	15	16	17	18	19
20	21	22	23	24	25	26
27	28	29	30	31

Viva Clipper !

Notes of a Clipper Language Student

Daily Archives: January 7, 2014

ASort()

ASORT()

ASize()

ASIZE()

AScan()

ASCAN()

Array()

ARRAY()

AIns()

AINS()

AFill()

AFILL()

AEval()

AEVAL()

ADel()

ADEL()

ACopy()

ACOPY()

AClone()

ACLONE()

ASORT()

Rate this:

ASIZE()

Rate this:

ASCAN()

Rate this:

ARRAY()

Rate this:

AINS()

Rate this:

AFILL()

Rate this:

AEVAL()

Rate this:

ADEL()

Rate this:

ACOPY()

Rate this:

ACLONE()

Rate this: