ALINES( ) Function

  • Article

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

ALINES(ArrayName, cExpression [, nFlags] [, cParseChar [, cParseChar2 [, ...]]])

Parameters

  • ArrayName
    Specifies the name of the array to store the copied lines in the character expression or memo field.

    Note

    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.

    Note

    When used with binary values, such as Varbinary and Blob, ALINES( ) creates an array with elements that have Varbinary type.

  • cExpression
    Specifies the character expression or memo field containing the lines to copy to the array. All character expressions are case-sensitive.

    Note

    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.

  • [, nFlags]

    Note

    In previous versions of Visual FoxPro, nFlags was the lTrim option. The lTrim option corresponds to a value of 1 for nFlag. Previous code will run identically in Visual FoxPro 9.0.

    The following table describes the values for nFlags.

    Bit Value (additive) Description

    0

    1

    (Default) Removes leading and trailing spaces from lines, or for Varbinary and Blob values, removes trailing zeroes (0) instead of spaces.

    1

    2

    Include the last element in the array even if the element is empty.

    2

    4

    Do not include empty elements in the array.

    3

    8

    Specifies case-insensitive parsing.

    4

    16

    Include the parsing characters in the array.

  • [, cParseChar[, c ParseChar2[, ...]]]
    Specifies one or more character strings that terminate the elements in cExpression. When cParseChar is specified, the line breaks when cParseChar is found, and the next line continues with the character following cParseChar.

    Note

    The maximum number of strings permitted in cParseChar is 23.

    You can use a line feed (CHR(10)) or carriage return (CHR(13)) character to denote the end of a line. You can also denote the end of the line with either combination of these two characters, for example, (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.

    Note

    When cParseChar is omitted for Varbinary or Blob input, ALINES( ) treats the hexadecimal value 0hA (10) as a carriage return and discontinues the line at that location. The value, 0hA, is not saved in the resulting array element and might result in an incorrect binary value. For example, given the binary value, 0hFE0AF2, ALINES( ) creates a two-element array with the values, 0hFE and 0hF2.

Return Value

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

Remarks

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.

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.")

- OR -

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

Example

The following example opens the Employee table in the Testdata.dbc sample 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. Various parsing character are specified in each of the ALINES( ) statements.

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

? ALINES(aMyArray, employee.notes)            && Displays 1
? ALINES(aMyArray, employee.notes, CHR(13))   && Displays 1

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

? ALINES(aMyArray, employee.notes, 8, "m")    && Displays 14
? ALINES(aMyArray, employee.notes, "m")       && Displays 11
? ALINES(aMyArray, employee.notes, "M")       && Displays 4

See Also

Reference

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

Other Resources

Functions
Language Reference (Visual FoxPro)