Source code
Revision control
Copy as Markdown
Other Tools
//! Utilities for the `NSArray` and `NSMutableArray` classes.
use alloc::vec::Vec;
#[cfg(feature = "NSEnumerator")]
use core::fmt;
use core::mem;
use core::ptr::NonNull;
use objc2::rc::{Retained, RetainedFromIterator};
use objc2::{msg_send, AnyThread, Message};
#[cfg(feature = "NSEnumerator")]
use crate::iter;
use crate::{util, NSArray, NSMutableArray};
/// Convenience creation methods.
impl<ObjectType: Message> NSArray<ObjectType> {
/// Create a new array from a slice of objects.
///
/// This is a safe interface to `initWithObjects:count:`.
///
/// # Examples
///
/// ```
/// use objc2_foundation::{NSArray, ns_string};
///
/// let array = NSArray::from_slice(&[
/// ns_string!("abc"),
/// ns_string!("def"),
/// ns_string!("ghi"),
/// ]);
/// ```
#[doc(alias = "initWithObjects:count:")]
pub fn from_slice(slice: &[&ObjectType]) -> Retained<Self> {
let len = slice.len();
let ptr = util::ref_ptr_cast_const(slice.as_ptr());
// SAFETY:
// - All `ObjectType: Message` use interior mutability, and the array
// extends the lifetime of them internally by retaining them.
// - The pointer and length are valid until the method has finished
// executing, at which point the array will have created its own
// internal storage for holding the pointers.
unsafe { Self::initWithObjects_count(Self::alloc(), ptr, len) }
}
/// Create a new array from a slice of retained objects.
///
/// This is a safe interface to `initWithObjects:count:`.
///
/// # Examples
///
/// ```
/// use objc2_foundation::{NSArray, NSObject};
///
/// let array = NSArray::from_retained_slice(&[
/// NSObject::new(),
/// NSObject::new(),
/// NSObject::new(),
/// ]);
/// ```
#[doc(alias = "initWithObjects:count:")]
pub fn from_retained_slice(slice: &[Retained<ObjectType>]) -> Retained<Self> {
let len = slice.len();
let ptr = util::retained_ptr_cast_const(slice.as_ptr());
// SAFETY: Same as `from_slice`, this is just a faster version to
// avoid creating a new slice if your elements are already retained.
//
// Otherwise equivalent to:
// Self::from_slice(&slice.iter().map(|obj| &*obj).collect())
unsafe { Self::initWithObjects_count(Self::alloc(), ptr, len) }
}
}
/// Convenience creation methods.
impl<ObjectType: Message> NSMutableArray<ObjectType> {
#[doc(alias = "initWithObjects:count:")]
pub fn from_slice(slice: &[&ObjectType]) -> Retained<Self> {
let len = slice.len();
let ptr = util::ref_ptr_cast_const(slice.as_ptr());
// SAFETY: Same as `NSArray::from_slice`.
unsafe { Self::initWithObjects_count(Self::alloc(), ptr, len) }
}
#[doc(alias = "initWithObjects:count:")]
pub fn from_retained_slice(slice: &[Retained<ObjectType>]) -> Retained<Self> {
let len = slice.len();
let ptr = util::retained_ptr_cast_const(slice.as_ptr());
// SAFETY: Same as `NSArray::from_retained_slice`
unsafe { Self::initWithObjects_count(Self::alloc(), ptr, len) }
}
}
/// Direct, unsafe object accessors.
///
/// Foundation's collection types store their items in such a way that they
/// can give out references to their data without having to autorelease it
/// first, see [the docs][collections-own].
///
/// This means that we can more efficiently access the array's objects, but
/// _only_ if the array isn't mutated via e.g. `NSMutableArray` methods while
/// doing so - otherwise, we might end up accessing a deallocated object.
///
/// [collections-own]: https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmPractical.html#//apple_ref/doc/uid/TP40004447-SW12
impl<ObjectType: Message> NSArray<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`](Self::objectAtIndex) method
/// instead, unless you're seeing performance issues from the retaining.
///
/// # Safety
///
/// The array must not be mutated while the reference is live.
#[doc(alias = "objectAtIndex:")]
#[inline]
pub unsafe fn objectAtIndex_unchecked(&self, index: usize) -> &ObjectType {
// SAFETY: Upheld by caller.
unsafe { msg_send![self, objectAtIndex: index] }
}
/// A direct reference to the array's first object, if any.
///
/// Consider using the [`firstObject`](Self::firstObject) method instead,
/// unless you're seeing performance issues from the retaining.
///
/// # Safety
///
/// The array must not be mutated while the reference is live.
#[doc(alias = "firstObject")]
#[inline]
pub unsafe fn firstObject_unchecked(&self) -> Option<&ObjectType> {
// SAFETY: Upheld by caller.
unsafe { msg_send![self, firstObject] }
}
/// A direct reference to the array's last object, if any.
///
/// Consider using the [`lastObject`](Self::lastObject) method instead,
/// unless you're seeing performance issues from the retaining.
///
/// # Safety
///
/// The array must not be mutated while the reference is live.
#[doc(alias = "lastObject")]
#[inline]
pub unsafe fn lastObject_unchecked(&self) -> Option<&ObjectType> {
// SAFETY: Upheld by caller.
unsafe { msg_send![self, lastObject] }
}
/// A vector containing direct references to the array's objects.
///
/// Consider using the [`to_vec`](Self::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.
#[doc(alias = "getObjects:")]
pub unsafe fn to_vec_unchecked(&self) -> Vec<&ObjectType> {
let len = self.count();
let mut vec: Vec<NonNull<ObjectType>> = Vec::with_capacity(len);
let ptr: NonNull<NonNull<ObjectType>> = NonNull::new(vec.as_mut_ptr()).unwrap();
// SAFETY: The buffer is at least the size of the array, as guaranteed
// by `Vec::with_capacity`.
unsafe {
#[allow(deprecated)]
self.getObjects(ptr)
};
// SAFETY: The elements were just initialized by `getObjects:`.
//
// Note: We set the length _after_ we've copied the elements, so that
// if `getObjects:` unwinds, we don't end up deallocating
// uninitialized elements.
unsafe { vec.set_len(len) };
// SAFETY: `NonNull<ObjectType>` has the same layout as `&ObjectType`,
// and the lifetime is bound to the array, and caller upholds that the
// array isn't mutated.
unsafe { mem::transmute::<Vec<NonNull<ObjectType>>, Vec<&ObjectType>>(vec) }
}
/// Iterate over the array without retaining the elements.
///
/// Consider using the [`iter`](Self::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.
#[cfg(feature = "NSEnumerator")]
#[doc(alias = "objectEnumerator")]
#[inline]
pub unsafe fn iter_unchecked(&self) -> IterUnchecked<'_, ObjectType> {
IterUnchecked(iter::IterUnchecked::new(self))
}
}
/// Various accessor methods.
impl<ObjectType: Message> NSArray<ObjectType> {
/// The amount of elements in the array.
#[doc(alias = "count")]
#[inline]
pub fn len(&self) -> usize {
self.count()
}
/// Whether the array is empty or not.
#[inline]
pub fn is_empty(&self) -> bool {
self.len() == 0
}
/// Convert the array to a `Vec` of the array's objects.
#[doc(alias = "getObjects:")]
pub fn to_vec(&self) -> Vec<Retained<ObjectType>> {
// SAFETY: We retain the elements below, so we know that the array
// isn't mutated while the references are alive.
//
// Note that this is _technically_ wrong; the user _could_ have
// implemented a `retain` method that mutates the array. We're going
// to rule this out though, as that's basically never going to happen,
// and will make a lot of other things unsound too.
let vec = unsafe { self.to_vec_unchecked() };
vec.into_iter().map(ObjectType::retain).collect()
}
/// Iterate over the array's elements.
#[cfg(feature = "NSEnumerator")]
#[doc(alias = "objectEnumerator")]
#[inline]
pub fn iter(&self) -> Iter<'_, ObjectType> {
Iter(iter::Iter::new(self))
}
/// Returns the objects within the given range.
///
/// # Panics
///
/// Panics if the range was out of bounds.
#[doc(alias = "getObjects:range:")]
#[cfg(feature = "NSRange")]
pub fn objects_in_range(&self, range: core::ops::Range<usize>) -> Vec<Retained<ObjectType>> {
let count = self.count();
// TODO: Replace this check with catching the thrown NSRangeException
if range.end > count {
panic!(
"range end index {} out of range for array of length {}",
range.end, count
);
}
let range = crate::NSRange::from(range);
let mut vec: Vec<NonNull<ObjectType>> = Vec::with_capacity(range.length);
let ptr: NonNull<NonNull<ObjectType>> = NonNull::new(vec.as_mut_ptr()).unwrap();
// SAFETY: Mostly the same as in `to_vec_unchecked`.
unsafe { self.getObjects_range(ptr, range) };
unsafe { vec.set_len(range.length) };
let vec = unsafe { mem::transmute::<Vec<NonNull<ObjectType>>, Vec<&ObjectType>>(vec) };
vec.into_iter().map(ObjectType::retain).collect()
}
}
/// Convenience mutation methods.
impl<ObjectType: Message> NSMutableArray<ObjectType> {
/// Insert an object into the array at the given index.
///
/// # Panics
///
/// Panics if the index is out of bounds.
#[doc(alias = "insertObject:atIndex:")]
pub fn insert(&self, index: usize, obj: &ObjectType) {
// TODO: Replace this check with catching the thrown NSRangeException
let len = self.len();
if index <= len {
self.insertObject_atIndex(obj, index)
} else {
panic!(
"insertion index (is {}) should be <= len (is {})",
index, len
);
}
}
/// Sort the array by the given comparison closure.
#[cfg(feature = "NSObjCRuntime")]
#[doc(alias = "sortUsingFunction:context:")]
pub fn sort_by<F: FnMut(&ObjectType, &ObjectType) -> core::cmp::Ordering>(&self, compare: F) {
unsafe extern "C-unwind" fn compare_with_closure<
ObjectType,
F: FnMut(&ObjectType, &ObjectType) -> core::cmp::Ordering,
>(
obj1: core::ptr::NonNull<ObjectType>,
obj2: core::ptr::NonNull<ObjectType>,
context: *mut core::ffi::c_void,
) -> isize {
let context: *mut F = context.cast();
// Bring back a reference to the closure.
// Guaranteed to be unique, we gave `sortUsingFunction` unique
// ownership, and that method only runs one function at a time.
let closure: &mut F = unsafe { context.as_mut().unwrap_unchecked() };
// SAFETY: The objects are guaranteed to be valid
let (obj1, obj2) = unsafe { (obj1.as_ref(), obj2.as_ref()) };
crate::NSComparisonResult::from((*closure)(obj1, obj2)) as _
}
// Create function pointer
let f: unsafe extern "C-unwind" fn(_, _, _) -> _ = compare_with_closure::<ObjectType, F>;
// Grab a type-erased pointer to the closure (a pointer to stack).
let mut closure = compare;
let context: *mut F = &mut closure;
unsafe { self.sortUsingFunction_context(f, context.cast()) };
// Keep the closure alive until the function has run.
drop(closure);
}
}
#[cfg(feature = "NSEnumerator")]
unsafe impl<ObjectType: Message> iter::FastEnumerationHelper for NSArray<ObjectType> {
type Item = ObjectType;
#[inline]
fn maybe_len(&self) -> Option<usize> {
Some(self.len())
}
}
#[cfg(feature = "NSEnumerator")]
unsafe impl<ObjectType: Message> iter::FastEnumerationHelper for NSMutableArray<ObjectType> {
type Item = ObjectType;
#[inline]
fn maybe_len(&self) -> Option<usize> {
Some(self.len())
}
}
/// An iterator over the items of an array.
#[derive(Debug)]
#[cfg(feature = "NSEnumerator")]
pub struct Iter<'a, ObjectType: Message>(iter::Iter<'a, NSArray<ObjectType>>);
#[cfg(feature = "NSEnumerator")]
__impl_iter! {
impl<'a, ObjectType: Message> Iterator<Item = Retained<ObjectType>> for Iter<'a, ObjectType> { ... }
}
/// An iterator over unretained items of an array.
///
/// # Safety
///
/// The array must not be mutated while this is alive.
#[derive(Debug)]
#[cfg(feature = "NSEnumerator")]
pub struct IterUnchecked<'a, ObjectType: Message>(iter::IterUnchecked<'a, NSArray<ObjectType>>);
#[cfg(feature = "NSEnumerator")]
__impl_iter! {
impl<'a, ObjectType: Message> Iterator<Item = &'a ObjectType> for IterUnchecked<'a, ObjectType> { ... }
}
/// A retained iterator over the items of an array.
#[derive(Debug)]
#[cfg(feature = "NSEnumerator")]
pub struct IntoIter<ObjectType: Message>(iter::IntoIter<NSArray<ObjectType>>);
#[cfg(feature = "NSEnumerator")]
__impl_iter! {
impl<ObjectType: Message> Iterator<Item = Retained<ObjectType>> for IntoIter<ObjectType> { ... }
}
#[cfg(feature = "NSEnumerator")]
__impl_into_iter! {
impl<ObjectType: Message> IntoIterator for &NSArray<ObjectType> {
type IntoIter = Iter<'_, ObjectType>;
}
impl<ObjectType: Message> IntoIterator for &NSMutableArray<ObjectType> {
type IntoIter = Iter<'_, ObjectType>;
}
impl<ObjectType: Message> IntoIterator for Retained<NSArray<ObjectType>> {
#[uses(new)]
type IntoIter = IntoIter<ObjectType>;
}
impl<ObjectType: Message> IntoIterator for Retained<NSMutableArray<ObjectType>> {
#[uses(new_mutable)]
type IntoIter = IntoIter<ObjectType>;
}
}
#[cfg(feature = "NSEnumerator")]
impl<ObjectType: fmt::Debug + Message> fmt::Debug for NSArray<ObjectType> {
#[inline]
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_list().entries(self).finish()
}
}
#[cfg(feature = "NSEnumerator")]
impl<ObjectType: fmt::Debug + Message> fmt::Debug for NSMutableArray<ObjectType> {
#[inline]
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
fmt::Debug::fmt(&**self, f)
}
}
impl<ObjectType: Message> Extend<Retained<ObjectType>> for &NSMutableArray<ObjectType> {
fn extend<I: IntoIterator<Item = Retained<ObjectType>>>(&mut self, iter: I) {
iter.into_iter().for_each(move |item| self.addObject(&item));
}
}
impl<'a, ObjectType: Message> Extend<&'a ObjectType> for &NSMutableArray<ObjectType> {
fn extend<I: IntoIterator<Item = &'a ObjectType>>(&mut self, iter: I) {
iter.into_iter().for_each(move |item| self.addObject(item));
}
}
impl<'a, ObjectType: Message + 'a> RetainedFromIterator<&'a ObjectType> for NSArray<ObjectType> {
fn retained_from_iter<I: IntoIterator<Item = &'a ObjectType>>(iter: I) -> Retained<Self> {
let vec = Vec::from_iter(iter);
Self::from_slice(&vec)
}
}
impl<ObjectType: Message> RetainedFromIterator<Retained<ObjectType>> for NSArray<ObjectType> {
fn retained_from_iter<I: IntoIterator<Item = Retained<ObjectType>>>(iter: I) -> Retained<Self> {
let vec = Vec::from_iter(iter);
Self::from_retained_slice(&vec)
}
}
impl<'a, ObjectType: Message + 'a> RetainedFromIterator<&'a ObjectType>
for NSMutableArray<ObjectType>
{
fn retained_from_iter<I: IntoIterator<Item = &'a ObjectType>>(iter: I) -> Retained<Self> {
// TODO: Is this, or is using `initWithCapacity` the most optimal?
let vec = Vec::from_iter(iter);
Self::from_slice(&vec)
}
}
impl<ObjectType: Message> RetainedFromIterator<Retained<ObjectType>>
for NSMutableArray<ObjectType>
{
fn retained_from_iter<I: IntoIterator<Item = Retained<ObjectType>>>(iter: I) -> Retained<Self> {
// TODO: Is this, or is using `initWithCapacity` the most optimal?
let vec = Vec::from_iter(iter);
Self::from_retained_slice(&vec)
}
}