SP_A2TOSING

 A2TOSING()

  Short:
  ------
  A2TOSING() Copies a given element from an array of arrays

  Returns:
  --------
  <aSingle> => a single dimensioned array

  Syntax:
  -------
  A2TOSING(a2Dim,nElement)

  Description:
  ------------
  Copies a given element position from a 2 dimensioned
  array of arrays into a single dimensioned array. <a2dim> is the
  source 2 dimensioned array. <nElement> is the element position
  within each sub-array to copy.

  Examples:
  ---------
  Both DBSTRUCT() and DIRECTORY() are good examples.
  Each return an array of arrays. DBSTRUCT() for instance, returns
  the structure of the current database file in an array whose
  length is equal to the number of fields in the database file.
  Each element of the array is a subarray containing information
  for one field.  The subarrays have the following format:

        { fieldname, fieldtype, fieldlength,fielddecimals}

  To extract a single dimensioned array of, say, the
  field names, you could use A2TOSING() with
  A2TOSING(DBSTRUCT(),1). For the field types you would use
  A2TOSING(DBSTRUCT(),2), etc.

  Here is an example with DIRECTORY()

   aDir         := DIRECTORY()
   aNames       := A2TOSING(adir,1)
   nWhichFile   := mchoice(aNames,10,10,20,20,"Which File?")

  Source:
  -------
  S_AFTYPE.PRG
Advertisements

[ ] Array element indicator

 


 [ ]
 Array element indicator                         (Special)
------------------------------------------------------------------------------
 Syntax

     <aArray>[<nSubscript>, ... ]
     <aArray>[<nSubscript1>][<nSubscript2>] ...

 Operands

     <aArray> is an expression that returns a reference to an array.
     This is generally a variable identifier or instance variable.

     <nSubscript> is a numeric expression that addresses an individual
     element in the specified array or subarray.  Each subscript corresponds
     to a dimension of the array.

 Description

     The subscript operator ([]) specifies a single array element.  The name
     of a previously declared array must precede the left bracket and the
     array element subscript must appear as a numeric expression within the
     brackets.  You can make array element references using Pascal or C-style
     syntax.

 Examples

     .  This example accesses each element in a two-dimensional array
        of known dimensions:

        LOCAL i, j
        FOR i := 1 TO 5
           FOR j := 1 TO 10
              ? aOne[i, j]
           NEXT
        NEXT

     .  These examples specify an <aArray> expression:

        LOCAL aArray := { 1, 2, 3, 4, 5 }
        //
        ? ArrayFunc()[2]                     // Result: 2
        ? { {1, 2}, {3, 4} }[1][2]           // Result: 2
        ? aArray[5]                          // Result: 5

        FUNCTION ArrayFunc
           STATIC aArray := { 1, 2 }
           RETURN aArray

     .  This example queries and assigns a static array encapsulated
        within a function definition:

        ? ArrayFunc()[1]                     // Result: 1
        ArrayFunc()[1] := 10
        ? ArrayFunc()[1]                     // Result: 10

        FUNCTION ArrayFunc
           STATIC aArray := { 1, 2 }
           RETURN aArray

See Also: ARRAY() LOCAL PRIVATE PUBLIC STATIC

Multi-Dimensional Arrays

Since elements of an array may be any data type, may be also an array. And when any element of an array is an array, it called multi-dimensional array.

As cited in array-basics, multi-dimensional array too subscripted like single dimension array. Only difference is specifying separate subscript for each dimension. This is correct for both defining and retrieving.

For example:

aArray2D := ARRAY( 2, 3 )
? HB_ValToExp( aArray2D )  // {{NIL, NIL, NIL}, {NIL, NIL, NIL}}
aArray2D := { { 1, 2, 3 }, { 4, 5, 6 } }
? HB_ValToExp( aArray2D )  // {{1, 2, 3}, {4, 5, 6}}

A multi-dim array doesn’t have to be “uniform”; any element of an array may be an array :

aArrMDim := { 1, "One", DATE(), .T., { 1, 2, 3, 4 } }
? HB_ValToExp(aArrMDim )  // {1, "One", 0d20130108, .T., {1, 2, 3, 4}}

In such case we can’t talk about aArrMDim[ 1, 1 ], aArrMDim[ 3, 2 ], … only aArrMDim[ 5, 1 ], aArrMDim[ 5, 2 ], …

Since fifth element of aArrMDim is a array, we can any array operation on it:

ASIZE( aArrMDim[ 5 ], 2 )
? HB_ValToExp(aArrMDim[ 5 ] )  // {1, 2}
? LEN( aArrMDim[ 5 ] )         // 2

Language doesn’t enforce any rules on what can be stored in an array; this level of control must be implemented programmatically.

The fact that you can assign an array ( or any data type else ) to an existing array element allows you to dynamically change structure of an array. For example, after an array built there is nothing prevent you from doing something like this:

aArrMDim[ 2 ] := { 2.5, 5.75, 3.14 }

This statement change second element of array from string to array. Now, aArrMDim[ 2, 3 ], aArrMDim[ 5, 3 ] are valid, but aArrMDim[ 3, 1 ] result a runtime error.

This feature of assigning an array reference to an array element can come in handy in lot of applications. The thing to remember is that you as the programmer must exercise whatever control you think is necessary for storing and addressing array elements. You cannot make any assumption about the structure of an array unless you enforce that structure.

