The Rust Standard Library

The Rust Standard Library is the foundation of portable Rust software, a set of minimal and battle-tested shared abstractions for the broader Rust ecosystem. It offers core types, like [Vec<T>] and [Option<T>], library-defined operations on language primitives, standard macros, [I/O] and [multithreading], among many other things.

std is available to all Rust crates by default. Therefore, the standard library can be accessed in use statements through the path std, as in use std::env.

How to read this documentation

If you already know the name of what you are looking for, the fastest way to find it is to use the search button at the top of the page.

Otherwise, you may want to jump to one of these useful sections:

• std::* modules
• Primitive types
• Standard macros
• [The Rust Prelude]

If this is your first time, the documentation for the standard library is written to be casually perused. Clicking on interesting things should generally lead you to interesting places. Still, there are important bits you don’t want to miss, so read on for a tour of the standard library and its documentation!

Once you are familiar with the contents of the standard library you may begin to find the verbosity of the prose distracting. At this stage in your development you may want to press the “ Summary” button near the top of the page to collapse it into a more skimmable view.

While you are looking at the top of the page, also notice the “Source” link. Rust’s API documentation comes with the source code and you are encouraged to read it. The standard library source is generally high quality and a peek behind the curtains is often enlightening.

What is in the standard library documentation?

First of all, The Rust Standard Library is divided into a number of focused modules, all listed further down this page. These modules are the bedrock upon which all of Rust is forged, and they have mighty names like [std::slice] and [std::cmp]. Modules’ documentation typically includes an overview of the module along with examples, and are a smart place to start familiarizing yourself with the library.

Second, implicit methods on primitive types are documented here. This can be a source of confusion for two reasons:

1. While primitives are implemented by the compiler, the standard libraryimplements methods directly on the primitive types (and it is the onlylibrary that does so), which are documented in the section on primitives.
2. The standard library exports many modules with the same name as primitive types. These define additional items related to the primitivetype, but not the all-important methods.

So for example there is a page for the primitive type char that lists all the methods that can be called on characters (very useful), and there is a page for the module std::char that documents iterator and error types created by these methods (rarely useful).

Note the documentation for the primitives [str] and [T] (also called ‘slice’). Many method calls on String and [Vec<T>] are actually calls to methods on [str] and [T] respectively, via deref coercions.

Third, the standard library defines [The Rust Prelude], a small collection of items - mostly traits - that are imported into every module of every crate. The traits in the prelude are pervasive, making the prelude documentation a good entry point to learning about the library.

And finally, the standard library exports a number of standard macros, and lists them on this page (technically, not all of the standard macros are defined by the standard library - some are defined by the compiler - but they are documented here the same). Like the prelude, the standard macros are imported by default into all crates.

Contributing changes to the documentation

Check out the Rust contribution guidelines here. The source for this documentation can be found on GitHub in the ‘library/std/’ directory. To contribute changes, make sure you read the guidelines first, then submit pull-requests for your suggested changes.

Contributions are appreciated! If you see a part of the docs that can be improved, submit a PR, or chat with us first on Zulip #docs.

A Tour of The Rust Standard Library

The rest of this crate documentation is dedicated to pointing out notable features of The Rust Standard Library.

Use before and after main()

Many parts of the standard library are expected to work before and after main(); but this is not guaranteed or ensured by tests. It is recommended that you write your own tests and run them on each platform you wish to support. This means that use of std before/after main, especially of features that interact with the OS or global state, is exempted from stability and portability guarantees and instead only provided on a best-effort basis. Nevertheless bug reports are appreciated.

On the other hand core and alloc are most likely to work in such environments with the caveat that any hookable behavior such as panics, oom handling or allocators will also depend on the compatibility of the hooks.

Some features may also behave differently outside main, e.g. stdio could become unbuffered, some panics might turn into aborts, backtraces might not get symbolicated or similar.

Non-exhaustive list of known limitations:

• after-main use of thread-locals, which also affects additional features:
  • thread::current
• under UNIX, before main, file descriptors 0, 1, and 2 may be unchanged(they are guaranteed to be open during main,and are opened to /dev/null O_RDWR if they weren’t open on program start)

Organization

