ARRAY

Function A2EDIT()

  A2EDIT(<nTop>, <nLeft>, <nBottom>, <nRight>, <aData>, <cUserFunc>, <aSay>, <aHeaders>, <aHeadSep>, <aColSep>, <aFootSep>, <aFooters>) --> NIL
 

A2EDIT() is a array function that determines the browse 2D array data in a table layout.

A2EDIT() lake a DBEDIT() function.

  arr := {{1,2,3,4,5}{11,22,33,44,55}{111,222,333,444,555}}
 A2EDIT(0, 0, maxrow(), maxcol(), arr, {"One", "Two", "Three", "Four", "Five"})
 

Function AADD()

 AADD(<aTarget>, <expValue>[, <keyValue>]) --> Value

AADD() is an array function that increases the actual length of the target array by one. The newly created array element is assigned the value specified by <expValue>.

AADD() is used to dynamically grow an array. It is useful for building dynamic lists or queues. A good example of this is the GetList array used by the Get system to hold Get objects. After a READ or CLEAR GETS, GetList becomes an empty array. Each time you execute an @...GET command, the Get system uses AADD() to add a new element to the end of the GetList array, and then assigns a new Get object to the new element.

AADD() is similar to ASIZE() but only adds one element at a time; ASIZE() can grow or shrink an array to a specified size. AADD(), however, has the advantage that it can assign a value to the new element, while ASIZE() cannot. AADD() may also seem similar to AINS(), but they are different: AINS() moves elements within an array, but it does not change the array's length.

Note: If <expValue> is another array, the new element in the target array will contain a reference to the array specified by <expValue>.

  These examples demonstrate the effects of multiple invocations
 of AADD() to an array:
 
 aArray := {}                  // Result: aArray is an empty array
 AADD(aArray, 5)               // Result: aArray is { 5 }
 AADD(aArray, 10)              // Result: aArray is { 5, 10 }
 AADD(aArray, { 12, 10 })      // Result: aArray is
 // { 5, 10, { 12, 10 } }
 
 

Function ACLONE()

 ACLONE(<aSource>) --> aDuplicate

ACLONE() is an array function that creates a complete duplicate of the <aSource> array. If <aSource> contains subarrays, ACLONE() creates matching subarrays and fills them with copies of the values in the <aSource> subarrays. ACLONE() is similar to ACOPY(), but ACOPY() does not duplicate nested arrays.

  This example creates an array then duplicates it using
 ACLONE().  The first array is then altered, but the duplicate copy is
 unaffected:
 
 LOCAL aOne, aTwo
 aOne := { 1, 2, 3 }         // Result: aOne is {1, 2, 3}
 aTwo := ACLONE(aOne)        // Result: aTwo is {1, 2, 3}
 aOne[1] := 99               // Result: aOne is {99, 2, 3}
 // aTwo is still {1, 2, 3}
 
 

Function ACOPY()

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

ACOPY() is an array function that copies elements from the <aSource> array to the <aTarget> array. The <aTarget> array must already exist and be large enough to hold the copied elements. If the <aSource> array has more elements, some elements will not be copied.

ACOPY() copies values of all data types including NIL and code blocks. If an element of the <aSource> array is a subarray, the corresponding element in the <aTarget> array will contain a reference to the subarray. Thus, ACOPY() will not create a complete duplicate of a multidimensional array. To do this, use the ACLONE() function.

  This example creates two arrays, each filled with a value.
 The first two elements from the source array are then copied into the
 target array:
 
 LOCAL nCount := 2, nStart := 1, aOne, aTwo
 aOne := { 1, 1, 1 }
 aTwo := { 2, 2, 2 }
 ACOPY(aOne, aTwo, nStart, nCount)
 // Result: aTwo is now { 1, 1, 2 }
 
 

Function ADEL()

 ADEL(<aTarget>, <nPosition>) --> aTarget

ADEL() is an array function that deletes an element from an array. The contents of the specified array element is lost, and all elements from that position to the end of the array are shifted up one element. The last element in the array becomes NIL.

