ralfbiedert / cheats.rs

Rust Language Cheat Sheet - https://cheats.rs

Rust Language Cheat Sheet

A single-page Rust resource for people who like high information density.

Use cases, in order of priority:

• identification & lookup guide for constructs encountered in code,
• discover parts of the language you might not know,
• learn about Rust if you have prior programming experience.

Building

Built with Zola, the static site generator written in Rust. See .zolaversion for the exact version the official site was deployed with. To develop locally download the indicated version, then run:

zola serve

Contributing

Contributions are welcome and you can PR bug fixes directly. If you somehow ended up here but prefer not to use Github write to [email protected], or use the on-site buttons.

Constructive feedback would be most actionable, but if you just want to vent your frustration that's fine too :)

Credits

Big shout-out to all the contributors and people filing issues and pull requests for being awesome!

Also:

• The Bronshtein and Semendyayev Handbook of Mathematics, the mother of all cheat sheets
• The Book (some tables)
• Idiomatic Rust Libraries (idiomatic Rust)
• Ferris (Rust mascot by Karen Rustad Tölva)
• Rust container cheat sheet (for data layout; Raph Levien)
• That one IEEE 754-2008 Powerpoint deck I can't find anymore ...
• String Conversions
• steffahn from users.rust-lang.org (for outstanding explanations)
• eddyb for feedback and explanations

FAQ

Answers to frequently asked questions can be found here.

Legal & License

Please see here for details.

cheats.rs's Issues

Have ways to grow

The site started as a language cheat sheet, but increasingly gets other cheats added, like tooling or formatting.

I very much like these additions, but they might conflict with with the one-page design and CTRL-F serchability. My two main concerns are:

• Glossability - Will a user get overwhelmed when browsing the page?
• Syntax highlighting time - On slower machines one can already feel a bit the delay of syntax highlighting the page, and scrolling also started to feel a tiny bit sluggish.

An idea could be to "fold" certain sections by default:

• They would still be part of the page
• But with JavaScript we only highlight them once unfolded.
• Also, how searching and folding work together would have to be investigated.

extern "C" fn

extern "C" fn is currently listed as “External dependency for FFI”. I don't think that's correct. That is what extern "C" { ... } is. extern "C" fn just specifies the calling convention.

What criteria for 3rd party cargo tools?

A few 3rd party cargo xxx commands have been added, and they seem useful.

However, there are several dozen, if not hundreds cargo helpers out there, and we can't list them all.

What should be the criteria for being listed?

• Downloads on crates.io > X?
• Stars on Github > Y?
• Actively maintained?
• Being cross-platform?

Considering using online hosted fonts especially Fira Code for your website

That would make the website much more cleaner and not rely on users fonts.

This is so awesome!

Feel free to close this "issue". Just wanted to let you know 😄

Add special `$crate` macro token

"Rust does not (yet) have a hygiene system for crate references, but it does provide a simple workaround for this problem. Within a macro imported from a crate named foo, the special macro variable $crate will expand to ::foo. By contrast, when a macro is defined and then used in the same crate, $crate will expand to nothing. This means we can write..."

https://doc.rust-lang.org/1.7.0/book/macros.html

Futures

Very useful. Thank you.

Could you perhaps include https://rufflewind.com/img/rust-futures-cheatsheet.html or the equivalent?

The same for Option/Result would be very useful too.

Lifetime ellision example is wrong

The code for lifetime ellision is wrong
Automatically annotate f(x: &T) to f(x: &'a T).
should be
Automatically annotate f(x: &T) to f<'a>(x: &'a T).

Here is the link to the wrong part: https://cheats.rs/#invisible-sugar
The code links to https://doc.rust-lang.org/book/ch10-03-lifetime-syntax.html#lifetime-elision, which also states, that there has to be <'a>.

suggestion: add a link to the cookbook

Maybe under books or cheat sheets there should be a link to the rust cookbook https://rust-lang-nursery.github.io/rust-cookbook/, for examples on doing common programing tasks in rust # #

examples for macro captures

I think it's very hard for new people to figure out what kind of captures should be used for certain types of code.

For example is this a pattern?:

match value {
    1 => 2
}

or

1 => 2

or

{
   1 => 2
}

Therefore the Explanation should include a bit more than just

"$x:pat is a pattern. (I guess that's obvious from the name itself)"

Angular brackets should be mentioned for trait disambiguation syntax, e.g: <X as Trait>::Assoc

(Comment from Reddit)

Unclear description of signed integer ranges

