Struct SBElementArray 

pub struct SBElementArray<ObjectType: ?Sized = AnyObject> { /* private fields */ }

Available on crate feature SBElementArray only.

SBElementArray is subclass of NSMutableArray that manages collections of related SBObject objects. For example, when you ask the Finder for a list of disks, or ask iTunes for a list of playlists, you get the result back as an SBElementArray containing Scripting Bridge objects representing those items.

SBElementArray defines methods beyond those of <doc ://com.apple.documentation/documentation/foundation/nsarray> for obtaining individual objects. In addition to <doc ://com.apple.documentation/documentation/foundation/nsarray/1417555-objectatindex>, SBElementArray also defines SBElementArray/objectWithName:, SBElementArray/objectWithID:, and SBElementArray/objectAtLocation:.

Subclassing Notes

The SBElementArray class is not designed for subclassing.

See also Apple’s documentation

Implementations

impl<ObjectType: ?Sized + Message> SBElementArray<ObjectType>

pub unsafe fn cast_unchecked<NewObjectType: ?Sized + Message>( &self, ) -> &SBElementArray<NewObjectType>

Unchecked conversion of the generic parameter.

Safety

The generic must be valid to reinterpret as the given type.

impl<ObjectType: Message> SBElementArray<ObjectType>

pub unsafe fn objectWithName(&self, name: &NSString) -> Retained<ObjectType>

Returns the object in the array with the given name.

This method is provided as an alternative to <doc ://com.apple.documentation/documentation/foundation/nsarray/1417555-objectatindex> for applications where a name is available instead of (or in addition to) an index. A name is generally more stable than an index. For example, it is typically more useful to identify a mailbox in Mail by its name than by its index in the list of mailboxes.

• Parameters:

• name: The name of one of the receiver’s objects.

• Returns: A reference to the designated object or nil if the object couldn’t be found.

pub unsafe fn objectWithID( &self, identifier: &AnyObject, ) -> Retained<ObjectType>

Returns the object in the array with the given identifier.

This method is provided as an alternative to <doc ://com.apple.documentation/documentation/foundation/nsarray/1417555-objectatindex> for applications where an identifier is available instead of (or in addition to) an index. A unique ID is generally more stable than an index. For example, it may be more useful to identify a contact in Address Book by its identifier (which doesn’t change over time) than by its index in the list of contacts (which can change as contacts are added or removed).

• Parameters:

• identifier: The identifier of one of the receiver’s objects.

• Returns: A reference to the identified object or nil if could not be found.

Safety

identifier should be of the correct type.

pub unsafe fn objectAtLocation( &self, location: &AnyObject, ) -> Retained<ObjectType>

Returns the object at the given location in the receiver.

This method is a generalization of <doc ://com.apple.documentation/documentation/foundation/nsarray/1417555-objectatindex> for applications where the “index” is not simply an integer. For example, Finder can specify objects using a <doc ://com.apple.documentation/documentation/foundation/nsurl> object as a location. In OSA this is known as “absolute position,” a generalization of the notion of “index” in Foundation—it could be an integer, but it doesn’t have to be. A single object may even have a number of different “absolute position” values depending on the container.

• Parameters:

• loc: An object that specifies the absolute position of the object within the array. It can be an integer index, a list of coordinates, a URL, or other determinant. See the discussion for clarification.

• Returns: A reference to the SBObject object identified by loc or nil if the object couldn’t be located.

Safety

location should be of the correct type.

pub unsafe fn arrayByApplyingSelector( &self, selector: Sel, ) -> Retained<NSArray<AnyObject>>

Returns an array containing the results of sending the specified message to each object in the receiver.

The method identified by selector must not take any arguments and must return an Objective-C object. It should not have the side effect of modifying the receiving array. The order of the items in the result array corresponds to the order of the items in the original array.

• Parameters:

• selector: A selector identifying the message to be sent to each object in the array.

• Returns: A new array containing the results of sending the selector message to each object in the receiver, starting with the first object and continuing through the element array to the last object.

Safety

selector must be a valid selector.

pub unsafe fn arrayByApplyingSelector_withObject( &self, a_selector: Sel, argument: &AnyObject, ) -> Retained<NSArray<AnyObject>>

Returns an array containing the results of sending the specified message to each object in the receiver.

