What `as` does

what_as_does.md

as does a huge number of things. Probably too many. Here's a comprehensive list of everything it can do. Entries in italics are the names of functions that actually exist in the standard library, while all entries attempt to have a descriptive name for what a function that does the same thing as that particular as would do.

• int <-> int
  • zero_extend: unsigned int -> bigger unsigned int. Pads the number with leading zeroes. This preserves the numeric value.
  • sign_extend: signed int -> bigger signed int. Pads the number with leading zeroes if positive, and leading ones if negative. This preserves the numeric value.
  • truncate: bigger int -> smaller int (regardless of signedness). Throws away the high bits of the number.
  • reinterpret_sign: int -> int of the same size and opposite signedness. Does nothing to the bits.
• int <-> float
  • cast_saturate_to_infinity: Yields the float closest to the specified integer. Yields infinity if the integer is out of bounds.
  • cast_nan_to_zero_saturating_when_out_of_bounds: Truncates the float and yields the corresponding integer. NaN yields 0, and the infinities yield the minimum and maximum integer value.
• int <-> ptr
  • expose_provenance: ptr -> int. Does nothing to the bits, and exposes the address (which is a provenance-related concept)
  • from_exposed_provenance: int -> ptr. Does nothing to the bits, inheriting the provenance of a pointer with the same address that was previously exposed.
• ptr <-> ptr
  • cast: ptr -> ptr: Does nothing to the bits, keeps the pointer's mutability while changing the type
  • cast_const: -> *const T -> *mut T. Does nothing to the bits. Changes the pointer's mutability while keeping the type
  • cast_mut: -> *mut T -> *const T. Does nothing to the bits. Changes the pointer's mutability while keeping the type
• function pointer -> pointer (this conversion only goes one way)
  • to_data_ptr: fnptr -> ptr. Does nothing to the bits.
• function pointer -> integer (this conversion only goes one way)
  • to_int: fnptr -> integer. Same as fnptr -> ptr -> integer: evaluates to the address of the function. If the integer is smaller than a function pointer, said address will be truncated.
• char -> u32 (this conversion only goes one way)
  • from: char -> u32. Does nothing to the bits.
• bool -> u8 (this conversion only goes one way)
  • from: bool -> u8 Does nothing to the bits, yields 1 for true and 0 for false.
• ref -> ptr (these conversions only go one way)
  • as_mut_ptr: &mut T -> *mut T. Does nothing to the bits.
  • as_const_ptr &T -> *const T. Does nothing to the bits.
• ptr to sized -> ptr to unsized (that is, any pointer or reference, including Box, Arc, etc, from Ptr<T> to Ptr<U> where U does not implement Sized)
  • unsize: Makes the pointer fat. The data pointer is still stored therein, and pointee-specific metadata is added.
• type ascription (That is, the fact that None as Option<u8> compiles)
  • ascribe: This... isn't really a function. It's more like a special inference thing.

On top of the above, some conversions may be performed implicitly around as, giving the appearance that as is sometimes transitive. A few honorable examples of these conversions include:

• char -> u8: Desugars to char -> u32 -> u8. That is, it truncates the character.
• &mut T -> *const T. Desugars to &mut T -> &T -> *const T. Notably, this means that if the resulting pointer is cast back to *mut T, it cannot be used for writes anyway.