objc2

https://docs.rs/objc2/latest/objc2
Admin
A Rust crate that provides bi-directional bindings and an interface for interacting with...
Tokens:223,436
Snippets:2,069
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example: Get Metaclass

Source: https://docs.rs/objc2/latest/objc2/runtime/type.Class.html

Demonstrates how to retrieve the metaclass of `NSObject` and verify its name.

```rust
use objc2::runtime::NSObject;
use objc2::ClassType;

let cls = NSObject::class();
let metacls = cls.metaclass();

assert_eq!(metacls.name(), c"NSObject");

```

--------------------------------

### Option::as_slice Inverse Example

Source: https://docs.rs/objc2/latest/objc2/ffi/type.IMP.html

Demonstrates the inverse relationship between Option::as_slice and slice::first, showing how to get the first element of a slice derived from an Option.

```rust
for i in [Some(1234_u16), None] {
    assert_eq!(i.as_ref(), i.as_slice().first());
}

```

--------------------------------

### PartialInit Methods

Source: https://docs.rs/objc2/latest/objc2/rc/struct.PartialInit.html

Provides methods to interact with a `PartialInit` object, such as getting raw pointers to the object.

```APIDOC
## PartialInit::as_ptr

### Description
Returns a raw pointer to the object. The pointer is valid for at least as long as the `PartialInit` is held.
See `PartialInit::as_mut_ptr` for the mutable equivalent.

### Method
`PartialInit::as_ptr(obj: &Self) -> *const T`

### Parameters
* `this` (*const Self*) - The `PartialInit` object.

### Returns
* `*const T` - A raw const pointer to the object.
```

```APIDOC
## PartialInit::as_mut_ptr

### Description
Returns a raw mutable pointer to the object. The pointer is valid for at least as long as the `PartialInit` is held.
See `PartialInit::as_ptr` for the immutable equivalent.

### Method
`PartialInit::as_mut_ptr(obj: &mut Self) -> *mut T`

### Parameters
* `this` (*mut Self*) - The `PartialInit` object.

### Returns
* `*mut T` - A raw mutable pointer to the object.
```

--------------------------------

### Example of Exchanging Method Implementations

Source: https://docs.rs/objc2/latest/objc2/ffi/type.objc_method.html

Demonstrates an atomic way to exchange method implementations using `set_implementation` and `implementation`.

```rust
use objc2::runtime::Method;

let m1: &Method;
let m2: &Method;

unsafe {
    let imp = m2.set_implementation(m1.implementation());
    m1.set_implementation(imp);
}

```

--------------------------------

### Attempt to get a non-existent class

Source: https://docs.rs/objc2/latest/objc2/macro.class.html

This example demonstrates calling `class!` with a name that does not correspond to an existing Objective-C class. This will result in a panic at runtime or a linker error if the unstable feature is enabled.

```rust
use objc2::class;

let _ = class!(NonExistentClass);
```

--------------------------------

### Cross-compiling Rust setup

Source: https://docs.rs/objc2/latest/objc2/topics/cross_compiling/index.html

Set up the target, linker, and SDK for cross-compiling Rust. Optionally configure C cross-compilation tools.

```bash
$ rustup target add aarch64-apple-darwin
$ export CARGO_TARGET_AARCH64_APPLE_DARWIN_LINKER=rust-lld
$ export SDKROOT=$(pwd)/MacOSX.sdk
$ export CC=clang CXX=clang++ AR=llvm-ar # If compiling C code
$ cargo build --target aarch64-apple-darwin
```

--------------------------------

### Registering a New Objective-C Class with ClassBuilder

Source: https://docs.rs/objc2/latest/objc2/runtime/struct.ClassBuilder.html

This example demonstrates how to create a new Objective-C class named `MyNumber` that inherits from `NSObject`. It adds a `u32` instance variable, a custom initializer `initWithNumber:`, a convenience class method `withNumber:`, and methods for setting (`setNumber:`) and getting (`number`) the value of the instance variable. Note the use of `AnyObject` for mutable receivers in `init` and `Cell<u32>` for interior mutability of the ivar.

```rust
use core::cell::Cell;

use objc2::rc::Retained;
use objc2::runtime::{AnyClass, AnyObject, ClassBuilder, NSObject, Sel};
use objc2::{sel, msg_send, ClassType};

fn register_class() -> &'static AnyClass {
    // Inherit from NSObject
    let mut builder = ClassBuilder::new(c"MyNumber", NSObject::class())
        .expect("a class with the name MyNumber likely already exists");

    // Add an instance variable of type `Cell<u32>`
    builder.add_ivar::<Cell<u32>>(c"_number");

    // Add an Objective-C method for initializing an instance with a number
    //
    // We "cheat" a bit here, and use `AnyObject` instead of `NSObject`,
    // since only the former is allowed to be a mutable receiver (which is
    // always safe in `init` methods, but not in others).
    unsafe extern "C-unwind" fn init_with_number(
        this: &mut AnyObject,
        _cmd: Sel,
        number: u32,
    ) -> Option<&mut AnyObject> {
        let this: Option<&mut AnyObject> = msg_send![super(this, NSObject::class()), init];
        this.map(|this| {
            let ivar = AnyClass::get(c"MyNumber").unwrap().instance_variable(c"_number").unwrap();
            // SAFETY: The ivar is added with the same type above
            *ivar.load_mut::<Cell<u32>>(this) = Cell::new(number);
            this
        })
    }
    unsafe {
        builder.add_method(
            sel!(initWithNumber:),
            init_with_number as unsafe extern "C-unwind" fn(_, _, _) -> _,
        );
    }

    // Add convenience method for getting a new instance with the number
    extern "C-unwind" fn with_number(
        cls: &AnyClass,
        _cmd: Sel,
        number: u32,
    ) -> *mut NSObject {
        let obj: Option<Retained<NSObject>> = unsafe {
            msg_send![
                msg_send![cls, alloc],
                initWithNumber: number,
            ]
        };
        obj.map(Retained::autorelease_return).unwrap_or(std::ptr::null_mut())
    }
    unsafe {
        builder.add_class_method(
            sel!(withNumber:),
            with_number as extern "C-unwind" fn(_, _, _) -> _,
        );
    }

    // Add an Objective-C method for setting the number
    extern "C-unwind" fn my_number_set(this: &NSObject, _cmd: Sel, number: u32) {
        let ivar = AnyClass::get(c"MyNumber").unwrap().instance_variable(c"_number").unwrap();
        // SAFETY: The ivar is added with the same type above
        unsafe { ivar.load::<Cell<u32>>(this) }.set(number);
    }
    unsafe {
        builder.add_method(sel!(setNumber:), my_number_set as extern "C-unwind" fn(_, _, _));
    }

    // Add an Objective-C method for getting the number
    extern "C-unwind" fn my_number_get(this: &NSObject, _cmd: Sel) -> u32 {
        let ivar = AnyClass::get(c"MyNumber").unwrap().instance_variable(c"_number").unwrap();
        // SAFETY: The ivar is added with the same type above
        unsafe { ivar.load::<Cell<u32>>(this) }.get()
    }
    unsafe {
        builder.add_method(sel!(number), my_number_get as extern "C-unwind" fn(_, _) -> _);
    }

    builder.register()
}

// Usage

// Note: you should only do class registration once! This can be ensured
// with `std::sync::Once` or the `once_cell` crate.
let cls = register_class();

let obj: Retained<NSObject> = unsafe {
    msg_send![cls, withNumber: 42u32]
};

let n: u32 = unsafe { msg_send![&obj, number] };
assert_eq!(n, 42);

let _: () = unsafe { msg_send![&obj, setNumber: 12u32] };
let n: u32 = unsafe { msg_send![&obj, number] };
assert_eq!(n, 12);

```