• TcpListener and TcpStream provide functionality for communication over TCP
• UdpSocket provides functionality for communication over UDP
• IpAddr represents IP addresses of either IPv4 or IPv6; Ipv4Addr andIpv6Addr are respectively IPv4 and IPv6 addresses
• SocketAddr represents socket addresses of either IPv4 or IPv6; SocketAddrV4and SocketAddrV6 are respectively IPv4 and IPv6 socket addresses
• ToSocketAddrs is a trait that is used for generic address resolution when interactingwith networking objects like TcpListener, TcpStream or UdpSocket
• Other types are return or parameter types for various methods in this module

Rust disables inheritance of socket objects to child processes by default when possible. For example, through the use of the CLOEXEC flag in UNIX systems or the HANDLE_FLAG_INHERIT flag on Windows.

Examples

use std::net::{TcpListener, TcpStream};

fn handle_client(stream: TcpStream) {
    // ...
}

fn main() -> std::io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:80")?;

    // accept connections and process them serially
    for stream in listener.incoming() {
        handle_client(stream?);
    }
    Ok(())
}

Examples

Creates a TCP listener bound to 127.0.0.1:80:

use std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:80").unwrap();

Creates a TCP listener bound to 127.0.0.1:80. If that fails, create a TCP listener bound to 127.0.0.1:443:

use std::net::{SocketAddr, TcpListener};

let addrs = [
    SocketAddr::from(([127, 0, 0, 1], 80)),
    SocketAddr::from(([127, 0, 0, 1], 443)),
];
let listener = TcpListener::bind(&addrs[..]).unwrap();

Creates a TCP listener bound to a port assigned by the operating system at 127.0.0.1.

use std::net::TcpListener;

let socket = TcpListener::bind("127.0.0.1:0").unwrap();

Panics

Panics if the value is an Err, with a panic message provided by the Err’s value.

Examples

Basic usage:

let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);

let x: Result<u32, &str> = Err("emergency failure");
x.unwrap(); // panics with `emergency failure`

Panics

Panics if writing to [io::stdout] fails.

Writing to non-blocking stdout can cause an error, which will lead this macro to panic.

Examples

println!(); // prints just a newline
println!("hello there!");
println!("format {} arguments", "some");
let local_variable = "some";
println!("format {local_variable} arguments");

Examples

use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, TcpListener};

let listener = TcpListener::bind("127.0.0.1:8080").unwrap();
assert_eq!(listener.local_addr().unwrap(),
           SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080)));

Basic Usage

String literals are string slices:

let hello_world = "Hello, World!";

Here we have declared a string slice initialized with a string literal. String literals have a static lifetime, which means the string hello_world is guaranteed to be valid for the duration of the entire program. We can explicitly specify hello_world’s lifetime as well:

let hello_world: &'static str = "Hello, world!";

Representation

A &str is made up of two components: a pointer to some bytes, and a length. You can look at these with the [as_ptr] and [len] methods:

use std::slice;
use std::str;

let story = "Once upon a time...";

let ptr = story.as_ptr();
let len = story.len();

// story has nineteen bytes
assert_eq!(19, len);

// We can re-build a str out of ptr and len. This is all unsafe because
// we are responsible for making sure the two components are valid:
let s = unsafe {
    // First, we build a &[u8]...
    let slice = slice::from_raw_parts(ptr, len);

    // ... and then convert that slice into a string slice
    str::from_utf8(slice)
};

assert_eq!(s, Ok(story));

Note: This example shows the internals of &str. unsafe should not be used to get a string slice under normal circumstances. Use as_str instead.

Invariant

Rust libraries may assume that string slices are always valid UTF-8.

Constructing a non-UTF-8 string slice is not immediate undefined behavior, but any function called on a string slice may assume that it is valid UTF-8, which means that a non-UTF-8 string slice can lead to undefined behavior down the road.

Errors

Will return [Err] if it’s not possible to parse this string slice into the desired type.

Examples

Basic usage:

let four: u32 = "4".parse().unwrap();

assert_eq!(4, four);

Using the ‘turbofish’ instead of annotating four:

let four = "4".parse::<u32>();

assert_eq!(Ok(4), four);

Failing to parse:

let nope = "j".parse::<u32>();

assert!(nope.is_err());

Examples

let v = [1, 2, 3];
let mut iter = v.into_iter();

assert_eq!(Some(1), iter.next());
assert_eq!(Some(2), iter.next());
assert_eq!(Some(3), iter.next());
assert_eq!(None, iter.next());