The footnote in the "Numeric Types" section says

• i8, i16, ... values range from -max/2 to max/2-1, rounded to larger value.

"Larger" is unclear when used in the context of negative numbers. It may refer to the absolute value as implied here, so -128 is "larger" than -127.5, or it may be a synonym of "greater than", in which case -127 is "larger" than -127.5.

It would be more clear to say something like "values range from -max/2 to max/2, rounded toward negative infinity."

Self-host fonts and remove Google Font dependency.

Is there a better way to do this than to copy the large font CSS generated by Google?

Fix minor rendering issues

• Header margin higher on bottom than on top
• iOS does not render "corner arrow"
• iOS does not render comments section
• iPhone / small display left column too wide, should use different media.

"Hardcoded magic"

From Reddit:

Next to the “invisible sugar” perhaps also provide ”hardcoded magic” for traits and other stuff that “seems” like a normal library item, but cannot be reimplemented by the user in terms of other items. For example, the traits “Copy”, “Clone”, “Deref”, etc.

`'b: 'a` operator commonly referred to as _outlives_

I've seen 'b: 'a often read as "'b outlives 'a". It may be worth updating the documentation to reflect that specific term.

Include "Captures" in the Cheat Sheet

It would be nice to include an overview of the things a macro accepts https://danielkeep.github.io/tlborm/book/mbe-macro-rules.html

suggestion: proc macro section

I can't seem to find any information about proc macros in cheats.rs. I feel like this is a relatively important part of the rust ecosystem and it deserves a section. Particularly with syn and quote just hitting their 1.0.0 releases, it seems like a good time to bring in some documentation for them.

I'd be happy to add one myself as a PR but I don't know proc macros well yet so it will have to wait until after I take the time to properly learn them.

Cheat Github Linguist into believing this is a Rust project.

No pun intended.

suggestion: rename code generation section

This is a minor nit but at first glance when I checked out this website I didn't think it had a section on macro_rules syntax. I think the section title "code generation" is a bit unintutitive.

Possible alternatives

• Macros
• Code Generation (macros)
• Macros & Attributes

Or anything really, so long as the string macro is in the title somehow, since that's the keyword everyone will expect to use when looking for this.

Add binary literals like `0b0000_1000`

Document break / continue labels.

Date should be automatically set on build.

Document data types?

• What exactly should be documented?
• Is this a table or a diagram?
• How would it look like?
• How would it differ from the "container cheat sheet"?

Survey Results 2019

General

• Survey was online from September 1, 2019 until September 30, 2019.
• 35 people participated
• During that period we had about 26k page visits, giving a response rate of about 1 per 750 visit.
• Average response time was 1:49 minutes, but varied heavily between 13 seconds and 21 minutes.

Questions

1. This visit to cheats.rs ...

2. Something you came to do in particular ...

Comment
function parameters
I looking for a Rust cheat sheet on Google and then I find the cheats.rs as the first result
No. Just to see the giraffe
Lifetime
Looking for an overall syntax summary
github redirected me to here and glad it did
async/await
I open cheats.rs almost every time I starting work
Lambda captures
Macros
rust
macro syntax
how to use matches
It's kind of hard to remember the as, to something for methods.
Tips on async/await :)

3. This site contains

4. Anything else you want to say

Comment
Awesome!!
Great page! Well structured and has just the right amount of infos on it.
Keep up the great work!
Looks great!
Perhaps sometimes some more examples or links to examples would be nice?
Great site, wish even more explanations.
This is a wonderful resource! It's so helpful to have all the syntactical forms summarised like this.
Please provide more information on rust. If there are separate cheat sheats for topics like concurrency, type system it would be best!!!
Very useful resource!!! I loved it from the first time I met it. I think that adding section with links to sites like "Are we X yet?" like http://arewegameyet.com , https://areweideyet.com and so on, would be very useful.
Recently discovered cheats.rs, and it's my new goto reference. I think it's a great complement to the Rust book. Thanks for this, and well done! The Rust community is awesome!
examples would be helpful
I wish every language had this. cheats.rs is amazing, THANK YOU!
The font used looks fine using the light theme - it looks crap using the dark theme sadly.
Very good website. Very useful
Maybe add something about mut ref in pattern matching?

5. How likely is it that you recommend cheats.rs to a friend or colleague?

• 26 supporters (rating 9 or 10)
• 7 neutral (rating 7 or 8)
• 2 detractors (rating 1 to 6)

NPS score of 69

suggestion: section about thread-safety (guide?)