Warning! xClipper implements multidimensional arrays by nesting arrays within other arrays. If the <aTarget> array is a multidimensional array, ADEL() can delete an entire subarray specified by <nPosition>, causing <aTarget> to describe an array with a different structure than the original.

  This example creates a constant array of three elements, and
 then deletes the second element.  The third element is moved up one
 position, and the new third element is assigned a NIL:
 
 LOCAL aArray
 aArray := { 1, 2, 3 }      // Result: aArray is
 // now { 1, 2, 3 }
 ADEL(aArray, 2)            // Result: aArray is
 // now { 1, 3, NIL }
 
 

Function AEVAL()

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

AEVAL() is an array function that evaluates a code block once for each element of an array, passing the element value and the element index as block parameters. The return value of the block is ignored. All elements in <aArray> are processed unless either the <nStart> or the <nCount> argument is specified.

AEVAL() makes no assumptions about the contents of the array elements it is passing to the block. It is assumed that the supplied block knows what type of data will be in each element.

AEVAL() is similar to DBEVAL() which applies a block to each record of a database file. Like DBEVAL(), AEVAL() can be used as a primitive for the construction of iteration commands for both simple and complex array structures.

Refer to the Code Blocks section in the "Basic Concepts" chapter of the Programming and Utilities Guide for more information on the theory and syntax of code blocks.

  This example uses AEVAL() to display an array of file names
 and file sizes returned from the DIRECTORY() function:
 
 #include "Directry.ch"
 //
 LOCAL aFiles := DIRECTORY("*.dbf"), nTotal := 0
 AEVAL(aFiles,;
 { | aDbfFile |;
 QOUT(PADR(aDbfFile[F_NAME], 10), aDbfFile[F_SIZE]),;
 nTotal += aDbfFile[F_SIZE]);
 } )
 //
 ?
 ? "Total Bytes:", nTotal
 
 This example uses AEVAL() to build a list consisting of
 selected items from a multidimensional array:
 
 #include "Directry.ch"
 //
 LOCAL aFiles := DIRECTORY("*.dbf"), aNames := {}
 AEVAL(aFiles,;
 { | file | AADD(aNames, file[F_NAME]) };
 )
 
 This example changes the contents of the array element
 depending on a condition.  Notice the use of the codeblock
 parameters:
 
 LOCAL aArray[6]
 AFILL(aArray,"old")
 AEVAL(aArray,;
 {|cValue,nIndex| IF(cValue == "old",;
 aArray[nIndex] := "new",)})
 
 

Function AFILL()

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

AFILL() is an array function that fills the specified array with a single value of any data type (including an array, code block, or NIL) by assigning <expValue> to each array element in the specified range.

Warning! AFILL() cannot be used to fill multidimensional arrays. xClipper implements multidimensional arrays by nesting arrays within other arrays. Using AFILL() with a multidimensional array will overwrite subarrays used for the other dimensions of the array.

 This example, creates a three-element array.  The array is
 then filled with the logical value, (.F.).  Finally, elements in
 positions two and three are assigned the new value of true (.T.):
 
 LOCAL aLogic[3]
 // Result: aLogic is { NIL, NIL, NIL }
 
 AFILL(aLogic, .F.)
 // Result: aLogic is { .F., .F., .F. }
 
 AFILL(aLogic, .T., 2, 2)
 // Result: aLogic is { .F., .T., .T. }

Function AINS()

 AINS(<aTarget>, <nPosition>) --> aTarget

AINS() is an array function that inserts a new element into a specified array. The newly inserted element is NIL data type until a new value is assigned to it. After the insertion, the last element in the array is discarded, and all elements after the new element are shifted down one position.

Warning! AINS() must be used carefully with multidimensional arrays. Multidimensional arrays in xClipper are implemented by nesting arrays within other arrays. Using AINS() in a multidimensional array discards the last element in the specified target array which, if it is an array element, will cause one or more dimensions to be lost. To insert a new dimension into an array, first add a new element to the end of the array using AADD() or ASIZE() before using AINS().

 This example demonstrates the effect of using AINS() on an
 array:
 
 LOCAL aArray
 aArray := { 1, 2, 3 }      // Result: aArray is
 // now { 1, 2, 3 }
 AINS(aArray, 2)            // Result: aArray is
 // now { 1, NIL, 2 }

