Struct CFArray 

#[repr(C)]
pub struct CFArray<T: ?Sized = Opaque> { /* private fields */ }

Available on crate feature CFArray only.

This is the type of a reference to immutable CFArrays.

See also Apple’s documentation

Implementations

impl<T: ?Sized> CFArray<T>

Convenience creation methods.

pub fn empty() -> CFRetained<Self>

where T: Type,

Create a new empty CFArray capable of holding CoreFoundation objects.

pub fn from_objects(objects: &[&T]) -> CFRetained<Self>

where T: Type,

Create a new CFArray with the given CoreFoundation objects.

pub fn from_CFTypes(objects: &[&T]) -> CFRetained<Self>

where T: Type,

👎Deprecated: renamed to CFArray::from_objects

Alias for easier transition from the core-foundation crate.

pub fn from_retained_objects(objects: &[CFRetained<T>]) -> CFRetained<Self>

where T: Type,

Create a new CFArray with the given retained CoreFoundation objects.

impl<T: ?Sized> CFArray<T>

Direct, unsafe object accessors.

CFArray stores its values directly, and you can get references to said values data without having to retain it first - but only if the array isn’t mutated while doing so - otherwise, we might end up accessing a deallocated object.

pub unsafe fn get_unchecked(&self, index: CFIndex) -> &T

where T: Type + Sized,

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

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

Safety

• The index must not be negative, and must be in bounds of the array.
• The array must not be mutated while the returned reference is live.

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

where T: Type,

Available on crate feature alloc only.

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) -> CFArrayIterUnchecked<'_, T>

where T: Type,

Iterate over the array without touching 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.

impl<T: ?Sized> CFArray<T>

Various accessor methods.

pub fn as_opaque(&self) -> &CFArray

Convert to the opaque/untyped variant.

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 get(&self, index: usize) -> Option<CFRetained<T>>

where T: Type + Sized,

Retrieve the object at the given index.

Returns None if the index was out of bounds.

pub fn to_vec(&self) -> Vec<CFRetained<T>>

where T: Type + Sized,

Available on crate feature alloc only.

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

pub fn iter(&self) -> CFArrayIter<'_, T>

Iterate over the array’s elements.

impl CFArray

pub unsafe fn new( allocator: Option<&CFAllocator>, values: *mut *const c_void, num_values: CFIndex, call_backs: *const CFArrayCallBacks, ) -> Option<CFRetained<CFArray>>

Creates a new immutable array with the given values.

Parameter allocator: The CFAllocator which should be used to allocate memory for the array and its storage for values. This parameter may be NULL in which case the current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.

Parameter values: A C array of the pointer-sized values to be in the array. The values in the array are ordered in the same order in which they appear in this C array. This parameter may be NULL if the numValues parameter is 0. This C array is not changed or freed by this function. If this parameter is not a valid pointer to a C array of at least numValues pointers, the behavior is undefined.

Parameter numValues: The number of values to copy from the values C array into the CFArray. This number will be the count of the array. If this parameter is negative, or greater than the number of values actually in the value’s C array, the behavior is undefined.

Parameter callBacks: A pointer to a CFArrayCallBacks structure initialized with the callbacks for the array to use on each value in the array. The retain callback will be used within this function, for example, to retain all of the new values from the values C array. A copy of the contents of the callbacks structure is made, so that a pointer to a structure on the stack can be passed in, or can be reused for multiple array creations. If the version field of this callbacks structure is not one of the defined ones for CFArray, the behavior is undefined. The retain field may be NULL, in which case the CFArray will do nothing to add a retain to the contained values for the array. The release field may be NULL, in which case the CFArray will do nothing to remove the array’s retain (if any) on the values when the array is destroyed. If the copyDescription field is NULL, the array will create a simple description for the value. If the equal field is NULL, the array will use pointer equality to test for equality of values. This callbacks parameter itself may be NULL, which is treated as if a valid structure of version 0 with all fields NULL had been passed in. Otherwise, if any of the fields are not valid pointers to functions of the correct type, or this parameter is not a valid pointer to a CFArrayCallBacks callbacks structure, the behavior is undefined. If any of the values put into the array is not one understood by one of the callback functions the behavior when that callback function is used is undefined.

Returns: A reference to the new immutable CFArray.

pub unsafe fn new_copy( allocator: Option<&CFAllocator>, the_array: Option<&CFArray>, ) -> Option<CFRetained<CFArray>>

Creates a new immutable array with the values from the given array.

Parameter allocator: The CFAllocator which should be used to allocate memory for the array and its storage for values. This parameter may be NULL in which case the current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.

Parameter theArray: The array which is to be copied. The values from the array are copied as pointers into the new array (that is, the values themselves are copied, not that which the values point to, if anything). However, the values are also retained by the new array. The count of the new array will be the same as the given array. The new array uses the same callbacks as the array to be copied. If this parameter is not a valid CFArray, the behavior is undefined.

