squiid/rust
1
0
Fork 0
Code Issues Pull requests Projects Activity

Elaborate a bit in the Reader docs regarding stream position.

Browse source 
Had a conversation with @cmr in IRC about some places that these
docs were confusing. The functions that advance the stream now say so.

In addition, I think that calling out the similarities to familliar C
functions should help people coming from other languages.
This commit is contained in:
Steve Klabnik 2013-05-19 12:57:00 -07:00
parent 9f671698e6
commit 1065a92bf3
1 changed files with 13 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
src/libcore/io.rs
View file

@ -84,14 +84,16 @@ pub trait Reader {
// FIXME (#2982): This should probably return an error.
/**
* Reads bytes and puts them into `bytes`. Returns the number of
* bytes read.
* Reads bytes and puts them into `bytes`, advancing the cursor. Returns the
* number of bytes read.
*
* The number of bytes to be read is `len` or the end of the file,
* whichever comes first.
*
* The buffer must be at least `len` bytes long.
*
* `read` is conceptually similar to C's `fread`.
*
* # Examples
*
* None right now.
@ -99,10 +101,12 @@ pub trait Reader {
fn read(&self, bytes: &mut [u8], len: uint) -> uint;
/**
* Reads a single byte.
* Reads a single byte, advancing the cursor.
*
* In the case of an EOF or an error, returns a negative value.
*
* `read_byte` is conceptually similar to C's `getc` function.
*
* # Examples
*
* None right now.
@ -112,6 +116,8 @@ pub trait Reader {
/**
* Returns a boolean value: are we currently at EOF?
*
* `eof` is conceptually similar to C's `feof` function.
*
* # Examples
*
* None right now.
@ -124,6 +130,8 @@ pub trait Reader {
* Takes an optional SeekStyle, which affects how we seek from the
* position. See `SeekStyle` docs for more details.
*
* `seek` is conceptually similar to C's `fseek`.
*
* # Examples
*
* None right now.
@ -133,6 +141,8 @@ pub trait Reader {
/**
* Returns the current position within the stream.
*
* `tell` is conceptually similar to C's `ftell` function.
*
* # Examples
*
* None right now.