Files & Data · 16 min · free lesson

Buffered Line Input

Separate a streaming parser from the place its bytes come from.

Core idea

A reader can fail between records; handle both I/O and parse errors.

Diagram for Buffered Line Input: a Rust code example flows to the lesson rule and the key observation.
BufRead, Cursor, and fallible iteration

Understand it

A file is a source of bytes, not a ready-made collection of valid records. Give the parser a generic R: BufRead input so the same function can accept a buffered file, locked stdin, or an in-memory Cursor. This separates the data transformation from permissions, paths, and device-specific I/O. It also makes the parser easy to exercise without creating a real file.

The lines() iterator yields io::Result<String> values. First handle the read result, then decide what a line means. For this small report, trim whitespace, skip blank lines, and parse every other line as i64. A malformed nonblank line is an error, not a zero and not a reason to silently discard the record. Include the one-based physical line number in that error, even when earlier lines were blank.

Use checked_add when the accepted numeric domain can overflow the accumulator. Returning a clear error preserves the contract instead of making behavior depend on a debug or release overflow setting. Streaming avoids retaining every record, but one unusually long line can still allocate a large string. A production parser needs a separate record-size limit; buffering alone is not a memory quota.

Local compiler profile: standard library only. The lab uses Cursor and needs no filesystem permission, package download, network request, or backend execution. Once the parser is correct, a desktop adapter can pass BufReader::new(File::open(path)?). In Crabrix, an adapter must use files granted to its sandbox. Keep the transformation independently testable before adding that adapter.

Read the code

use std::io::{BufRead, Cursor};
fn main() {
    let input = Cursor::new("12\n\n8\n");
    for line in input.lines() {
        println!("{}", line.unwrap());
    }
}

BufRead, Cursor, and fallible iteration

Try it

Implement total(reader): skip blank lines, sum trimmed i64 records with checked_add, return line N for the first malformed physical line, overflow for arithmetic overflow, and read failed for an I/O failure. In the Crabrix app, open the compiler lab and complete the supplied function in solution.rs. The reading question is a separate exercise.

What success looks like: The local compiler accepts the changed solution and the separate verification harness finishes all normal and boundary cases. Printing a success message alone does not complete this lab.

Check your understanding

Why can filter_map(Result::ok) silently corrupt this report?

Reveal the answer
  1. It turns every successful line into bytes
  2. It drops read failures instead of reporting incomplete input
  3. It forces all numbers to zero

Dropping errors can produce a believable total from only part of the input. Propagate read failures and identify malformed records.

Go deeper

Common misconception: A buffered reader has already validated every record.

Buffering changes how bytes are read; parsing and error policy are separate.

  1. Read: Unwrap each fallible line before parsing its contents.
  2. Validate: Track the physical line number and reject invalid integers.
  3. Accumulate: Add with overflow detection and return one result.

Transfer challenge: Replace Cursor with a deliberately failing Read implementation. Confirm the report returns an error rather than a partial total.

Connections

  • Paths & Boundaries: Path, PathBuf, and lexical validation