Returns: A reference to the new immutable CFArray.

impl CFArray

pub fn count(self: &CFArray) -> CFIndex

Returns the number of values currently in the array.

Parameter theArray: The array to be queried. If this parameter is not a valid CFArray, the behavior is undefined.

Returns: The number of values in the array.

pub unsafe fn count_of_value( self: &CFArray, range: CFRange, value: *const c_void, ) -> CFIndex

Counts the number of times the given value occurs in the array.

Parameter theArray: The array to be searched. If this parameter is not a valid CFArray, the behavior is undefined.

Parameter range: The range within the array to search. If the range location or end point (defined by the location plus length minus 1) is outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0).

Parameter value: The value for which to find matches in the array. The equal() callback provided when the array was created is used to compare. If the equal() callback was NULL, pointer equality (in C, ==) is used. If value, or any of the values in the array, are not understood by the equal() callback, the behavior is undefined.

Returns: The number of times the given value occurs in the array, within the specified range.

pub unsafe fn contains_value( self: &CFArray, range: CFRange, value: *const c_void, ) -> bool

Reports whether or not the value is in the array.

Parameter theArray: The array to be searched. If this parameter is not a valid CFArray, the behavior is undefined.

Parameter range: The range within the array to search. If the range location or end point (defined by the location plus length minus 1) is outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0).

Parameter value: The value for which to find matches in the array. The equal() callback provided when the array was created is used to compare. If the equal() callback was NULL, pointer equality (in C, ==) is used. If value, or any of the values in the array, are not understood by the equal() callback, the behavior is undefined.

Returns: true, if the value is in the specified range of the array, otherwise false.

pub unsafe fn value_at_index(self: &CFArray, idx: CFIndex) -> *const c_void

Retrieves the value at the given index.

Parameter theArray: The array to be queried. If this parameter is not a valid CFArray, the behavior is undefined.

Parameter idx: The index of the value to retrieve. If the index is outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined.

Returns: The value with the given index in the array.

pub unsafe fn values(self: &CFArray, range: CFRange, values: *mut *const c_void)

Fills the buffer with values from the array.

Parameter theArray: The array to be queried. If this parameter is not a valid CFArray, the behavior is undefined.

Parameter range: The range of values within the array to retrieve. If the range location or end point (defined by the location plus length minus 1) is outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0), in which case no values are put into the buffer.

Parameter values: A C array of pointer-sized values to be filled with values from the array. The values in the C array are ordered in the same order in which they appear in the array. If this parameter is not a valid pointer to a C array of at least range.length pointers, the behavior is undefined.

pub unsafe fn apply_function( self: &CFArray, range: CFRange, applier: CFArrayApplierFunction, context: *mut c_void, )

Calls a function once for each value in the array.

Parameter theArray: The array to be operated upon. If this parameter is not a valid CFArray, the behavior is undefined.

Parameter range: The range of values within the array to which to apply the function. If the range location or end point (defined by the location plus length minus 1) is outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0).

Parameter applier: The callback function to call once for each value in the given range in the array. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. If there are values in the range which the applier function does not expect or cannot properly apply to, the behavior is undefined.

Parameter context: A pointer-sized user-defined value, which is passed as the second parameter to the applier function, but is otherwise unused by this function. If the context is not what is expected by the applier function, the behavior is undefined.

pub unsafe fn first_index_of_value( self: &CFArray, range: CFRange, value: *const c_void, ) -> CFIndex

Searches the array for the value.

Parameter theArray: The array to be searched. If this parameter is not a valid CFArray, the behavior is undefined.

Parameter range: The range within the array to search. If the range location or end point (defined by the location plus length minus 1) is outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0). The search progresses from the smallest index defined by the range to the largest.

Parameter value: The value for which to find a match in the array. The equal() callback provided when the array was created is used to compare. If the equal() callback was NULL, pointer equality (in C, ==) is used. If value, or any of the values in the array, are not understood by the equal() callback, the behavior is undefined.

Returns: The lowest index of the matching values in the range, or kCFNotFound if no value in the range matched.

pub unsafe fn last_index_of_value( self: &CFArray, range: CFRange, value: *const c_void, ) -> CFIndex

Searches the array for the value.

Parameter theArray: The array to be searched. If this parameter is not a valid CFArray, the behavior is undefined.

Parameter range: The range within the array to search. If the range location or end point (defined by the location plus length minus 1) is outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0). The search progresses from the largest index defined by the range to the smallest.

Parameter value: The value for which to find a match in the array. The equal() callback provided when the array was created is used to compare. If the equal() callback was NULL, pointer equality (in C, ==) is used. If value, or any of the values in the array, are not understood by the equal() callback, the behavior is undefined.

Returns: The highest index of the matching values in the range, or kCFNotFound if no value in the range matched.

