0000010: Documentation of Pervasives.input

View Issue Details [ Jump to Notes ]

[ Issue History ] [ Print ]

Project

Category

View Status

Date Submitted

Last Update

0000010

OCaml

OCaml general

public

1999-12-20 11:23

2000-02-07 14:19

Reporter

administrator

Assigned To

Priority

normal

Severity

minor

Reproducibility

always

Status

closed

Resolution

fixed

Platform

OS Version

Product Version

Target Version

Fixed in Version

Summary

0000010: Documentation of Pervasives.input

Description

Full_Name: Norman Ramsey
Version:
OS:
Submission from: estephe.inria.fr (128.93.11.95)
Submitted by: xleroy

The documentation for input needs to be improved.
The existing documentation reads as follows:

  val input : in_channel -> string -> int -> int -> int

     input chan buff ofs len attempts to read len characters from
     channel chan, storing them in string buff, starting at character
     number ofs. It returns the actual number of characters read,
     between 0 and len (inclusive). A return value of 0 means that the
     end of file was reached. A return value between 0 and len
     exclusive means that no more characters were available at that
     time; input must be called again to read the remaining
     characters, if desired. Exception Invalid_argument "input" is
     raised if ofs and len do not designate a valid substring of buff.


The key phrase is ``no more characters were available at that time.''
I interpreted this to mean if I read from an ordinary disk file, I
would be guaranteed to get as many characters as were available.
Boy, was I wrong. If I try to read 31 characters at offset 4092 from
a 120696-character file, I get only 4 characters. What a surprise!

I would prefer the following wording:

     input chan buff ofs len reads up to len characters from channel
     chan, storing them in string buff, starting at character number
     ofs. It returns the actual number of characters read, between 0
     and len (inclusive). A return value of 0 means that the end of
     file was reached. A return value between 0 and len exclusive
     means that the implementation did not find it convenient to
     return len characters; input must be called again to read the
     remaining characters, if desired. Exception Invalid_argument
     "input" is raised if ofs and len do not designate a valid
     substring of buff.

I would have used really_input, except I didn't find a way to figure
out how many characters were read before the end of file.

Issue History
Date Modified	Username	Field	Change
2005-11-18 10:13	administrator	New Issue

Notes
(0000286) administrator (administrator) 2000-02-07 14:19	Fixed in 3.00

Relationships