Struct NSCoder

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

Available on crate feature NSCoder only.

Apple’s documentation

Implementations

impl NSCoder

pub unsafe fn encodeValueOfObjCType_at( &self, type: NonNull<c_char>, addr: NonNull<c_void>, )

pub unsafe fn encodeDataObject(&self, data: &NSData)

Available on crate feature NSData only.

pub unsafe fn decodeDataObject(&self) -> Option<Retained<NSData>>

Available on crate feature NSData only.

pub unsafe fn decodeValueOfObjCType_at_size( &self, type: NonNull<c_char>, data: NonNull<c_void>, size: NSUInteger, )

pub unsafe fn versionForClassName(&self, class_name: &NSString) -> NSInteger

Available on crate feature NSString only.

impl NSCoder

Methods declared on superclass NSObject.

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

pub unsafe fn new() -> Retained<Self>

impl NSCoder

NSExtendedCoder.

pub unsafe fn encodeObject(&self, object: Option<&AnyObject>)

pub unsafe fn encodeRootObject(&self, root_object: &AnyObject)

pub unsafe fn encodeBycopyObject(&self, an_object: Option<&AnyObject>)

pub unsafe fn encodeByrefObject(&self, an_object: Option<&AnyObject>)

pub unsafe fn encodeConditionalObject(&self, object: Option<&AnyObject>)

pub unsafe fn encodeArrayOfObjCType_count_at( &self, type: NonNull<c_char>, count: NSUInteger, array: NonNull<c_void>, )

pub unsafe fn encodeBytes_length( &self, byteaddr: *const c_void, length: NSUInteger, )

pub unsafe fn decodeObject(&self) -> Option<Retained<AnyObject>>

pub unsafe fn decodeTopLevelObjectAndReturnError( &self, ) -> Result<Retained<AnyObject>, Retained<NSError>>

Available on crate feature NSError only.

pub unsafe fn decodeArrayOfObjCType_count_at( &self, item_type: NonNull<c_char>, count: NSUInteger, array: NonNull<c_void>, )

pub unsafe fn decodeBytesWithReturnedLength( &self, lengthp: NonNull<NSUInteger>, ) -> *mut c_void

pub unsafe fn encodePropertyList(&self, a_property_list: &AnyObject)

pub unsafe fn decodePropertyList(&self) -> Option<Retained<AnyObject>>

pub unsafe fn setObjectZone(&self, zone: *mut NSZone)

Available on crate feature NSZone only.

pub unsafe fn objectZone(&self) -> *mut NSZone

Available on crate feature NSZone only.

pub unsafe fn systemVersion(&self) -> c_uint

pub unsafe fn allowsKeyedCoding(&self) -> bool

pub unsafe fn encodeObject_forKey( &self, object: Option<&AnyObject>, key: &NSString, )

Available on crate feature NSString only.

pub unsafe fn encodeConditionalObject_forKey( &self, object: Option<&AnyObject>, key: &NSString, )

Available on crate feature NSString only.

pub unsafe fn encodeBool_forKey(&self, value: bool, key: &NSString)

Available on crate feature NSString only.

pub unsafe fn encodeInt_forKey(&self, value: c_int, key: &NSString)

Available on crate feature NSString only.

pub unsafe fn encodeInt32_forKey(&self, value: i32, key: &NSString)

Available on crate feature NSString only.

pub unsafe fn encodeInt64_forKey(&self, value: i64, key: &NSString)

Available on crate feature NSString only.

pub unsafe fn encodeFloat_forKey(&self, value: c_float, key: &NSString)

Available on crate feature NSString only.

pub unsafe fn encodeDouble_forKey(&self, value: c_double, key: &NSString)

Available on crate feature NSString only.

pub unsafe fn encodeBytes_length_forKey( &self, bytes: *const u8, length: NSUInteger, key: &NSString, )

Available on crate feature NSString only.

pub unsafe fn containsValueForKey(&self, key: &NSString) -> bool

Available on crate feature NSString only.

pub unsafe fn decodeObjectForKey( &self, key: &NSString, ) -> Option<Retained<AnyObject>>

Available on crate feature NSString only.

pub unsafe fn decodeTopLevelObjectForKey_error( &self, key: &NSString, ) -> Result<Retained<AnyObject>, Retained<NSError>>

Available on crate features NSError and NSString only.

pub unsafe fn decodeBoolForKey(&self, key: &NSString) -> bool

Available on crate feature NSString only.

pub unsafe fn decodeIntForKey(&self, key: &NSString) -> c_int

