## Expand description

Safe conversion between FFI-safe and ergonomic Rust types.

An implementation of `Iffi`

trait (which can be derived) on a type `T`

over a *universe* `U`

(the type parameter on the trait)
provides assertions that a value of type `U`

can be safely transmuted into a value of type `T`

.

`iffi::try_from`

and `iffi::into`

perform the conversion safely.

## Glossary & Concepts

#### FFI-safe

a type that can be used with FFI.

This can be a primitve, a type marked with `#[repr(C)]`

or `#[repr(Int)]`

,
or a type marked with `#[repr(transparent)]`

with only one non-zero sized field which must be FFI-safe.

#### bit-pattern

a sequence of bits representing a potential value of a type.

Each type defines some bit-patterns (with the same number of bits as the type) that are valid and others that are invalid.

For example, for `u16`

, all bit-patterns are valid because `0x0000`

through `0xffff`

are all correctly initialized `u16`

values,
but for `bool`

only the patterns `0x00`

and `0x01`

, (`false`

and `true`

respectively) are valid.
`0x02..=0xff`

are all *invalid* bit-patterns for `bool`

.

An invalid bit-pattern is also called a niche.
Types like `u16`

where all bit-patterns are valid are *nicheless*.

This definition is subtly different to the one in the Unsafe Code Guidelines. In the context of bit-patterns this crate assumes all bits are initialized, so there is a one-to-one relationship between invalid bit patterns and niches.

#### well-defined

a potential value represented in memory by a valid bit-pattern.

A null reference or zeroed `NonZero*`

is not well-defined, for example.

#### nicheless

a type with no niches i.e. no invalid bit-patterns.

The `Nicheless`

trait cannot be automatically implemented
and must be derived or implemented manually.

ZSTs are always nicheless. Uninhabited types are never nicheless.

A more technical definition is availible in the Unsafe Code Guidelines.

#### layout

the combination of the size, alignment and ABI behaviour of a type.

#### universe

a nicheless type with the same layout as some potentially non-nicheless type.

`MaybeInvalid<T>`

is a universe of all `T`

.

A type may have many universes.
As an example, `NonZeroU8`

has the universes `MaybeInvalid<NonZeroU8>`

and `u8`

.

## Structs

- A dynamically-sized pattern of bits.
- A set of ranges of bit-patterns that are applicable for a type.
- An error encountered while converting with
`Iffi`

, wrapped with type name information. - Represents a value of the type
`T`

that may not be well-defined.

## Enums

- Potential errors converting with
`Iffi`

.

## Traits

- The core trait of the
`iffi`

crate. - Indicates that a value of this type is FFI-safe and well-defined no matter the underlying bit-pattern.
- Indicates that the type has exactly one niche, which is filled by niche optimization and so implements
`Nicheless`

in option-like enums (`Option<T>`

,`Result<T, ()>`

).

## Functions

- Converts an ergonomic Rust type to an FFI-safe nicheless type.
- Tries to convert an FFI-safe nicheless type to a more ergonomic one.