xHarbour Reference Documentation > Function Reference

HB_ReadLine()

Scans a formatted character string or memo field for text lines.

Syntax

HB_ReadLine( <cText>           , ;
            [<cDelim>|<aDelim>], ;
             <nLineLen>        , ;
            [<nTabWidth>]      , ;
             <lWrap>           , ;
            [<nStartOffset>]   , ;
            @<lFound>          , ;
            @<lEOF>            , ;
            @<nEndOffSet>      , ;
            @<nEndOfLine>        ) --> NIL

Arguments

<cText>

This is 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.

<cDelim>|<aDelim>

This is either a character string holding the end-of-line character(s) to search in <cText>, or an array holding individual end-of-line character(s). The default value is determined by the SET EOL setting.

<nLineLen>

This is a numeric value specifying the number of characters that fit into one extracted line.

<nTabWidth>

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 <cText> 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.

<nStartOffset>

A numeric value specifying the first character in <cText> to begin finding the next text line. It defaults to 1.

@<lFound>

This parameter must be passed by reference. It receives a logical value: when <lFound> is .T. (true), the text line ends with <cDelim>, otherwise it does not include the end-of-line character(s).

@<lEOF>

This parameter must be passed by reference. It receives a logical value: when <lEOF> is .T. (true), no more text lines can be extracted from <cText>.

@<nEndOffSet>

This parameter must be passed by reference. It receives a numeric value indicating the end position of the found text line without the end-of-line character(s).

@<nEndOfLine>

This parameter must be passed by reference. It receives a numeric value indicating the end position of the found text line including the end-of-line character(s).

Return

The return value is always NIL.

Description

HB_ReadLine() is a fast text scanning function 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)). Text is usually scanned for single lines within a DO WHILE loop until <lEOF> is .T. (true).

Info

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

Example

// The example demonstrates how an entire text file can be transferred
// line by line into an array.

   PROCEDURE Main
      LOCAL cText        := MemoRead( "HB_ReadLine.prg" )
      LOCAL nLineLen     := 60
      LOCAL lWrap        := .T.
      LOCAL nEndOfLine   := 0
      LOCAL nStartOffset := 1
      LOCAL nEndOffSet   := 0
      LOCAL lFound       := .F.
      LOCAL lEof         := .F.
      LOCAL aLines       := {}
      LOCAL cLine

      CLS

      DO WHILE .NOT. lEof
         HB_ReadLine( cText       , ;
                      NIL         , ;
                      nLineLen    , ;
                      NIL         , ;
                      lWrap       , ;
                      nStartOffset, ;
                      @lFound     , ;
                      @lEof       , ;
                      @nEndOffset , ;
                      @nEndOfLine   )

         cLine := SubStr( cText, nStartOffset, nEndOffset-nStartOffset+1 )

         IF cLine == ""
            cLine := " "  // empty line for AChoice()
         ENDIF

         AAdd( aLines, cLine )

         nStartOffSet := nEndOfLine
      ENDDO

      AChoice( ,,,, aLines )
   RETURN