Available on crate feature NSString only.

pub unsafe fn decodeInt32ForKey(&self, key: &NSString) -> i32

Available on crate feature NSString only.

pub unsafe fn decodeInt64ForKey(&self, key: &NSString) -> i64

Available on crate feature NSString only.

pub unsafe fn decodeFloatForKey(&self, key: &NSString) -> c_float

Available on crate feature NSString only.

pub unsafe fn decodeDoubleForKey(&self, key: &NSString) -> c_double

Available on crate feature NSString only.

pub unsafe fn decodeBytesForKey_returnedLength( &self, key: &NSString, lengthp: *mut NSUInteger, ) -> *const u8

Available on crate feature NSString only.

pub unsafe fn decodeBytesWithMinimumLength( &self, length: NSUInteger, ) -> *mut c_void

Decode bytes from the decoder. The length of the bytes must be greater than or equal to the length parameter. If the result exists, but is of insufficient length, then the decoder uses failWithError to fail the entire decode operation. The result of that is configurable on a per-NSCoder basis using NSDecodingFailurePolicy.

pub unsafe fn decodeBytesForKey_minimumLength( &self, key: &NSString, length: NSUInteger, ) -> *const u8

Available on crate feature NSString only.

Decode bytes from the decoder for a given key. The length of the bytes must be greater than or equal to the length parameter. If the result exists, but is of insufficient length, then the decoder uses failWithError to fail the entire decode operation. The result of that is configurable on a per-NSCoder basis using NSDecodingFailurePolicy.

pub unsafe fn encodeInteger_forKey(&self, value: NSInteger, key: &NSString)

Available on crate feature NSString only.

pub unsafe fn decodeIntegerForKey(&self, key: &NSString) -> NSInteger

Available on crate feature NSString only.

pub unsafe fn requiresSecureCoding(&self) -> bool

pub unsafe fn decodeObjectOfClass_forKey( &self, a_class: &AnyClass, key: &NSString, ) -> Option<Retained<AnyObject>>

Available on crate feature NSString only.

pub unsafe fn decodeTopLevelObjectOfClass_forKey_error( &self, a_class: &AnyClass, key: &NSString, ) -> Result<Retained<AnyObject>, Retained<NSError>>

Available on crate features NSError and NSString only.

pub unsafe fn decodeArrayOfObjectsOfClass_forKey( &self, cls: &AnyClass, key: &NSString, ) -> Option<Retained<NSArray>>

Available on crate features NSArray and NSString only.

Decodes the NSArrayobject for the given key,which should be an NSArray<cls>,containing the given non-collection class (no nested arrays or arrays of dictionaries, etc) from the coder.

Requires NSSecureCodingotherwise an exception is thrown and sets the decodingFailurePolicyto NSDecodingFailurePolicySetErrorAndReturn. Returns nilif the object for keyis not of the expected types, or cannot be decoded, and sets the erroron the decoder.

pub unsafe fn decodeDictionaryWithKeysOfClass_objectsOfClass_forKey( &self, key_cls: &AnyClass, object_cls: &AnyClass, key: &NSString, ) -> Option<Retained<NSDictionary>>

Available on crate features NSDictionary and NSString only.

Decodes the NSDictionaryobject for the given key,which should be an NSDictionary<keyCls,objectCls>, with keys of type given in keyClsand objects of the given non-collection class objectCls(no nested dictionaries or other dictionaries contained in the dictionary, etc) from the coder.

Requires NSSecureCodingotherwise an exception is thrown and sets the decodingFailurePolicyto NSDecodingFailurePolicySetErrorAndReturn. Returns nilif the object for keyis not of the expected types, or cannot be decoded, and sets the erroron the decoder.

pub unsafe fn decodeObjectOfClasses_forKey( &self, classes: Option<&NSSet<AnyClass>>, key: &NSString, ) -> Option<Retained<AnyObject>>

Available on crate features NSSet and NSString only.

pub unsafe fn decodeTopLevelObjectOfClasses_forKey_error( &self, classes: Option<&NSSet<AnyClass>>, key: &NSString, ) -> Result<Retained<AnyObject>, Retained<NSError>>

Available on crate features NSError and NSSet and NSString only.

pub unsafe fn decodeArrayOfObjectsOfClasses_forKey( &self, classes: &NSSet<AnyClass>, key: &NSString, ) -> Option<Retained<NSArray>>

Available on crate features NSArray and NSSet and NSString only.

Decodes the NSArrayobject for the given key,which should be an NSArray,containing the given non-collection classes (no nested arrays or arrays of dictionaries, etc) from the coder.

