xHarbour Reference Documentation > Function Reference

MemoLine()

Extracts a line of text from a formatted character string or memo field.

Syntax

MemoLine( <cString>    , ;
         [<nLineLen>]  , ;
         [<nLineNum>]  , ;
         [<nTabSize>]  , ;
         [<lWrap>]     , ;
         [<lLongLines>], ;
         [@<nOffSet>]    ) --> cTextLine

Arguments

<cString>

A character string or memo field to extract a text line from. It can be a formatted text string that includes Tab and Hard/Soft carriage return characters.

<nLineLen>

A numeric value specifying the number of characters per extracted line. It is usually a value between 4 and 254. If <nLineLen> is larger than 254 characters, parameter <lLongLines> must be set to .T. (true). The default value for <nLineLen> is 79.

<nLineNum>

A numeric value specifying the line number to extract. It defaults to 1.

<nTabSize>

A numeric value specifying the number of blank spaces the Tab character should be expanded to. It defaults to 4 blank spaces.

<lWrap>

A logical value indicating if word wrapping should be applied to <cString> when lines are extracted. The default value is .T. (true), resulting in extracted text lines that contain whole words only. When a word does not fit entirely to the end of the extracted text line, it is wrapped to the next text line. Passing .F. (false) for this parameter turns word wrapping off so that only lines ending with a hard carriage return are extracted.

<lLongLines>

This parameter defaults to .F. (false). It must be set to .T. (true) when text lines of more than 254 characters should be extracted.

@<nOffSet>

A numeric value specifying the first character in <cString> to begin with extracting text lines. It defaults to 1. If passed by reference, <nOffSet> receives the starting position of the next line that can be extracted from <cString> in a repeated call to MemoLine(). This improves the speed of MemoLine() considerably when multiple lines are extracted from text of more than 64 kB.

Return

The function returns a character string of <nLineLen> characters. If <lWrap> is .T. (true) and the extracted line does not end with a complete word, the line is filled with blank spaces up to the length of <nLineLen>. If <lWrap> is .F. (false), the returned string contains <nLineLen> characters and a next call to MemoLine() extracts characters following the next hard carriage return.

If <nLineNum> is larger than the number of lines contained in <cString>, an empty string ("") is returned.

Description

MemoLine() is used to extract single text lines from a formatted text string that may include Tab characters (Chr(9)), Soft carriage returns (Chr(141)) or Hard carriage returns (Chr(13)). Multiple lines are usually extracted within a FOR..NEXT loop whose upper boundary is determined by the total number of text lines in a string, as reported by function MLCount().

If multiple lines are extracted, it is strongly recommended to pass <nOffSet> by reference to MemoLine(), initializing the parameter with 1. This improves the speed of text extraction considerably.

note:  when text lines extracted with MemoLine() are displayed, they have only the same length if a fixed-size font is used for display.

Info

See also:	FLineCount(), HB_FReadLine(), HB_ReadLine(), MemoEdit(), MemoRead(), MemoWrit(), MLCount(), MLPos()
Category:	Character functions , Memo functions
Source:	rtl\txtline.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example demonstrates MemoLine() usage for extracting all lines
// of a text file. The difference of using line numbers versus using
// line offsets is outlined.

   PROCEDURE Main( cFileName )
      LOCAL nLineLen  := 60
      LOCAL nTabSize  :=  8
      LOCAL lWrap     := .T.
      LOCAL i, imax, cText, cLine, nOffSet, nTextLen
      LOCAL t1, t2, t3

      IF Empty( cFileName ) .OR. .NOT. File( cFileName )
         ? "No file specified"
         QUIT
      ENDIF

      cText := MemoRead( cFileName )

      t1   := Seconds()
      imax := MLCount( cText, nLineLen, nTabSize, lWrap )
      FOR i:=1 TO imax
         cLine := MemoLine( cText, nLineLen, i, nTabSize, lWrap )
      NEXT
      t2 := Seconds()

      // This example shows the use of the <nOffSet> parameter.
      // Note that the line number does not change, but the starting
      // position in the text to begin extracting a line
      nTextLen := Len( cText )
      nOffSet  := 1
      i        := 0
      DO WHILE nOffSet <= nTextLen
         cLine := MemoLine( cText, nLineLen, 1, nTabSize, lWrap,, @nOffSet )
         i++
      ENDDO
      t3 := Seconds()

      ? "Using line number:", t2-t1, "secs (" + Ltrim(Str(imax)) + " lines)"
      ? "Using line offset:", t3-t2, "secs (" + Ltrim(Str(i)) + " lines)"
   RETURN