14 March 2023
After getting into some of the fundamentals of Rust with traits, generics, and lifetimes, we’ll take a look at something more pedestrian today: reading and writing text.
We’ll start with reading a file line-by-line:
use std::fs::File;
use std::io;
use std::io::{BufRead, BufReader};
fn main() -> io::Result<()> {
let file = File::open("foo.txt")?; // open for reading
let reader = BufReader::new(file);
for line in reader.lines() {
println!("read from file: {}", line?);
}
Ok(())
}The tools we use are File::open, which opens a file read-only, BufReader, which provides buffering and methods to read data one line at a time, and the lines method, which returns an iterator over the lines in the file.
If you’re paying close attention you may have noticed that I’m
importing the std::io::BufRead trait, but then it doesn’t
appear anywhere else in the code. The reason is a rule in Rust that can
be suprising to those new to the language (it was for me, anyways): if
you want to use a method defined in a trait, you have to import the
trait, not just the concrete type that implements the method. In this
case the lines method is defined in BufRead.
In the standard library, functions that do input or output usually
return std::io::Result
to enable proper error handling in case something goes wrong. In the
example, I’ve defined main to return
io::Result<()> to simplify error handling (see Rust: Functions). Notice the two
question marks in the code pointing out where something could go wrong:
opening the file and reading a line.
To read a whole file in one go, you can use the read_to_string
method, defined in the Read trait:
use std::fs::File;
use std::io;
use std::io::Read;
fn main() -> io::Result<()> {
let mut file = File::open("foo.txt")?;
let mut buffer = String::new();
file.read_to_string(&mut buffer)?;
println!("whole file:\n{}", buffer);
Ok(())
}If you want to read from standard input instead of a file, you can
use the stdin
function. It returns an Stdin
object, which like File implement the Read
trait. It also has a lines method that lets us iterate over
input lines without using a BufReader:
use std::io;
fn main() -> io::Result<()> {
let stdin = io::stdin();
for line in stdin.lines() {
println!("read from stdin: {}", line?);
}
Ok(())
}If you want to write a text file, open it with File::create, then use the write_all method to write a string, or the write! and writeln! macros for formatted output. This example shows both:
use std::fs::File;
use std::io;
use std::io::Write;
fn main() -> io::Result<()> {
let mut file = File::create("foo.txt")?; // open for writing
file.write_all("Hello, world!\n".as_bytes())?; // write string
writeln!(file, "{} plus {} is {}", 2, 2, 4)?; // formatted output
Ok(())
}File::create creates the file if it doesn’t exist, and truncates it (deletes its content) it if does. If that’s not what you want, take a look at File::options instead.
I’m using write_all here instead of the write
method because write doesn’t guarantee that it writes the
whole buffer. If you use write, you need to check its
return value and call it repeatedly until all data is written.
To write to standard out you can obviously just use
print! and println!, but sometimes it’s useful
to treat standard out like a file. For those cases, std::io::stdout
returns a file-like object:
use std::io;
use std::io::Write;
fn main() -> io::Result<()> {
let mut file = std::io::stdout();
file.write_all("Hello, world!\n".as_bytes())?; // write string
writeln!(file, "{} plus {} is {}", 2, 2, 4)?; // formatted output
Ok(())
}To use standard error instead, replace println! with
eprintln! and std::io::stdout with
std::io::stderr.
So far we haven’t paid much attention to error handling: if you
define main to return a Result, you can just
return an error. That’s fine for sample code, but for a real project
you’d probably want real error handling. Here’s another example reading
input line-by-line, this time with more explicit error handling:
use std::io;
fn main() {
for line in io::stdin().lines() {
match line {
Err(e) => eprintln!("error reading line: {}", e),
Ok(line) => println!("read line: {}", line),
}
}
}Let’s try it out by sending three lines of text on the command line:
$ printf 'Hello!\n¡Buenos días!\nBonjour!' |
> cargo run
read line: Hello!
read line: ¡Buenos días!
read line: Bonjour!As expected, we hit the Ok case three times.
How do we test the Err case? For text input, there’s an
easy way: text input is always expected to be valid UTF-8. We can use
the iconv utility to convert the input from UTF-8 to the old ISO-8859-1
encoding, then feed that into the program. Here’s what happens:
$ printf 'Hello!\n¡Buenos días!\nBonjour!' |
> iconv -f UTF-8 -t ISO-8859-1 |
> cargo run
read line: Hello!
error reading line: stream did not contain valid UTF-8
read line: Bonjour!The first and last line are the same in both encodings, so they’re
processed without issues, but when the ¡ and í
characters are converted to ISO-8859-1 we end up with bytes that aren’t
valid UTF-8 at all, and the iterator returns an Err
value.
Here’s code that writes a line to a file with very explicit error handling:
use std::fs::File;
use std::io::Write;
fn main() {
match File::create("foo.txt") {
Err(e) => {
eprintln!("error opening file: {}", e);
}
Ok(mut file) => {
if let Err(e) = file.write_all("Hello!\n".as_bytes()) {
eprintln!("error writing file: {}", e);
}
}
}
}If we just run it normally, it writes the file as expected:
$ cargo run
$ cat foo.txt
Hello!Let’s try to hit both Err cases to verify that they work
the way we’d expect. We have a lot of options here – many things can go
wrong when you’re writing to a file! A simple one is when the user
doesn’t have permission to open the file. On Linux or Mac OS we can use
the chmod utility to change permissions:
$ touch foo.txt && chmod 000 foo.txt && cargo run
error opening file: Permission denied (os error 13)That’s the first Err case. To test the second we can use
the /dev/full special file, which simulates a full disk.
(This works on Linux, not sure about Mac OS.) If we turn
foo.txt into a symlink to
/dev/full, it’ll also act like it’s on a full disk:
$ ln -s /dev/full foo.txt && cargo run
error writing file: No space left on device (os error 28)Neat!