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 !

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

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

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

 

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

 

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

 

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

 

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

 

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

SP_SGETMANY

SGETMANY()

  Short:
  ------
  SGETMANY()    Virtual (scrolling)  gets in a popup box

  Returns:
  --------
  <lSave> => False if ESC pressed, true otherwise

  Syntax:
  -------
  SGETMANY(aGets,aDesc,nTop,nLeft,nBottom,nRight,[cTitle],[cFoot],[nPadding])

  Description:
  ------------
  READs a series of GETs in a popup box, with the
  ability to scroll the GETs up/down when there are more GETs than fit in
  the box.

  <aGets> is an array of get objects. There are two
  ways to create this:

      1.    Use GETNEW() (the Clipper function) to create each
            individual get object. Get row and column do not
            matter - they will be adjusted.

            GET postblock and preblock (valid and when)
            may be assigned as normal. As each new GET object is created,
            add it to an array.

            Pass this array as <aGets>.

      2.    Use the normal @row,col GET... commands, but to a
            location off the screen - otherwise the gets will DISPLAY
            as you are assigning them.

            @MAXROW()+1,MAXCOL()+1 GET... works for me.

  Using @...GET automatically places new get
  objects in the global array GETLIST. Pass GETLIST as <aGets>.

  <aDesc> this is an array of descriptions for each
  get. (the SAY portion). These will be displayed to the left of
  the get.

  <nTop,nLeft,nBottom,nRight> are the dimensions of the
  popup box. The Editing area will be the inside dimensions of this
  box. Make sure there's room!

  [cTitle] is a string to be used for the title.
  Displayed at <nTop>,<nLeft>+1

  [cFoot] is now ignored. This parameter used to be the footer. It
  is now just a placeholder for downward compatibility.

  [nPadding] is for the number of spaces of padding
  between the box frame and the editing area. The default is 0,
  which places the editing area at
  nTop+1,nLeft+1,nBottom-1,nRight-1. A [nPadding] of 1 would place
  the editing area at nTop+2,nLeft+2,nBottom-2,nRight-2 etc.

  Examples:
  ---------

   local i
   local aDesc := {}
   local aGets
   USE CUSTOMER
   aGets := dbf2array()

   for i = 1 to len(aGets)
     @maxrow()+1,maxcol()+1 get aGets[i]
     aadd(aDesc,field(i))
   next

   SGETMANY(getlist,aDesc,10,10,17,50,;
         "Editing","ESC quits, F10 saves",1)

  NOTES:
  -------
  Do not pass a 0 length string as a GET

  Source:
  -------
  S_GETMANY.PRG

---