Crate objc2_foundation

Expand description

§Bindings to the `Foundation` framework

This is the std equivalent for Objective-C, containing essential data types, collections, and operating-system services.

A quick overview of some types you will encounter often in Objective-C, and their approximate Rust equivalent.

Objective-C	(approximately) equivalent Rust
`NSData*`	`Rc<[u8]>`
`NSMutableData*`	`Rc<Cell<Vec<u8>>>`
`NSString*`	`Rc<str>`
`NSMutableString*`	`Rc<Cell<String>>`
`NSValue*`	`Rc<dyn Any>`
`NSNumber*`	`Arc<enum { I8(i8), U8(u8), I16(i16), ... }>`
`NSError*`	`Arc<dyn Error + Send + Sync>`
`NSException*`	`Arc<dyn Error + Send + Sync>`
`NSRange`	`ops::Range<usize>`
`NSComparisonResult`	`cmp::Ordering`
`NSEnumerator<T>*`	`Rc<dyn Iterator<Item = Retained<T>>>`
`NSCopying*`	`Rc<dyn Clone>`
`NSArray<T>*`	`Rc<[Retained<T>]>`
`NSMutableArray<T>*`	`Rc<Cell<Vec<Retained<T>>>>`
`NSDictionary<K, V>*`	`Rc<HashMap<Retained<K>, Retained<V>>>`
`NSMutableDictionary<K, V>*`	`Rc<Cell<HashMap<Retained<K>, Retained<V>>>>`

Note, in particular, that all “Mutable” variants use interior mutability, and that some things are thread-safe (Arc), while others are not (Rc).

Basic usage of a few Foundation types.

$ cargo add objc2-foundation

use objc2_foundation::{ns_string, NSCopying, NSArray};

let string = ns_string!("world");
println!("hello {string}");

let array = NSArray::from_slice(&[string]);
println!("{array:?}");

use objc2_foundation::{ns_string, NSArray, NSDictionary, NSObject};

fn main() {
    // Create and compare NSObjects
    let obj = NSObject::new();
    #[allow(clippy::eq_op)]
    {
        println!("{obj:?} == {obj:?}? {:?}", obj == obj);
    }

    let obj2 = NSObject::new();
    println!("{obj:?} == {obj2:?}? {:?}", obj == obj2);

    // Create an NSArray from a Vec
    let objs = vec![obj, obj2];
    let array = NSArray::from_retained_slice(&objs);
    for obj in array.iter() {
        println!("{obj:?}");
    }
    println!("{}", array.len());

    // Turn the NSArray back into a Vec
    let mut objs = array.to_vec();
    let obj = objs.pop().unwrap();

    // Create a static NSString
    let string = ns_string!("Hello, world!");
    // And use the `ToString` implementation to convert it into a string
    let _s = string.to_string();
    // Or use the `Display` implementation directly
    println!("{string}");

    // Create a dictionary mapping strings to objects
    let keys = &[string];
    let objects = &[&*obj];
    let dict = NSDictionary::from_slices(keys, objects);
    println!("{:?}", dict.objectForKey(string));
    println!("{}", dict.len());
}

An example showing how to define your own interfaces to parts that may be missing in the autogenerated interface.

//! Speak synthethized text.
//!
//! This uses `NSSpeechSynthesizer` on macOS, and `AVSpeechSynthesizer` on
//! other Apple platforms. Note that `AVSpeechSynthesizer` _is_ available on
//! macOS, but only since 10.15!
//!
//! Works on macOS >= 10.7 and iOS > 7.0.
#![deny(unsafe_op_in_unsafe_fn)]
#![allow(unused_imports)]

use std::thread;
use std::time::Duration;

use objc2::rc::Retained;
use objc2::{extern_class, msg_send, ClassType};
use objc2_foundation::{ns_string, NSObject, NSString};

#[cfg(target_os = "macos")]
mod implementation {
    use objc2_foundation::NSCopying;
    use std::cell::Cell;

    use super::*;

