The Rust source file (.rs)

The basics

What is an RS file?

Anatomy

What's inside a Rust file

A Rust file is a list of items: use declarations, types, functions, modules and constants, in any order. Statements only appear inside functions. Here is a small but complete program that converts a temperature, with a unit test at the bottom, part by part.

//! A tiny temperature converter.
use std::env;

#[derive(Debug)]
struct Reading {
    celsius: f64,
}

impl Reading {
    fn fahrenheit(&self) -> f64 {
        self.celsius * 9.0 / 5.0 + 32.0
    }
}

fn parse(arg: &str) -> Result<Reading, String> {
    let celsius: f64 = arg.parse().map_err(|_| format!("not a number: {arg}"))?;
    Ok(Reading { celsius })
}

fn main() {
    let arg = env::args().nth(1).unwrap_or_else(|| String::from("20"));
    match parse(&arg) {
        Ok(r) => println!("{}°C is {:.1}°F", r.celsius, r.fahrenheit()),
        Err(e) => eprintln!("error: {e}"),
    }
}

#[cfg(test)]
mod tests {
    #[test]
    fn boiling() {
        assert_eq!(super::parse("100").unwrap().fahrenheit(), 212.0);
    }
}

1. 1//! A tiny temperature converter.

   A documentation comment

   //! documents the file or crate it's in; /// documents the item below it. cargo doc turns both into HTML pages. Ordinary comments use // or /* … */.

2. 2use std::env;

   A use declaration

   Brings a module from the standard library (std) into scope, so the code can write env::args() instead of the full path.

3. 3#[derive(Debug)]

   An attribute

   #[…] attaches information to the next item. derive asks the compiler to write a trait implementation, here the one that lets {:?} print the struct.

4. 4struct Reading { celsius: f64 }

   A struct

   A type with named fields. Rust has no classes: data lives in structs and enums, behaviour in impl blocks and traits.

5. 5impl Reading { fn fahrenheit(&self) … }

   A method

   &self means the method borrows the value instead of taking ownership of it. The last expression without a semicolon is the return value.

6. 6-> Result<Reading, String>

   A Result

   Rust has no exceptions for ordinary errors. A function that can fail returns Ok(value) or Err(error), and the caller has to deal with both.

7. 7map_err(…)?

   The ? operator

   If the parse failed, ? returns the error from parse straight away; otherwise it unwraps the value. format! builds a String, and {arg} inserts the variable.

8. 8fn main()

   The entry point

   Where the program starts. A crate whose root file has fn main compiles to an executable; a library's root, lib.rs, has none.

9. 9match parse(&arg) { Ok(r) => …, Err(e) => … }

   A match

   Picks a branch by the shape of the value. The compiler refuses a match that doesn't cover every case.

10. 10println!(…) / eprintln!(…)

    Macros

    The ! marks a macro, code that expands at compile time. These print to standard output and standard error; the format string is checked when the program is compiled.

11. 11#[cfg(test)] mod tests { #[test] … }

    A unit test

    Compiled only by cargo test or rustc --test, so it adds nothing to the normal program. Tests live in the same file as the code they test.

How to

How to compile and run a .rs file

Projects

Cargo.toml, main.rs, lib.rs and mod.rs

converter/
├── Cargo.toml        the manifest: name, edition, dependencies
├── Cargo.lock        exact dependency versions (written by Cargo)
├── src/
│   ├── main.rs       the program's entry point (fn main)
│   ├── lib.rs        a library crate, if the package has one
│   ├── units.rs      module "units", declared with: mod units;
│   └── bin/
│       └── extra.rs  a second executable
├── tests/            integration tests
├── examples/         example programs (cargo run --example name)
└── target/           build output, not committed to version control

[package]
name = "converter"
version = "0.1.0"
edition = "2024"

[dependencies]
serde = { version = "1", features = ["derive"] }

Versions

Rust editions: 2015, 2018, 2021 and 2024

Tooling

cargo fmt, cargo clippy and cargo test

Related formats

The files around a .rs file, and how Rust compares

Troubleshooting

The Rust compile errors people hit most

How to

How to open and edit a .rs file, and is it safe?

Free downloads

Sample Rust files to download

Free sample Rust files for testing compilers, editors, CI pipelines, syntax highlighters, upload filters and size limits. Every sample except the deliberately broken one compiles with Rust 1.97 and passes cargo fmt --check and cargo clippy -- -D warnings in a 2024-edition package.