--------------------------------

### Option::into_flat_iter Example

Source: https://docs.rs/objc2/latest/objc2/ffi/type.IMP.html

Demonstrates transforming an optional iterator into a flat iterator. This API is nightly-only and experimental.

```rust
#![feature(option_into_flat_iter)]

let o1 = Some([1, 2]);
let o2 = None::<&[usize]>;

assert_eq!(o1.into_flat_iter().collect::<Vec<_>>(), [1, 2]);
assert_eq!(o2.into_flat_iter().collect::<Vec<_>>(), Vec::<&usize>::new());

```

--------------------------------

### Objective-C Instance Creation and Method Call

Source: https://docs.rs/objc2/latest/objc2/topics/layered_safety/index.html

Shows how to create an instance of `NSData` using `msg_send!` and retrieve its length. This example requires manual `release` calls.

```rust
use objc2::ffi::NSUInteger;
use objc2::runtime::NSObject;
use objc2::{class, msg_send};

let obj: *const NSObject = unsafe { msg_send![class!(NSData), new] };
let length: NSUInteger = unsafe { msg_send![obj, length] };
// We have to specify the return type here, see layer 4 below
let _: () = unsafe { msg_send![obj, release] };
```

--------------------------------

### Example Usage of Bridging

Source: https://docs.rs/objc2/latest/objc2/topics/crate_interop/index.html

Demonstrates the practical application of `CFString` to `NSString` and `NSString` to `CFString` conversions with assertions to verify correctness.

```rust
use core_foundation::base::TCFType;
use core_foundation::string::{CFString, CFStringRef};
use objc2_foundation::{NSString, ns_string};
use objc2::rc::Retained;

fn cf_string_to_ns(s: &CFString) -> &NSString {
    let ptr: CFStringRef = s.as_concrete_TypeRef();
    let ptr: *const NSString = ptr.cast();
    // SAFETY: CFString is toll-free bridged with NSString.
    unsafe { ptr.as_ref().unwrap() }
}

// Note: The `core_foundation` crate does not allow zero-cost (non-owning)
// references to objects, so we have to convert from a `Retained<NSString>` to
// the owning `CFString` (i.e. `&NSString -> &CFString` is not possible).
fn ns_string_to_cf(s: Retained<NSString>) -> CFString {
    // Yield ownership over the string
    let ptr: *const NSString = Retained::into_raw(s);
    let ptr: CFStringRef = ptr.cast();
    // SAFETY: NSString is toll-free bridged with CFString, and
    // ownership was passed above with `Retained::into_raw`.
    unsafe { CFString::wrap_under_create_rule(ptr) }
}

let cf = CFString::new("foo");
let ns = NSString::from_str("foo");
assert_eq!(cf_string_to_ns(&cf), &*ns);
assert_eq!(cf, ns_string_to_cf(ns));
```

--------------------------------

### Example: Create NSView on Main Thread

Source: https://docs.rs/objc2/latest/objc2/trait.MainThreadOnly.html

Demonstrates allocating and initializing an NSView on the main thread using MainThreadMarker. Ensure you are on the main thread before calling MainThreadMarker::new().

```rust
use objc2::{MainThreadOnly, MainThreadMarker};
use objc2_app_kit::NSView;
use objc2_core_foundation::CGRect;

let mtm = MainThreadMarker::new().expect("must be on the main thread");

let frame = CGRect::default();
let view = NSView::initWithFrame(NSView::alloc(mtm), frame);
```

--------------------------------

### Example of Exchanging Method Implementations

Source: https://docs.rs/objc2/latest/objc2/runtime/struct.Method.html

Demonstrates a manual, non-atomic way to exchange method implementations, which is often superseded by `exchange_implementation` for safety and atomicity.

```rust
use objc2::runtime::Method;

let m1: &Method;
let m2: &Method;

unsafe {
    let imp = m2.set_implementation(m1.implementation());
    m1.set_implementation(imp);
}
```

--------------------------------

### Registering Common Selectors

Source: https://docs.rs/objc2/latest/objc2/macro.sel.html

Demonstrates how to get `Sel` objects for common Objective-C selectors like `alloc`, `description`, and private methods.

```rust
use objc2::sel;
let sel = sel!(alloc);
let sel = sel!(description);
let sel = sel!(_privateMethod);
```

--------------------------------

### Example: Verify Selector Types

Source: https://docs.rs/objc2/latest/objc2/runtime/type.Class.html