Portability

SocketAddr is intended to be a portable representation of socket addresses and is likely not the same as the internal socket address type used by the target operating system’s API. Like all repr(Rust) structs, however, its exact layout remains undefined and should not be relied upon between builds.

Examples

use std::net::{IpAddr, Ipv4Addr, SocketAddr};

let socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);

assert_eq!("127.0.0.1:8080".parse(), Ok(socket));
assert_eq!(socket.port(), 8080);
assert_eq!(socket.is_ipv4(), true);

Examples

Creating a SocketAddr iterator that yields one item:

use std::net::{ToSocketAddrs, SocketAddr};

let addr = SocketAddr::from(([127, 0, 0, 1], 443));
let mut addrs_iter = addr.to_socket_addrs().unwrap();

assert_eq!(Some(addr), addrs_iter.next());
assert!(addrs_iter.next().is_none());

Creating a SocketAddr iterator from a hostname:

use std::net::{SocketAddr, ToSocketAddrs};

// assuming 'localhost' resolves to 127.0.0.1
let mut addrs_iter = "localhost:443".to_socket_addrs().unwrap();
assert_eq!(addrs_iter.next(), Some(SocketAddr::from(([127, 0, 0, 1], 443))));
assert!(addrs_iter.next().is_none());

// assuming 'foo' does not resolve
assert!("foo:443".to_socket_addrs().is_err());

Creating a SocketAddr iterator that yields multiple items:

use std::net::{SocketAddr, ToSocketAddrs};

let addr1 = SocketAddr::from(([0, 0, 0, 0], 80));
let addr2 = SocketAddr::from(([127, 0, 0, 1], 443));
let addrs = vec![addr1, addr2];

let mut addrs_iter = (&addrs[..]).to_socket_addrs().unwrap();

assert_eq!(Some(addr1), addrs_iter.next());
assert_eq!(Some(addr2), addrs_iter.next());
assert!(addrs_iter.next().is_none());

Attempting to create a SocketAddr iterator from an improperly formatted socket address &str (missing the port):

use std::io;
use std::net::ToSocketAddrs;

let err = "127.0.0.1".to_socket_addrs().unwrap_err();
assert_eq!(err.kind(), io::ErrorKind::InvalidInput);

[TcpStream::connect] is an example of a function that utilizes ToSocketAddrs as a trait bound on its parameter in order to accept different types:

use std::net::{TcpStream, Ipv4Addr};

let stream = TcpStream::connect(("127.0.0.1", 443));
// or
let stream = TcpStream::connect("127.0.0.1:443");
// or
let stream = TcpStream::connect((Ipv4Addr::new(127, 0, 0, 1), 443));

Uses

Assertions are always checked in both debug and release builds, and cannot be disabled. See debug_assert for assertions that are not enabled in release builds by default.

Unsafe code may rely on assert! to enforce run-time invariants that, if violated could lead to unsafety.

Other use-cases of assert! include testing and enforcing run-time invariants in safe code (whose violation cannot result in unsafety).

Custom Messages

This macro has a second form, where a custom panic message can be provided with or without arguments for formatting. See std::fmt for syntax for this form. Expressions used as format arguments will only be evaluated if the assertion fails.

Examples

// the panic message for these assertions is the stringified value of the
// expression given.
assert!(true);

fn some_computation() -> bool {
    // Some expensive computation here
    true
}

assert!(some_computation());

// assert with a custom message
let x = true;
assert!(x, "x wasn't true!");

let a = 3; let b = 27;
assert!(a + b == 30, "a = {}, b = {}", a, b);

Examples

let mut s = [1, 2, 3];
let ptr: *mut u32 = s.as_mut_ptr();
assert!(!ptr.is_null());

Safety

Many functions in this module take raw pointers as arguments and read from or write to them. For this to be safe, these pointers must be valid for the given access. Whether a pointer is valid depends on the operation it is used for (read or write), and the extent of the memory that is accessed (i.e., how many bytes are read/written) – it makes no sense to ask “is this pointer valid”; one has to ask “is this pointer valid for a given access”. Most functions use *mut T and *const T to access only a single value, in which case the documentation omits the size and implicitly assumes it to be size_of::<T>() bytes.

The precise rules for validity are not determined yet. The guarantees that are provided at this point are very minimal:

• For memory accesses of size zero, every pointer is valid, including the nullpointer. The following points are only concerned with non-zero-sized accesses.
• A null pointer is never valid.
• For a pointer to be valid, it is necessary, but not always sufficient, that the pointer bedereferenceable. The provenance of the pointer is used to determine which allocationit is derived from; a pointer is dereferenceable if the memory range of the given sizestarting at the pointer is entirely contained within the bounds of that allocation. Notethat in Rust, every (stack-allocated) variable is considered a separate allocation.
• All accesses performed by functions in this module are non-atomic in the senseof [atomic operations] used to synchronize between threads. This means it isundefined behavior to perform two concurrent accesses to the same location from differentthreads unless both accesses only read from memory. Notice that this explicitlyincludes read_volatile and write_volatile: Volatile accesses cannotbe used for inter-thread synchronization, regardless of whether they are acting onRust memory or not.
• The result of casting a reference to a pointer is valid for as long as theunderlying allocation is live and no reference (just raw pointers) is used toaccess the same memory. That is, reference and pointer accesses cannot beinterleaved.

These axioms, along with careful use of [offset] for pointer arithmetic, are enough to correctly implement many useful things in unsafe code. Stronger guarantees will be provided eventually, as the aliasing rules are being determined. For more information, see the book as well as the section in the reference devoted to undefined behavior.

We say that a pointer is “dangling” if it is not valid for any non-zero-sized accesses. This means out-of-bounds pointers, pointers to freed memory, null pointers, and pointers created with NonNull::dangling are all dangling.

Provenance

Pointers are not simply an “integer” or “address”. For instance, it’s uncontroversial to say that a Use After Free is clearly Undefined Behavior, even if you “get lucky” and the freed memory gets reallocated before your read/write (in fact this is the worst-case scenario, UAFs would be much less concerning if this didn’t happen!). As another example, consider that [wrapping_offset] is documented to “remember” the allocation that the original pointer points to, even if it is offset far outside the memory range occupied by that allocation. To rationalize claims like this, pointers need to somehow be more than just their addresses: they must have provenance.

A pointer value in Rust semantically contains the following information:

• The address it points to, which can be represented by a usize.
• The provenance it has, defining the memory it has permission to access. Provenance can beabsent, in which case the pointer does not have permission to access any memory.

The exact structure of provenance is not yet specified, but the permission defined by a pointer’s provenance have a spatial component, a temporal component, and a mutability component:

• Spatial: The set of memory addresses that the pointer is allowed to access.
• Temporal: The timespan during which the pointer is allowed to access those memory addresses.
• Mutability: Whether the pointer may only access the memory for reads, or also access it forwrites. Note that this can interact with the other components, e.g. a pointer might permitmutation only for a subset of addresses, or only for a subset of its maximal timespan.

When an allocation is created, it has a unique Original Pointer. For alloc APIs this is literally the pointer the call returns, and for local variables and statics, this is the name of the variable/static. (This is mildly overloading the term “pointer” for the sake of brevity/exposition.)

The Original Pointer for an allocation has provenance that constrains the spatial permissions of this pointer to the memory range of the allocation, and the temporal permissions to the lifetime of the allocation. Provenance is implicitly inherited by all pointers transitively derived from the Original Pointer through operations like [offset], borrowing, and pointer casts. Some operations may shrink the permissions of the derived provenance, limiting how much memory it can access or how long it’s valid for (i.e. borrowing a subfield and subslicing can shrink the spatial component of provenance, and all borrowing can shrink the temporal component of provenance). However, no operation can ever grow the permissions of the derived provenance: even if you “know” there is a larger allocation, you can’t derive a pointer with a larger provenance. Similarly, you cannot “recombine” two contiguous provenances back into one (i.e. with a fn merge(&[T], &[T]) -> &[T]).

A reference to a place always has provenance over at least the memory that place occupies. A reference to a slice always has provenance over at least the range that slice describes. Whether and when exactly the provenance of a reference gets “shrunk” to exactly fit the memory it points to is not yet determined.

A shared reference only ever has provenance that permits reading from memory, and never permits writes, except inside [UnsafeCell].

Provenance can affect whether a program has undefined behavior:

• It is undefined behavior to access memory through a pointer that does not have provenance over that memory. Note that a pointer “at the end” of its provenance is not actually outside its provenance, it just has 0 bytes it can load/store. Zero-sized accesses do not require any provenance since they access an empty range of memory.