PROCEDURE Main()
   ?
   ? "Multi-dim arrays :"
   ?

   aArray2D := ARRAY( 2, 3 )
   ShowValue( aArray2D, "two-dim"  )
   Show2DArr( aArray2D )

   aArray2D := { { 1, 2, 3 }, { 4, 5, 6 } }
   ShowValue( aArray2D, "two-dim"  )
   Show2DArr( aArray2D )

   aArrMDim := { 1, "One", DATE(), .T., { 1, 2, 3, 4 } }
   ShowValue( aArrMDim, "Multi-dim"  )

   ? "Before ASIZE() :", LEN( aArrMDim )
   ASIZE( aArrMDim[ 5 ], 2 )
   ShowValue( aArrMDim, "Shrinked subarray"  )
   ? "After ASIZE() :", LEN( aArrMDim )
   ? HB_ValToExp(aArrMDim[ 5 ] )  // {1, 2}
   ? LEN( aArrMDim[ 5 ] ) //
   ShowValue( aArrMDim, "Shrinked"  )

   ?
   @ MAXROW(), 0
   WAIT "EOF MD_Arrays.prg"

RETURN // MD_Arrays.Main

*-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._

PROCEDURE ShowValue( xValue, cComment )
   LOCAL cType := VALTYPE( xValue )
   ? cComment, ":",;
     ValType( xValue ),;
     IF( cType $ "CMA", HB_ValToExp( LEN( xValue ) ),''),;
     HB_ValToExp( xValue )
   ?
RETURN // ShowValue()
*-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._
PROCEDURE Show2DArr( a2DArr )
   ?
   FOR nD1 := 1 TO 2
      FOR nD2 := 1 TO 3
         ?? a2DArr[ nD1, nD2 ]
      NEXT
      ?
   NEXT
RETURN // Show2DArr()
*-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._

 MD_Arrays

C5 super arrays

Clipper 5’s super arrays

Array Terms

Array :

A data structure that contains an ordered series of values called elements. The elements of an array are referred to by ordinal number; the first element is number 1, the second is number 2, etc. A numeric expression used to specify an element of an array is referred to as a subscript or index. In Clipper language, the elements of an array may be values of any type, including references to other arrays.

See Also : Array Reference, Nested Array, Subarray, Subscript

Array Functions :

Those functions that specifically perform their tasks on arrays.

See Also : Array, Element, Function, Subscript

Array Iterator :

A function that traverses an array, performing an operation on each element.

See Also : Array

Array Reference :

A special data value that allows access to an array. In Clipper language, program variables and array elements cannot directly contain arrays; they may, however, contain array references. A variable that contains a reference to a particular array is said to refer to that array, and the array’s elements may be accessed by applying a subscript to the variable. If the value of a variable containing an array reference is assigned to a second variable, the second variable will contain a copy of the array reference; both variables then refer to the same array, and the array’s elements may be accessed by applying a subscript to either variable.

See Also: Array, Nested Array, Subarray, Subscript

Constant Array :

See : Literal Array

Dimension :

The maximum number of subscripts required to specify an array element. For example, a two-dimensional array must have two subscripts, a three-dimensional array must have three subscripts and so on.

See Also: Subscript

Element :

A component unit of an array, usually referred to by a numeric subscript or index.

See Also: Array, Subscript

Literal Array :

In Clipper language, an array specified by enclosing a series of expressions in curly ({}) braces. A literal array is an expression that evaluates to an array reference.

See Also: Array, Array Reference

Multidimensional Array :

In Clipper language, an array whose elements consist entirely of references to other arrays (called subarrays). The elements of the subarrays may, in turn, contain references to other arrays. Arrays organized in this fashion are said to be nested. Each level of nesting may be viewed as a dimension of the main array, and the elements of the subarrays may be accessed by applying multiple subscripts to the main array.

See Also: Array, Array Reference, Nested Array, Subscript

Nested Array :

In Clipper language, two arrays are said to be nested if one of them contains a reference to the other. When an array contains a reference to a second array, the second array is sometimes called a subarray of the first array

See Also: Array, Array Reference, Multidimensional Array

Reference :

A special value that refers indirectly to a variable or array. If one variable contains a reference to a second variable (achieved by passing the second variable by reference in a function or procedure call), operations on the first variable (including assignment) are passed through to the second variable. If a variable contains a reference to an array, the elements of the array can be accessed by applying a subscript to the variable.

See Also: Array Reference, Parameter

Single-dimensional Array :

In Clipper language, an array whose elements do not contain references to other arrays.

See Also:Array, Multidimensional Array, Nested Array, Subarray, Subscript

Sort Order :

Describes the various ways database files and arrays are ordered.

. Ascending

Causes the order of data in a sort to be from lowest value to highest value.

. Descending

Causes the order of data in a sort to be from highest value to lowest value.

. Chronological

Causes data in a sort to be ordered based on a date value, from earliest to most recent.

. ASCII

Causes data in a sort to be ordered according to the ASCII Code values of the data to be sorted.

. Dictionary

The data in a sort is ordered in the way it would appear if the items sorted were entries in a dictionary of the English language.

. Collating Sequence

Data in a sort will be placed in sequence following the order of characters in the Extended Character Set.

. Natural

The order in which data was entered into the database.

Subarray :

In Clipper language, an array that is referred to by an element of another array.

See Also:Array, Multidimensional Array, Nested Array, Subscript

Subscript :

A numeric value used to designate a particular element of an array. Applying a subscript to an array is called subscripting the array. In Clipper programs, subscripting is specified by enclosing a numeric expression in square   ([ ]) brackets after the name of a program variable. The variable is then said to be subscripted.

See Also: Array, Array Reference, Nested Array, Subarray

Two-dimensional Array :

An array that has two dimensions. In Clipper language, an array whose elements contain references to other arrays, all of which have the same length and do not refer to other arrays.

See Also: Array, Array Reference, Nested Array, Subscript