pub unsafe fn b_search_values( self: &CFArray, range: CFRange, value: *const c_void, comparator: CFComparatorFunction, context: *mut c_void, ) -> CFIndex

Searches the array for the value using a binary search algorithm.

Parameter theArray: The array to be searched. If this parameter is not a valid CFArray, the behavior is undefined. If the array is not sorted from least to greatest according to the comparator function, the behavior is undefined.

Parameter range: The range within the array to search. If the range location or end point (defined by the location plus length minus 1) is outside the index space of the array (0 to N-1 inclusive, where N is the count of the array), the behavior is undefined. If the range length is negative, the behavior is undefined. The range may be empty (length 0).

Parameter value: The value for which to find a match in the array. If value, or any of the values in the array, are not understood by the comparator callback, the behavior is undefined.

Parameter comparator: The function with the comparator function type signature which is used in the binary search operation to compare values in the array with the given value. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. If there are values in the range which the comparator function does not expect or cannot properly compare, the behavior is undefined.

Parameter context: A pointer-sized user-defined value, which is passed as the third parameter to the comparator function, but is otherwise unused by this function. If the context is not what is expected by the comparator function, the behavior is undefined.

Returns: The return value is either 1) the index of a value that matched, if the target value matches one or more in the range, 2) greater than or equal to the end point of the range, if the value is greater than all the values in the range, or 3) the index of the value greater than the target value, if the value lies between two of (or less than all of) the values in the range.

Methods from Deref<Target = CFType>

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

Attempt to downcast the type to that of type T.

This is the reference-variant. Use CFRetained::downcast if you want to convert a retained type. See also ConcreteType for more details on which types support being converted to.

pub fn retain_count(&self) -> usize

Get the reference count of the object.

This function may be useful for debugging. You normally do not use this function otherwise.

Beware that some things (like CFNumbers, small CFStrings etc.) may not have a normal retain count for optimization purposes, and can return usize::MAX in that case.

Trait Implementations

impl<T: ?Sized> AsRef<AnyObject> for CFArray<T>

fn as_ref(&self) -> &AnyObject

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

impl<T: ?Sized> AsRef<CFArray<T>> for CFArray<T>

fn as_ref(&self) -> &Self

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

impl<T: ?Sized> AsRef<CFArray<T>> for CFMutableArray<T>

fn as_ref(&self) -> &CFArray<T>

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

impl<T: ?Sized + Type> AsRef<CFArray> for CFArray<T>

fn as_ref(&self) -> &CFArray

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

impl<T: ?Sized> AsRef<CFType> for CFArray<T>

fn as_ref(&self) -> &CFType

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

impl<T: ?Sized> Borrow<AnyObject> for CFArray<T>

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl<T: ?Sized> Borrow<CFArray<T>> for CFMutableArray<T>

fn borrow(&self) -> &CFArray<T>

Immutably borrows from an owned value.

impl<T: ?Sized + Type> Borrow<CFArray> for CFArray<T>

fn borrow(&self) -> &CFArray

Immutably borrows from an owned value.

impl<T: ?Sized> Borrow<CFType> for CFArray<T>

fn borrow(&self) -> &CFType

Immutably borrows from an owned value.

impl ConcreteType for CFArray

fn type_id() -> CFTypeID

Returns the type identifier of all CFArray instances.

impl<T: ?Sized> Debug for CFArray<T>

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

Formats the value using the given formatter.

impl<T: ?Sized> Deref for CFArray<T>

type Target = CFType

The resulting type after dereferencing.

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

Dereferences the value.

impl<T: ?Sized> Hash for CFArray<T>

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<'a, T: Type> IntoIterator for &'a CFArray<T>

type Item = CFRetained<T>

The type of the elements being iterated over.

type IntoIter = CFArrayIter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: ?Sized> Message for CFArray<T>

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

where Self: Sized,

Increment the reference count of the receiver.

impl<T: ?Sized> PartialEq for CFArray<T>

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<T: ?Sized> RefEncode for CFArray<T>

const ENCODING_REF: Encoding

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

impl<T: ?Sized> Type for CFArray<T>

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

where Self: Sized,

Increment the reference count of the receiver.

fn as_concrete_TypeRef(&self) -> &Self

👎Deprecated: this is redundant

Helper for easier transition from the core-foundation crate.

unsafe fn wrap_under_get_rule(ptr: *const Self) -> CFRetained<Self>

where Self: Sized,

👎Deprecated: use CFRetained::retain

Helper for easier transition from the core-foundation crate.

fn as_CFTypeRef(&self) -> &CFType

where Self: AsRef<CFType>,

👎Deprecated: this is redundant (CF types deref to CFType)

Helper for easier transition from the core-foundation crate.

unsafe fn wrap_under_create_rule(ptr: *const Self) -> CFRetained<Self>

where Self: Sized,

👎Deprecated: use CFRetained::from_raw

Helper for easier transition from the core-foundation crate.

impl<T: ?Sized> Eq for CFArray<T>