• It is undefined behavior to [offset] a pointer across a memory range that is not contained in the allocation it is derived from, or to [offset_from] two pointers not derived from the same allocation. Provenance is used to say what exactly “derived from” even means: the lineage of a pointer is traced back to the Original Pointer it descends from, and that identifies the relevant allocation. In particular, it’s always UB to offset a pointer derived from something that is now deallocated, except if the offset is 0.

But it is still sound to:

• Create a pointer without provenance from just an address (see without_provenance). Such a pointer cannot be used for memory accesses (except for zero-sized accesses). This can still be useful for sentinel values like null or to represent a tagged pointer that will never be dereferenceable. In general, it is always sound for an integer to pretend to be a pointer “for fun” as long as you don’t use operations on it which require it to be valid (non-zero-sized offset, read, write, etc).

• Forge an allocation of size zero at any sufficiently aligned non-null address. i.e. the usual “ZSTs are fake, do what you want” rules apply.

• [wrapping_offset] a pointer outside its provenance. This includes pointers which have “no” provenance. In particular, this makes it sound to do pointer tagging tricks.

• Compare arbitrary pointers by address. Pointer comparison ignores provenance and addresses are just integers, so there is always a coherent answer, even if the pointers are dangling or from different provenances. Note that if you get “lucky” and notice that a pointer at the end of one allocation is the “same” address as the start of another allocation, anything you do with that fact is probably going to be gibberish. The scope of that gibberish is kept under control by the fact that the two pointers still aren’t allowed to access the other’s allocation (bytes), because they still have different provenance.

Note that the full definition of provenance in Rust is not decided yet, as this interacts with the as-yet undecided aliasing rules.

    /// Creates a new pointer with the given address.
    ///
    /// This performs the same operation as an `addr as ptr` cast, but copies
    /// the *provenance* of `self` to the new pointer.
    /// This allows us to dynamically preserve and propagate this important
    /// information in a way that is otherwise impossible with a unary cast.
    ///
    /// This is equivalent to using `wrapping_offset` to offset `self` to the
    /// given address, and therefore has all the same capabilities and restrictions.
    pub fn with_addr(self, addr: usize) -> Self;

unsafe {
    // A flag we want to pack into our pointer
    static HAS_DATA: usize = 0x1;
    static FLAG_MASK: usize = !HAS_DATA;

    // Our value, which must have enough alignment to have spare least-significant-bits.
    let my_precious_data: u32 = 17;
    assert!(align_of::<u32>() > 1);

    // Create a tagged pointer
    let ptr = &my_precious_data as *const u32;
    let tagged = ptr.map_addr(|addr| addr | HAS_DATA);

    // Check the flag:
    if tagged.addr() & HAS_DATA != 0 {
        // Untag and read the pointer
        let data = *tagged.map_addr(|addr| addr & FLAG_MASK);
        assert_eq!(data, 17);
    } else {
        unreachable!()
    }
}

Examples

use std::ptr;

let p: *mut i32 = ptr::null_mut();
assert!(p.is_null());
assert_eq!(p as usize, 0); // this pointer has the address 0

Transmutation between pointers and integers

Special care has to be taken when transmuting between pointers and integers, e.g. transmuting between *const () and usize.

Transmuting pointers to integers in a const context is undefined behavior, unless the pointer was originally created from an integer. (That includes this function specifically, integer-to-pointer casts, and helpers like dangling, but also semantically-equivalent conversions such as punning through repr(C) union fields.) Any attempt to use the resulting value for integer operations will abort const-evaluation. (And even outside const, such transmutation is touching on many unspecified aspects of the Rust memory model and should be avoided. See below for alternatives.)

Transmuting integers to pointers is a largely unspecified operation. It is likely not equivalent to an as cast. Doing non-zero-sized memory accesses with a pointer constructed this way is currently considered undefined behavior.

All this also applies when the integer is nested inside an array, tuple, struct, or enum. However, MaybeUninit<usize> is not considered an integer type for the purpose of this section. Transmuting *const () to MaybeUninit<usize> is fine—but then calling assume_init() on that result is considered as completing the pointer-to-integer transmute and thus runs into the issues discussed above.