    #[link(name = "AppKit", kind = "framework")]
    extern "C" {}

    extern_class!(
        /// <https://developer.apple.com/documentation/appkit/nsspeechsynthesizer?language=objc>
        #[unsafe(super(NSObject))]
        #[name = "NSSpeechSynthesizer"]
        pub(crate) struct Synthesizer;
    );

    impl Synthesizer {
        // Uses default voice
        pub(crate) fn new() -> Retained<Self> {
            unsafe { msg_send![Self::class(), new] }
        }

        fn set_rate(&self, rate: f32) {
            unsafe { msg_send![self, setRate: rate] }
        }

        fn set_volume(&self, volume: f32) {
            unsafe { msg_send![self, setVolume: volume] }
        }

        fn start_speaking(&self, s: &NSString) {
            let _: bool = unsafe { msg_send![self, startSpeakingString: s] };
        }

        pub(crate) fn speak(&self, utterance: &Utterance) {
            // Convert to the range 90-720 that `NSSpeechSynthesizer` seems to
            // support
            //
            // Note that you'd probably want a nonlinear conversion here to
            // make it match `AVSpeechSynthesizer`.
            self.set_rate(90.0 + (utterance.rate.get() * (360.0 - 90.0)));
            self.set_volume(utterance.volume.get());
            self.start_speaking(&utterance.string);
        }

        pub(crate) fn is_speaking(&self) -> bool {
            unsafe { msg_send![self, isSpeaking] }
        }
    }

    // Shim to make NSSpeechSynthesizer work similar to AVSpeechSynthesizer
    pub(crate) struct Utterance {
        rate: Cell<f32>,
        volume: Cell<f32>,
        string: Retained<NSString>,
    }

    impl Utterance {
        pub(crate) fn new(string: &NSString) -> Self {
            Self {
                rate: Cell::new(0.5),
                volume: Cell::new(1.0),
                string: string.copy(),
            }
        }

        pub(crate) fn set_rate(&self, rate: f32) {
            self.rate.set(rate);
        }

        pub(crate) fn set_volume(&self, volume: f32) {
            self.volume.set(volume);
        }
    }
}

#[cfg(all(target_vendor = "apple", not(target_os = "macos")))]
mod implementation {
    use super::*;
    use objc2::AllocAnyThread;

    #[link(name = "AVFoundation", kind = "framework")]
    extern "C" {}

    extern_class!(
        /// <https://developer.apple.com/documentation/avfaudio/avspeechsynthesizer?language=objc>
        #[unsafe(super(NSObject))]
        #[name = "AVSpeechSynthesizer"]
        #[derive(Debug)]
        pub(crate) struct Synthesizer;
    );

    impl Synthesizer {
        pub(crate) fn new() -> Retained<Self> {
            unsafe { msg_send![Self::class(), new] }
        }

        pub(crate) fn speak(&self, utterance: &Utterance) {
            unsafe { msg_send![self, speakUtterance: utterance] }
        }

        pub(crate) fn is_speaking(&self) -> bool {
            unsafe { msg_send![self, isSpeaking] }
        }
    }

    extern_class!(
        /// <https://developer.apple.com/documentation/avfaudio/avspeechutterance?language=objc>
        #[unsafe(super(NSObject))]
        #[name = "AVSpeechUtterance"]
        #[derive(Debug)]
        pub struct Utterance;
    );

    impl Utterance {
        pub(crate) fn new(string: &NSString) -> Retained<Self> {
            unsafe { msg_send![Self::alloc(), initWithString: string] }
        }

        pub(crate) fn set_rate(&self, rate: f32) {
            unsafe { msg_send![self, setRate: rate] }
        }

        pub(crate) fn set_volume(&self, volume: f32) {
            unsafe { msg_send![self, setVolume: volume] }
        }
    }
}

#[cfg(target_vendor = "apple")]
use implementation::{Synthesizer, Utterance};

