ALINES( ) Function

  • Article

Copies each line in a character expression or memo field to a corresponding row in an array.

ALINES(ArrayName, cExpression [, lTrim] [cParseChar, , ,cParseChar])

Return Values

Numeric

Parameters

  • ArrayName
    Specifies the name of the array to which the lines in the character expression or memo field are copied. If the array you specify doesn't exist, Visual FoxPro automatically creates the array. If the array exists and isn't large enough to contain all the lines in the memo field, Visual FoxPro automatically increases the size of the array. If the array is larger than necessary, Visual FoxPro truncates the array.
  • cExpression
    Specifies the character expression or memo field containing the lines copied to the array. If cExpression is the empty string or the null value, an array with a single row is created and the row contains the empty string. You can use double-byte expressions.
  • lTrim
    Specifies that leading and trailing blanks are removed from the lines copied to the array. If lTrim is true (.T.), leading and trailing blanks are removed from the lines. If lTrim is false (.F.) or is omitted, leading and trailing blanks are not removed.
  • cParseChar
    Specifies one or more characters that delimit the elements in cExpression that are returned by the ALINES( ) function. The maximum number of cParseChars is 23.

Remarks

ALINES( ) returns the number of rows in the array (or, identically, the number of lines in the character expression or memo field). The first line of the character expression or memo field is copied to the first row of the array, the second line of the character expression or memo field is copied to the second row of the array, and so on.

All character expressions are case-sensitive.

A line feed (CHR(10)) or carriage return (CHR(13)) character denotes the end of a line. The end of the line can also be denoted with either combination of these two characters (CHR(10) + CHR(13) or CHR(13) + CHR(10)). The default behavior for ALINES( ) is to ignore CHR(13) and CHR(10) when you specify one or more values for cParseChar, unless you also specify the end of line characters.

ALINES( ) provides an easy way to parse lines in a character expression or memo field. While MLINES( ) can also be used to parse a character expression or memo field, ALINES( ) is faster and requires less programming. Also, ALINES( ) is not affected by the value of SET MEMOWIDTH.

You must have sufficient memory to copy the lines in a large memo field to an array. Visual FoxPro generates an error message if you lack sufficient memory.

If you want to perform a case-insensitive parse, you can follow one of the following examples.

? ALINES(aMyArray,UPPER(employee.notes), "R.") 
? ALINES(aMyArray,employee.notes, "R.", "r.")

Example

The following program opens the Employee table in the Testdata database. ALINES( ) is used to copy the lines in the Notes memo field to an array named aMyArray, and then the contents of the array is displayed.

In this example, ALINES( ) returns 1 because the employee description was typed into the memo field without pressing Enter after any of the sentences.

CLOSE DATABASES
CLEAR
SET TALK OFF
OPEN DATABASE (HOME(2) + 'data\testdata')
USE employee  && Open Employee table

? ALINES(aMyarray,employee.notes,CHR(13))  && Displays 1
? ALINES(aMyarray,employee.notes,".")  && Displays 7
? ALINES(aMyarray,employee.notes,",")  && Displays 4
? ALINES(aMyarray,employee.notes," ")  && Displays 75
? ALINES(aMyarray,employee.notes,".", ",")  && Displays 10
? ALINES(aMyArray, employee.notes)  && Displays 1
? aMyArray(1)

See Also

MEMLINES( ) | _MLINE System Variable | SCATTER Command | MLINE( ) Function | SET MEMOWIDTH Command | ATCLINE( ) Function | ATLINE( ) Function | COPY MEMO Command | MODIFY MEMO Command