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.

Character code (decimal)

(hexadecimal)

Represents

CHR(141)

0x8D

Soft carriage return (U.S.) 

CHR(255)

0xFF

Soft carriage return (Europe) 

CHR(138)

0x8A

Soft linefeed (U.S.) 

CHR(0)

0x00

Soft linefeed (Europe) 

CHR(13)

0x0D

Hard carriage return 

CHR(10)

0x0A

Hard linefeed 

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(†).