Module objc2::encode

Expand description

§Support for type-encodings.

This module contains traits for annotating types that has an Objective-C type-encoding: Specifically Encode for structs/numeric types and RefEncode for references.

Additionally, this exports the Encoding and EncodingBox types from objc2-encode, see that crate for a few more details on what Objective-C type-encodings are.

§Examples

Implementing Encode and RefEncode for a custom type:

use objc2::encode::{Encode, Encoding, RefEncode};

#[repr(C)]
struct MyStruct {
    a: f32, // float
    b: i16, // int16_t
}

unsafe impl Encode for MyStruct {
    const ENCODING: Encoding = Encoding::Struct(
        "MyStruct", // Must use the same name as defined in C header files
        &[
            f32::ENCODING, // Same as Encoding::Float
            i16::ENCODING, // Same as Encoding::Short
        ],
    );
}

// @encode(MyStruct) -> "{MyStruct=fs}"
assert!(MyStruct::ENCODING.equivalent_to_str("{MyStruct=fs}"));

unsafe impl RefEncode for MyStruct {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

// @encode(MyStruct*) -> "^{MyStruct=fs}"
assert!(MyStruct::ENCODING_REF.equivalent_to_str("^{MyStruct=fs}"));

Implementing Encode for a few core-graphics types.

Note that these are available in objc2-foundation, so the implementation here is mostly for demonstration.

use objc2::encode::{Encode, Encoding};

#[cfg(target_pointer_width = "32")]
type CGFloat = f32;
#[cfg(target_pointer_width = "64")]
type CGFloat = f64;

#[repr(C)]
struct CGPoint {
    x: CGFloat,
    y: CGFloat,
}

// SAFETY: The struct is `repr(C)`, and the encoding is correct.
unsafe impl Encode for CGPoint {
    const ENCODING: Encoding = Encoding::Struct("CGPoint", &[CGFloat::ENCODING, CGFloat::ENCODING]);
}

#[repr(C)]
struct CGSize {
    width: CGFloat,
    height: CGFloat,
}

// SAFETY: The struct is `repr(C)`, and the encoding is correct.
unsafe impl Encode for CGSize {
    const ENCODING: Encoding = Encoding::Struct("CGSize", &[CGFloat::ENCODING, CGFloat::ENCODING]);
}

#[repr(C)]
struct CGRect {
    origin: CGPoint,
    size: CGSize,
}

// SAFETY: The struct is `repr(C)`, and the encoding is correct.
unsafe impl Encode for CGRect {
    const ENCODING: Encoding = Encoding::Struct("CGRect", &[CGPoint::ENCODING, CGSize::ENCODING]);
}

fn main() {
    let expected = if cfg!(target_pointer_width = "64") {
        "{CGRect={CGPoint=dd}{CGSize=dd}}"
    } else {
        "{CGRect={CGPoint=ff}{CGSize=ff}}"
    };

    assert!(CGRect::ENCODING.equivalent_to_str(expected));
}

Implementing Encode and RefEncode for a transparent newtype.

use objc2::encode::{Encode, Encoding, RefEncode};

// Note: In this case `NSUInteger` could be a type alias for `usize`, and
// actually that's already available as `objc2::ffi::NSUInteger`.
#[repr(transparent)]
struct NSUInteger {
    _inner: usize,
}

// SAFETY: `NSUInteger` has the same `repr` as `usize`.
unsafe impl Encode for NSUInteger {
    // Running `@encode(NSUInteger)` gives `Q` on 64-bit systems and `I` on
    // 32-bit systems. This corresponds exactly to `usize`, which is also how
    // we've defined our struct.
    const ENCODING: Encoding = usize::ENCODING;
}

// SAFETY: `&NSUInteger` has the same representation as `&usize`.
unsafe impl RefEncode for NSUInteger {
    // Running `@encode(NSUInteger*)` gives `^Q` on 64-bit systems and `^I` on
    // 32-bit systems. So implementing `RefEncode` as a plain pointer is
    // correct.
    const ENCODING_REF: Encoding = Encoding::Pointer(&NSUInteger::ENCODING);
}

fn main() {
    assert!(NSUInteger::ENCODING.equivalent_to_str("Q"));
    assert!(<&NSUInteger>::ENCODING.equivalent_to_str("^Q"));
    assert!(<&NSUInteger>::ENCODING.equivalent_to_str("r^Q"));
}

Implementing RefEncode for an object, in this case NSString.

use objc2::encode::{Encode, Encoding, RefEncode};
use objc2::runtime::AnyObject;

#[repr(transparent)]
struct NSString {
    // `NSString` has the same layout / works the same as `AnyObject`.
    _priv: AnyObject,
}

// We don't know the size of NSString, so we can only hold pointers to it.
//
// SAFETY: The string is `repr(transparent)` over `AnyObject`.
unsafe impl RefEncode for NSString {
    const ENCODING_REF: Encoding = Encoding::Object;
}

fn main() {
    // The `RefEncode` implementation provide an `Encode` implementation for
    // pointers to the object.
    assert_eq!(<*const NSString>::ENCODING, Encoding::Object);
    assert_eq!(<*mut NSString>::ENCODING, Encoding::Object);
    assert_eq!(<&NSString>::ENCODING, Encoding::Object);
    assert_eq!(<&mut NSString>::ENCODING, Encoding::Object);
    assert_eq!(<Option<&NSString>>::ENCODING, Encoding::Object);
    assert_eq!(<Option<&mut NSString>>::ENCODING, Encoding::Object);
}

Implementing RefEncode for a type where you don’t necessarily know about the exact internals / the internals are not representable in Rust.

use objc2::encode::{Encoding, RefEncode};

// We choose in this case to represent `NSDecimal` as an opaque struct because
// we don't know much about the internals.
//
// Therefore we do not implement `Encode`.
#[repr(C)]
struct NSDecimal {
    // Note: This should be an [extern type][rfc-1861] instead, when that
    // becomes possible, for now we use this as a workaround.
    //
    // [rfc-1861]: https://rust-lang.github.io/rfcs/1861-extern-types.html
    _priv: [u8; 0],
}

// SAFETY: `&NSDecimal` is a valid pointer, and the encoding is correct.
unsafe impl RefEncode for NSDecimal {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Encoding::Struct("?", &[]));
}

fn main() {
    // Running `@encode` on `NSDecimal*` on my 64-bit system gives
    // `^{?=cCCC[38C]}`, but empty structs are treated as equivalent to all
    // other structs by `objc2`.
    assert!(NSDecimal::ENCODING_REF.equivalent_to_str("^{?=cCCC[38C]}"));
    // Does not compile:
    // println!("{:?}", NSDecimal::ENCODING);
}

Structs§

ParseError
The error that was encountered while parsing an encoding string.

Enums§

Encoding
An Objective-C type-encoding.
EncodingBox
The boxed version of Encoding.

Traits§