Loading…

What's inside sample-main.rs

The file is commented: open it in a text editor and each numbered comment marks one of these parts. Compile it with rustc --edition 2024 sample-main.rs and run the result: it prints a total per person, and reports one line it skipped.

1. Comments 1 to 4: types

   A use declaration, a struct and an enum with #[derive], and an impl block whose match turns a text label into an enum value.

2. Comment 5: an error type

   An enum of the ways parsing can fail, and a Display implementation that turns each into a readable message.

3. Comments 6 and 7: Result, ? and Option

   parse_line returns a Result and uses let … else and ?; parse_cents returns an Option and keeps money in whole cents with overflow-checked arithmetic.

4. Comments 8 and 9: borrowing and iterators

   A function that borrows the list and returns a BTreeMap whose keys borrow from it, then filter, map and sum on an iterator.

5. Comments 10 and 11: data and main

   The input is a string constant with five lines, one of them invalid. main collects the good lines, prints the bad one to standard error with eprintln!, and prints totals: €49.75 for Ada Example, €138.90 for Ben Example.

6. Comment 12: unit tests

   Three #[test] functions in a #[cfg(test)] module. rustc --edition 2024 --test sample-main.rs -o sample-tests builds a test runner; running it reports 3 passed.

All sample Rust files

• Commented sample program

  sample-main.rs · 5.9 KB (6,059 bytes)

  A complete command-line program: structs, enums, traits, Result and ?, borrowing, iterators and a unit-test module, with numbered comments explaining each part. Compiles with rustc alone, no dependencies.

  • Checking a compiler, CI job or syntax highlighter on modern Rust
  • Teaching the building blocks of a Rust program
  DownloadOpen

• Library crate (lib.rs) with doc tests

  sample-lib.rs · 4.6 KB (4,734 bytes)

  A library root as it would sit in src/lib.rs of a package named sample-lib: public functions, a trait with a default method, a generic function, //! and /// documentation with examples that cargo test runs as doc tests, and unit tests.

  • Testing `cargo test`, `cargo doc` and doc-test handling
  • An example of a documented public API
  DownloadOpen

• UTF-8 with BOM and CRLF line endings

  sample-unicode-bom-crlf.rs · 1.9 KB (1,913 bytes)

  Starts with the UTF-8 byte order mark EF BB BF and uses Windows line endings throughout. Prints six sample strings (Latin, Greek, Japanese, Arabic, emoji) with byte and character counts, and shows that rustc ignores the BOM and reads CRLF as LF, even inside a string literal.

  • Testing editors, linters and diff tools on BOM and CRLF files
  • Showing `len()` (bytes) vs `chars().count()`
  DownloadOpen

• Deliberately broken file (does not compile)

  sample-compile-error.rs · 1.3 KB (1,296 bytes)

  Clearly labelled at the top: it fails with E0382 (use of a moved value) and E0502 (conflicting borrows), and its comments give the fix for each. Nothing in it is harmful.

  • Checking how editors and CI jobs report compile errors
  • Teaching ownership and borrowing errors
  DownloadOpen

• 100 KB Rust file

  sample-100kb.rs · 100 KB (102,400 bytes)

  A program with a table of the first 13,200 prime numbers that checks every one, padded with comment lines to exactly 102,400 bytes. Needs Rust 1.87 or later.

  • Upload and size-limit tests
  • Editor, highlighter and formatter performance
  DownloadOpen

Ways to test with them

• Compiler and CI: build sample-main.rs and sample-100kb.rs; both should compile without warnings and print their results. sample-compile-error.rs should fail with exactly two errors, E0382 and E0502.
• Editions: compile sample-main.rs with plain rustc and then with --edition 2024. It uses let … else, which works in every edition, so both succeed; it's a quick way to show that a bare rustc defaults to 2015 without breaking anything.
• Encodings and line endings: open sample-unicode-bom-crlf.rs in your editor, run it through rustfmt and your diff tool, and check the BOM and the CRLF endings survive (or are converted the way you expect).
• Upload limits: sample-100kb.rs is exactly 102,400 bytes, for testing a limit at the boundary.

Free to use for testing, teaching and demos, commercially or not, with no attribution needed. A link back to this page is always appreciated.

Questions

Rust files, frequently asked