The method identified by selector must take a single argument—whose value is provided in argument—and must return an object. It should not have the side effect of modifying the receiving array. The order of the items in the result array corresponds to the order of the items in the original array.

• Parameters:

• selector: A selector identifying the message to be sent to each object in the array.

• argument: The value for the parameter of the message identified by selector.

• Returns: A new array containing the results of sending the selector message to each object in the receiver, starting with the first object and continuing through the element array to the last object.

Safety

• a_selector must be a valid selector.
• argument should be of the correct type.

pub unsafe fn get(&self) -> Option<Retained<NSArray<ObjectType>>>

Forces evaluation of the receiver, causing the real object to be returned immediately.

This method forces the evaluation of the current object reference (the receiver), resulting in the return of the referenced object. By default, Scripting Bridge deals with references to objects until you actually request some concrete data from them or until you call the get method.

• Returns: The object referenced by the receiver.

impl<ObjectType: Message> SBElementArray<ObjectType>

Methods declared on superclass NSMutableArray.

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

pub unsafe fn initWithCapacity( this: Allocated<Self>, num_items: NSUInteger, ) -> Retained<Self>

pub unsafe fn initWithCoder( this: Allocated<Self>, coder: &NSCoder, ) -> Option<Retained<Self>>

Safety

coder possibly has further requirements.

impl<ObjectType: Message> SBElementArray<ObjectType>

Methods declared on superclass NSArray.

pub unsafe fn initWithObjects_count( this: Allocated<Self>, objects: *mut NonNull<ObjectType>, cnt: NSUInteger, ) -> Retained<Self>

Safety

objects must be a valid pointer or null.

impl<ObjectType: Message> SBElementArray<ObjectType>

Methods declared on superclass NSObject.

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

Methods from Deref<Target = NSMutableArray<ObjectType>>

pub fn insert(&self, index: usize, obj: &ObjectType)

Insert an object into the array at the given index.

Panics

Panics if the index is out of bounds.

pub unsafe fn cast_unchecked<NewObjectType>( &self, ) -> &NSMutableArray<NewObjectType>

where NewObjectType: Message + ?Sized,

Unchecked conversion of the generic parameter.

Safety

The generic must be valid to reinterpret as the given type.

pub fn addObject(&self, an_object: &ObjectType)

pub fn insertObject_atIndex(&self, an_object: &ObjectType, index: usize)

pub fn removeLastObject(&self)

pub fn removeObjectAtIndex(&self, index: usize)

pub fn replaceObjectAtIndex_withObject( &self, index: usize, an_object: &ObjectType, )

pub fn addObjectsFromArray(&self, other_array: &NSArray<ObjectType>)

pub fn exchangeObjectAtIndex_withObjectAtIndex(&self, idx1: usize, idx2: usize)

pub fn removeAllObjects(&self)

pub fn removeObject(&self, an_object: &ObjectType)

pub fn removeObjectIdenticalTo(&self, an_object: &ObjectType)

pub unsafe fn removeObjectsFromIndices_numIndices( &self, indices: NonNull<usize>, cnt: usize, )

👎Deprecated: Not supported

Safety

indices must be a valid pointer.

pub fn removeObjectsInArray(&self, other_array: &NSArray<ObjectType>)

pub fn setArray(&self, other_array: &NSArray<ObjectType>)

pub unsafe fn sortUsingFunction_context( &self, compare: unsafe extern "C-unwind" fn(NonNull<ObjectType>, NonNull<ObjectType>, *mut c_void) -> isize, context: *mut c_void, )

Safety

• compare must be implemented correctly.
• context must be a valid pointer or null.

pub unsafe fn sortUsingSelector(&self, comparator: Sel)

Safety

comparator must be a valid selector.

pub fn setObject_atIndexedSubscript(&self, obj: &ObjectType, idx: usize)

Methods from Deref<Target = NSArray<ObjectType>>

pub unsafe fn objectAtIndex_unchecked(&self, index: usize) -> &ObjectType

Get a direct reference to one of the array’s objects.

Throws an error if the object was not found.

Consider using the objectAtIndex method instead, unless you’re seeing performance issues from the retaining.

Safety

The array must not be mutated while the reference is live.

pub unsafe fn firstObject_unchecked(&self) -> Option<&ObjectType>

A direct reference to the array’s first object, if any.

