file_into_string/
lib.rs

1//! # file_into_string Rust crate
2//! 
3//! Read a typical text file into a string or vector of strings.
4//! 
5//! * `file_into_string(file: File) -> std::io::Result<String>`
6//! 
7//! * `file_into_strings(file: File) -> std::io::Result<Vec<String>>`
8//! 
9//! Examples:
10//! 
11//! ```rust
12//! use std::fs::File;
13//! use file_into_string::*;
14//! 
15//! // Open an existing text file; read the File into a String.
16//! let file = File::open("example.txt").unwrap();
17//! let string = file_into_string(file).unwrap();
18//! 
19//! // Open an existing text file; read the File into a Vec<String>.
20//! let file = File::open("example.txt").unwrap();
21//! let strings = file_into_strings(file).unwrap();
22//! ```
23//! 
24//! ## Install
25//! 
26//! You can use this Rust crate:
27//! 
28//! ```toml
29//! [dependencies]
30//! file_into_string = "*"
31//! ```
32//! 
33//! Or if you prefer, you can copy the source code into your own program.
34//! 
35//! ## Notes
36//! 
37//! These functions deliberately preserve line endings,
38//! which are `\n` newlines and `\r` carriage returns.
39//! 
40//! These functions use buffered readers for efficiency.
41//! 
42//! These functions are written to be easy to understand,
43//! so you can copy them into your own code if you wish.
44//! 
45//! If you're reading very large files, then you may prefer
46//! to write your own code to process each line as it's read.
47//! 
48//! ## Tracking
49//! 
50//! * Project: file-into-string-rust-crate
51//! * Version: 1.1.1
52//! * Created: 2022-10-01T22:58:34Z
53//! * Updated: 2022-10-12T21:56:45Z
54//! * Website: https://github.com/sixarm/file-into-string-rust-crate
55//! * Contact: Joel Parker Henderson <joel@joelparkerhenderson.com>
56//! * License: MIT OR Apache-2.0 OR GPL-2.0 OR GPL-3.0
57  
58use std::fs::File;
59use std::io::BufRead;
60use std::io::BufReader;
61
62/// Read a File into a String.
63/// 
64/// ```
65/// use std::fs::File;
66/// use file_into_string::*;
67/// 
68/// let file: File = File::open("example.txt").unwrap();
69/// let string: String = file_into_string(file).unwrap();
70/// ```
71/// 
72/// Note: this function deliberately preserves line endings,
73/// which are `\n` newlines and `\r` carriage returns.
74/// 
75pub fn file_into_string(file: File) -> ::std::io::Result<String> {
76    let mut string = String::new();
77    let mut reader = BufReader::new(file);
78    let mut buf = String::new();
79    let mut n: usize;
80    loop {
81        n = reader.read_line(&mut buf)?;
82        if n == 0 { break; }
83        string.push_str(&buf);
84        buf.clear();
85    }
86    Ok(string)
87}
88
89/// Read a File into a Vec<String>.
90/// 
91/// ```
92/// use std::fs::File;
93/// use file_into_string::*;
94/// 
95/// let file: File = File::open("example.txt").unwrap();
96/// let strings: Vec<String> = file_into_strings(file).unwrap();
97/// ```
98/// 
99/// Note: this function deliberately preserves line endings,
100/// which are `\n` newlines and `\r` carriage returns.
101/// 
102pub fn file_into_strings(file: File) -> ::std::io::Result<Vec<String>> {
103    let mut strings = Vec::<String>::new();
104    let mut reader = BufReader::new(file);
105    let mut buf = String::new();
106    let mut n: usize;
107    loop {
108        n = reader.read_line(&mut buf)?;
109        if n == 0 { break; }
110        strings.push(buf.clone());
111        buf.clear();
112    }
113    Ok(strings)
114}
115
116#[cfg(test)]
117mod tests {
118    use super::*;
119
120    static PATH: &str = "example.txt"; // The contents must be "lorem\nipsum\n"
121
122    #[test]
123    fn test_file_into_string() {
124        let file = std::fs::File::open(PATH).unwrap();
125        let s = file_into_string(file).unwrap();
126        assert_eq!(s, "lorem\nipsum\n");
127    }
128
129    #[test]
130    fn test_file_into_strings() {
131        let file = std::fs::File::open(PATH).unwrap();
132        let actual_strings = file_into_strings(file).unwrap();
133        let expect_strings = vec![String::from("lorem\n"), String::from("ipsum\n")];
134        assert_eq!(actual_strings, expect_strings);
135    }
136
137}
file_into_string/lib.rs

file_into_string/
lib.rs
