How I can insert a new …

How I can insert  a new item to an array ?

Short answer : We have a special function : AIns()
Long Answer :

AIns() function may cause some confusions when documentation not read carefully:

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.

 

Let’s try:

 aTest := { 'One', 'Two', 'Four' }
 AIns( aTest, 3 ) 
 AEVAL( aTest, { | c1 | QQOUT( c1, '' ) } ) 
 

Result : One Two NIL: “Four” lost !

Since it’s NIL, we can assign a value to it:

 aTest := { 'One', 'Two', 'Four' }
 AIns( aTest, 3 )
 aTest[ 3 ] := "Three"
 AEVAL( aTest, { | c1 | QQOUT( c1, '' ) } ) 
 

Result : One Two Three: “Four” lost !

Before insert we can add a dummy item to end of array:

 aTest := { 'One', 'Two', 'Four' }
 AADD( aTest, NIL )
 AIns( aTest, 3 )
 aTest[ 3 ] := "Three"
 AEVAL( aTest, { | c1 | QQOUT( c1, '' ) } ) 
 

Result : One Two Three Four : OK
Or we can change size of array :

 aTest := { 'One', 'Two', 'Four' }
 ASIZE( aTest, 4 )
 AIns( aTest, 3 )
 aTest[ 3 ] := "Three"
 AEVAL( aTest, { | c1 | QQOUT( c1, '' ) } ) 
 

Result : One Two Three Four : OK

But wait; we have another possibility: a new Harbour function:

 aTest := { 'One', 'Two', 'Four' }
 HB_AIns( aTest, 3, "Three" )
 AEVAL( aTest, { | c1 | QQOUT( c1, '' ) } ) 

Result : One Two Three: “Four” lost !

And we have a fourth parameter : Grow or not:

 aTest := { 'One', 'Two', 'Four' }
 HB_AIns( aTest, 3, "Three", .T. )
 AEVAL( aTest, { | c1 | QQOUT( c1, '' ) } ) 
 

Result : One Two Three Four

That’s all !

Advertisements

Harbour All Functions – A

AAdd
Abs
AChoice
AClone
ACopy
ACos

ADays
AddASCII
AddMonth
ADel
ADir
AfterAtNum
AEval
AFields
AFill
AIns
Alert
Alias
AllTrim

AMonths
Array
Asc
AScan
ASCIISum
ASCPos
ASin
ASize
ASort
At
AtAdjust
ATail
ATan
ATn2
AtNum
AtRepl
AtToken

Harbour Array Functions

Array Functions

AAdd Dynamically add an element to an array
AClone Duplicate an array
ACopy Copy elements from one array to another
ADel Delete an element form an array
AEval Evaluates the subscript element of an array
AFill Fill an array with a specified value
AIns Insert a NIL value at an array subscript position
Array Build an uninitialized array of specified length
AScan Scan array elements for a specified condition
ASize Adjust the size of an array
ASort Sort an array
ATail Returns the rightmost element of an array

Len()

LEN()

Returns size of a string or size of an array.

Syntax

      LEN( <cString> | <aArray> ) --> <nLength>

Arguments

<acString> is a character string or the array to check.

Returns

The length of the string or the number of elements that contains an array.

Description

This function returns the string length or the size of an array or the size of a hash table. If it is used with a multidimensional array it returns the size of the first dimension.

Examples

      ? LEN( "Harbour" )           // 7
      ? LEN( { "One", "Two" } )    // 2

Tests

      PROCEDURE Test()
         LOCAL cName := ""
         ACCEPT "Enter your name: " TO cName
         ? LEN( cName )
         RETURN

Compliance

Clipper

Files

Library is rtl

Seealso

EMPTY(), RTRIM(), LTRIM(), AADD(), ASIZE()

ATail()

 

ATAIL()

Returns the rightmost element of an array

Syntax

      ATAIL( <aArray> ) --> Element

Arguments

<aArray> is the array.

Returns

<Element> the expression of the last element in the array.

Description

This function return the value of the last element in the array named <aArray>. This function does not alter the size of the array or any of the subscript values.

Examples

      LOCAL aArray := { "Harbour", "is", "Supreme", "Power" }
      ? ATail( aArray ) // Result is "Power"

Compliance

Clipper

Files

Library is vm

Seealso

LEN(), ARRAY(), ASIZE(), AADD()

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

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