Read_to_string() Function vs read_to_string() Method

help
1

I'm still really new to rust, but it's been fascinating so far. Forgive me if some of my syntax is off. I'm still getting used to statically/strongly-typed languages again.

I noticed that read_to_string() can either be used as a module-level function, or as a method of sorts (still learning/remembering rust's terminology) that's attached to the File handle object. Are these two different functions though? They seem to be, but I can't find docs that define both of them.

The module-level version appears to take a single string param for the file name, and return a Result<T, E> like so:

let contents = fs::read_to_string("readme.txt").expect("Invalid file");

fs::read_to_string() is pretty straightforward: provide a file/path, and it'll string that contains the contents of the file wrapped in a Result if all goes well.

The read_to_string() method that is attached to a File object seems less straightforward:

let f = File::open("readme.txt").expect("Invalid file");
let mut contents = String::new();

match f.read_to_string(&mut contents) {
  Ok(_) => println!("loaded file: {}", contents),
  Err(e) => println!("error occurred: {}", e);
};

Since this is a File handle object, it can be assumed that the file is already opened, and so it appears to take a mutable string to serve a memory location of where to allocate and fill the contents with the file's data. Still makes sense. It also appears to return a Result<T, E> in case of errors, which makes sense for errors, but not for succeses. What does the Ok() variant return? Is it just a unit()? How come read_to_string() takes a mutable reference in this case? Couldn't that method instantiate a new string within its implementation details, and return the newly-allocated string in its Ok() variant instead like fs::read_to_string() does?

My only guess is that this somehow violates the borrow checker because this function is a method that's attached to an object, and this goes the memory/scoping rules that the borrow checker is supposed to enforce. Does that sound about right?

I've gone through the borrow checker stuff a lot, but I'm still wrapping my head around it.

2

The read_to_string function on the Read trait (which File implements) returns the number of bytes read on success in the ok variant. As for returning a String, yes that would also be possible, but the current design allows reuse of an existing allocation.

3

Agh, so it's because it conforms to a trait. Returning the number of bytes actually written upon success makes complete sense to me now too. Thanks, @alice!

4

When calling the read_to_string() method on a File you need an &mut because reading from a file will mutate it. For example if I were to read 128 bytes from a file, its internal position would be moved forward by 128 bytes.

The &mut self in the method signature means you're able to mutate self, so it isn't related to mutating the buffer (passed in as the buf: &mut [u8] parameter) instead of returning a newly allocated string.

For example, this is perfectly valid in Rust:

use std::{
    error::Error,
    io::{self, Write},
};

struct Person {
    name: String,
}

impl Person {
    pub fn copy_name_to_buffer(&self, mut buffer: &mut [u8]) -> Result<usize, io::Error> {
        buffer.write(self.name.as_bytes())
    }
}

fn main() -> Result<(), Box<dyn Error>> {
    let mut buffer = [0; 256];
    let person = Person {
        name: String::from("Michael"),
    };

    let bytes_written = person.copy_name_to_buffer(&mut buffer)?;
    let name = std::str::from_utf8(&buffer[..bytes_written])?;

    println!("My name is {}", name);

    Ok(())
}

(link to the playground if you want to experiment)

5

Strictly speaking this is not true. There's impl<'a> Read for &'a File in stdlib. Concurrenty of file handle's internal state is managed by the kernel so user process cannot trigger data race on it. The reason why Read::read_to_string() takes &mut self is to allow more types like &[u8] or VecDeque<u8> to impl Read on it.

2 Likes
6

Oh yeah, I forgot about the file object's internal cursor position. That makes sense.

7

to answer another of your questions, the read_to_string method takes a String buffer instead of allocating a String internally, so you can control the allocation. for example, you might want to allocate one string, and reuse its capacity to read every file in a directory, processing the contents in the body of a loop, and then clearing the contents for three next file's contents. this can be a big performance win in many circumstances.

1 Like
8

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.