#[cfg(target_vendor = "apple")]
fn main() {
    let synthesizer = Synthesizer::new();
    let utterance = Utterance::new(ns_string!("Hello from Rust!"));
    utterance.set_rate(0.5);
    utterance.set_volume(0.5);
    synthesizer.speak(&utterance);

    // Wait until speech has properly started up
    thread::sleep(Duration::from_millis(1000));
    // Wait until finished speaking
    while synthesizer.is_speaking() {
        thread::sleep(Duration::from_millis(100));
    }
}

#[cfg(not(target_vendor = "apple"))]
fn main() {
    panic!("this example is only supported on Apple platforms");
}

Modules§

arrayNSArray: Utilities for the NSArray and NSMutableArray classes.
dictionaryNSDictionary: Utilities for the NSDictionary and NSMutableDictionary classes.
enumeratorNSEnumerator: Utilities for the NSEnumerator class.
setNSSet: Utilities for the NSSet and NSMutableSet classes.

Macros§

ns_stringNSString: Create a NSString from a static str.

Structs§

Enums§

NSComparisonResultNSObjCRuntime: Constants that indicate sort order.

Constants§

Statics§

Traits§

CopyingHelperNSObject: A helper type for implementing NSCopying.
MutableCopyingHelperNSObject: A helper type for implementing NSMutableCopying.
NSCacheDelegateNSCache: Apple’s documentation
NSCodingNSObject: Apple’s documentation
NSConnectionDelegateDeprecatedNSConnection: Apple’s documentation
NSCopyingNSObject: A protocol to provide functional copies of objects.
NSDecimalNumberBehaviorsNSDecimalNumber: Apple’s documentation
NSDiscardableContentNSObject: ********* Discardable Content **********
NSExtensionRequestHandlingNSExtensionRequestHandling: Apple’s documentation
NSFastEnumerationNSEnumerator: Apple’s documentation
NSFileManagerDelegateNSFileManager: Apple’s documentation
NSFilePresenterNSFilePresenter: Apple’s documentation
NSItemProviderReadingNSItemProvider: Apple’s documentation
NSItemProviderWritingNSItemProvider: Apple’s documentation
NSKeyedArchiverDelegateNSKeyedArchiver: Apple’s documentation
NSKeyedUnarchiverDelegateNSKeyedArchiver: Apple’s documentation
NSLockingNSLock: Apple’s documentation
NSMachPortDelegateNSPort: Apple’s documentation
NSMetadataQueryDelegateNSMetadata: Apple’s documentation
NSMutableCopyingNSObject: A protocol to provide mutable copies of objects.
NSNetServiceBrowserDelegateNSNetServices: Apple’s documentation
NSNetServiceDelegateNSNetServices: Apple’s documentation
NSObjectNSArchiverCallbackNSArchiver: Category “NSArchiverCallback” on NSObject. ********** Object call back ***************
NSObjectNSClassDescriptionPrimitivesNSClassDescription: Category “NSClassDescriptionPrimitives” on NSObject.
NSObjectNSCoderMethodsNSObject: Category “NSCoderMethods” on NSObject. ********* Base class **********
NSObjectNSComparisonMethodsNSScriptWhoseTests: Category “NSComparisonMethods” on NSObject.
NSObjectNSDelayedPerformingNSRunLoop: Category “NSDelayedPerforming” on NSObject. ************** Delayed perform *****************
NSObjectNSDiscardableContentProxyNSObject: Category “NSDiscardableContentProxy” on NSObject.
NSObjectNSErrorRecoveryAttemptingNSError: Category “NSErrorRecoveryAttempting” on NSObject.
NSObjectNSKeyValueCodingNSKeyValueCoding: Category “NSKeyValueCoding” on NSObject.
NSObjectNSKeyValueObserverNotificationNSKeyValueObserving: Category “NSKeyValueObserverNotification” on NSObject.
NSObjectNSKeyValueObserverRegistrationNSKeyValueObserving: Category “NSKeyValueObserverRegistration” on NSObject.
NSObjectNSKeyValueObservingNSKeyValueObserving: Category “NSKeyValueObserving” on NSObject.
NSObjectNSKeyValueObservingCustomizationNSKeyValueObserving: Category “NSKeyValueObservingCustomization” on NSObject.
NSObjectNSKeyValueSharedObserverRegistrationNSKeyValueSharedObservers: Category “NSKeyValueSharedObserverRegistration” on NSObject.
NSObjectNSKeyedArchiverObjectSubstitutionNSKeyedArchiver: Category “NSKeyedArchiverObjectSubstitution” on NSObject.
NSObjectNSKeyedUnarchiverObjectSubstitutionNSKeyedArchiver: Category “NSKeyedUnarchiverObjectSubstitution” on NSObject.
NSObjectNSScriptClassDescriptionNSScriptClassDescription: Category “NSScriptClassDescription” on NSObject.
NSObjectNSScriptKeyValueCodingNSScriptKeyValueCoding: Category “NSScriptKeyValueCoding” on NSObject.
NSObjectNSScriptObjectSpecifiersNSScriptObjectSpecifiers: Category “NSScriptObjectSpecifiers” on NSObject.
NSObjectNSScriptingNSObjectScripting: Category “NSScripting” on NSObject.
NSObjectNSScriptingComparisonMethodsNSScriptWhoseTests: Category “NSScriptingComparisonMethods” on NSObject.
NSObjectNSThreadPerformAdditionsNSThread: Category “NSThreadPerformAdditions” on NSObject.
NSObjectProtocol: The methods that are fundamental to most Objective-C objects.
NSPortDelegateNSPort: Apple’s documentation
NSProgressReportingNSProgress: Apple’s documentation
NSSecureCodingNSObject: Apple’s documentation
NSSpellServerDelegateNSSpellServer: Apple’s documentation
NSStreamDelegateNSStream: Apple’s documentation
NSURLAuthenticationChallengeSenderNSURLAuthenticationChallenge: This protocol represents the sender of an authentication challenge. It has methods to provide a credential, to continue without any credential, getting whatever failure result would happen in that case, cancel a challenge, perform the default action as defined by the system, or reject the currently supplied protection-space in the challenge.
NSURLConnectionDataDelegateNSURLConnection: Delegate methods used for loading data to memory. These delegate methods are all optional.
NSURLConnectionDelegateNSURLConnection: Delegate methods that are common to all forms of NSURLConnection. These are all optional. This protocol should be considered a base class for the NSURLConnectionDataDelegate and NSURLConnectionDownloadDelegate protocols.
NSURLConnectionDownloadDelegateNSURLConnection: Delegate methods used to perform resource downloads directly to a disk file. All the methods are optional with the exception of connectionDidFinishDownloading:destinationURL: which must be implemented in order to inform the delegate of the location of the finished download. This delegate and download implementation is currently only available on iOS 5.0 or later.
NSURLDownloadDelegateNSURLDownload: The NSURLDownloadDelegate delegate is used to report the progress of the download.
NSURLHandleClientDeprecatedNSURLHandle: Apple’s documentation
NSURLProtocolClientNSURLProtocol: NSURLProtocolClient provides the interface to the URL loading system that is intended for use by NSURLProtocol implementors.
NSURLSessionDataDelegateNSURLSession: Apple’s documentation
NSURLSessionDelegateNSURLSession: Apple’s documentation
NSURLSessionDownloadDelegateNSURLSession: Apple’s documentation
NSURLSessionStreamDelegateNSURLSession: Apple’s documentation
NSURLSessionTaskDelegateNSURLSession: Apple’s documentation
NSURLSessionWebSocketDelegateNSURLSession: Apple’s documentation
NSUserActivityDelegateNSUserActivity: Apple’s documentation
NSUserNotificationCenterDelegateNSUserNotification: Apple’s documentation
NSXMLParserDelegateNSXMLParser: Apple’s documentation
NSXPCListenerDelegateNSXPCConnection: Apple’s documentation
NSXPCProxyCreatingNSXPCConnection: Apple’s documentation