Demonstrates verifying the signature of the `isKindOfClass:` selector on `NSObject` to ensure it accepts a class and returns a `BOOL`.

```rust
use objc2::{class, sel};
use objc2::runtime::{AnyClass, Bool};
let cls = class!(NSObject);
let sel = sel!(isKindOfClass:);
// Verify that `isKindOfClass:`:
// - Exists on the class
// - Takes a class as a parameter
// - Returns a BOOL
let result = cls.verify_sel::<(&AnyClass,), Bool>(sel);
assert!(result.is_ok());

```

--------------------------------

### Implementing NSObjectProtocol for MyClass

Source: https://docs.rs/objc2/latest/objc2/macro.extern_conformance.html

This example demonstrates how to use the `extern_conformance!` macro to implement the `NSObjectProtocol` for a type `MyClass` defined with `extern_class!`. This is a common pattern for ensuring basic Objective-C compatibility.

```rust
use objc2_foundation::NSObjectProtocol;
use objc2::runtime::NSObject;
use objc2::{extern_class, extern_conformance};

extern_class!(
    #[unsafe(super(NSObject))]
    #[derive(PartialEq, Eq, Hash, Debug)]
    pub struct MyClass;
);

// SAFETY: The class `MyClass` conforms to the `NSObject` protocol (since
// its superclass `NSObject` does).
extern_conformance!(unsafe impl NSObjectProtocol for MyClass {});
```

--------------------------------

### Configure Objective-C Compiler Flags with cc crate

Source: https://docs.rs/objc2/latest/objc2/ffi/index.html

Example usage in a build.rs file to configure Objective-C compiler flags for exceptions, ARC, and runtime.

```rust
fn main() {
    let mut builder = cc::Build::new();
    builder.compiler("clang");
    builder.file("my_objective_c_script.m");

    builder.flag("-fobjc-exceptions");
    builder.flag("-fobjc-arc");
    builder.flag("-fobjc-runtime=..."); // If not compiling for Apple

    builder.compile("libmy_objective_c_script.a");
}
```

--------------------------------

### Equivalent Objective-C Code

Source: https://docs.rs/objc2/latest/objc2/macro.define_class.html

This Objective-C code provides a direct equivalent to the Rust `define_class!` example, demonstrating the same class structure, instance variables, methods, and protocol implementation.

```objective-c
#import <Foundation/Foundation.h>

@interface MyCustomObject: NSObject <NSCopying>
- (instancetype)initWithFoo:(uint8_t)foo;
- (uint8_t)foo;
- (NSObject*)object;
+ (BOOL)myClassMethod;
@end


@implementation MyCustomObject {
    // Instance variables
    uint8_t foo;
    int bar;
    NSObject* _Nonnull object;
}

- (instancetype)initWithFoo:(uint8_t)foo_arg {
    self = [super init];
    if (self) {
        self->foo = foo_arg;
        self->bar = 42;
        self->object = [NSObject new];
    }
    return self;
}

- (uint8_t)foo {
    return self->foo;
}

- (NSObject*)object {
    return self->object;
}

+ (BOOL)myClassMethod {
    return YES;
}

// NSCopying

- (id)copyWithZone:(NSZone *)_zone {
    MyCustomObject* new = [[MyCustomObject alloc] initWithFoo: self->foo];
    new->bar = self->bar;
    new->obj = self->obj;
    return new;
}

@end

```

--------------------------------

### Option::is_none_or Example

Source: https://docs.rs/objc2/latest/objc2/ffi/type.IMP.html

Checks if an Option is None or if its value satisfies a given predicate. This method consumes the Option if it's Some.

```rust
let x: Option<u32> = Some(2);
assert_eq!(x.is_none_or(|x| x > 1), true);

let x: Option<u32> = Some(0);
assert_eq!(x.is_none_or(|x| x > 1), false);

let x: Option<u32> = None;
assert_eq!(x.is_none_or(|x| x > 1), true);

let x: Option<String> = Some("ownership".to_string());
assert_eq!(x.as_ref().is_none_or(|x| x.len() > 1), true);
println!("still alive {:?}", x);

```

--------------------------------

### Create a Simple GUI Application with objc2

Source: https://docs.rs/objc2/latest/objc2/index.html

This example demonstrates creating a basic GUI application using `objc2-foundation` and `objc2-app-kit`. It defines a delegate for `NSApplication` and `NSWindow` to manage the application lifecycle and window behavior, including displaying a "Hello World" label.