• when is something thread-safe?
• https://rust-unofficial.github.io/too-many-lists/third-arc.html
• std::marker::Send, std::marker::Sync:
  • From https://limpet.net/mbrubeck/2019/02/07/rust-a-unique-perspective.html
    • T: Send means it's safe to access a T on a single other thread, where one thread at a time has exclusive access. A value of this type can be moved to another thread by unique ownership, or borrowed on another thread by unique reference (&mut T). A more descriptive name for this trait might be UniqueThreadSafe.
    • T: Sync means it’s safe for many threads to access a T simultaneously, with each thread having shared access. Values of such types can be accessed on other threads via shared ownership or shared references (&T). A more descriptive name would be SharedThreadSafe.
  • From https://www.reddit.com/r/rust/comments/e66aqb/need_clarification_about_sync_properties/f9o9pra/
    • "Think of Send as: it is safe to give another thread unique access to this value"
    • "Think of Sync as: it is safe to share access to this value across threads."
  • Examples:
    • Send+Sync: most types, AtomicUsize
    • !Send+Sync: MutexGuard, RwLockReadGuard, RwLockWriteGuard
    • Send+!Sync: Cell, RefCell
    • !Send+!Sync: Rc, Formatter, &dyn Trait
  • https://doc.rust-lang.org/nomicon/send-and-sync.html
  • https://doc.rust-lang.org/book/ch16-04-extensible-concurrency-sync-and-send.html
• Mutex<T>, RWLock<T>
• https://doc.rust-lang.org/std/sync/atomic/

Primitive casting description could be better.

For the as operator, the description is "Primitive casting, safe yet dangerous." "safe yet dangerous" isn't terribly helpful, I feel. Perhaps it would be better described as "may silently truncate input"?

Awesome site, btw!

Break can take in an argument

The break keyword can be followed by a statement that lets you assign values to the result of a loop i.e.:

let x: i32 = loop {
     break 5;
}

Replace the "Pill" icon

In Chinese, "药丸"(pill) pronouns the same as "要完"(dead meat; incurable). And everyone usually uses this emoji to express this meaning. So it reads... a little strange for us, since there're so many of them on the page : )

Maybe it's not a big deal, but maybe we can just change it to something else.

Add guide for writing polymorphic code

