read_n_chars

Gamma: Version 4.0
Prev |  | Next

# `read_n_chars`

`read_n_chars` -- reads and stores characters.

## Syntax

    read_n_chars (file, nchars)

## Arguments

`file`

  A file pointer to a previously opened file. This may be either a file in the file system, or a string opened for read and write.

`nchars`

  The number of characters to read.

## Returns

A buffer containing the characters read. The length of the return buffer is equal to the number of characters actually read. This function returns nil if no characters could be read.

## Description

This function reads the given number of characters from the file, without any form of translation, and builds a new buffer object in which to store them. If this function reaches the end of the file before all characters are read, then the buffer will be shorter than the requested number of characters.

## Example

An input file contains the following:

        To be or not to be, that is the question.

Successive calls to `read_n_chars` will produce:

        Gamma> ft = open ("myreadnfile.dat", "r");
        #<File:"myreadnfile.dat">
        Gamma> read_n_chars(ft,15);
        #{To be or not to}
        Gamma> read_n_chars(ft,18);
        #{ be, that is the q}
        Gamma> read_n_chars(ft,18);
        #{uestion.}
        Gamma> read_n_chars(ft,18);
        nil
        Gamma>

## See Also

`read_char`

Prev | Home | Next
`read_line` | Up | `read_until`

Copyright 1995-2002 by Cogent Real-Time Systems, Inc.