```rust
#![deny(unsafe_op_in_unsafe_fn)]
use std::cell::OnceCell;

use objc2::rc::Retained;
use objc2::runtime::ProtocolObject;
use objc2::{
    define_class,
    msg_send,
    DefinedClass,
    MainThreadOnly,
};
use objc2_app_kit::{
    NSApplication,
    NSApplicationActivationPolicy,
    NSApplicationDelegate,
    NSAutoresizingMaskOptions,
    NSBackingStoreType,
    NSColor,
    NSFont,
    NSTextAlignment,
    NSTextField,
    NSWindow,
    NSWindowDelegate,
    NSWindowStyleMask,
};
use objc2_foundation::{
    ns_string,
    MainThreadMarker,
    NSNotification,
    NSObject,
    NSObjectProtocol,
    NSPoint,
    NSRect,
    NSSize,
};

#[derive(Debug, Default)]
struct AppDelegateIvars {
    window: OnceCell<Retained<NSWindow>>,
}

define_class!(
    // SAFETY:
    // - The superclass NSObject does not have any subclassing requirements.
    // - `Delegate` does not implement `Drop`.
    #[unsafe(super = NSObject)]
    #[thread_kind = MainThreadOnly]
    #[ivars = AppDelegateIvars]
    struct Delegate;

    // SAFETY: `NSObjectProtocol` has no safety requirements.
    unsafe impl NSObjectProtocol for Delegate {}

    // SAFETY: `NSApplicationDelegate` has no safety requirements.
    unsafe impl NSApplicationDelegate for Delegate {
        // SAFETY: The signature is correct.
        #[unsafe(method(applicationDidFinishLaunching:))]
        fn did_finish_launching(&self, notification: &NSNotification) {
            let mtm = self.mtm();

            let app = unsafe {
                notification.object()
            }
            .unwrap()
            .downcast::<NSApplication>()
            .unwrap();

            let text_field = unsafe {
                let text_field = NSTextField::labelWithString(ns_string!("Hello, World!"), mtm);
                text_field.setFrame(NSRect::new(
                    NSPoint::new(5.0, 100.0),
                    NSSize::new(290.0, 100.0),
                ));
                text_field.setTextColor(Some(&NSColor::colorWithSRGBRed_green_blue_alpha(
                    0.0, 0.5, 0.0, 1.0,
                )));
                text_field.setAlignment(NSTextAlignment::Center);
                text_field.setFont(Some(&NSFont::systemFontOfSize(45.0)));
                text_field.setAutoresizingMask(
                    NSAutoresizingMaskOptions::ViewWidthSizable
                        | NSAutoresizingMaskOptions::ViewHeightSizable,
                );
                text_field
            };

            // SAFETY: We disable releasing when closed below.
            let window = unsafe {
                NSWindow::initWithContentRect_styleMask_backing_defer(
                    NSWindow::alloc(mtm),
                    NSRect::new(NSPoint::new(0.0, 0.0), NSSize::new(300.0, 300.0)),
                    NSWindowStyleMask::Titled
                        | NSWindowStyleMask::Closable
                        | NSWindowStyleMask::Miniaturizable
                        | NSWindowStyleMask::Resizable,
                    NSBackingStoreType::Buffered,
                    false,
                )
            };
            // SAFETY: Disable auto-release when closing windows.
            // This is required when creating `NSWindow` outside a window
            // controller.
            unsafe { window.setReleasedWhenClosed(false) };

            // Set various window properties.
            window.setTitle(ns_string!("A window"));
            let view = window.contentView().expect("window must have content view");
            unsafe { view.addSubview(&text_field) };
            window.center();
            unsafe { window.setContentMinSize(NSSize::new(300.0, 300.0)) };
            window.setDelegate(Some(ProtocolObject::from_ref(self)));

            // Show the window.
            window.makeKeyAndOrderFront(None);

            // Store the window in the delegate.
            self.ivars().window.set(window).unwrap();

            app.setActivationPolicy(NSApplicationActivationPolicy::Regular);

            // Activate the application.
            // Required when launching unbundled (as is done with Cargo).
            #[allow(deprecated)]
            app.activateIgnoringOtherApps(true);
        }
    }

    // SAFETY: `NSWindowDelegate` has no safety requirements.
    unsafe impl NSWindowDelegate for Delegate {
        #[unsafe(method(windowWillClose:))]
        fn window_will_close(&self, _notification: &NSNotification) {
            // Quit the application when the window is closed.
            unsafe { NSApplication::sharedApplication(self.mtm()).terminate(None) };
        }
    }
);

impl Delegate {

```

--------------------------------

### Objective-C @encode Directive Example

Source: https://docs.rs/objc2/latest/objc2/encode/enum.Encoding.html

This snippet demonstrates how to use the Objective-C @encode directive to get the type encoding of a class like NSException.

```objective-c
NSLog(@"Encoding of NSException: %s", @encode(NSException));
```

--------------------------------

### Launch Application from Storyboard (macOS)

Source: https://docs.rs/objc2/latest/objc2/topics/run_loop/index.html

This example shows how to launch an application using a storyboard on macOS. It ensures the `AppDelegate` class is initialized so the storyboard can find it. This is typically used when the application is bundled and configured via a storyboard.

```rust
use objc2::MainThreadMarker;
use objc2_app_kit::NSApplication;
use crate::AppDelegate; // Assuming AppDelegate is defined in the same crate

// AppKit (macOS), if bundled and using a storyboard.
#[cfg(target_os = "macos")]
fn main() {
    let mtm = MainThreadMarker::new().unwrap();
    // Initialize the class so that the storyboard can see it.
    //
    // The name specified in `define_class!`, i.e. "AppDelegate", must
    // match what's specified in the storyboard.
    let _cls = AppDelegate::class();
    NSApplication::main(mtm);
}
```

--------------------------------

### Launch Application with Delegate (UIKit)

Source: https://docs.rs/objc2/latest/objc2/topics/run_loop/index.html

This example demonstrates launching a UIKit application (iOS, tvOS, watchOS, visionOS) using `UIApplication::main`. It specifies the delegate class name as a string, which is required for UIKit applications not using scenes.

```rust
use objc2::MainThreadMarker;
use objc2_foundation::NSString;
use objc2_ui_kit::UIApplication;
use crate::AppDelegate; // Assuming AppDelegate is defined in the same crate

// UIKit (iOS/tvOS/watchOS/visionOS).
#[cfg(not(target_os = "macos"))]
fn main() {
    let mtm = MainThreadMarker::new().unwrap();
    let delegate_class = NSString::from_class(AppDelegate::class());
    UIApplication::main(None, Some(&delegate_class), mtm);
}
```

--------------------------------

### fn take(self, limit: u64) -> Take<Self>

Source: https://docs.rs/objc2/latest/objc2/rc/type.Id.html

Creates an adapter which will read at most `limit` bytes from it.

```APIDOC
## fn take(self, limit: u64) -> Take<Self>

### Description
Creates an adapter which will read at most `limit` bytes from it.

### Method
`take`

### Parameters
- **limit** (u64): The maximum number of bytes to read.

### Response
- **Take<Self>**: A `Take` adapter that limits the number of bytes read.
```

--------------------------------

### RefEncode Example: Object Pointer

Source: https://docs.rs/objc2/latest/objc2/encode/trait.RefEncode.html

Example implementation of `ENCODING_REF` for types that are Objective-C objects.

```rust
const ENCODING_REF: Encoding = Encoding::Object;
```

--------------------------------

### Example of MainThreadMarker::new() usage

Source: https://docs.rs/objc2/latest/objc2/struct.MainThreadMarker.html