In particular, doing a pointer-to-integer-to-pointer roundtrip via transmute is not a lossless process. If you want to round-trip a pointer through an integer in a way that you can get back the original pointer, you need to use as casts, or replace the integer type by MaybeUninit<$int> (and never call assume_init()). If you are looking for a way to store data of arbitrary type, also use MaybeUninit<T> (that will also handle uninitialized memory due to padding). If you specifically need to store something that is “either an integer or a pointer”, use *mut (): integers can be converted to pointers and back without any loss (via as casts or via transmute).

Examples

There are a few things that transmute is really useful for.

Turning a pointer into a function pointer. This is not portable to machines where function pointers and data pointers have different sizes.

fn foo() -> i32 {
    0
}
// Crucially, we `as`-cast to a raw pointer before `transmute`ing to a function pointer.
// This avoids an integer-to-pointer `transmute`, which can be problematic.
// Transmuting between raw pointers and function pointers (i.e., two pointer types) is fine.
let pointer = foo as fn() -> i32 as *const ();
let function = unsafe {
    std::mem::transmute::<*const (), fn() -> i32>(pointer)
};
assert_eq!(function(), 0);

Extending a lifetime, or shortening an invariant lifetime. This is advanced, very unsafe Rust!

struct R<'a>(&'a i32);
unsafe fn extend_lifetime<'b>(r: R<'b>) -> R<'static> {
    unsafe { std::mem::transmute::<R<'b>, R<'static>>(r) }
}

unsafe fn shorten_invariant_lifetime<'b, 'c>(r: &'b mut R<'static>)
                                             -> &'b mut R<'c> {
    unsafe { std::mem::transmute::<&'b mut R<'static>, &'b mut R<'c>>(r) }
}

Alternatives

Don’t despair: many uses of transmute can be achieved through other means. Below are common applications of transmute which can be replaced with safer constructs.

Turning raw bytes ([u8; SZ]) into u32, f64, etc.:

let raw_bytes = [0x78, 0x56, 0x34, 0x12];

let num = unsafe {
    std::mem::transmute::<[u8; 4], u32>(raw_bytes)
};

// use `u32::from_ne_bytes` instead
let num = u32::from_ne_bytes(raw_bytes);
// or use `u32::from_le_bytes` or `u32::from_be_bytes` to specify the endianness
let num = u32::from_le_bytes(raw_bytes);
assert_eq!(num, 0x12345678);
let num = u32::from_be_bytes(raw_bytes);
assert_eq!(num, 0x78563412);

Turning a pointer into a usize:

let ptr = &0;
let ptr_num_transmute = unsafe {
    std::mem::transmute::<&i32, usize>(ptr)
};

// Use an `as` cast instead
let ptr_num_cast = ptr as *const i32 as usize;

Note that using transmute to turn a pointer to a usize is (as noted above) undefined behavior in const contexts. Also outside of consts, this operation might not behave as expected – this is touching on many unspecified aspects of the Rust memory model. Depending on what the code is doing, the following alternatives are preferable to pointer-to-integer transmutation:

• If the code just wants to store data of arbitrary type in some buffer and needs to pick atype for that buffer, it can use MaybeUninit.
• If the code actually wants to work on the address the pointer points to, it can use ascasts or ptr.addr().

Turning a *mut T into a &mut T:

let ptr: *mut i32 = &mut 0;
let ref_transmuted = unsafe {
    std::mem::transmute::<*mut i32, &mut i32>(ptr)
};

// Use a reborrow instead
let ref_casted = unsafe { &mut *ptr };

Turning a &mut T into a &mut U:

let ptr = &mut 0;
let val_transmuted = unsafe {
    std::mem::transmute::<&mut i32, &mut u32>(ptr)
};

// Now, put together `as` and reborrowing - note the chaining of `as`
// `as` is not transitive
let val_casts = unsafe { &mut *(ptr as *mut i32 as *mut u32) };

Turning a &str into a &[u8]:

// this is not a good way to do this.
let slice = unsafe { std::mem::transmute::<&str, &[u8]>("Rust") };
assert_eq!(slice, &[82, 117, 115, 116]);

// You could use `str::as_bytes`
let slice = "Rust".as_bytes();
assert_eq!(slice, &[82, 117, 115, 116]);

// Or, just use a byte string, if you have control over the string
// literal
assert_eq!(b"Rust", &[82, 117, 115, 116]);