Consider using the firstObject method instead, unless you’re seeing performance issues from the retaining.

Safety

The array must not be mutated while the reference is live.

pub unsafe fn lastObject_unchecked(&self) -> Option<&ObjectType>

A direct reference to the array’s last object, if any.

Consider using the lastObject method instead, unless you’re seeing performance issues from the retaining.

Safety

The array must not be mutated while the reference is live.

pub unsafe fn to_vec_unchecked(&self) -> Vec<&ObjectType>

A vector containing direct references to the array’s objects.

Consider using the to_vec method instead, unless you’re seeing performance issues from the retaining.

Safety

The array must not be mutated while the returned references are alive.

pub unsafe fn iter_unchecked(&self) -> IterUnchecked<'_, ObjectType>

Iterate over the array without retaining the elements.

Consider using the iter method instead, unless you’re seeing performance issues from the retaining.

Safety

The array must not be mutated for the lifetime of the iterator or for the lifetime of the elements the iterator returns.

pub fn len(&self) -> usize

The amount of elements in the array.

pub fn is_empty(&self) -> bool

Whether the array is empty or not.

pub fn to_vec(&self) -> Vec<Retained<ObjectType>>

Convert the array to a Vec of the array’s objects.

pub fn iter(&self) -> Iter<'_, ObjectType>

Iterate over the array’s elements.

pub unsafe fn cast_unchecked<NewObjectType>(&self) -> &NSArray<NewObjectType>

where NewObjectType: Message + ?Sized,

Unchecked conversion of the generic parameter.

Safety

The generic must be valid to reinterpret as the given type.

pub fn count(&self) -> usize

pub fn objectAtIndex(&self, index: usize) -> Retained<ObjectType>

pub fn arrayByAddingObject( &self, an_object: &ObjectType, ) -> Retained<NSArray<ObjectType>>

pub fn arrayByAddingObjectsFromArray( &self, other_array: &NSArray<ObjectType>, ) -> Retained<NSArray<ObjectType>>

pub fn componentsJoinedByString( &self, separator: &NSString, ) -> Retained<NSString>

pub fn containsObject(&self, an_object: &ObjectType) -> bool

pub fn description(&self) -> Retained<NSString>

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

Safety

locale should be of the correct type.

pub unsafe fn descriptionWithLocale_indent( &self, locale: Option<&AnyObject>, level: usize, ) -> Retained<NSString>

Safety

locale should be of the correct type.

pub fn firstObjectCommonWithArray( &self, other_array: &NSArray<ObjectType>, ) -> Option<Retained<ObjectType>>

pub fn indexOfObject(&self, an_object: &ObjectType) -> usize

pub fn indexOfObjectIdenticalTo(&self, an_object: &ObjectType) -> usize

pub fn isEqualToArray(&self, other_array: &NSArray<ObjectType>) -> bool

pub fn firstObject(&self) -> Option<Retained<ObjectType>>

pub fn lastObject(&self) -> Option<Retained<ObjectType>>

pub unsafe fn objectEnumerator(&self) -> Retained<NSEnumerator<ObjectType>>

Safety

The returned enumerator’s underlying collection should not be mutated while in use.

pub unsafe fn reverseObjectEnumerator( &self, ) -> Retained<NSEnumerator<ObjectType>>

Safety

The returned enumerator’s underlying collection should not be mutated while in use.

pub unsafe fn sortedArrayUsingFunction_context( &self, comparator: unsafe extern "C-unwind" fn(NonNull<ObjectType>, NonNull<ObjectType>, *mut c_void) -> isize, context: *mut c_void, ) -> Retained<NSArray<ObjectType>>

Safety

• comparator must be implemented correctly.
• context must be a valid pointer or null.

pub unsafe fn sortedArrayUsingSelector( &self, comparator: Sel, ) -> Retained<NSArray<ObjectType>>

Safety

comparator must be a valid selector.

pub unsafe fn writeToURL_error( &self, url: &NSURL, ) -> Result<(), Retained<NSError>>

pub unsafe fn makeObjectsPerformSelector(&self, a_selector: Sel)

Safety

a_selector must be a valid selector.

pub unsafe fn makeObjectsPerformSelector_withObject( &self, a_selector: Sel, argument: Option<&AnyObject>, )

Safety

• a_selector must be a valid selector.
• argument should be of the correct type.

