Share via

ALINES( ) Function

  • Article

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

ALINES( ) provides an easy way to parse lines in a character expression or memo field. While you can also use MLINES( ) 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.

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

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 does not exist, Visual FoxPro automatically creates the array. If the array exists but is not 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. All character expressions are case-sensitive.

    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 character strings that terminate the elements in cExpression. The maximum number of strings permitted in cParseChar is 23. The maximum length for each string is 11 characters.

    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.

Return Values

Numeric. ALINES( ) returns the number of rows in the array, or, identically, the number of lines in the character expression or memo field.

Remarks

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.

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 example opens the Employee table in the Testdata.dbc sample database. ALINES( ) copies 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( ) Function | _MLINE System Variable | SCATTER Command | MLINE( ) Function | SET MEMOWIDTH Command | ATCLINE( ) Function | ATLINE( ) Function | COPY MEMO Command | MODIFY MEMO Command