ALINES()

Hacker’s Guide to Visual FoxPro
An irreverent look at how Visual FoxPro really works. Tells you the inside scoop on every command, function, property, event and method of Visual FoxPro.

`ALINES()`

This function, added in VFP 6, lets you take character or memo data and dump it into an array, one line per array element. It’s faster and easier than using MLINE() and _MLINE for the task. Though each of the two approaches has advantages and disadvantages, the additional functionality added in VFP 7 confirms ALINES() as our first choice for many parsing tasks.

Usage

nLineCount = ALINES( DestArray, cString [, lTrimIt ]
                     [ cParseChar1, ... cParseCharn ] )

Parameter	Value	Meaning
DestArray	Array Name	The array to contain the character or memo data.
cString	Memo or Character	The string to be broken into lines. Can be a character or memo field or any character expression.
lTrimIt	.T.	Remove leading and trailing blanks from each line.
lTrimIt	.F. or Omitted	Leave leading and trailing blanks on lines.
ParseCharx	Character	One or more characters to be treated as line breaks.
nLineCount	Numeric	The number of lines in cString, which is the same as the number of rows created in DestArray.

There are all kinds of times when we want to take a multi-line string and break it into its constituent lines for processing. We’ve had the ability to do so using the MLINE() function and its helper variable, _MLINE, for many versions of FoxPro. But it’s always required a bunch of code—and putting the results into an array, which we often want to do, calls for even more code. Enter ALINES(), one function call to do the whole job.

ALINES() breaks up strings based on explicit line-break characters (either CHR(13) or CHR(10) or a combination of the two) and, starting in VFP 7, on any other characters we specify as well. It doesn’t handle breaking long lines into reasonable lengths as MLINE() does, and doesn’t pay any attention to the MEMOWIDTH setting. This is both a good thing and a bad thing. When the string is VFP code that you want to execute one line at a time or text from another application that you’re processing, not adding line breaks based on MEMOWIDTH is great. When the string is a message that you’re trying to make printable, it’s a pain. We wish they’d given us an optional line-length parameter (though it would undoubtedly slow the function down). For this reason, if you’re trying to break up lines into human-readable lengths (or lengths to fit into character fields), a loop with MLINE() may be the better choice.

There’s one other significant difference between ALINES() and MLINE(). MLINE() strips trailing blanks from each line it creates. By default, ALINES() doesn’t. If you need those blanks, this is a big deal.

Our favorite use for ALINES() is parsing lists of things. For example:

cColors = "Red, Orange, Yellow, Green, Blue, Purple"
nItems = ALINES( aColors, cColors, .T., ",")

That code requires VFP 7 or later, but you can do the same thing in VFP 6 by including STRTRAN() in the mix:

cColors = "Red, Orange, Yellow, Green, Blue, Purple"
nItems = ALINES( aColors, STRTRAN(cColors, ",", CHR(13)), .T.)

The last two parameters to ALINES() are a little unusual. Normally, you have to include parameters in the order listed, but VFP is smart enough to figure out that a character string as the third parameter means that you’re omitting the lTrimIt parameter.

Example

* Assume mField is a memo field.
= ALINES(aAllLines, mField, .T.)

* Or use this with a string.
nLines = ALINES(aAllLines, "Here is a string composed of " + ;
                "several lines."+ ;
                CHR(13)+"Here's the second line." + ;
                CHR(10)+"Here's the third line."+ ;
                CHR(13)+CHR(10)+"Notice that it doesn't "+ ;
                "matter which line break character you use.")

ALINES()

Usage

Example

See Also

`ALINES()`