Functions§

NSAllHashTableObjects^⚠NSArray and NSHashTable
NSAllMapTableKeys^⚠NSArray and NSMapTable
NSAllMapTableValues^⚠NSArray and NSMapTable
NSAllocateCollectable^⚠NSZone
NSAllocateMemoryPages^⚠NSZone
NSAllocateObject^⚠NSObject and NSZone: ********* Object Allocation / Deallocation ******
NSClassFromString^⚠NSObjCRuntime and NSString
NSCompareHashTables^⚠NSHashTable
NSCompareMapTables^⚠NSMapTable
NSContainsRect^⚠NSGeometry and objc2-core-foundation
NSCopyHashTableWithZone^⚠NSHashTable and NSZone
NSCopyMapTableWithZone^⚠NSMapTable and NSZone
NSCopyMemoryPages^⚠NSZone
NSCopyObject^⚠DeprecatedNSObject and NSZone
NSCountFrames^⚠NSDebug
NSCountHashTable^⚠NSHashTable
NSCountMapTable^⚠NSMapTable
NSCreateHashTable^⚠NSHashTable and NSString
NSCreateHashTableWithZone^⚠NSHashTable and NSString and NSZone
NSCreateMapTable^⚠NSMapTable and NSString
NSCreateMapTableWithZone^⚠NSMapTable and NSString and NSZone
NSCreateZone^⚠NSZone
NSDeallocateMemoryPages^⚠NSZone
NSDeallocateObject^⚠NSObject
NSDecimalAdd^⚠NSDecimal
NSDecimalCompact^⚠NSDecimal
NSDecimalCompare^⚠NSDecimal and NSObjCRuntime
NSDecimalCopy^⚠NSDecimal: ************* Operations **********
NSDecimalDivide^⚠NSDecimal
NSDecimalMultiply^⚠NSDecimal
NSDecimalMultiplyByPowerOf10^⚠NSDecimal
NSDecimalNormalize^⚠NSDecimal
NSDecimalPower^⚠NSDecimal
NSDecimalRound^⚠NSDecimal
NSDecimalString^⚠NSDecimal and NSString
NSDecimalSubtract^⚠NSDecimal
NSDecrementExtraRefCountWasZero^⚠NSObject
NSDefaultMallocZone^⚠NSZone
NSDivideRect^⚠NSGeometry and objc2-core-foundation
NSEdgeInsetsEqual^⚠NSGeometry and objc2-core-foundation
NSEndHashTableEnumeration^⚠NSHashTable
NSEndMapTableEnumeration^⚠NSMapTable
NSEnumerateHashTable^⚠NSHashTable
NSEnumerateMapTable^⚠NSMapTable
NSEqualPoints^⚠NSGeometry and objc2-core-foundation
NSEqualRects^⚠NSGeometry and objc2-core-foundation
NSEqualSizes^⚠NSGeometry and objc2-core-foundation
NSExtraRefCount^⚠NSObject
NSFileTypeForHFSTypeCode^⚠NSHFSFileTypes and NSString
NSFrameAddress^⚠NSDebug: ************** Stack processing ***************
NSFreeHashTable^⚠NSHashTable
NSFreeMapTable^⚠NSMapTable
NSFullUserName^⚠NSPathUtilities and NSString
NSGetSizeAndAlignment^⚠NSObjCRuntime
NSGetUncaughtExceptionHandler^⚠NSException
NSHFSTypeCodeFromFileType^⚠NSHFSFileTypes and NSString
NSHFSTypeOfFile^⚠NSHFSFileTypes and NSString
NSHashGet^⚠NSHashTable
NSHashInsert^⚠NSHashTable
NSHashInsertIfAbsent^⚠NSHashTable
NSHashInsertKnownAbsent^⚠NSHashTable
NSHashRemove^⚠NSHashTable
NSHomeDirectory^⚠NSPathUtilities and NSString
NSHomeDirectoryForUser^⚠NSPathUtilities and NSString
NSIncrementExtraRefCount^⚠NSObject
NSInsetRect^⚠NSGeometry and objc2-core-foundation
NSIntegralRect^⚠NSGeometry and objc2-core-foundation
NSIntegralRectWithOptions^⚠NSGeometry and objc2-core-foundation
NSIntersectionRange^⚠NSRange
NSIntersectionRect^⚠NSGeometry and objc2-core-foundation
NSIntersectsRect^⚠NSGeometry and objc2-core-foundation
NSIsEmptyRect^⚠NSGeometry and objc2-core-foundation
NSIsFreedObject^⚠NSDebug
NSLogPageSize^⚠NSZone
NSMapGet^⚠NSMapTable
NSMapInsert^⚠NSMapTable
NSMapInsertIfAbsent^⚠NSMapTable
NSMapInsertKnownAbsent^⚠NSMapTable
NSMapMember^⚠NSMapTable
NSMapRemove^⚠NSMapTable
NSMouseInRect^⚠NSGeometry and objc2-core-foundation
NSNextHashEnumeratorItem^⚠NSHashTable
NSNextMapEnumeratorPair^⚠NSMapTable
NSOffsetRect^⚠NSGeometry and objc2-core-foundation
NSOpenStepRootDirectory^⚠NSPathUtilities and NSString
NSPageSize^⚠NSZone
NSPointFromString^⚠NSString and objc2-core-foundation and NSGeometry
NSPointInRect^⚠NSGeometry and objc2-core-foundation
NSProtocolFromString^⚠NSObjCRuntime and NSString
NSRangeFromString^⚠NSRange and NSString
NSRealMemoryAvailable^⚠DeprecatedNSZone
NSReallocateCollectable^⚠NSZone
NSRecordAllocationEvent^⚠NSDebug
NSRectFromString^⚠NSString and objc2-core-foundation and NSGeometry
NSRecycleZone^⚠NSZone
NSResetHashTable^⚠NSHashTable
NSResetMapTable^⚠NSMapTable
NSReturnAddress^⚠NSDebug
NSRoundDownToMultipleOfPageSize^⚠NSZone
NSRoundUpToMultipleOfPageSize^⚠NSZone
NSSearchPathForDirectoriesInDomains^⚠NSArray and NSPathUtilities and NSString
NSSelectorFromString^⚠NSObjCRuntime and NSString
NSSetUncaughtExceptionHandler^⚠NSException
NSSetZoneName^⚠NSZone and NSString
NSShouldRetainWithZone^⚠NSObject and NSZone
NSSizeFromString^⚠NSString and objc2-core-foundation and NSGeometry
NSStringFromClass^⚠NSObjCRuntime and NSString
NSStringFromHashTable^⚠NSHashTable and NSString
NSStringFromMapTable^⚠NSMapTable and NSString
NSStringFromPoint^⚠NSGeometry and NSString and objc2-core-foundation
NSStringFromProtocol^⚠NSObjCRuntime and NSString
NSStringFromRange^⚠NSRange and NSString
NSStringFromRect^⚠NSGeometry and NSString and objc2-core-foundation
NSStringFromSelector^⚠NSObjCRuntime and NSString
NSStringFromSize^⚠NSGeometry and NSString and objc2-core-foundation
NSTemporaryDirectory^⚠NSPathUtilities and NSString
NSUnionRange^⚠NSRange
NSUnionRect^⚠NSGeometry and objc2-core-foundation
NSUserName^⚠NSPathUtilities and NSString
NSZoneCalloc^⚠NSZone
NSZoneFree^⚠NSZone
NSZoneFromPointer^⚠NSZone
NSZoneMalloc^⚠NSZone
NSZoneName^⚠NSString and NSZone
NSZoneRealloc^⚠NSZone
NXReadNSObjectFromCoder^⚠DeprecatedNSCoder
is_main_threadDeprecatedNSThread: Whether the current thread is the main thread.
is_multi_threadedNSThread: Whether the application is multithreaded according to Cocoa.

Type Aliases§

Crate objc2_foundationCopy item path

§Bindings to the Foundation framework

§Rust vs. Objective-C types

§Examples