Requires NSSecureCodingotherwise an exception is thrown and sets the decodingFailurePolicyto NSDecodingFailurePolicySetErrorAndReturn. Returns nilif the object for keyis not of the expected types, or cannot be decoded, and sets the erroron the decoder.

pub unsafe fn decodeDictionaryWithKeysOfClasses_objectsOfClasses_forKey( &self, key_classes: &NSSet<AnyClass>, object_classes: &NSSet<AnyClass>, key: &NSString, ) -> Option<Retained<NSDictionary>>

Available on crate features NSDictionary and NSSet and NSString only.

Decodes the NSDictionaryobject for the given key,which should be an NSDictionary,with keys of the types given in keyClassesand objects of the given non-collection classes in objectClasses(no nested dictionaries or other dictionaries contained in the dictionary, etc) from the given coder.

Requires NSSecureCodingotherwise an exception is thrown and sets the decodingFailurePolicyto NSDecodingFailurePolicySetErrorAndReturn. Returns nilif the object for keyis not of the expected types, or cannot be decoded, and sets the erroron the decoder.

pub unsafe fn decodePropertyListForKey( &self, key: &NSString, ) -> Option<Retained<AnyObject>>

Available on crate feature NSString only.

pub unsafe fn allowedClasses(&self) -> Option<Retained<NSSet<AnyClass>>>

Available on crate feature NSSet only.

pub unsafe fn failWithError(&self, error: &NSError)

Available on crate feature NSError only.

Signals to this coder that the decode has failed. Parameter non-nil error that describes the reason why the decode failed

Sets an error on this NSCoder once per TopLevel decode; calling it repeatedly will have no effect until the call stack unwinds to one of the TopLevel decode entry-points.

This method is only meaningful to call for decodes.

Typically, you would want to call this method in your -initWithCoder: implementation when you detect situations like:

• lack of secure coding
• corruption of your data
• domain validation failures

After calling -failWithError: within your -initWithCoder: implementation, you should clean up and return nil as early as possible.

Once an error has been signaled to a decoder, it remains set until it has handed off to the first TopLevel decode invocation above it. For example, consider the following call graph: A -decodeTopLevelObjectForKey:error: B -initWithCoder: C -decodeObjectForKey: D -initWithCoder: E -decodeObjectForKey: F -failWithError:

In this case the error provided in stack-frame F will be returned via the outError in stack-frame A. Furthermore the result object from decodeTopLevelObjectForKey:error: will be nil, regardless of the result of stack-frame B.

NSCoder implementations support two mechanisms for the stack-unwinding from F to A:

• forced (NSException based)
• particpatory (error based)

The kind of unwinding you get is determined by the decodingFailurePolicy property of this NSCoder (which defaults to NSDecodingFailurePolicyRaiseException to match historical behavior).

pub unsafe fn decodingFailurePolicy(&self) -> NSDecodingFailurePolicy

Defines the behavior this NSCoder should take on decode failure (i.e. corrupt archive, invalid data, etc.).

The default result of this property is NSDecodingFailurePolicyRaiseException, subclasses can change this to an alternative policy.

pub unsafe fn error(&self) -> Option<Retained<NSError>>

Available on crate feature NSError only.

The current error (if there is one) for the current TopLevel decode.

The meaning of this property changes based on the result of the decodingFailurePolicy property: For NSDecodingFailurePolicyRaiseException, this property will always be nil. For NSDecodingFailurePolicySetErrorAndReturn, this property can be non-nil, and if so, indicates that there was a failure while decoding the archive (specifically its the very first error encountered).

While .error is non-nil, all attempts to decode data from this coder will return a nil/zero-equivalent value.

This error is consumed by a TopLevel decode API (which resets this coder back to a being able to potentially decode data).

impl NSCoder

NSTypedstreamCompatibility.

pub unsafe fn encodeNXObject(&self, object: &AnyObject)

👎Deprecated: Not supported

pub unsafe fn decodeNXObject(&self) -> Option<Retained<AnyObject>>

👎Deprecated: Not supported

impl NSCoder

NSDeprecated.

pub unsafe fn decodeValueOfObjCType_at( &self, type: NonNull<c_char>, data: NonNull<c_void>, )

👎Deprecated

impl NSCoder

NSGeometryCoding.

pub unsafe fn encodePoint(&self, point: NSPoint)

Available on crate features NSGeometry and objc2-core-foundation only.

pub unsafe fn decodePoint(&self) -> NSPoint