Function ARRAY()

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

ARRAY() is an array function that returns an uninitialized array with the specified number of elements and dimensions. If more than one <nElements> argument is specified, a multidimensional array is created with the number of dimensions equal to the number of <nElements> arguments specified. Any <nElements> that is itself an array creates a nested array.

In xClipper, there are several ways to create an array. You can declare an array using a declaration statement such as LOCAL or STATIC; you can create an array using a PRIVATE or PUBLIC statement; you can assign a literal array to an existing variable; or you can use the ARRAY() function. ARRAY() has the advantage that it can create arrays within expressions or code blocks.

  This example creates a one-dimensional array of five elements
 using the ARRAY() function, and then shows the equivalent action by
 assigning a literal array of NIL values:
 
 aArray := ARRAY(5)
 aArray := { NIL, NIL, NIL, NIL, NIL }
 
 This example shows three different statements which create the
 same multidimensional array:
 
 aArray := ARRAY(3, 2)
 aArray := { {NIL, NIL}, {NIL, NIL}, {NIL, NIL} }
 aArray := { ARRAY(2), ARRAY(2), ARRAY(2) }
 
 This example creates a nested, multidimensional array:
 
 aArray := ARRAY(3, {NIL,NIL})
 
 

Function ASCAN()

 ASCAN(<aArr>, <Expression>, [<nStart>], [<nCount>], [lBack])	--> <nStoppedAt>

ASCAN() scanns an array <aArr> for a value <Expression> or until a code block <Expression> returns TRUE and uses for comparions operator (=).

 arr := {"Ann", "Mary", "Jhon", "Suzi"}
 ASCAN(arr, "Mary")    //	--> 2

Function ASIZE()

 ASIZE(<aTarget>, <nLength>) --> aTarget

ASIZE() is an array function that changes the actual length of the <aTarget> array. The array is shortened or lengthened to match the specified length. If the array is shortened, elements at the end of the array are lost. If the array is lengthened, new elements are added to the end of the array and assigned NIL.

ASIZE() is similar to AADD() which adds a single new element to the end of an array and optionally assigns a new value at the same time. Note that ASIZE() is different from AINS() and ADEL(), which do not actually change the array's length.

Note: ASIZE() only supports single-dimensional arrays.

  These examples demonstrate adding new elements and deleting
 existing elements:
 
 aArray := { 1 }          // Result: aArray is { 1 }
 ASIZE(aArray, 3)         // Result: aArray is { 1, NIL, NIL }
 ASIZE(aArray, 1)         // Result: aArray is { 1 }
 
 

Function ASORT()

 ASORT(<aTarget>, [<nStart>],[<nCount>], [<bOrder>]) --> aTarget

ASORT() is an array function that sorts all or part of an array containing elements of a single data type. Data types that can be sorted include character, date, logical, and numeric.

If the <bOrder> argument is not specified, the default order is ascending. Elements with low values are sorted toward the top of the array (first element), while elements with high values are sorted toward the bottom of the array (last element).

If the <bOrder> block argument is specified, it is used to determine the sorting order. Each time the block is evaluated, two elements from the target array are passed as block parameters. The block must return true (.T.) if the elements are in sorted order. This facility can be used to create a descending or dictionary order sort. See the examples below.