I think a guide would be nice that explains what to choose when writing polymorphic code (sort of the inverse of https://cheats.rs/#generics-constraints which explains what the syntax means if you see it in the wild).

See also:

• https://stackoverflow.com/questions/32059370/when-is-it-appropriate-to-use-an-associated-type-versus-a-generic-type

Functions (arguments/return values)

dyn Trait

dynamic binding (trait object) => no monomorphization

• advantages:
  • smaller binaries
• disadvantages:
  • runtime overhead (vtable)
  • the trait must be object-safe:
    • return type must not be Self
    • there are no generic type parameters.

impl Trait

static binding => monomorphization

• advantages:
  • no runtime overhead
• disadvantages:
  • larger binaries
  • implies that all return values are of the same type
  • can not be used in traits at return position

generics

static binding? monomorphization?

• advantages:
• disadvantages:

Data structures

• enums:
  • static binding (?)
  • advantages:
  • disadvantages:
    • the set of possible values can not be extended externally
• generics with associated types
  • advantages:
    • code using that structure gets simpler
  • disadvantages:
• generics without associated types
  • advantages:
  • disadvantages:

This may or may not fit https://cheats.rs/#generics-constraints

Add section on `format!` flags?

I don't see a section on format flags (e.g. debug print, justification, field width, and other specifiers). I would be happy to PR a new section for this.

Bad pointer examples

In the references and pointers section, *const x is described as an immutable raw pointer and *mut x is described as a mutable raw pointer. However those expressions are not valid; you wouldn't create a raw pointer to x using *const x, but using &x as *const T where T is the type of x (or if you like, &x as *const _).

Pack served CSS + JS

Ideally we could pack everything into a generated index.html, or a single dependencies.js. Maybe with WebPack, ParcelJS, ...?

Stray transform in book.css causes annoying horizontal scrolling

I noticed a small amount of horizontal scrolling on this page even though it fits visually within my 1920px wide screen. This is driving me quite mad when I just want to scroll down the page and it flops left and right.

Adding this style

* {
  outline: 1px solid red;
}

reveals the culprit to be the #page div, which has this style:

@media screen and (min-width: 1050px)
.page {
    transition: 0s;
    /* transform: scale(1.05); */
}

The transform is the obvious issue, I don't know why it's even there. Removing it fixes the bug. Transform should basically never be used. In addition to the scrolling issue, it causes the fonts and lines to be rendered with "fuzzy" edges and other artifacts, whose severity depend on the screen size.

See before (forced horizontal scroll):

And after:

If this is intentional, you should increase the font size and not mess with scaling.

document running cargo commands with a different toolchain

A quite obscure cargo feature which is occasionally useful is to run a single command with a different toolchain like this:

cargo +nightly build

This can be helpful to install a tool (racer/rls/clippy/rustfmt) which might at times require nightly.

This is documented here: https://github.com/rust-lang/rustup.rs#override-precedence

add $(,)* or $(,)? to the cheat sheet

Some people prefer to have trailing commas, but macros don't allow this by default

macro_rules! vec {
    ( $( $x:expr ),* ) => {
        {
            let mut temp_vec = Vec::new();
            $(
                temp_vec.push($x);
            )*
            temp_vec
        }
    };
}

vec![ 1, 2, 3, ];

will give a compiler error.

You can fix this by adding $(,)* to the end of the capture like this:

macro_rules! vec {
    ( $( $x:expr ),*  $(,)*) => {
        {
            let mut temp_vec = Vec::new();
            $(
                temp_vec.push($x);
            )*
            temp_vec
        }
    };
}

vec![ 1, 2, 3, ];

I got this from https://stackoverflow.com/a/43143459

Linking 3rd party cheat sheets.

Currently we only link 3rd party cheat sheets that "look good 200x200".

There should probably be a section / table with more links, where the visual ones get a preview image, and all the others a table entry (cmp. #17).

[RFC] Next Steps

Currently this is primarily a sigils + keywords cheat sheet.

However, cases like the ones in here, (esp. this one) make me think more surprising syntax combinations should be listed as well (e.g., we are already a bit inconsistent with repeatedly documenting _, although I believe this improves clarity).

Even further, we could include cheats around

• memory layout / data types (#11)
• common types
• iterator chaining
• lifetimes and borrows
• macros
• futures (#17)

The basic question is, should these be included, or rather linked to? If they are included, the whole cheat sheet will probably transform from a "sigils" and "keywords" layout, to a more functional grouping.

There is also the balance of being comprehensive vs. lightweight.

I am generally in favor of expanding this, as long as I don't get lost in it as a user.

Change let pattern matching example

First up, great cheat sheet! Thanks for creating it, I think it will be very useful for heaps of people :).

While reading, the following example confused me a bit:

let Some(x) = Some(5);

Because it does not compile:

refutable pattern in local binding: None not covered

Did you mean for Some to be the Option variant or a placeholder for some type? Maybe you could change it to a tuple struct instead, e.g. let S(x) = value?

Consider having navigation menu?

"Tooling" needs `cargo new` command

Should have tool in build process to check validity of links

• Check link is generally up
• Also check #target is defined in HTML

Automatically build and deploy upon commit (on certain branch)

Remove all false uses of `...` because it looks like syntax.

Slices can sometimes live on the stack

RFC1909 (rust-lang/rust#48055) was merged and is partially implemented on nightly, which means that this

#![feature(unsized_locals)]
fn foo(x: [u8]) { dbg!(&x) }

works and will land on stable at some point.

Currently, the cheat-sheet says:

Array type of unspecified length, i.e., slice. STD EX REF Can't live on stack

I think it would be good to add a foot note or super script after "Can't live on stack" saying "for now", and linking to that tracking issue.

Proposal: Dark/Light theme switcher

A simple toggle button between two themes, user preference stored in localstorage. PDF export would use default light theme.

Pdf request

Hey !
Is there any way to make the site available in PDF version with all the functionalities. I am working offline most of the time from some time.

suggestion: note about Cargo.lock and git

I'm not sure if this is worthy of inclusion but I've had multiple times where I forgot and had to look up if I should or shouldn't commit Cargo.lock for bins and libs.

It might be worth adding a note somewhere that mentions that Cargo.lock should be version controlled for bins and not for libs so that people can easily find the rule when they forget it. cargo new --lib adds it to the .gitignore file by default, so this may be an issue most people don't worry about, I'll leave it up to you to determine if it should be included.

Get rid of `/_/` in path.

Seems to be related to the zola book theme. However, using the toplevel _index.md does not render properly.

Add `..` to match and/or wildcard patterns

This one is useful for matching enums with a "don't care" number of parameters:

match foo {
  Bar(..) => ...
}

vs

match foo {
  Bar(_, _) => ...
}