A simple example demonstrating how to use MainThreadMarker::new() to check if the current thread is the main thread.

```rust
use objc2::MainThreadMarker;

if MainThreadMarker::new().is_some() {
    // Is the main thread
} else {
    // Not the main thread
}
```

--------------------------------

### Getting Type-Erased Object

Source: https://docs.rs/objc2/latest/objc2/runtime/struct.ProtocolObject.html

Get a type-erased object from a type implementing a protocol. This is the recommended method for obtaining an owned, type-erased object.

```rust
pub fn from_retained<T>(obj: Retained<T>) -> Retained<Self>
where P: ImplementedBy<T> + 'static, T: Message + 'static,
```

--------------------------------

### Get Instance Variable (Deprecated)

Source: https://docs.rs/objc2/latest/objc2/ffi/type.objc_object.html

Deprecated method to get an instance variable of a specific type. Use `Ivar::load` instead.

```rust
pub unsafe fn get_ivar<T: Encode>(&self, name: &str) -> &T
```

--------------------------------

### Create NSURLComponents using idiomatic Rust

Source: https://docs.rs/objc2/latest/objc2/macro.msg_send.html

Shows the idiomatic Rust equivalent for creating and configuring `NSURLComponents` using the framework's provided methods, which is generally preferred over direct `msg_send!`.

```rust
use objc2_foundation::{NSNumber, NSString, NSURLComponents};

let components = unsafe { NSURLComponents::new() };
safe { components.setPort(Some(&NSNumber::new_i32(8080))) };
safe { components.setHost(Some(&NSString::from_str("example.com"))) };
safe { components.setScheme(Some(&NSString::from_str("http"))) };
let string = unsafe { components.string() };

assert_eq!(string.unwrap().to_string(), "http://example.com:8080");

```

--------------------------------

### RefEncode Example: Pointer to Type

Source: https://docs.rs/objc2/latest/objc2/encode/trait.RefEncode.html

Example implementation of `ENCODING_REF` for types that are pointers to other types, delegating to the inner type's `Encode` implementation.

```rust
const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
```

--------------------------------

### Getting Type-Erased Object (Deprecated)

Source: https://docs.rs/objc2/latest/objc2/runtime/struct.ProtocolObject.html

Get a type-erased object from a type implementing a protocol. This method is deprecated; use `ProtocolObject::from_retained` instead.

```rust
pub fn from_id<T>(obj: Retained<T>) -> Retained<Self>
where P: ImplementedBy<T> + 'static, T: Message + 'static,
```

--------------------------------

### Get Mutable Instance Variable (Deprecated)

Source: https://docs.rs/objc2/latest/objc2/ffi/type.objc_object.html

Deprecated method to get a mutable instance variable of a specific type. Use `Ivar::load_mut` instead.

```rust
pub unsafe fn get_mut_ivar<T: Encode>(&mut self, name: &str) -> &mut T
```

--------------------------------

### Create and Run Objective-C Application with Delegate in Rust

Source: https://docs.rs/objc2/latest/objc2/index.html

This snippet initializes a new Objective-C application, sets a custom delegate, and starts the application's run loop. Ensure the `MainThreadMarker` is correctly obtained.

```rust
fn new(mtm: MainThreadMarker) -> Retained<Self> {
    let this = Self::alloc(mtm).set_ivars(AppDelegateIvars::default());
    // SAFETY: The signature of `NSObject`'s `init` method is correct.
    unsafe { msg_send![super(this), init] }
}
}

fn main() {
    let mtm = MainThreadMarker::new().unwrap();

    let app = NSApplication::sharedApplication(mtm);
    let delegate = Delegate::new(mtm);
    app.setDelegate(Some(ProtocolObject::from_ref(&*delegate)));

    app.run();
}
```

--------------------------------

### class_getInstanceSize

Source: https://docs.rs/objc2/latest/objc2/ffi/fn.class_getInstanceSize.html

Get the size of an instance of a class.

```APIDOC
## class_getInstanceSize

### Description
Get the size of an instance of a class.

### Signature
```rust
pub unsafe extern "C" fn class_getInstanceSize(
    cls: *const AnyClass,
) -> usize
```

### Parameters
* `cls` (*const AnyClass) - A pointer to the class.

### Returns
* `usize` - The size of an instance of the class in bytes.
```

--------------------------------

### type_id(&self) -> TypeId

Source: https://docs.rs/objc2/latest/objc2/struct.MainThreadMarker.html

Gets the TypeId of the MainThreadMarker.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`. Read more
```

--------------------------------

### Create a new NSObject instance

Source: https://docs.rs/objc2/latest/objc2/runtime/struct.NSObject.html

Use `NSObject::new()` as a shorthand for calling `alloc` and then `init` to create a new, empty NSObject instance.

```rust
use objc2::runtime::NSObject;
use objc2::AnyThread;

let obj = NSObject::init(NSObject::alloc());
```

--------------------------------

### Get Instance Size

Source: https://docs.rs/objc2/latest/objc2/runtime/type.Class.html

Returns the size in bytes of instances of the class.

```rust
pub fn instance_size(&self) -> usize

```

--------------------------------

### Create NSURLComponents using msg_send!

Source: https://docs.rs/objc2/latest/objc2/macro.msg_send.html

Demonstrates creating an empty `NSURLComponents` instance by calling the `new` class method using `msg_send!`.