When sorted, character strings are ordered in ASCII sequence; logical values are sorted with false (.F.) as the low value; date values are sorted chronologically; and numeric values are sorted by magnitude.

 This example creates an array of five unsorted elements, sorts
 the array in ascending order, then sorts the array in descending
 order using a code block:
 
 aArray := { 3, 5, 1, 2, 4 }
 ASORT(aArray)
 // Result: { 1, 2, 3, 4, 5 }
 
 ASORT(aArray,,, { |x, y| x > y })
 // Result: { 5, 4, 3, 2, 1 }
 
 
 This example sorts an array of character strings in ascending
 order, independent of case.  It does this by using a code block that
 converts the elements to uppercase before they are compared:
 
 aArray := { "Fred", Kate", "ALVIN", "friend" }
 ASORT(aArray,,, { |x, y| UPPER(x) < UPPER(y) })
 
 This example sorts a nested array using the second element of
 each subarray:
 
 aKids := { {"Mary", 14}, {"Joe", 23}, {"Art", 16} }
 aSortKids := ASORT(aKids,,, { |x, y| x[2] < y[2] })
 
 Result:
 
 { {"Mary", 14}, {"Art", 16}, {"Joe", 23} }

Function ATAIL()

 ATAIL(<aArray>) --> Element

ATAIL() is an array function that returns the highest numbered element of an array. It can be used in applications as shorthand for <aArray>[LEN(<aArray>)] when you need to obtain the last element of an array.

 The following example creates a literal array and returns that
 last element of the array:
 
 aArray := {"a", "b", "c", "d"}
 ? ATAIL(aArray)                     // Result: d

Function EMPTY()

 EMPTY(<exp>) --> lEmpty

The EMPTY() function has a number of uses. You can use it to determine if a user entered a value into a Get object before committing changes to a database file. It can also determine whether a formal parameter is NIL or unsupplied. In addition, it can test an array for zero-length.

 List of Empty Values
 ------------------------------------------------------------------------
 Data Type    Contents
 ------------------------------------------------------------------------
 Array        Zero-length
 Character    Spaces, tabs, CR/LF, or ("")
 Numeric      0
 Date         Null (CTOD(""))
 Logical      False (.F.)
 Memo         Same as character
 NIL          NIL
 ------------------------------------------------------------------------
 

 These examples illustrate use of EMPTY() against several
 different data types:
 
 ? EMPTY(SPACE(5)), EMPTY("")        // Result: .T. .T.
 ? EMPTY(0), EMPTY(CTOD(""))         // Result: .T. .T.
 ? EMPTY(.F.), EMPTY(NIL)            // Result: .T. .T.
 
 This example uses EMPTY() to determine whether the user
 entered a value into the first Get object before writing the new
 value to the database file:
 
 LOCAL cCust := SPACE(15), nAmount := 0
 USE Sales NEW
 @ 10, 10 GET cCust
 @ 11, 10 GET nAmount PICTURE "999.99"
 READ
 //
 IF !EMPTY(cCust)
 APPEND BLANK
 REPLACE Sales->Cust WITH cCust, Sales->Amount ;
 WITH nAmount
 ENDIF
 
 This example uses EMPTY() as part of the VALID clause to force
 the user to enter data into the current Get object:
 
 LOCAL cCode := SPACE(5)
 @ 2, 5 SAY "Enter code" GET cCode VALID !EMPTY(cCode)
 READ

Function __FLEDIT()

 __Fledit( <aSrc>, <aList>) --> <aSelected>

__FlEdit() searches each element of <aList>[1] (DBS_NAME) in <aSrc>. If the element is found, this element of <aSrs> is added to destination array <aSelected>. According of other subelements (DBS_TYPE, DBS_LEN, DBS_DEC) isn't checked. Categories TCP is the set of functions for work with sockets.

For functions TCPListen() and TCPAccept() many thanks to Sergio Zayas.

 aList:=GetUserList()  //Get user's defined field's list
 aRealFlds:=__FlEdit(DbStruct(), aList) //and select only correct

Function FT_AADDITION()

 FT_AADDITION( <aList1>, <aList2> [, <lTrimmer> [, <lCaseSens> ] ] ) ;
 --> aNewArray

This function will add the elements unique of aList2 with aList1. It returns a new array including all the elements of aList1 plus the unique elements of aList2.

 aList1 := {"apple", "orange", "pear"}
 aList2 := {"apple ", "banana", "PEAR"}
 
 FT_AADDITION( aList1, aList2 )
 // ignores spaces, sensitive to case
 // returns {"apple","orange","pear","banana","PEAR"}
 
 FT_AADDITION( aList1, aList2, , .F. )
 // ignores spaces, not sensitive to case
 // returns {"apple","orange","pear","banana"}
 
 FT_AADDITION( aList1, aList2, .F., .F. )
 // sensitive to spaces, not sensitive to case
 // returns {"apple","orange","pear","apple ","banana"}

Function FT_AAVG()

 FT_AAVG( <aArray> [, <nStartIndex> [, <nEndIndex> ] ] ) --> nAverage

This function is used to get a numeric average of selected or all elements of an array.

This routine requires FT_ASUM().

 FT_AAVG(aSubTotals)          // Get Average of Entire Array
 
 FT_AAVG(aSubTotals, 5)       // Get Average of 5th Element On
 
 FT_AAVG(aSubTotals, , 10)    // Get Average of 1st 10 Elements
 
 FT_AAVG(aSubTotals, 5, 10)   // Get Average of Elements 5-10

Function FT_ADESSORT()

 FT_ADESSORT( <aArray> [, <nStartIndex> [, <nEndIndex> ] ] ) --> aSorted

This function is used to sort an array in descending order, i.e., Z-A

 FT_ADESSORT(aNames)               // Sort the Entire Array
 
 FT_ADESSORT(aNames, 5)            // Sort from the 5th Element On
 
 FT_ADESSORT(aNames, , 10)         // Sort the 1st 10 Elements
 
 FT_ADESSORT(aNames, 5, 10)        // Sort Elements 5-10

Function FT_AEMAXLEN()

 FT_AEMAXLEN( <aArray> [, <nDimension> [, <nStart> [, <nCount> ] ] ] ) ;
 --> nMaxlen

This function will measure each element of an array dimension and return the longest element.

 FT_AEMAXLEN(aArray)       // Measure the 1st dimension of an Array
 
 FT_AEMAXLEN(aArray,2)     // Measure the 2nd dimension of an Array
 
 FT_AEMAXLEN(aArray,2,,9)  // Measure Elements 1-9 of the
 2nd dimension or subarray
 
 FT_AEMAXLEN(aArray,3,5,9) // Measure Elements 5-9 of the
 3rd dimension or subarray
 
 FT_AEMAXLEN(aArray,3,5)   // Measure Elements 5 to last in the
 3rd dimension or subarray

Function FT_AEMINLEN()

 FT_AEMINLEN( <aArray> [, <nDimension> [, <nStart> [, <nCount> ] ] ] )
 --> nMinlen

This function will measure each element of an array dimension and return the shortest element.

 FT_AEMINLEN(aArray)       // Measure the 1st dimension of an Array
 
 FT_AEMINLEN(aArray,2)     // Measure the 2nd dimension of an Array
 
 FT_AEMINLEN(aArray,2,,9)  // Measure Elements 1-9 of 2nd dimension
 
 FT_AEMINLEN(aArray,3,5,9) // Measure Elements 5-9 of 3rd dimension
 
 FT_AEMINLEN(aArray,3,5)   // Measure Elements 5 to end of 3rd dimension

Function FT_AMEDIAN()

 FT_AMEDIAN( <aArray> [, <nStart> [, <nEnd> ] ] )
 --> nMedian

This function sorts the elements of a numeric array and then returns the value in the middle element of the sorted array. If there is no exact middle value, then it returns the average of the two middle values. Half of the elements are > median and half are < median. A median average may more reflect a more useful average when there are extreme values in the set.

 FT_AMEDIAN( aArray )      // Return Median for entire array
 
 FT_AMEDIAN( aArray, 2)    // Return Median for elements from 2 to end
 
 FT_AMEDIAN( aArray, ,9)   // Return Median for 1st 9 elements
 
 FT_AMEDIAN( aArray,8,40 ) // Return Median for elements 8 to 40

Function FT_ANOMATCHES()

 FT_ANOMATCHES( <aArray>, <bCompareBlock> ;
 [, <nStartIndex> [, <nEndIndex> ] ] ) --> nNoOfMatches

This function returns the number of array elements that, when passed to the supplied code block, cause that code block to return a .T. value.

 // Search the Entire Array
 FT_ANOMATCHES(aTries, { | x | x <= 100 } )
 
 // Search from the 5th Element On
 FT_ANOMATCHES(aCodes, { | x | UPPER(x) == cCurrentCode }, 5)
 
 // Search the 1st 10 Elements
 FT_ANOMATCHES(aDates, { | x | IS_BETWEEN(DATE()-7,x,DATE() + 7) }, 10)
 
 // Search Elements 5-10
 FT_ANOMATCHES(aNames, { | x | x <= cLastGoodName }, 5, 10)

Function FT_AREDIT()

 FT_AREDIT( <nTop>, <nLeft>, <nBottom>, <nRight>, <Array Name>, ;
 <nElem>, <aHeadings>, <aBlocks> [, <bGetFunc> ] ) --> xElement

This function allows you to position yourself in an array, add and delete rows with the <F7> and <F8> keys, and pass a UDF with information to edit the individual gets.

 FT_AREDIT(3, 5, 18, 75, ar, @nElem, aHeadings, aBlocks)
 
 This example will allow you to browse a 2 dimensional array
 But you can't edit it since there is no GetBlock UDF
 It allows the user to hit ENTER to select an element or ESC to
 return 0
 
 * This second example shows how to edit a 2 dimensional array
 * as might be done to edit an invoice
 
 LOCAL i, ar[3, 26], aBlocks[3], aHeadings[3]
 LOCAL nElem := 1, bGetFunc
 
 * Set up two dimensional array "ar"
 
 FOR i = 1 TO 26
 ar[1, i] := i          //  1  ->  26  Numeric
 ar[2, i] := CHR(i+64)  // "A" -> "Z"  Character
 ar[3, i] := CHR(91-i)  // "Z" -> "A"  Character
 NEXT i
 
 * SET UP aHeadings Array for column headings
 
 aHeadings  := { "Numbers", "Letters", "Reverse" }
 
 * Need to set up individual array blocks for each TBrowse column
 
 aBlocks[1] := {|| STR(ar[1, nElem], 2) } // prevent default 10 spaces
 aBlocks[2] := {|| ar[2, nElem] }
 aBlocks[3] := {|| ar[3, nElem] }
 
 * set up TestGet() as the passed Get Function so FT_ArEdit knows how
 * to edit the individual gets.
 
 bGetFunc   := { | b, ar, nDim, nElem | TestGet(b, ar, nDim, nElem) }
 SetColor( "N/W, W/N, , , W/N" )
 CLEAR SCREEN
 FT_AREDIT(3, 5, 18, 75, ar, @nElem, aHeadings, aBlocks, bGetFunc)
 

Function FT_ASUM()

 FT_ASUM( <aArray> [, <nStartIndex> [, <nEndIndex> ] ] ) --> nSum

This function is to sum the elements of a numeric array or to sum the lengths of a character array.

  FT_ASUM(aSubTotals)               // Sum the Entire Array
 
 FT_ASUM(aSubTotals, 5)            // Sum from the 5th Element On
 
 FT_ASUM(aSubTotals, , 10)         // Sum the 1st 10 Elements
 
 FT_ASUM(aSubTotals, 5, 10)        // Sum Elements 5-10

Function FT_RESTARR()

 FT_RESTARR( <cFileName>, <nErrorCode> ) --> aArray

FT_RESTARR() restores an array which was saved to a disc file using FT_SAVEARR().

[10/1/92 Librarian note:

This function does not appear to work with multi-dimensional arrays. If you'd care to modify it to support this feature, please do and send it to Glenn Scott 71620,1521.]

 aArray := { {'Invoice 1',CTOD('04/15/91'),1234.32,.T.},;
 {'Invoice 2',DATE(),234.98,.F.},;
 {'Invoice 3',DATE() + 1,0,.T.}  }
 nErrorCode := 0
 FT_SAVEARR(aArray,'INVOICE.DAT',@nErrorCode)
 IF nErrorCode = 0
 aSave := FT_RESTARR('INVOICE.DAT',@nErrorCode)
 IF nErrorCode # 0
 ? 'Error restoring array'
 ENDIF
 ELSE
 ? 'Error writing array'
 ENDIF
 

Function FT_SAVEARR()

 FT_SAVEARR( <aArray>, <cFileName>, <nErrorCode> ) --> lRet

FT_SAVEARR() saves any Clipper array, except those containing compiled code blocks, to a disc file. The array can be restored from the disc file using FT_RESTARR().

[10/1/92 Librarian note:

This function does not appear to work with multi-dimensional arrays. If you'd care to modify it to support this feature, please do and send it to Glenn Scott 71620,1521.]

 aArray := { {'Invoice 1',CTOD('04/15/91'),1234.32,.T.},;
 {'Invoice 2',DATE(),234.98,.F.},;
 {'Invoice 3',DATE() + 1,0,.T.}  }
 nErrorCode := 0
 FT_SAVEARR(aArray,'INVOICE.DAT',@nErrorCode)
 IF nErrorCode = 0
 aSave := FT_RESTARR('INVOICE.DAT',@nErrorCode)
 IF nErrorCode # 0
 ? 'Error restoring array'
 ENDIF
 ELSE
 ? 'Error writing array'
 ENDIF
 

Function LEN()

 LEN(<cString> | <aTarget>) --> nCount

LEN() is a character and array function that returns the length of a character string or the number of elements in an array. With a character string, each byte counts as one, including an embedded null byte (CHR(0)). By contrast, a null string ("") counts as zero.

For an array, LEN() returns the number of elements. If the array is multidimensional, subarrays count as one element. This means that the LEN() of a nested or multidimensional array simply returns the length of the first dimension. To determine the number of elements in other dimensions, use LEN() on the subarrays as shown in the example below. Note that nested arrays in xClipper need not have uniform dimensions.

 These examples demonstrate LEN() with various arguments:
 
 ? LEN("string of characters")         // Result: 20
 ? LEN("")                              // Result: 0
 ? LEN(CHR(0))                        // Result: 1
 //
 LOCAL aTest[10]
 ? LEN(aTest)                           // Result: 10
 
 This example creates a literal two-dimensional array, and then
 returns the number of elements in the subarray contained in the first
 element of the original array:
 
 LOCAL aArray := { {1, 2}, {1, 2}, {1, 2} }
 ? LEN(aArray)                        // Result: 3
 ? LEN(aArray[1])                     // Result: 2
 
 This example navigates a multidimensional array using LEN():
 
 LOCAL aArray := { {1, 2}, {1, 2}, {1, 2} }
 LOCAL nRow, nColumn, nRowCount, nColumnCount
 
 //
 nRowCount = LEN(aArray)
 FOR nRow = 1 TO nRowCount
 nColumnCount = LEN(aArray[nRow])
 FOR nColumn = 1 TO nColumnCount
 ? nRow, nColumn, aArray[nRow][nColumn]
 NEXT
 NEXT
 
 In this example a function returns an array of numeric values
 that describe the dimensions of a nested or multidimensional array.
 The function assumes that the array has uniform dimensions:
 
 FUNCTION Dimensions( aArray )
 LOCAL aDims := {}
 DO WHILE ( VALTYPE(aArray) == "A" )
 AADD( aDims, LEN(aArray) )
 aArray := aArray[1]
 ENDDO
 RETURN (aDims)

Function MAP()

 MAP() 	--> <oObject>

MAP() createst new empty object (associative array) and returns it.

 aMap := MAP()
 aMap:Name := "User1"
 aMap:Phone := "111-11-11"
 aMap:PhoneCount := 12
 
 PrintInfo(aMap)	     // Users name: User1
 // Phone     : 111-11-11
 // Count     :  13
 ////////////////
 static function PrintInfo( Obj )
 qout ("Users name: "+Obj:Name)
 qout ("Phone     : "+Obj:Phone)
 Obj:PhoneCount ++
 qout ("Count     : "+str(Obj:PhoneCount, 3))
 return .t.

Function MAPMODIFY

 MAPMODIFY(<oObj>, <lMode>) 	--> <lOldMode>

MAPMODIFY() includes/excludes the control mode for attributes when this attributes try changes.

If <lMode> is TRUE and source object <oObj> contents method <Modify>, then before changes attributes value automatically called method oObj:Modify(<nHashAttr>, <vNewValue>). When <nHashAttr> is the attribute hash code, <vNewValue> new value, what must be assigned. The <Modify> method must returned realy value for modifyed attribute.

 static function modify(selfobj, HashAttr, Val)
 local ret
 ret := Val
 if HashAttr == hashstr("GROUP")
 ret := Val
 if Val == NIL
 ret := "WORKGROUP"
 endif
 endif
 return ret
 
 Person := MAP()
 Person:NAME := "User1"
 Person:GROUP := "WORKGROUP"
 Person:PASSWD := "****"
 Person:MODIFY := @modify()
 
 ? Person:GROUP		// --> WORKGROUP
 
 Person:GROUP := NIL
 
 ? Person:GROUP		// --> NIL
 
 Person:GROUP := "ABC"
 
 ? Person:GROUP		// --> ABC
 
 MAPMODIFY(Person, .T.)
 Person:GROUP := NIL
 ? Person:GROUP		// --> WORKGROUP
 

Function TYPE()

 TYPE(<cExp>) --> cType

TYPE() is a system function that returns the type of the specified expression. It can test expression validity as long as the expression uses xCLIPPER.LIB functions and does not reference local or static variables, user-defined functions, or built-in functions supplied in EXTEND.LIB.

TYPE() is like VALTYPE() but uses the macro operator (&) to determine the type of the argument. This precludes the use of TYPE() to determine the type of local and static variables. VALTYPE(), by contrast, evaluates an expression and determines the data type of the return value. This lets you determine the type of user-defined functions as well as local and static variables.

TYPE() Return Values
 ------------------------------------------------------------------------
 Returns   Meaning
 ------------------------------------------------------------------------
 A         Array
 B         Block
 C         Character
 D         Date
 L         Logical
 M         Memo
 N         Numeric
 O         Object
 U         NIL, local, or static
 UE        Error syntactical
 UI        Error indeterminate
 ------------------------------------------------------------------------
 

 These examples demonstrate various results from invocations of
 TYPE():
 
 ? TYPE('SUBSTR("Hi There", 4, 5)')      // Result: C
 ? TYPE("UDF()")                         // Result: UI
 ? TYPE('IF(.T., "true", 12)')           // Result: C
 
 This example shows two methods for testing for the existence
 and type of declared parameters:
 
 FUNCTION TestParams
 PARAMETERS cParam1, nParam2
 IF cParam1 = NIL
 ? "First parameter was not passed"
 cParam1 := "Default value"
 ENDIF
 
 IF TYPE('nParam2') == "U"
 ? "Second parameter was not passed"
 ENDIF
 .
 . <statements>
 .
 RETURN NIL

Function VALTYPE()

 VALTYPE(<exp>) --> cType

VALTYPE() is a system function that takes a single argument, evaluates it, and returns a one-character string describing the data type of the return value. It is similar to TYPE(), but differs by actually evaluating the specified argument and determining the type of the return value. For this reason, you can determine the type of local and static variables, user-defined functions, and EXTEND.LIB functions. TYPE(), by contrast, uses the macro operator (&) to evaluate the type of its argument. Note that if the argument does not exist, an error ("undefined error") will occur, unlike TYPE which will return "U."

VALTYPE() Return Values
 ------------------------------------------------------------------------
 Returns   Meaning
 ------------------------------------------------------------------------
 A         Array
 B         Block
 C         Character
 D         Date
 L         Logical
 M         Memo
 N         Numeric
 O         Object
 U         NIL
 ------------------------------------------------------------------------
 

 These examples show the return values for several data types:
 
 ? VALTYPE(1)                // Result: N
 ? VALTYPE("GOOB")           // Result: C
 ? VALTYPE(NIL)              // Result: U
 ? VALTYPE(array)            // Result: A
 ? VALTYPE(block)            // Result: B