# Pointers and References As with the other primitive data types, the Rust language does not unify raw pointers or references in any way, and insists that users treat `*const T`, `*mut T`, `*const T: !Sized`, and `*mut T: !Sized` as essentially four completely independent types that happen to look similar. This has worked so far, but ongoing efforts with pointer provenance and mutability tracking make improper choice of pointer storage increasingly hazardous to well-formed programs. Furthermore, advances in the Rust type system, including the recently-stabilized Generic Associated Types, allow increasingly expressive type declarations that can nevertheless result in code generation that uses the ordinary primitives. This module implements indirect-access permission tracking in the type system, and allows code to be generic over permissions. This means that you can write against a `Pointer` and have access to behavior that is common to all pointers (address inspection, loading from the pointed-to location), or you can specify a `Pointer` and gain access to behavior that requires mutable or unique access permission. ## Usage Your code should be generic over the `Permission` trait when you primarily expect to read from memory or to hold pointers and pass them through to known use sites. You can also explicitly demand pointers that specify a `Shared` or `Unique` permission type parameter in order to make use of their specific capabilities. The `Pointer` type can be temporarily downgraded to `Pointer`. This type acts identically to `Pointer`, except that it has memory of being derived from a `Unique` permission and can be *safely* restored to that. `Pointer` can be *unsafely* upgraded to `Pointer`, but this operation requires you to have upheld Rust’s provenance guarantees about write permissions to the pointed-to memory. The `Permission` trait is intended for use only in type relation graphs. It contains runtime functionality that cannot be expressed anywhere else in the module, but these functions are not part of the public API and are hidden from the documentation. ## Associated Types The `Permission::Ptr` type is either a `*const T` or a `*mut T` raw pointer. This is the only value stored inside a `Pointer`, and the `Permission` implementation allows `Pointer` to store the correct value type and satisfy Rust’s expectations about pointer mutability provenance. Similarly, the `Permission::Ref` type is either a `&T` or an `&mut T`. The `Pointer` APIs work primarily with these associated types rather than the concrete primitives. Some functions operate on raw pointers directly so that you can have direct access to them rather than relying on the `Pointer` type or `RawPtr` trait. ## API Surface As with the rest of `funty`, the `Pointer` type strives to match the stable API surface of the pointer primitives. However, the pointers have a great deal of still-unstable methods that make them actually useful, including all of the operations on slice pointers and direct address manipulation. Since the `ferrilab` project is committed to using the stable series, these APIs will not be provided until they stabilize. If you urgently want them available for your project under a `cfg(feature = "nightly")` gate, please file an issue.