File

Render the reader without exposing its host handle.

Read at most max_bytes bytes. Short reads are valid, even before the end of the file. Asking for zero bytes performs no I/O and returns Ok([]); otherwise the result is never empty, and the end of the file is Err(EndOfInput). Returned bytes remain valid after later reads or seeks.

Read exactly count bytes, or report UnexpectedEndOfInput. Zero succeeds without I/O. Errors may consume bytes; partial data is not returned and the cursor is not restored.

Read bytes through and including the next delimiter.

If the file ends first, the bytes before the end are returned without a delimiter, and the read after that is Err(EndOfInput). So the result is never empty, and its last byte shows whether the delimiter arrived: to follow a growing file line by line, use reader.read_until!('\n') rather than [read_line!].

Read a line of text.

A line ends at \n. The terminator is not returned, and one \r before it is removed. A file that ends without a \n still yields its last line; after that the result is Err(EndOfInput). An empty line is Ok(""). Lines have no length limit.

A line that is not valid UTF-8 is consumed and reported as BadUtf8; the next call reads the line after it. For the bytes of a line, use reader.read_until!('\n').

Return the byte position of the next read, accounting for buffered bytes.

Move the shared cursor and return its new absolute byte position. Seeking past EOF does not extend the file. Invalid offsets and sources that cannot seek report FileErr. A failed seek need not restore the cursor. Aliases of this reader observe the same cursor.

Lazily read this reader a line at a time, as [read_line!] does.

Building the stream reads nothing. The stream ends at the end of the file. A BadUtf8 item concerns one line, and the stream continues with the next. A FileErr item is the last one; the reader stays usable and a new stream may be started.

Each item is one read from the shared cursor and the stream holds no data of its own, so it can be mixed with [seek!], [position!] and the other reads, and leaving the loop early loses nothing.

for! item in reader.lines() {
    match item {
        Ok(line) => Stdout.line!(line)?
        Err(BadUtf8(_)) => {}
        Err(FileErr(err)) => { return Err(FileErr(err)) }
    }
}

The stream keeps the file open until it has finished or is released.

Lazily read this reader as non-empty chunks of at most 64 KiB. Chunk boundaries do not correspond to records, newlines, or text encoding boundaries. For a chosen size, call [read_up_to!] in a loop.

Building the stream reads nothing; each item is one read from the shared cursor. The stream ends at the end of the file. A FileErr item is the last one; the reader stays usable and a new stream may be started, for example after a [seek!]. Retained chunks remain valid.

for! item in reader.chunks() {
    bytes = item?
    $total = $total + bytes.len()
}

The stream keeps the file open until it has finished or is released. Process chunks individually to bound memory; Stream.collect! accumulates every chunk.

Render the writer without exposing its host handle.

Write all of bytes, to the buffer or to the file.

Write all of text as UTF-8, to the buffer or to the file. No line ending is added.

Write each chunk of a stream as it arrives, holding one chunk in memory at a time.

Stops at the first Err item, which is returned as SourceErr; the chunks before it have been written. A failed write is FileErr. Nothing is flushed at the end.

Any stream of byte chunks will do: reader.chunks(), Stdin.chunks(), the response.chunks() of an Http.send_streaming! response, or a stream mapped from one of them.

reader = File.open_reader!(source)?
File.with_writer!(destination, Truncate, |writer|
    writer.write_stream!(reader.chunks().map(|chunk| chunk.map_ok(redact))))?

Hand every buffered byte to the operating system.

This is the call that reports whether the bytes written so far reached the file. It does not force them to the storage device.