pub fn objectAtIndexedSubscript(&self, idx: usize) -> Retained<ObjectType>

pub unsafe fn getObjects(&self, objects: NonNull<NonNull<ObjectType>>)

👎Deprecated: Use -getObjects:range: instead

Safety

objects must be a valid pointer.

pub unsafe fn writeToFile_atomically( &self, path: &NSString, use_auxiliary_file: bool, ) -> bool

👎Deprecated

pub unsafe fn writeToURL_atomically( &self, url: &NSURL, atomically: bool, ) -> bool

👎Deprecated

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<ObjectType: ?Sized + Message> AsRef<AnyObject> for SBElementArray<ObjectType>

fn as_ref(&self) -> &AnyObject

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

impl<ObjectType: ?Sized + Message> AsRef<NSArray<ObjectType>> for SBElementArray<ObjectType>

fn as_ref(&self) -> &NSArray<ObjectType>

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

impl<ObjectType: ?Sized + Message> AsRef<NSMutableArray<ObjectType>> for SBElementArray<ObjectType>

fn as_ref(&self) -> &NSMutableArray<ObjectType>

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

impl<ObjectType: ?Sized + Message> AsRef<NSObject> for SBElementArray<ObjectType>

fn as_ref(&self) -> &NSObject

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

impl<ObjectType: ?Sized + Message> AsRef<SBElementArray<ObjectType>> for SBElementArray<ObjectType>

fn as_ref(&self) -> &Self

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

impl<ObjectType: ?Sized + Message> Borrow<AnyObject> for SBElementArray<ObjectType>

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl<ObjectType: ?Sized + Message> Borrow<NSArray<ObjectType>> for SBElementArray<ObjectType>

fn borrow(&self) -> &NSArray<ObjectType>

Immutably borrows from an owned value.

impl<ObjectType: ?Sized + Message> Borrow<NSMutableArray<ObjectType>> for SBElementArray<ObjectType>

fn borrow(&self) -> &NSMutableArray<ObjectType>

Immutably borrows from an owned value.

impl<ObjectType: ?Sized + Message> Borrow<NSObject> for SBElementArray<ObjectType>

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl<ObjectType: ?Sized + Message> ClassType for SBElementArray<ObjectType>

const NAME: &'static str = "SBElementArray"

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

type Super = NSMutableArray<ObjectType>

The superclass of this class.

type ThreadKind = <<SBElementArray<ObjectType> 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<ObjectType: ?Sized + Message> Deref for SBElementArray<ObjectType>

type Target = NSMutableArray<ObjectType>

The resulting type after dereferencing.

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

Dereferences the value.

impl<ObjectType: ?Sized> Hash for SBElementArray<ObjectType>

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<ObjectType: ?Sized + Message> Message for SBElementArray<ObjectType>

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

where Self: Sized,

Increment the reference count of the receiver.

impl<ObjectType: ?Sized + NSCoding> NSCoding for SBElementArray<ObjectType>

unsafe fn encodeWithCoder(&self, coder: &NSCoder)

where Self: Sized + Message,

Safety

unsafe fn initWithCoder( this: Allocated<Self>, coder: &NSCoder, ) -> Option<Retained<Self>>

where Self: Sized + Message,

Safety

impl<ObjectType: ?Sized> NSFastEnumeration for SBElementArray<ObjectType>

unsafe fn countByEnumeratingWithState_objects_count( &self, state: NonNull<NSFastEnumerationState>, buffer: NonNull<*mut AnyObject>, len: usize, ) -> usize

where Self: Sized + Message,

Safety

impl<ObjectType: ?Sized> NSObjectProtocol for SBElementArray<ObjectType>

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<ObjectType: ?Sized + NSSecureCoding> NSSecureCoding for SBElementArray<ObjectType>

fn supportsSecureCoding() -> bool

where Self: Sized + ClassType,

impl<ObjectType: ?Sized> PartialEq for SBElementArray<ObjectType>

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<ObjectType: ?Sized + Message> RefEncode for SBElementArray<ObjectType>

const ENCODING_REF: Encoding = <NSMutableArray<ObjectType> as ::objc2::RefEncode>::ENCODING_REF

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

impl DowncastTarget for SBElementArray<AnyObject>

impl<ObjectType: ?Sized> Eq for SBElementArray<ObjectType>