```rust
use objc2::rc::Retained;
use objc2::{msg_send, ClassType};
use objc2_foundation::{NSNumber, NSString, NSURLComponents};


// Create an empty `NSURLComponents` by calling the class method `new`.
let components: Retained<NSURLComponents> = unsafe {
    //          ^^^^^^^^^^^^^^^^^^^^^^^^^ the return type, a memory-managed
    //                                    `NSURLComponents` instance
    //
    msg_send![NSURLComponents::class(), new]
    //        ------------------------  ^^^ the selector `new`
    //        |
    //        the receiver, in this case the class itself
};


// Create a new `NSNumber` from an integer.
let port: Retained<NSNumber> = unsafe {
    msg_send![NSNumber::class(), numberWithInt: 8080i32]
    //                           -------------- ^^^^^^^ the argument to the method
    //                           |
    //                           the selector `numberWithInt:`
    //
    // Note how we must fully specify the argument as `8080i32` instead of just `8080`.
};


// Set the port property of the URL.
let _: () = unsafe { msg_send![&components, setPort: &*port] };
//     --                                   -------- ^^^^^^ the port is deref'd to
//     |
//     |
//     |
//     return type (i.e. nothing / void)
//
// Note that even return types of `void` must be explicitly specified as `()`.


// Set the `host` property of the URL.
let host: Retained<NSString> = unsafe {
    msg_send![NSString::class(), stringWithUTF8String: c"example.com".as_ptr()]
};
let _: () = unsafe { msg_send![&components, setHost: &*host] };


// Set the `scheme` property of the URL.
let scheme: Retained<NSString> = unsafe {
    msg_send![NSString::class(), stringWithUTF8String: c"http".as_ptr()]
};
let _: () = unsafe { msg_send![&components, setScheme: &*scheme] };


// Get the combined URL in string form.
let string: Option<Retained<NSString>> = unsafe { msg_send![&components, string] };
//          ^^^^^^ the method can return NULL, so we specify an option here


assert_eq!(string.unwrap().to_string(), "http://example.com:8080");

```

--------------------------------

### ProtocolObject::from_retained

Source: https://docs.rs/objc2/latest/objc2/runtime/struct.ProtocolObject.html

Get a type-erased object from a type implementing a protocol.

```APIDOC
## ProtocolObject::from_retained

### Description
Get a type-erased object from a type implementing a protocol.

### Method
`pub fn from_retained<T>(obj: Retained<T>) -> Retained<Self>`

### Parameters
#### Path Parameters
- **obj** (`Retained<T>`): A retained object implementing the protocol.

### Type Constraints
- `P: ?Sized`
- `P: ImplementedBy<T> + 'static`
- `T: Message + 'static`
```

--------------------------------

### Using objc-sys v0.0.1

Source: https://docs.rs/objc2/latest/objc2/topics/changelog/index.html

The project now uses the `objc-sys` crate version `v0.0.1` for potentially better interoperability with other crates linking to `libobjc`.

```rust
Now uses the `objc-sys` (`v0.0.1`) crate for possibly better interoperability with other crates that link to `libobjc`.
```

--------------------------------

### Example: Check if Metaclass

Source: https://docs.rs/objc2/latest/objc2/runtime/type.Class.html

Compares `is_metaclass()` for a regular class (`NSObject`) and its metaclass.

```rust
use objc2::runtime::NSObject;
use objc2::ClassType;

let cls = NSObject::class();
let metacls = cls.metaclass();

assert!(!cls.is_metaclass());
assert!(metacls.is_metaclass());

```

--------------------------------

### from(obj: &T) -> Self

Source: https://docs.rs/objc2/latest/objc2/struct.MainThreadMarker.html

Get a `MainThreadMarker` from a main-thread-only object. This is a shorthand for `MainThreadOnly::mtm`.

```APIDOC
## fn from(obj: &T) -> Self

### Description
Get a `MainThreadMarker` from a main-thread-only object.
This is a shorthand for `MainThreadOnly::mtm`.
```

--------------------------------

### Getting Selector Name

Source: https://docs.rs/objc2/latest/objc2/runtime/struct.Sel.html

Returns the string representation of the selector as a static CStr.

```rust
pub fn name(self) -> &'static CStr
```

--------------------------------

### Using Autogenerated Framework Bindings for `NSData`

Source: https://docs.rs/objc2/latest/objc2/topics/layered_safety/index.html

Demonstrates the usage of `objc2-foundation` crate, which provides autogenerated bindings for Apple's frameworks, allowing for a concise and safe way to interact with Objective-C classes like `NSData`.

```rust
use objc2_foundation::NSData;

let obj = NSData::new();
let length = obj.length();
```

--------------------------------

### ProtocolObject::from_ref

Source: https://docs.rs/objc2/latest/objc2/runtime/struct.ProtocolObject.html

Get an immutable type-erased reference from a type implementing a protocol.

```APIDOC
## ProtocolObject::from_ref

### Description
Get an immutable type-erased reference from a type implementing a protocol.

### Method
`pub fn from_ref<T: ?Sized + Message>(obj: &T) -> &Self`

### Parameters
#### Path Parameters
- **obj** (`&T`): A reference to the object implementing the protocol.

### Type Constraints
- `P: ?Sized`
- `T: ?Sized + Message`
- `P: ImplementedBy<T>`
```

--------------------------------

### NSData Creation and Usage with Retained Pointers

Source: https://docs.rs/objc2/latest/objc2/topics/layered_safety/index.html

Demonstrates creating an NSData instance using `msg_send!` and managing its memory with the `Retained` smart pointer, ensuring automatic deallocation.

```APIDOC
## `Retained<T>` Example

### Description
This example shows how to create an `NSData` object and retrieve its length using the `Retained` smart pointer for automatic memory management.

### Method
`msg_send!` macro for object creation and method invocation.

### Endpoint
N/A (Illustrative code)

### Parameters
N/A

### Request Example
```rust
use objc2::ffi::NSUInteger;
use objc2::rc::Retained;
use objc2::runtime::NSObject;
use objc2::{class, msg_send};

let obj: Retained<NSObject> = unsafe { msg_send![class!(NSData), new] };
let length: NSUInteger = unsafe { msg_send![&obj, length] };
// `obj` goes out of scope, `release` is automatically sent to the object
```

