Trait objc2_encode::RefEncode

source · [−]
pub unsafe trait RefEncode {
    const ENCODING_REF: Encoding<'static>;
}
Expand description

Types whoose references has an Objective-C type-encoding.

Implementing this for T provides Encode implementations for:

  • *const T
  • *mut T
  • &T
  • &mut T
  • NonNull<T>
  • Option<&T>
  • Option<&mut T>
  • Option<NonNull<T>>

Reasoning behind this trait’s existence

External crates cannot implement Encode for pointers or Options containing references, so instead, they can implement this trait. Additionally it would be very cumbersome if every type had to implement Encode for all possible pointer types.

Finally, having this trait allows for much cleaner generic code that need to represent types that can be encoded as pointers.

Safety

References to the object must be FFI-safe.

See the nomicon entry on representing opaque structs for information on how to represent objects that you don’t know the layout of (or use extern type (RFC-1861) if you’re using nightly).

Objective-C will make assumptions about the type (like its size, alignment and ABI) from its encoding, so the implementer must verify that the encoding is accurate.

Concretely, Self::ENCODING_REF must match the result of running @encode in Objective-C with a pointer to the type in question.

Required Associated Constants

The Objective-C type-encoding for a reference of this type.

Should be one of Encoding::Object, Encoding::Block, Encoding::Class, Encoding::Pointer, Encoding::Sel or Encoding::Unknown.

Examples

This is usually implemented either as an object pointer:

const ENCODING_REF: Encoding<'static> = Encoding::Object;

Or as a pointer to the type, delegating the rest to the Encode implementation:

const ENCODING_REF: Encoding<'static> = Encoding::Pointer(&Self::ENCODING);

Implementations on Foreign Types

Pointers to i8 use the special Encoding::String encoding.

Pointers to u8 use the special Encoding::String encoding.

Implementors