Turning a Vec<&T> into a Vec<Option<&T>>.

To transmute the inner type of the contents of a container, you must make sure to not violate any of the container’s invariants. For Vec, this means that both the size and alignment of the inner types have to match. Other containers might rely on the size of the type, alignment, or even the TypeId, in which case transmuting wouldn’t be possible at all without violating the container invariants.

let store = [0, 1, 2, 3];
let v_orig = store.iter().collect::<Vec<&i32>>();

// clone the vector as we will reuse them later
let v_clone = v_orig.clone();

// Using transmute: this relies on the unspecified data layout of `Vec`, which is a
// bad idea and could cause Undefined Behavior.
// However, it is no-copy.
let v_transmuted = unsafe {
    std::mem::transmute::<Vec<&i32>, Vec<Option<&i32>>>(v_clone)
};

let v_clone = v_orig.clone();

// This is the suggested, safe way.
// It may copy the entire vector into a new one though, but also may not.
let v_collected = v_clone.into_iter()
                         .map(Some)
                         .collect::<Vec<Option<&i32>>>();

let v_clone = v_orig.clone();

// This is the proper no-copy, unsafe way of "transmuting" a `Vec`, without relying on the
// data layout. Instead of literally calling `transmute`, we perform a pointer cast, but
// in terms of converting the original inner type (`&i32`) to the new one (`Option<&i32>`),
// this has all the same caveats. Besides the information provided above, also consult the
// [`from_raw_parts`] documentation.
let (ptr, len, capacity) = v_clone.into_raw_parts();
let v_from_raw = unsafe {
    Vec::from_raw_parts(ptr.cast::<*mut Option<&i32>>(), len, capacity)
};

Implementing split_at_mut:

use std::{slice, mem};

// There are multiple ways to do this, and there are multiple problems
// with the following (transmute) way.
fn split_at_mut_transmute<T>(slice: &mut [T], mid: usize)
                             -> (&mut [T], &mut [T]) {
    let len = slice.len();
    assert!(mid <= len);
    unsafe {
        let slice2 = mem::transmute::<&mut [T], &mut [T]>(slice);
        // first: transmute is not type safe; all it checks is that T and
        // U are of the same size. Second, right here, you have two
        // mutable references pointing to the same memory.
        (&mut slice[0..mid], &mut slice2[mid..len])
    }
}

// This gets rid of the type safety problems; `&mut *` will *only* give
// you a `&mut T` from a `&mut T` or `*mut T`.
fn split_at_mut_casts<T>(slice: &mut [T], mid: usize)
                         -> (&mut [T], &mut [T]) {
    let len = slice.len();
    assert!(mid <= len);
    unsafe {
        let slice2 = &mut *(slice as *mut [T]);
        // however, you still have two mutable references pointing to
        // the same memory.
        (&mut slice[0..mid], &mut slice2[mid..len])
    }
}

// This is how the standard library does it. This is the best method, if
// you need to do something like this
fn split_at_stdlib<T>(slice: &mut [T], mid: usize)
                      -> (&mut [T], &mut [T]) {
    let len = slice.len();
    assert!(mid <= len);
    unsafe {
        let ptr = slice.as_mut_ptr();
        // This now has three mutable references pointing at the same
        // memory. `slice`, the rvalue ret.0, and the rvalue ret.1.
        // `slice` is never used after `let ptr = ...`, and so one can
        // treat it as "dead", and therefore, you only have two real
        // mutable slices.
        (slice::from_raw_parts_mut(ptr, mid),
         slice::from_raw_parts_mut(ptr.add(mid), len - mid))
    }
}

Examples

use std::env;

let key = "HOME";
match env::var_os(key) {
    Some(val) => println!("{key}: {val:?}"),
    None => println!("{key} is not defined in the environment.")
}

If expecting a delimited variable (such as PATH), split_paths can be used to separate items.

Examples

let x: Option<u32> = Some(2);
assert_eq!(x.is_some_and(|x| x > 1), true);

let x: Option<u32> = Some(0);
assert_eq!(x.is_some_and(|x| x > 1), false);

let x: Option<u32> = None;
assert_eq!(x.is_some_and(|x| x > 1), false);

let x: Option<String> = Some("ownership".to_string());
assert_eq!(x.as_ref().is_some_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);