rust/conversions.md

% Type Conversions

At the end of the day, everything is just a pile of bits somewhere, and type systems are just there to help us use those bits right. Needing to reinterpret those piles of bits as different types is a common problem and Rust consequently gives you several ways to do that.

Safe Rust

First we'll look at the ways that Safe Rust gives you to reinterpret values. The most trivial way to do this is to just destructure a value into its constituent parts and then build a new type out of them. e.g.

struct Foo {
	x: u32,
	y: u16,
}

struct Bar {
	a: u32,
	b: u16,
}

fn reinterpret(foo: Foo) -> Bar {
	let Foo { x, y } = foo;
	Bar { a: x, b: y }
}

But this is, at best, annoying to do. For common conversions, rust provides more ergonomic alternatives.

Auto-Deref

Deref is a trait that allows you to overload the unary * to specify a type you dereference to. This is largely only intended to be implemented by pointer types like &, Box, and Rc. The dot operator will automatically perform automatic dereferencing, so that foo.bar() will work uniformly on Foo, &Foo, &&Foo, &Rc<Box<&mut&Box<Foo>>> and so-on. Search bottoms out on the first match, so implementing methods on pointers is generally to be avoided, as it will shadow "actual" methods.

Coercions

Types can implicitly be coerced to change in certain contexts. These changes are generally just weakening of types, largely focused around pointers. They mostly exist to make Rust "just work" in more cases. For instance &mut T coerces to &T, and &T coerces to *const T. The most useful coercion you will actually think about it is probably the general Deref Coercion: &T coerces to &U when T: Deref<U>. This enables us to pass an &String where an &str is expected, for instance.

Casts

Casts are a superset of coercions: every coercion can be explicitly invoked via a cast, but some changes require a cast. These "true casts" are generally regarded as dangerous or problematic actions. True casts revolves around raw pointers and the primitive numeric types. Here's an exhaustive list of all the true casts:

• rawptr -> rawptr (e.g. *mut T as *const T or *mut T as *mut U)
• rawptr <-> usize (e.g. *mut T as usize or usize as *mut T)
• number -> number (e.g. u32 as i8 or i16 as f64)
• c-like enum -> integer/bool (e.g. DaysOfWeek as u32)
• u8 -> char
• something about arrays?

For number -> number casts, there are quite a few cases to consider:

• unsigned to bigger unsigned will zero-extend losslessly
• unsigned to smaller unsigned will truncate via wrapping
• signed to unsigned will ... TODO rest of this list

The casts involving rawptrs also allow us to completely bypass type-safety by re-interpretting a pointer of T to a pointer of U for arbitrary types, as well as interpret integers as addresses. However it is impossible to actually capitalize on this violation in Safe Rust, because derefencing a raw ptr is unsafe.

Conversion Traits

For full formal specification of all the kinds of coercions and coercion sites, see: https://github.com/rust-lang/rfcs/blob/master/text/0401-coercions.md

• Coercions
• Casts
• Conversion Traits (Into/As/...)

Unsafe Rust

• raw ptr casts
• mem::transmute