chars_waiting

Gamma: Version 4.0
Prev |  | Next

# `chars_waiting`

`chars_waiting` -- checks for characters waiting to be read on a file.

## Syntax

    chars_waiting (file)

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

## Returns

The number of characters waiting on the open file.

## Description

This function determines whether there are any characters waiting to be read on the given file. The file may be a string file (created by `open_string`), in which case the number of characters which have not yet been treated by a `read` or similar call will be returned.

If `chars_waiting` is to be called on a file after it has been partially read, the file must be unbuffered first with `unbuffer_file`. Otherwise characters will be read in buffer by buffer and held locally in groups of 1024. This will cause `chars_waiting` to return unexpected results.

## Example

        Gamma> ft = open("mytestfile.dat", "r");
        #<File:"mytestfile.dat">
        Gamma> unbuffer_file(ft);
        #<File:"mytestfile.dat">
        Gamma> chars_waiting(ft);
        9
        Gamma> char(read_char(ft));
        "A"
        Gamma> chars_waiting(ft);
        8
        Gamma> read_line(ft);
        "BCDEFGHI"
        Gamma>

        Gamma> x = open_string("hello");
        #<File:"String">
        Gamma> chars_waiting(x);
        5
        Gamma> char(read_char(x));
        "h"
        Gamma> chars_waiting(x);
        4
        Gamma>

## See Also

`open`, `open_string`, `unbuffer_file`

Prev | Home | Next
`cd` | Up | `directory`

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