Struct AnyObject

#[repr(C)]
pub struct AnyObject { /* private fields */ }

An Objective-C object.

This is slightly different from NSObject in that it may represent an instance of an arbitrary Objective-C class (e.g. it does not have to be a subclass of NSObject, so it can represent other root classes like NSProxy).

Retained<AnyObject> is equivalent to Objective-C’s id _Nonnull.

This is an opaque type that contains UnsafeCell, and is similar to that in that one can safely access and perform interior mutability on this (both via msg_send! and through ivars), so long as Rust’s mutability rules are upheld, and that data races are avoided.

Note: This is intentionally neither Sync, Send, UnwindSafe, RefUnwindSafe nor Unpin, since that is something that may change depending on the specific subclass. For example, NSAutoreleasePool is not Send, it has to be deallocated on the same thread that it was created. NSLock is not Send either.

Implementations

impl AnyObject

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn set_class<'s>(this: &Self, cls: &AnyClass) -> &'s AnyClass

Change the class of the object at runtime.

Returns the object’s previous class.

Safety

The new class must:

1. Be a subclass of the object’s current class.

2. The subclass must not add any instance variables - importantly, the instance size of old and the new classes must be the same.

3. Any overridden methods on the new class must be fully compatible with the old ones.

Note that in the general case, where arbitrary parts of the program may be trying to modify the class of the object concurrently, these requirements are not actually possible to uphold.

Since usage of this function is expected to be extremely rare, and even more so trying to do it concurrently, it is recommended that you verify that the returned class is what you would expect, and if not, panic.

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

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

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

👎Deprecated: this is difficult to use correctly, use Ivar::load_mut instead.

Use Ivar::load_mut instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T: DowncastTarget>(&self) -> Option<&T>

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

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

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AnyObject> for AnyClass

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<AnyObject> for AnyProtocol

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<AnyObject> for Exception

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<AnyObject> for NSObject

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl<P: ?Sized + 'static> AsRef<AnyObject> for ProtocolObject<P>

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for NSObject

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Debug for AnyObject

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Message for AnyObject

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl MessageReceiver for &mut AnyObject

&mut AnyObject is allowed as mutable, for easier transition from objc, even though it’s basically always incorrect to hold &mut AnyObject.

Use *mut AnyObject instead if you know for certain you need mutability, and cannot make do with interior mutability.

unsafe fn send_message<A: EncodeArguments, R: EncodeReturn>( self, sel: Sel, args: A, ) -> R

Sends a message to the receiver with the given selector and arguments.

unsafe fn send_super_message<A: EncodeArguments, R: EncodeReturn>( self, superclass: &AnyClass, sel: Sel, args: A, ) -> R

Sends a message to a specific superclass with the given selector and arguments.

impl RefEncode for AnyObject

const ENCODING_REF: Encoding = Encoding::Object

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