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