### Response
N/A
```

--------------------------------

### Get Method Name

Source: https://docs.rs/objc2/latest/objc2/runtime/struct.Method.html

Retrieves the name of a method. This is a fundamental operation for introspection.

```rust
pub fn name(&self) -> Sel
```

--------------------------------

### Implementing DowncastTarget for NSString

Source: https://docs.rs/objc2/latest/objc2/trait.DowncastTarget.html

Example of safely implementing DowncastTarget for NSString, which has no generic parameters.

```rust
// SAFETY: NSString does not have any generic parameters.
unsafe impl DowncastTarget for NSString {}
```

--------------------------------

### Constructing a Root ClassBuilder

Source: https://docs.rs/objc2/latest/objc2/declare/type.ClassDecl.html

Use this method to construct a `ClassBuilder` for a new root class. An implementation for `+initialize` must be provided. Note that implementing a root class is complex and may require implementing the entire `NSObject` protocol.

```rust
pub fn root<F>(name: &CStr, initialize_fn: F) -> Option<Self>
where
    F: MethodImplementation<Callee = AnyClass, Arguments = (), Return = ()>,
```

--------------------------------

### Get Metaclass

Source: https://docs.rs/objc2/latest/objc2/runtime/type.Class.html

Returns the metaclass of the current class. The metaclass is the class of a class object.

```rust
pub fn metaclass(&self) -> &Self

```

--------------------------------

### NSObject::new

Source: https://docs.rs/objc2/latest/objc2/runtime/struct.NSObject.html

Creates a new empty NSObject. This is a shorthand for calling `alloc` and then `init`.

```APIDOC
## NSObject::new

### Description
Creates a new empty `NSObject`.
This method is a shorthand for calling `alloc` and then `init`.

### Returns
A new, retained `NSObject` instance.
```

--------------------------------

### Get Method Implementation

Source: https://docs.rs/objc2/latest/objc2/runtime/struct.Method.html

Retrieves the current implementation pointer for the method. This is an unsafe operation.

```rust
pub fn implementation(&self) -> Imp
```

--------------------------------

### Create NSObject using msg_send! and from_raw

Source: https://docs.rs/objc2/latest/objc2/rc/type.Id.html

Demonstrates creating an `NSObject` using `msg_send!`, raw pointers, and `Retained::from_raw`.

```rust
use objc2::rc::Retained;
use objc2::runtime::NSObject;
use objc2::{msg_send, AnyThread, ClassType};

// Manually using `msg_send!`, pointers and `Retained::from_raw`
let obj: *mut NSObject = unsafe { msg_send![NSObject::class(), alloc] };
let obj: *mut NSObject = unsafe { msg_send![obj, init] };
// SAFETY: `-[NSObject init]` returns +1 retain count
let obj: Retained<NSObject> = unsafe { Retained::from_raw(obj).unwrap() };

// Or automatically by specifying `Retained` as the return value from
// `msg_send!` (it will do the correct conversion internally).
let obj: Retained<NSObject> = unsafe { msg_send![NSObject::alloc(), init] };

// Or using the `NSObject::new` method
let obj = NSObject::new();
```

--------------------------------

### Option::is_none Example

Source: https://docs.rs/objc2/latest/objc2/ffi/type.IMP.html

Checks if an Option is None. Returns true if it's None, false if it's Some.

```rust
let x: Option<u32> = Some(2);
assert_eq!(x.is_none(), false);

let x: Option<u32> = None;
assert_eq!(x.is_none(), true);

```

--------------------------------

### Allocating and Initializing an Object

Source: https://docs.rs/objc2/latest/objc2/trait.ClassType.html

Shows how to allocate a new instance of an object using `alloc()` and then initialize it using a message send. This is a common pattern for creating Objective-C objects in Rust.

```rust
use objc2::{msg_send, AnyThread};
use objc2::rc::Retained;

let obj = MyObject::alloc();

// Now we can call initializers on this newly allocated object.
//
// SAFETY: `MyObject` can safely be initialized with `init`.
let obj: Retained<MyObject> = unsafe { msg_send![obj, init] };
```

--------------------------------

### Get Protocol Name

Source: https://docs.rs/objc2/latest/objc2/runtime/struct.AnyProtocol.html

Returns the name of the protocol as a CStr. This is a reference to the protocol's name string.

```rust
pub fn name(&self) -> &CStr
```

--------------------------------

### fn by_ref(&mut self) -> &mut Self

Source: https://docs.rs/objc2/latest/objc2/rc/type.Id.html

Creates a "by reference" adapter for this instance.

```APIDOC
## fn by_ref(&mut self) -> &mut Self

### Description
Creates a “by reference” adapter for this instance of `Read` or `Write`.

### Method
`by_ref`

### Parameters
None

### Response
- **&mut Self**: A mutable reference to the adapter.
```

--------------------------------

### fn stream_position(&mut self) -> Result<u64>

Source: https://docs.rs/objc2/latest/objc2/rc/type.Id.html

Returns the current seek position from the start of the stream.

```APIDOC
## fn stream_position(&mut self) -> Result<u64>

### Description
Returns the current seek position from the start of the stream.

### Method
`stream_position`

### Parameters
None

### Response
- **Result<u64>**: The current stream position on success, or an Error on failure.
```

--------------------------------

### Option::is_some_and Example

Source: https://docs.rs/objc2/latest/objc2/ffi/type.IMP.html

Checks if an Option is Some and its value satisfies a given predicate. This method consumes the Option if it's Some.

```rust
let x: Option<u32> = Some(2);
assert_eq!(x.is_some_and(|x| x > 1), true);

let x: Option<u32> = Some(0);
assert_eq!(x.is_some_and(|x| x > 1), false);

let x: Option<u32> = None;
assert_eq!(x.is_some_and(|x| x > 1), false);

let x: Option<String> = Some("ownership".to_string());
assert_eq!(x.as_ref().is_some_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);

```

--------------------------------

### fn chain<R>(self, next: R) -> Chain<Self, R>

Source: https://docs.rs/objc2/latest/objc2/rc/type.Id.html

Creates an adapter which will chain this stream with another.

```APIDOC
## fn chain<R>(self, next: R) -> Chain<Self, R>

### Description
Creates an adapter which will chain this stream with another.

### Method
`chain`

### Parameters
- **next** (R): The next `Read` instance to chain.

### Response
- **Chain<Self, R>**: A `Chain` adapter that combines two `Read` instances.
```

--------------------------------

### Querying NSObject Class Information

Source: https://docs.rs/objc2/latest/objc2/runtime/index.html

Demonstrates how to retrieve and inspect properties of the `NSObject` class using runtime functions. This includes checking for method existence, examining instance variables, and inspecting method signatures.

```rust
use objc2::runtime::{AnyClass, NSObject};
use objc2::{sel, ClassType, Encode};

