The Periodic Table of Rust Types

Immutable Pointer Mutable Pointer Owned Pointer Bare Unsized Raw *const T

Immutable raw pointer *mut T

Mutable raw pointer *const T or *mut T should be used as appropriate. See also Unique< T > . Raw pointers do not have ownership,orshould be used as appropriate. See also Simple &' r T

Immutable borrowed reference &' r mut T

Mutable borrowed reference Box< T >

Owned pointer T

Primitive type, struct, enum and so on Trait &' r ( Trait + K )

Immutable borrowed trait object &' r mut ( Trait + K )

Mutable borrowed trait object Box< Trait + K >

Owned trait object Trait + K

Unsized trait type Array &' r [ T ]

Immutable borrowed slice &' r mut [ T ]

Mutable borrowed slice Box<[ T ]>

Owned array

Vec< T >

Owned growable vector [ T ; n ]

Fixed-size array [ T ]

Unsized array type String &' r str

Immutable borrowed string slice &' r mut str

Mutable borrowed string slice (not that useful) Box<str>

Owned string (theoretical)

String

Owned growable string Fixed sized storage is impractical for the variable length UTF-8 encoding. str

Unsized string type Supported as of 1.0.0-alpha Provided by the standard library Impossible ' r

Lifetime K

Trait bounds T…

Function arguments -> U

Function return extern " ABI "

ABI definition

What is this?

This "periodic table" is a cheatsheet for various Rust types. Rust programming language has a versatile type system that avoids a certain class of memory error in the safe context, and consequently has somewhat many types at the first glance. This table organizes them into an orthogonal tabular form, making them easier to understand and reason.

This table does not indicate that Rust has a complex type system compared to other languages. Rust does have seemingly many types, but you only need to understand the meaning of each axis, or even just each column. There are some non-trivial but reasonable interactions between rows and columns though, therefore this table strives to illustrate that.

The periodic table was made by Kang Seonghoon as a thought experiment, and then... it have got redditted unexpectedly :p Henceforth I've made the URL permanent and added some descriptions. Some post-reddit changes include:

2014-01-15 08:30 UTC: The table was updated slightly to include a missing fixed-size vector [ T , .. n ] , so it has a new "unsized" column now.

, so it has a new "unsized" column now. 2014-01-16 19:00 UTC: Axes and labels are now close to the official terminology. Proposed types are hidden by default (they led to much confusion). The trait row is now below the simple row, since these two rows have related to each other (particularly, types in the simple row can be coerced into those in the trait row). The unboxed types ( T ) occupy two cells since you can use trait methods to those types. Also proposed function traits are updated and some of them are marked impossible as per the comments by glaebhoerl. Thanks everyone in /r/rust and #rust-internals for suggestions!

) occupy two cells since you can use trait methods to those types. Also proposed function traits are updated and some of them are marked impossible as per the comments by glaebhoerl. Thanks everyone in /r/rust and #rust-internals for suggestions! 2014-01-17 19:00 UTC: The table now reflects the fact that bare function types can be coerced into procedures.

2014-07-02 06:00 UTC: The table was updated to reflect changes from 0.10 to 0.11. The old version for 0.10 is available here.

2015-01-13 01:30 UTC: The table was updated to reflect changes from 0.11 to 1.0.0-alpha. This integrates both dynamically sized types and unboxed closures into the default. The old version for 0.11 is available here.

2015-01-13 11:00 UTC: Updated the raw owned pointer cell to link to a new Unique type (suggested by /u/kennytm). This is still #[unstable] , but it can be the recommended solution if it gets stabilized.

type (suggested by /u/kennytm). This is still , but it can be the recommended solution if it gets stabilized. 2015-01-13 11:30 UTC: Further updated the table to reflect comments from Danial Micay. This finally fixes several inconsistent or incorrect terminologies, and includes a clear note that library types are representative.

Discussion: /r/rust, /r/programming, Hacker News

Guide

Columns indicate the ownership. There are two big groups from left to right: indirect (i.e. pointers) and direct. Particularly indirect types can be used in place of other indirect types in many cases: &mut self methods can be used for Box< T > (when the box itself is mutable), and &self methods can be used for &mut T .

Rows indicate the different kind of types. There are three big groups from top to bottom: unsafe dereference, safe dereference and callable.

The owned column is special that every type is a library type; Box< T > is a representative smart pointer which is also most used, and Vec< T > and String are also representative growable types. Please note that there are several other types specialized to specific tasks (for example, Rc< T > ).

Names for each cell are mostly from the Rusticon, but with necessary changes to make them consistent.

There are some optional syntactic parts possible in types. Many of them are turned off by default since they are normally verbose, but you can turn them on if you want.

Copyright © 2014–2015, Kang Seonghoon. This work is licensed under a Creative Commons Attribution 4.0 International License.

a part of cosmic.mearie.org.