Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Specify that Reader::read doesn't return 0. #18289

Closed
wants to merge 1 commit into from
Closed

Specify that Reader::read doesn't return 0. #18289

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 11 additions & 9 deletions src/libstd/io/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -535,20 +535,22 @@ pub trait Reader {
// Only method which need to get implemented for this trait

/// Read bytes, up to the length of `buf` and place them in `buf`.
/// Returns the number of bytes read. The number of bytes read may
/// be less than the number requested, even 0. Returns `Err` on EOF.
///
/// # Error
/// # Return value
///
/// If the length of `buf` is 0, the return value is unspecified.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can this be changed to say that implementations may either return Ok(0) or Err(...) at their choosing? It seems like that shouldn't effectively limit implementations and it'll be good to forbid totally silly values like Ok(1123465234).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you have cases in mind where returning Ok(1) would be dangerous?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Methods that pass a buffer to read and then slice it down to the part that was filled will panic, for example.

///
/// Otherwise, on success, the number of bytes read is returned. The number of bytes
/// read may be less than the number requested, but not 0.
///
/// If an error occurs during this I/O operation, then it is returned as
/// `Err(IoError)`. Note that end-of-file is considered an error, and can be
/// inspected for in the error's `kind` field. Also note that reading 0
/// bytes is not considered an error in all circumstances
/// If an error occurs during the I/O operation, then it is returned as
/// `Err(IoError)`. Note that end-of-file is considered an error, and can be inspected
/// for in the error's `kind` field.
///
/// # Implementation Note
///
/// When implementing this method on a new Reader, you are strongly encouraged
/// not to return 0 if you can avoid it.
/// If you've reached EOF, return `Err(EndOfFile)`. If no data is available and you
/// don't want to block, return `Err(ResourceUnavailable)`.
fn read(&mut self, buf: &mut [u8]) -> IoResult<uint>;

// Convenient helper methods based on the above methods
Expand Down