Available on crate features NSGeometry and objc2-core-foundation only.

pub unsafe fn encodeSize(&self, size: NSSize)

Available on crate features NSGeometry and objc2-core-foundation only.

pub unsafe fn decodeSize(&self) -> NSSize

Available on crate features NSGeometry and objc2-core-foundation only.

pub unsafe fn encodeRect(&self, rect: NSRect)

Available on crate features NSGeometry and objc2-core-foundation only.

pub unsafe fn decodeRect(&self) -> NSRect

Available on crate features NSGeometry and objc2-core-foundation only.

impl NSCoder

NSGeometryKeyedCoding.

pub unsafe fn encodePoint_forKey(&self, point: NSPoint, key: &NSString)

Available on crate features NSGeometry and NSString and objc2-core-foundation only.

pub unsafe fn encodeSize_forKey(&self, size: NSSize, key: &NSString)

Available on crate features NSGeometry and NSString and objc2-core-foundation only.

pub unsafe fn encodeRect_forKey(&self, rect: NSRect, key: &NSString)

Available on crate features NSGeometry and NSString and objc2-core-foundation only.

pub unsafe fn decodePointForKey(&self, key: &NSString) -> NSPoint

Available on crate features NSGeometry and NSString and objc2-core-foundation only.

pub unsafe fn decodeSizeForKey(&self, key: &NSString) -> NSSize

Available on crate features NSGeometry and NSString and objc2-core-foundation only.

pub unsafe fn decodeRectForKey(&self, key: &NSString) -> NSRect

Available on crate features NSGeometry and NSString and objc2-core-foundation only.

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = 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 get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎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 fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

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 NSCoder

fn as_ref(&self) -> &AnyObject

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

impl AsRef<NSCoder> for NSArchiver

Available on crate feature NSArchiver only.

fn as_ref(&self) -> &NSCoder

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

impl AsRef<NSCoder> for NSCoder

fn as_ref(&self) -> &Self

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

impl AsRef<NSCoder> for NSKeyedArchiver

Available on crate feature NSKeyedArchiver only.

fn as_ref(&self) -> &NSCoder

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

impl AsRef<NSCoder> for NSKeyedUnarchiver

Available on crate feature NSKeyedArchiver only.

fn as_ref(&self) -> &NSCoder

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

impl AsRef<NSCoder> for NSPortCoder

Available on crate feature NSPortCoder only.

fn as_ref(&self) -> &NSCoder

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

impl AsRef<NSCoder> for NSUnarchiver

Available on crate feature NSArchiver only.

fn as_ref(&self) -> &NSCoder

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

impl AsRef<NSCoder> for NSXPCCoder

Available on crate feature NSXPCConnection only.

fn as_ref(&self) -> &NSCoder

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

impl AsRef<NSObject> for NSCoder

fn as_ref(&self) -> &NSObject

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

impl Borrow<AnyObject> for NSCoder

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSCoder> for NSArchiver

Available on crate feature NSArchiver only.

fn borrow(&self) -> &NSCoder

Immutably borrows from an owned value.

impl Borrow<NSCoder> for NSKeyedArchiver

Available on crate feature NSKeyedArchiver only.

fn borrow(&self) -> &NSCoder

Immutably borrows from an owned value.

impl Borrow<NSCoder> for NSKeyedUnarchiver

Available on crate feature NSKeyedArchiver only.

fn borrow(&self) -> &NSCoder

Immutably borrows from an owned value.

impl Borrow<NSCoder> for NSPortCoder

Available on crate feature NSPortCoder only.

fn borrow(&self) -> &NSCoder

Immutably borrows from an owned value.

impl Borrow<NSCoder> for NSUnarchiver

Available on crate feature NSArchiver only.

fn borrow(&self) -> &NSCoder

Immutably borrows from an owned value.

impl Borrow<NSCoder> for NSXPCCoder

Available on crate feature NSXPCConnection only.

fn borrow(&self) -> &NSCoder

Immutably borrows from an owned value.

impl Borrow<NSObject> for NSCoder

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for NSCoder

const NAME: &'static str = "NSCoder"

The name of the Objective-C class that this type represents.

type Super = NSObject

The superclass of this class.

type ThreadKind = <<NSCoder as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl Debug for NSCoder

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

Formats the value using the given formatter.

impl Deref for NSCoder

type Target = NSObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for NSCoder

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for NSCoder

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for NSCoder

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl PartialEq for NSCoder

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for NSCoder

const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF

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

impl DowncastTarget for NSCoder

impl Eq for NSCoder