pub struct MPSNDArray { /* private fields */ }MPSNDArray only.Expand description
A MPSNDArray object is a MTLBuffer based storage container for multi-dimensional data.
Operations on MPSNDArrays will commonly implicitly reshape the multidimensional structure into a 2-dimensional structure by reinterpreting higher dimensions as a single dimensional array of matrix rows. For example a [a, b, c, d] NDArray passed to a matrix multiplication may be implicitly reinterpreted as a [abc, d] matrix and a 2D matrix multiplication performed. In practice, the major row (the dimension in which successive elements appear adjacent to one another in memory) is the 0th dimension (represented as ‘d’ in the above example). It has both a dimension size indicating the number of elements and a storage size which may be slightly bigger to allow for performance improvement arising from better data alignment in memory. In principle, the rowBytes may also be used to create a 0th-dimension slice out of a larger array stored in the underlying MTLBuffer.
MPS will automatically manage the storage size of the major row (“rowBytes”) though you may set it in the descriptor if you have a need to do so. Generally, it should be at least a multiple of 16 bytes. Dimensions after the 0th are a densely packed array of rows of size rowBytes. Thus, the 1st dimension is an array of rows. The 2nd dimension is an array of arrays of rows with identical size, and so forth. When the reduction to 2 dimensions is done, no data is moved. MPS just reinterprets a higher order N-1 dimensions of matrix rows as a single large 1-dimensional array of rows.
It is a common desire to reorder the dimensions of NDArrays or define a subregion thereof. A transpose or slice operation is performed by making a MPSNDArray view of the original. The dimensions to transpose or slice are given by the descriptor for the new view. If both a transpose and slice operation are defined, then the slice is performed first and the result of the slice is transposed. Because many MPS kernels can operate on transposed data at speed, MPS will usually defer doing a physical transpose operation until later, when it becomes clear that one is actually required. For this reason, conversions to formats that do not support deferred transposes and slices such as MPSMatrix MPSVector view or using -exportWithCommandBuffer: toBuffer:offset:rowStrides, may cause substantial new computation to be done and new memory to be allocated. These should be avoided except when necessary. As a general rule, transposes that do not involve the 0th dimension should be able to be handled by nearly everything natively. MPSNDArrayMatrixMultiplication and reductions can handle 0th dimension transposes. Other filters may insert a physical repacking operation. If you wish to force a physical repacking use MPSAliasingStrategyShallNotAlias. To avoid confusion with aliased NDArrays the parent property is provided. MPSNDArrays that alias share a common ancestor.
See also Apple’s documentation
Implementations§
Source§impl MPSNDArray
impl MPSNDArray
Sourcepub unsafe fn defaultAllocator() -> Retained<ProtocolObject<dyn MPSNDArrayAllocator>>
Available on crate feature MPSCore only.
pub unsafe fn defaultAllocator() -> Retained<ProtocolObject<dyn MPSNDArrayAllocator>>
MPSCore only.Get a well known <MPSNDArrayAllocator
that makes standard MTLBuffers
Sourcepub unsafe fn label(&self) -> Option<Retained<NSString>>
Available on crate feature MPSCore only.
pub unsafe fn label(&self) -> Option<Retained<NSString>>
MPSCore only.A used specified string to help identify the array during debugging.
May be externally visible to tools like Instruments
Sourcepub unsafe fn setLabel(&self, label: Option<&NSString>)
Available on crate feature MPSCore only.
pub unsafe fn setLabel(&self, label: Option<&NSString>)
MPSCore only.Sourcepub unsafe fn dataType(&self) -> MPSDataType
Available on crate features MPSCore and MPSCoreTypes only.
pub unsafe fn dataType(&self) -> MPSDataType
MPSCore and MPSCoreTypes only.The type of data stored by each element in the array
Sourcepub unsafe fn dataTypeSize(&self) -> usize
Available on crate feature MPSCore only.
pub unsafe fn dataTypeSize(&self) -> usize
MPSCore only.The size of one element in the MPSNDArray
Sourcepub unsafe fn numberOfDimensions(&self) -> NSUInteger
Available on crate feature MPSCore only.
pub unsafe fn numberOfDimensions(&self) -> NSUInteger
MPSCore only.Number of dimensions in the NDArray
Sourcepub unsafe fn lengthOfDimension(
&self,
dimension_index: NSUInteger,
) -> NSUInteger
Available on crate feature MPSCore only.
pub unsafe fn lengthOfDimension( &self, dimension_index: NSUInteger, ) -> NSUInteger
MPSCore only.The number of elements in the dimension at dimensionIndex
The dimension length is at least as large as the existing slice length. Views of this MPSNDArray may have differing dimension lengths.
Sourcepub unsafe fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>
Available on crate feature MPSCore only.
pub unsafe fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>
MPSCore only.The device on which the MSPNDArray may be used
Sourcepub unsafe fn descriptor(&self) -> Retained<MPSNDArrayDescriptor>
Available on crate feature MPSCore only.
pub unsafe fn descriptor(&self) -> Retained<MPSNDArrayDescriptor>
MPSCore only.Create a MPSNDArrayDescriptor that describes this MPSNDArray
The descriptor will describe the shape of the MPSNDArray after all deferred slicing and transposes have completed. A new descriptor is created each time to allow for further customization of the descriptor by the application.
Returns: A new autoreleased MPSNDArrayDescriptor that matches the shape of the MPSNDArray, suitable for introduction of slice, cast and transpose operations.
pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>
MPSCore only.Sourcepub unsafe fn initWithDevice_descriptor(
this: Allocated<Self>,
device: &ProtocolObject<dyn MTLDevice>,
descriptor: &MPSNDArrayDescriptor,
) -> Retained<Self>
Available on crate feature MPSCore only.
pub unsafe fn initWithDevice_descriptor( this: Allocated<Self>, device: &ProtocolObject<dyn MTLDevice>, descriptor: &MPSNDArrayDescriptor, ) -> Retained<Self>
MPSCore only.Initialize an MPSNDArrayDescriptor object on a device for given dimension sizes in descriptor.
Parameter device: The device on which the data type will be created.
Parameter descriptor: The MPSNDArrayDescriptor used for initializing the the NDArray
Returns: A valid MPSNDArray object or nil, if failure.
Sourcepub unsafe fn initWithDevice_scalar(
this: Allocated<Self>,
device: &ProtocolObject<dyn MTLDevice>,
value: c_double,
) -> Retained<Self>
Available on crate feature MPSCore only.
pub unsafe fn initWithDevice_scalar( this: Allocated<Self>, device: &ProtocolObject<dyn MTLDevice>, value: c_double, ) -> Retained<Self>
MPSCore only.Create a 1-Dimensional length=1 NDArray to hold a scalar
Sourcepub unsafe fn initWithBuffer_offset_descriptor(
this: Allocated<Self>,
buffer: &ProtocolObject<dyn MTLBuffer>,
offset: NSUInteger,
descriptor: &MPSNDArrayDescriptor,
) -> Retained<Self>
Available on crate feature MPSCore only.
pub unsafe fn initWithBuffer_offset_descriptor( this: Allocated<Self>, buffer: &ProtocolObject<dyn MTLBuffer>, offset: NSUInteger, descriptor: &MPSNDArrayDescriptor, ) -> Retained<Self>
MPSCore only.Initialize an MPSNDArray object from a Metal Buffer with a given descriptor and offset in bytes.
Parameter buffer: The buffer used for initializing. The NDArray will alias to this buffer at the given offset.
Parameter offset: Offset in bytes to the buffer.
Parameter descriptor: The MPSNDArrayDescriptor used for initializing the the NDArray.
Returns: A valid MPSNDArray object or nil, if failure.
§Safety
buffermay need to be synchronized.buffermay be unretained, you must ensure it is kept alive while in use.buffercontents should be of the correct type.
Sourcepub unsafe fn userBuffer(
&self,
) -> Option<Retained<ProtocolObject<dyn MTLBuffer>>>
Available on crate feature MPSCore only.
pub unsafe fn userBuffer( &self, ) -> Option<Retained<ProtocolObject<dyn MTLBuffer>>>
MPSCore only.Returns the user buffer in case the NDArray was initialized with an MTLBuffer.
Returns: The user-provided MTLBuffer that was used to initialize this MPSNDArray or nil, in case it was not..
Sourcepub unsafe fn resourceSize(&self) -> NSUInteger
Available on crate feature MPSCore only.
pub unsafe fn resourceSize(&self) -> NSUInteger
MPSCore only.Get the number of bytes used to allocate underyling MTLResources
This is the size of the backing store of underlying MTLResources. It does not include all storage used by the object, for example the storage used to hold the MPSNDArray instantiation and MTLBuffer is not included. It only measures the size of the allocation used to hold the MPSNDArray data in the MTLBuffer. This value is subject to change between different devices and operating systems.
Except when -initWithBuffer:descriptor: is used, most MPSNDArrays are allocated initiallly without a backing store. The backing store is allocated lazily when it is needed, typically when the MPSNDArray is written to the first time. Consequently, in most cases, it should be inexpensive to make a MPSImage to see how much memory it will need, and release it if it is too large.
Sourcepub unsafe fn arrayViewWithCommandBuffer_descriptor_aliasing(
&self,
cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>,
descriptor: &MPSNDArrayDescriptor,
aliasing: MPSAliasingStrategy,
) -> Option<Retained<MPSNDArray>>
Available on crate features MPSCore and MPSCoreTypes only.
pub unsafe fn arrayViewWithCommandBuffer_descriptor_aliasing( &self, cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>, descriptor: &MPSNDArrayDescriptor, aliasing: MPSAliasingStrategy, ) -> Option<Retained<MPSNDArray>>
MPSCore and MPSCoreTypes only.Make a new representation of a MPSNDArray with a slice, transpose or other change in property
If possible, the views will merely record the slice or transpose without performing the operation. Many MPSKernels are able to operate on subregions of a MPSNDArray or operate on transposed data, so making a new copy of the data for these operations would be wasteful. A copy may be forced by a change in dataType, rowBytes, or when using a view with a MPSKernel that does not support the deferred operation. To force an operation to occur immediately, use MPSAliasingStrategyShallNotAlias Otherwise, it is likely that the new MPSNDArray will share a MTLBuffer with the parent and alias its memory.
Parameter cmdBuf: The command buffer on which to perform physical copies if any are required
Parameter descriptor: A MPSNDArrayDescriptor describing the shape of the new view of the data
Parameter aliasing: A aliasing strategy to direct MPS how to respond to cases when aliasing can or can not
be performed.
Returns: A new MPSNDArray, if it is possible to make one. Otherwise nil is returned. The MPSNDArray is autoreleased.
Sourcepub unsafe fn arrayViewWithDescriptor(
&self,
descriptor: &MPSNDArrayDescriptor,
) -> Option<Retained<MPSNDArray>>
Available on crate feature MPSCore only.
pub unsafe fn arrayViewWithDescriptor( &self, descriptor: &MPSNDArrayDescriptor, ) -> Option<Retained<MPSNDArray>>
MPSCore only.Make a new representation of a MPSNDArray with a slice, transpose or other change in property, trying to alias to result.
The same as arrayViewWithCommandBuffer, except that tries to always alias, and therefore does not require a commanbuffer.
If aliasing is not possible nil is returned.
This method is useful in making aliasing transposes and slices, that are guaranteed to be able to alias. For reshapes it is recommended
to use the MPSNDArrayIdentity methods.
Parameter descriptor: A MPSNDArrayDescriptor describing the shape of the new view of the data
Returns: A new MPSNDArray, if it is possible to make one. Otherwise nil is returned. The MPSNDArray is autoreleased.
Sourcepub unsafe fn arrayViewWithShape_strides(
&self,
shape: Option<&MPSShape>,
strides: &MPSShape,
) -> Option<Retained<MPSNDArray>>
Available on crate features MPSCore and MPSCoreTypes only.
pub unsafe fn arrayViewWithShape_strides( &self, shape: Option<&MPSShape>, strides: &MPSShape, ) -> Option<Retained<MPSNDArray>>
MPSCore and MPSCoreTypes only.Make a new representation of a MPSNDArray with given strides and a new shape.
This operation always returns a new view of the same underlying MTLBuffer, but works only with contiguous buffers.
Parameter shape: The new shape for the NDArray. Fastest running dimension last. If nil then current shape is used.
Parameter strides: The strides for each dimension. Must be at least length of new shape. Last number must be one. Must be non-increasing.
Returns: A new MPSNDArray, if it is possible to make one. Otherwise nil is returned. The MPSNDArray is autoreleased.
Sourcepub unsafe fn arrayViewWithDimensionCount_dimensionSizes_strides(
&self,
number_of_dimensions: NSUInteger,
dimension_sizes: NonNull<NSUInteger>,
dim_strides: NonNull<NSUInteger>,
) -> Option<Retained<MPSNDArray>>
Available on crate feature MPSCore only.
pub unsafe fn arrayViewWithDimensionCount_dimensionSizes_strides( &self, number_of_dimensions: NSUInteger, dimension_sizes: NonNull<NSUInteger>, dim_strides: NonNull<NSUInteger>, ) -> Option<Retained<MPSNDArray>>
MPSCore only.Make a new representation of a MPSNDArray with given strides and a new shape.
This operation always returns a new view of the same underlying MTLBuffer, but works only with contiguous buffers.
Parameter numberOfDimensions: Number of dimensions in the new view.
Parameter dimensionSizes: Size of each new dimension. Fastest running dimension first. Must be of length numberOfDimensions.
Parameter dimStrides: The strides for each dimension. First number must be one. Must be non-decreasing. Must be of length numberOfDimensions.
Returns: A new MPSNDArray, if it is possible to make one. Otherwise nil is returned. The MPSNDArray is autoreleased.
§Safety
dimension_sizesmust be a valid pointer.dim_stridesmust be a valid pointer.
Sourcepub unsafe fn parent(&self) -> Option<Retained<MPSNDArray>>
Available on crate feature MPSCore only.
pub unsafe fn parent(&self) -> Option<Retained<MPSNDArray>>
MPSCore only.The parent MPSNDArray that this object aliases
If the MPSNDArray was createrd as a array view of another MPSNDArray object, and aliases content in the same MTLBuffer, the original MPSNDArray will be retained as the parent here. Two MPSNDArrays alias if they share a common ancestor. Note that the parent may itself have a parent, and so forth.
Sourcepub unsafe fn exportDataWithCommandBuffer_toBuffer_destinationDataType_offset_rowStrides(
&self,
cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>,
buffer: &ProtocolObject<dyn MTLBuffer>,
destination_data_type: MPSDataType,
offset: NSUInteger,
row_strides: *mut NSInteger,
)
Available on crate features MPSCore and MPSCoreTypes only.
pub unsafe fn exportDataWithCommandBuffer_toBuffer_destinationDataType_offset_rowStrides( &self, cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>, buffer: &ProtocolObject<dyn MTLBuffer>, destination_data_type: MPSDataType, offset: NSUInteger, row_strides: *mut NSInteger, )
MPSCore and MPSCoreTypes only.Do a GPU side copy of the contents of a MPSNDArray to a MTLBuffer
To do a transpose or slice as part of the operation, make a MPSNDArray view first that encodes that operation.
Parameter cmdBuf: The command buffer on which to encode the operation
Parameter buffer: The destination to overwrite
Parameter destinationDataType: The destination data type.
Parameter offset: The byte offset to where the {0,0,0…}th element will be written
Parameter rowStrides: An optional array of (numberOfDimensions-1) byte counts which describe
the byte offset from position 0 of the respective dimension to position 1.
§Safety
buffermay need to be synchronized.buffermay be unretained, you must ensure it is kept alive while in use.buffercontents should be of the correct type.row_stridesmust be a valid pointer or null.
Sourcepub unsafe fn importDataWithCommandBuffer_fromBuffer_sourceDataType_offset_rowStrides(
&self,
cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>,
buffer: &ProtocolObject<dyn MTLBuffer>,
source_data_type: MPSDataType,
offset: NSUInteger,
row_strides: *mut NSInteger,
)
Available on crate features MPSCore and MPSCoreTypes only.
pub unsafe fn importDataWithCommandBuffer_fromBuffer_sourceDataType_offset_rowStrides( &self, cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>, buffer: &ProtocolObject<dyn MTLBuffer>, source_data_type: MPSDataType, offset: NSUInteger, row_strides: *mut NSInteger, )
MPSCore and MPSCoreTypes only.Do a GPU side copy of the contents of a MTLBuffer into a MPSNDArray
Copy data from provided buffer to the NDArray. Implicit transposes and slicing shall be honored.
Parameter cmdBuf: The command buffer on which to encode the operation
Parameter buffer: The destination to read from
Parameter sourceDataType: The source data type.
Parameter offset: The byte offset in the buffer from where the {0,0,0…}th element is to be read.
Parameter rowStrides: An optional array of (numberOfDimensions-1) byte counts which describe
the byte offset from position 0 of the respective dimension to position 1.
§Safety
buffermay need to be synchronized.buffermay be unretained, you must ensure it is kept alive while in use.buffercontents should be of the correct type.row_stridesmust be a valid pointer or null.
Sourcepub unsafe fn exportDataWithCommandBuffer_toImages_offset(
&self,
cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>,
images: &MPSImageBatch,
offset: MPSImageCoordinate,
)
Available on crate features MPSCore and MPSCoreTypes and MPSImage only.
pub unsafe fn exportDataWithCommandBuffer_toImages_offset( &self, cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>, images: &MPSImageBatch, offset: MPSImageCoordinate, )
MPSCore and MPSCoreTypes and MPSImage only.Do a GPU side copy of the contents of a MPSNDArray to a MPSImageBatch.
To do a transpose or slice as part of the operation, make a MPSNDArray view first that encodes that operation. The shape of the array must be [ C, W, H, N, 1, 1, … ], where C is dimension 0 (normally the fastest running index) and is mapped to feature channels in the destination image, W and H are mapped to x and y coordinates in the destination image and N is mapped to the image batch index. You can use arrayViewWithCommandBuffer: to transpose, slice and reshape the source array to layout the data in the desired way for the image(s).
Parameter cmdBuf: The command buffer on which to encode the operation/
Parameter images: The destination images. NOTE: you can use [images subarrayWithRange:…] to get a sub-batch of images.
Parameter offset: The offset to the image where to write - the size of the operation is defined by the source array.
Note: offset.featureChannel must be multiple of four, otherwise results are undefined.
Sourcepub unsafe fn importDataWithCommandBuffer_fromImages_offset(
&self,
cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>,
images: &MPSImageBatch,
offset: MPSImageCoordinate,
)
Available on crate features MPSCore and MPSCoreTypes and MPSImage only.
pub unsafe fn importDataWithCommandBuffer_fromImages_offset( &self, cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>, images: &MPSImageBatch, offset: MPSImageCoordinate, )
MPSCore and MPSCoreTypes and MPSImage only.Do a GPU side copy of the contents of a MPSImageBatch into a MPSNDArray.
This reverses exportDataWithCommandBuffer:toImages: function.
Parameter cmdBuf: The command buffer on which to encode the operation.
Parameter images: The source images. NOTE: you can use [images subarrayWithRange:…] to get a sub-batch of images.
Parameter offset: The offset to the image where to read - the size of the operation is defined by the destination array.
Sourcepub unsafe fn readBytes_strideBytes(
&self,
buffer: NonNull<c_void>,
stride_bytes_per_dimension: *mut NSInteger,
)
Available on crate feature MPSCore only.
pub unsafe fn readBytes_strideBytes( &self, buffer: NonNull<c_void>, stride_bytes_per_dimension: *mut NSInteger, )
MPSCore only.Copy bytes from MPSNDArray into buffer
The dimensionality and size of the copy region is given by the size of the MPSNDArray For subregions, use a MPSNDArray view.
Parameter buffer: A pointer to memory where to write the data
Parameter strideBytesPerDimension: An optional array of numberOfDimensions sizes, which gives the distance
in bytes from one element to the next in that dimension in buffer. The first value
is typically dataTypeSize. The next is a row bytes. The next is 2d matrix bytes,
and so forth. If the value is nil, these are calculated for you assuming that the
data is packed without additional space in between elements, rows, etc.
0 and negative values are permitted.
§Safety
buffermust be a valid pointer.stride_bytes_per_dimensionmust be a valid pointer or null.
Sourcepub unsafe fn writeBytes_strideBytes(
&self,
buffer: NonNull<c_void>,
stride_bytes_per_dimension: *mut NSInteger,
)
Available on crate feature MPSCore only.
pub unsafe fn writeBytes_strideBytes( &self, buffer: NonNull<c_void>, stride_bytes_per_dimension: *mut NSInteger, )
MPSCore only.Copy bytes from a buffer into the MPSNDArray
The dimensionality and size of the copy region is given by the size of the MPSNDArray For subregions, use a MPSNDArray view.
Parameter buffer: A pointer to memory where to read the data
Parameter strideBytesPerDimension: An optional array of numberOfDimensions sizes, which gives the distance
in bytes from one element to the next in that dimension in buffer. The first value
is typically dataTypeSize. The next is a row bytes. The next is 2d matrix bytes,
and so forth. If strideBytesPerDimension is nil, these are calculated for you assuming that the
data is packed without additional space in between elements, rows, etc.
0 and negative values are permitted.
§Safety
buffermust be a valid pointer.stride_bytes_per_dimensionmust be a valid pointer or null.
Sourcepub unsafe fn synchronizeOnCommandBuffer(
&self,
command_buffer: &ProtocolObject<dyn MTLCommandBuffer>,
)
Available on crate feature MPSCore only.
pub unsafe fn synchronizeOnCommandBuffer( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, )
MPSCore only.Use a blit encoder if a discrete device to update CPU contents of underlying buffer with latest GPU value
Parameter commandBuffer: The commandBuffer on which we transfer the contents.
Methods from Deref<Target = NSObject>§
Sourcepub fn doesNotRecognizeSelector(&self, sel: Sel) -> !
pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !
Handle messages the object doesn’t recognize.
See Apple’s documentation for details.
Methods from Deref<Target = AnyObject>§
Sourcepub fn class(&self) -> &'static AnyClass
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());Sourcepub unsafe fn get_ivar<T>(&self, name: &str) -> &Twhere
T: Encode,
👎Deprecated: this is difficult to use correctly, use Ivar::load instead.
pub unsafe fn get_ivar<T>(&self, name: &str) -> &Twhere
T: Encode,
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.
Sourcepub fn downcast_ref<T>(&self) -> Option<&T>where
T: DowncastTarget,
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§
Source§impl AsRef<AnyObject> for MPSNDArray
Available on crate feature MPSCore only.
impl AsRef<AnyObject> for MPSNDArray
MPSCore only.Source§impl AsRef<MPSNDArray> for MPSNDArray
Available on crate feature MPSCore only.
impl AsRef<MPSNDArray> for MPSNDArray
MPSCore only.Source§impl AsRef<MPSNDArray> for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl AsRef<MPSNDArray> for MPSTemporaryNDArray
MPSCore only.Source§fn as_ref(&self) -> &MPSNDArray
fn as_ref(&self) -> &MPSNDArray
Source§impl AsRef<NSObject> for MPSNDArray
Available on crate feature MPSCore only.
impl AsRef<NSObject> for MPSNDArray
MPSCore only.Source§impl Borrow<AnyObject> for MPSNDArray
Available on crate feature MPSCore only.
impl Borrow<AnyObject> for MPSNDArray
MPSCore only.Source§impl Borrow<MPSNDArray> for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl Borrow<MPSNDArray> for MPSTemporaryNDArray
MPSCore only.Source§fn borrow(&self) -> &MPSNDArray
fn borrow(&self) -> &MPSNDArray
Source§impl Borrow<NSObject> for MPSNDArray
Available on crate feature MPSCore only.
impl Borrow<NSObject> for MPSNDArray
MPSCore only.Source§impl ClassType for MPSNDArray
Available on crate feature MPSCore only.
impl ClassType for MPSNDArray
MPSCore only.Source§const NAME: &'static str = "MPSNDArray"
const NAME: &'static str = "MPSNDArray"
Source§type ThreadKind = <<MPSNDArray as ClassType>::Super as ClassType>::ThreadKind
type ThreadKind = <<MPSNDArray as ClassType>::Super as ClassType>::ThreadKind
Source§impl Debug for MPSNDArray
Available on crate feature MPSCore only.
impl Debug for MPSNDArray
MPSCore only.Source§impl Deref for MPSNDArray
Available on crate feature MPSCore only.
impl Deref for MPSNDArray
MPSCore only.Source§impl Hash for MPSNDArray
Available on crate feature MPSCore only.
impl Hash for MPSNDArray
MPSCore only.Source§impl Message for MPSNDArray
Available on crate feature MPSCore only.
impl Message for MPSNDArray
MPSCore only.Source§impl NSObjectProtocol for MPSNDArray
Available on crate feature MPSCore only.
impl NSObjectProtocol for MPSNDArray
MPSCore only.Source§fn isEqual(&self, other: Option<&AnyObject>) -> bool
fn isEqual(&self, other: Option<&AnyObject>) -> bool
Source§fn hash(&self) -> usize
fn hash(&self) -> usize
Source§fn isKindOfClass(&self, cls: &AnyClass) -> bool
fn isKindOfClass(&self, cls: &AnyClass) -> bool
Source§fn is_kind_of<T>(&self) -> bool
fn is_kind_of<T>(&self) -> bool
isKindOfClass directly, or cast your objects with AnyObject::downcast_refSource§fn isMemberOfClass(&self, cls: &AnyClass) -> bool
fn isMemberOfClass(&self, cls: &AnyClass) -> bool
Source§fn respondsToSelector(&self, aSelector: Sel) -> bool
fn respondsToSelector(&self, aSelector: Sel) -> bool
Source§fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool
fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool
Source§fn debugDescription(&self) -> Retained<NSObject>
fn debugDescription(&self) -> Retained<NSObject>
Source§impl PartialEq for MPSNDArray
Available on crate feature MPSCore only.
impl PartialEq for MPSNDArray
MPSCore only.Source§impl RefEncode for MPSNDArray
Available on crate feature MPSCore only.
impl RefEncode for MPSNDArray
MPSCore only.Source§const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF
const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF
impl DowncastTarget for MPSNDArray
MPSCore only.impl Eq for MPSNDArray
MPSCore only.