Re: Reading a line of text from a stream



On Wed, 05 Mar 2008 12:07:46 -0800, Micah Cowan wrote:

Nelu <spamahead@xxxxxxxxx> writes:

I would appreciate some comments on the code below for reading a line
of text from a stream.
<snip>
/**
* Reads a line of text from a stream and returns the string on *
success and NULL on failure.
* fstream - the stream to read from
* maxRead - a variable that specifies the maximum number of *
characters to read. If maxRead is NULL then SIZE_MAX-1 is * considered
as the maximum value. If maxRead is different from NULL * then the
function will set the value to the length of non-NULL * string
returned by the function.

You've accidentally left out documentation that if maxRead is not NULL,
it will be used to set an upper limit on the line read.

The documentation above is also a bit hard to read; it'd be nice if it
were easier to find the start of each parameter description. Perhaps by
indenting continuation lines:

* maxRead - a variable that specifies the maximum number of *
characters to read. If maxRead is NULL then SIZE_MAX-1
...

You've also neglected to explicitly specify that the terminating "\n"
will not be included in the string.

IME documentation tends to get out-of-sync with the code pretty quickly,
even when it doesn't already start out that way. My preference is to
document it in the form of readable test cases that demonstrate the
supported use cases (if the function itself can't be made so readable as
to make its usage obvious). Of course, I realize that various shops have
various documentation requirements, let alone individual preferences.

The documentation was just a late addition and I didn't spend time on it.
I was more interested in the correctness of the code.


It's a personal preference thing, but I dislike that you're overloading
maxRead's meaning to both specify an optional maximum _and_ receive the
size of the string. It makes things cumbersome for callers that may
desire one function or the other, but not both. The one who merely
wishes to specify an upper length may have to copy their value into a
"receiving" object, passing its pointer; the one who wants the length
but not an upper length either has to pass a var preset to SIZE_MAX-1,
or to call strlen() after.

Fair enough.

<snip code>
The above check and potential realloc() could have been avoided, if you
instead checked for stringLength+1==capacity at the previous if
statement that I marked.

Good point.


This design suffers from a couple of difficiencies (IMO):
- It is not possible to distinguish between an empty line and EOF. -
It is not possible to distinguish between I/O failures and allocation
failures (both return NULL).


I was thinking about adding these then I thought that it would get to be
uglier than it already is.




Thank you.


--
Ioan - Ciprian Tandau
tandau _at_ freeshell _dot_ org (hope it's not too late)
(... and that it still works...)

.



Relevant Pages

  • Re: Reading a line of text from a stream
    ... Reads a line of text from a stream and returns the string on ... If maxRead is NULL then SIZE_MAX-1 is ... The documentation above is also a bit hard to read; ... You've also neglected to explicitly specify that the terminating "\n" ...
    (comp.lang.c)
  • Re: John Resig has a new idea
    ... empty styleSheets collection, ... documentation, the behavior is unexpected. ... the property name is an "integer index", ... This index would be provided as a string for property access. ...
    (comp.lang.javascript)
  • Re: Anyone heard of Bee Lisp?
    ... so I took a quick look at the documentation. ... CAR/CDR/CONS - seems to work on lists instead of cons cells. ... QUOTE - Prevents evaluation of the parameter. ... STRREAD - reads a string from the console ...
    (comp.lang.lisp)
  • Re: another docs problem - imp
    ... > The first sentence says that the _path_ argument is a search path. ... Correct it does not say it's a string. ... > technical documentation a bit more carefully. ... Yes, read it a second time, didn't see the alternate interpretation. ...
    (comp.lang.python)
  • Re: empty vs null
    ... The documentation you refer to is for the System.String type, ... though they moved to being immutable reference types. ... to Vb.NET, suddenly we could actually compare string references, and at the same ... > references compare equal to each other. ...
    (microsoft.public.dotnet.languages.vb)