puts( )

Topic group Related topics

Writes a character string, and one or two end-of-line characters, to a file previously opened with create( ) or open( ). Returns the number of characters written.

Syntax

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

<oRef>

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

<string expC>

The character expression to write to the specified file. If you want to write only a portion of <string expC> to the file, use the <characters expN> argument.

<characters expN>

The number of characters of the specified character expression <string expC> to write to the specified file, starting at the first character in <string expC>. If omitted, the entire string is written.

<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:

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

Property of

File

Description

Use puts( ) to write text files. puts( ) writes a character string and one or two end-of-line characters to a file. If the file was opened in append-only or read and append mode, the string is always added to the end of the file. Otherwise, the string is written starting at the current file pointer position, overwriting any existing characters. You must have either write or append access to use puts( ).

puts( ) returns the number of bytes written to the file, including the end-of-line character(s). If puts( ) returns 0, no characters were written. Either <string expC> is an empty string, or the write was unsuccessful.

Use error( ) to determine if an error occurred.

When puts( ) finishes executing, the file pointer is located at the character immediately after the last character written, which is the end-of-line character. Successive puts( ) calls writes one line after another. Use seek( ) to move the file pointer before or after you use puts( ).

To write to a file that is not a text file, use write( ). write( ) does not add the end-of-line character(s). To read from a text file, use gets( ). writeln( ) is identical to puts( ).