gets( )

Topic group Related topics Example

Returns a line of text from a file previously opened with create( ) or open( ).

Syntax

<oRef>.gets([<characters expN> [, <end-of-line expC>]])

<oRef>

A reference to the File object that created or opened the file.

<characters expN>

The number of characters to read and return before a carriage return is reached.

<end-of-line expC>

The end-of-line indicator, which can be a string of one or two characters. If omitted, the default is a hard carriage return and line feed. The following table lists standard codes used as end-of-line indicators.

Use the CHR( ) function to create the <end-of-line expC> if needed. To designate the <end-of-line expC>, you must also specify the <characters expN>. If you don’t want a line length limit, use an arbitrarily high number. For example:

cLine = f.gets( 10000, chr( 0x8d ) ) // Soft carriage return (U.S.)

Property of

File

Description

Use gets( ) to read lines from a text file. gets( ) reads and returns a character string from the file opened by the File object, starting at the file pointer position, and reading past but not returning the first end-of-line character(s) it encounters.

gets( ) will read characters until it encounters the end-of-line character(s) or it reads the number of characters you specify with <characters expN>, whichever comes first. If a file does not have end-of-line character(s) and you do not specify <characters expN>, gets( ) will read and return everything from the current file pointer position to the end of the file.

If the file pointer position is at an end-of-line character(s), gets( ) returns an empty string (""); the line is empty.

If gets( ) encounters an end-of-line character(s), it positions the file pointer at the character after the end-of-line character(s); that is, at the beginning of the next line. Otherwise, gets( ) positions the file pointer at the character after the last character it returns. Use seek( ) to move the file pointer before or after using gets( ).

If the file being read is not a text file, use read( ) instead. read( ) requires <characters expN> to be specified, and does not treat end-of-line characters specially.

To write a text file, use puts( ). readln( ) is identical to gets( ).