fn main() {
    // Get the class representing `NSObject`
    let cls = NSObject::class();

    // Inspect various properties of the class
    println!("NSObject superclass: {:?}", cls.superclass());
    println!("NSObject size: {}", cls.instance_size());
    println!(
        "-[NSObject alloc] would work: {}",
        cls.responds_to(sel!(alloc))
    );
    println!(
        "+ [NSObject alloc] would work: {}",
        cls.metaclass().responds_to(sel!(alloc))
    );

    // Inspect an instance variable on the class
    //
    // Note: You should not rely on the `isa` ivar being available,
    // this is only for demonstration.
    let ivar = cls
        .instance_variable(c"isa")
        .expect("no ivar with name 'isa' found on NSObject");
    println!(
        "Instance variable {:?} has type encoding {:?}",
        ivar.name(),
        ivar.type_encoding()
    );
    assert!(<*const AnyClass>::ENCODING.equivalent_to_str(ivar.type_encoding().to_str().unwrap()));

    // Inspect a method of the class
    let method = cls.instance_method(sel!(hash)).unwrap();
    println!(
        "-[NSObject hash] takes {} parameters",
        method.arguments_count()
    );
    let hash_return = method.return_type();
    println!("-[NSObject hash] return type: {hash_return:?}");
    assert!(usize::ENCODING.equivalent_to_str(hash_return.to_str().unwrap()));

    // Create an instance
    let obj = NSObject::new();

    println!("NSObject address: {obj:p}");

    // Read an ivar on the object
    let isa: *const AnyClass = unsafe { *ivar.load(&obj) };
    println!("NSObject isa: {isa:?}");
}

```

--------------------------------

### Option::is_some Example

Source: https://docs.rs/objc2/latest/objc2/ffi/type.IMP.html

Checks if an Option contains a Some value. Returns true if it's Some, false if it's None.

```rust
let x: Option<u32> = Some(2);
assert_eq!(x.is_some(), true);

let x: Option<u32> = None;
assert_eq!(x.is_some(), false);

```

--------------------------------

### AnyClass::instance_methods

Source: https://docs.rs/objc2/latest/objc2/runtime/struct.AnyClass.html

Provides a list of all instance methods implemented by this Objective-C class.

```APIDOC
## AnyClass::instance_methods

### Description
Describes the instance methods implemented by self.

### Method
`pub fn instance_methods(&self) -> impl Deref<Target = [&Method]> + AsRef<[&Method]> + Debug`

### Response
#### Success Response
- `impl Deref<Target = [&Method]> + AsRef<[&Method]> + Debug` - A collection of `Method` references.
```

--------------------------------

### Check if NSObject is a Proxy

Source: https://docs.rs/objc2/latest/objc2/runtime/trait.NSObjectProtocol.html

Determines if an NSObject is a subclass of NSProxy. The example asserts that a newly created NSObject is not a proxy.

```rust
use objc2::runtime::{NSObject, NSObjectProtocol};

let obj = NSObject::new();
assert!(!obj.isProxy());
```

--------------------------------

### Using Autogenerated Framework Crates for NSData

Source: https://docs.rs/objc2/latest/objc2/topics/layered_safety/index.html

Shows how to use `NSData` from the `objc2-foundation` crate, which is autogenerated from Objective-C headers, providing a high-confidence, correct, and safe interface.

```APIDOC
## Framework Crates Example

### Description
This example demonstrates using the `NSData` type from the `objc2-foundation` crate, which provides a safe and autogenerated interface based on Objective-C headers.

### Method
Direct method calls on the `NSData` type provided by `objc2-foundation`.

### Endpoint
N/A (Illustrative code)

### Parameters
N/A

### Request Example
```rust
use objc2_foundation::NSData;

let obj = NSData::new();
let length = obj.length();
```

### Response
N/A
```

--------------------------------

### Get Description of NSObject

Source: https://docs.rs/objc2/latest/objc2/runtime/trait.NSObjectProtocol.html

Safely casts the description of an NSObject to an NSString and prints it. Assumes descriptions are always NSString.

```rust
use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSObjectProtocol, NSString};

// SAFETY: Descriptions are always `NSString`.
let desc: Retained<NSString> = unsafe { Retained::cast_unchecked(obj.description()) };
println!("{desc:?}");
```

--------------------------------

### Migrating Dependencies from icrate to objc2 Crates

Source: https://docs.rs/objc2/latest/objc2/topics/about_generated/changelog/index.html

Illustrates the change in dependency management from a monolithic `icrate` crate to smaller, feature-flagged `objc2-*` crates. This change aims to reduce compilation times by allowing more precise dependency specification.

```toml
# Before
[dependencies.icrate]
version = "0.1.0"
features = [
  "Foundation",
  "Foundation_NSNotification",
  "Foundation_NSString",
  "Foundation_NSThread",
  "Foundation_NSArray",
  "Foundation_NSMutableArray",
  "AppKit",
  "AppKit_NSApplication",
]

# After
# Moved to `objc2-foundation` and `objc2-app-kit` crates.
[dependencies]
# Removed `Foundation_NSMutableArray`, it is included via `NSArray`.
# Added `NSObject` as the `NSCopying` protocol comes from there.
objc2-foundation = { version = "0.2", features = ["NSNotification", "NSString", "NSThread", "NSObject", "NSArray"] }
# Added `NSResponder` as it's required by `NSApplication`.
# Added `NSRunningApplication` as a lot of application constants come from here.
objc2-app-kit = { version = "0.2", features = ["NSResponder", "NSApplication", "NSRunningApplication"] }
```

--------------------------------

### Get Superclass

Source: https://docs.rs/objc2/latest/objc2/runtime/type.Class.html

Returns the superclass of the current class. Returns `None` if the class is a root class (e.g., `NSObject`).

```rust
pub fn superclass(&self) -> Option<&AnyClass>

```
Tokens:
Raw