objc2_foundation/
lib.rs

1//! # Bindings to the `Foundation` framework
2//!
3//! See [Apple's docs][apple-doc] and [the general docs on framework crates][framework-crates] for more information.
4//!
5//! [apple-doc]: https://developer.apple.com/documentation/foundation/
6//! [framework-crates]: https://docs.rs/objc2/latest/objc2/topics/about_generated/index.html
7//!
8//! This is the [`std`] equivalent for Objective-C, containing essential data
9//! types, collections, and operating-system services.
10//!
11//!
12//! ## Rust vs. Objective-C types
13//!
14//! A quick overview of some types you will encounter often in Objective-C,
15//! and their approximate Rust equivalent.
16//!
17//! | Objective-C                  | (approximately) equivalent Rust               |
18//! | ---------------------------- | --------------------------------------------- |
19//! | `NSData*`                    | `Rc<[u8]>`                                    |
20//! | `NSMutableData*`             | `Rc<Cell<Vec<u8>>>`                           |
21//! | `NSString*`                  | `Rc<str>`                                     |
22//! | `NSMutableString*`           | `Rc<Cell<String>>`                            |
23//! | `NSValue*`                   | `Rc<dyn Any>`                                 |
24//! | `NSNumber*`                  | `Arc<enum { I8(i8), U8(u8), I16(i16), ... }>` |
25//! | `NSError*`                   | `Arc<dyn Error + Send + Sync>`                |
26//! | `NSException*`               | `Arc<dyn Error + Send + Sync>`                |
27//! | `NSRange`                    | `ops::Range<usize>`                           |
28//! | `NSComparisonResult`         | `cmp::Ordering`                               |
29//! | `NSEnumerator<T>*`           | `Rc<dyn Iterator<Item = Retained<T>>>`        |
30//! | `NSCopying*`                 | `Rc<dyn Clone>`                               |
31//! | `NSArray<T>*`                | `Rc<[Retained<T>]>`                           |
32//! | `NSMutableArray<T>*`         | `Rc<Cell<Vec<Retained<T>>>>`                  |
33//! | `NSDictionary<K, V>*`        | `Rc<HashMap<Retained<K>, Retained<V>>>`       |
34//! | `NSMutableDictionary<K, V>*` | `Rc<Cell<HashMap<Retained<K>, Retained<V>>>>` |
35//!
36//! Note, in particular, that all "Mutable" variants use interior mutability,
37//! and that some things are thread-safe (`Arc`), while others are not (`Rc`).
38//!
39//!
40//! ## Examples
41//!
42//! Basic usage of a few Foundation types.
43//!
44//! ```console
45//! $ cargo add objc2-foundation
46//! ```
47//!
48//! ```ignore
49//! use objc2_foundation::{ns_string, NSCopying, NSArray};
50//!
51//! let string = ns_string!("world");
52//! println!("hello {string}");
53//!
54//! let array = NSArray::from_slice(&[string]);
55//! println!("{array:?}");
56//! ```
57//!
58//! ```ignore
59#![doc = include_str!("../examples/basic_usage.rs")]
60//! ```
61//!
62//! An example showing how to define your own interfaces to parts that may be
63//! missing in the autogenerated interface.
64//!
65//! ```ignore
66#![doc = include_str!("../examples/speech_synthesis.rs")]
67//! ```
68#![no_std]
69#![cfg_attr(docsrs, feature(doc_auto_cfg))]
70// Update in Cargo.toml as well.
71#![doc(html_root_url = "https://docs.rs/objc2-foundation/0.3.1")]
72#![allow(non_snake_case)]
73#![recursion_limit = "512"]
74
75#[cfg(not(feature = "alloc"))]
76compile_error!("The `alloc` feature currently must be enabled.");
77
78extern crate alloc;
79
80#[cfg(feature = "std")]
81extern crate std;
82
83#[doc(hidden)]
84pub mod __ns_macro_helpers;
85#[cfg(feature = "NSEnumerator")]
86#[macro_use]
87mod iter;
88#[cfg(feature = "NSArray")]
89pub mod array;
90#[cfg(feature = "NSAttributedString")]
91mod attributed_string;
92#[cfg(feature = "NSBundle")]
93mod bundle;
94#[cfg(feature = "NSObjCRuntime")]
95mod comparison_result;
96#[cfg(feature = "NSObject")]
97mod copying;
98#[cfg(feature = "NSData")]
99mod data;
100#[cfg(feature = "NSDecimal")]
101mod decimal;
102#[cfg(feature = "NSDictionary")]
103pub mod dictionary;
104#[cfg(feature = "NSEnumerator")]
105pub mod enumerator;
106#[cfg(feature = "NSError")]
107mod error;
108#[cfg(feature = "NSException")]
109mod exception;
110#[cfg(feature = "NSEnumerator")]
111mod fast_enumeration_state;
112mod generated;
113#[cfg(feature = "NSGeometry")]
114mod geometry;
115mod macros;
116mod ns_consumed;
117#[cfg(feature = "NSValue")]
118mod number;
119#[cfg(feature = "NSProcessInfo")]
120mod process_info;
121#[cfg(feature = "NSRange")]
122mod range;
123#[cfg(feature = "NSSet")]
124pub mod set;
125#[cfg(feature = "NSString")]
126mod string;
127#[cfg(test)]
128mod tests;
129#[cfg(feature = "NSThread")]
130mod thread;
131#[cfg(feature = "NSObject")]
132mod to_owned;
133#[cfg(feature = "NSURL")]
134mod url;
135mod util;
136#[cfg(feature = "NSUUID")]
137mod uuid;
138#[cfg(feature = "NSValue")]
139mod value;
140
141#[cfg(feature = "NSObjCRuntime")]
142pub use self::comparison_result::NSComparisonResult;
143#[cfg(feature = "NSObject")]
144pub use self::copying::{CopyingHelper, MutableCopyingHelper, NSCopying, NSMutableCopying};
145#[cfg(feature = "NSDecimal")]
146pub use self::decimal::NSDecimal;
147#[cfg(feature = "NSEnumerator")]
148pub use self::fast_enumeration_state::NSFastEnumerationState;
149#[allow(unused_imports, unreachable_pub)]
150pub use self::generated::*;
151#[cfg(feature = "NSGeometry")]
152pub use self::geometry::NSRectEdge;
153#[cfg(all(feature = "NSGeometry", feature = "objc2-core-foundation"))]
154pub use self::geometry::{NSPoint, NSRect, NSSize};
155#[cfg(feature = "NSMapTable")]
156pub use self::ns_consumed::NSFreeMapTable;
157#[cfg(feature = "NSRange")]
158pub use self::range::NSRange;
159#[cfg(feature = "NSThread")]
160pub use self::thread::*;
161
162// Available under Foundation, so makes sense here as well:
163// https://developer.apple.com/documentation/foundation/numbers_data_and_basic_values?language=objc
164pub use objc2::ffi::{NSInteger, NSUInteger};
165
166// Special types that are stored in `objc2`, but really belong here
167#[doc(inline)]
168#[cfg(feature = "NSZone")]
169pub use objc2::runtime::NSZone;
170#[doc(inline)]
171#[cfg(feature = "NSProxy")]
172pub use objc2::runtime::__NSProxy as NSProxy;
173pub use objc2::runtime::{NSObject, NSObjectProtocol};
174#[deprecated = "Moved to `objc2::MainThreadMarker`"]
175pub use objc2::MainThreadMarker;
176
177#[cfg_attr(feature = "gnustep-1-7", link(name = "gnustep-base", kind = "dylib"))]
178extern "C" {}
179
180// MacTypes.h
181#[allow(unused)]
182pub(crate) type Boolean = u8; // unsigned char
183#[allow(unused)]
184pub(crate) type FourCharCode = u32;
185#[allow(unused)]
186pub(crate) type OSType = FourCharCode;
187#[allow(unused)]
188pub(crate) type UTF32Char = u32; // Or maybe Rust's char?
189#[allow(unused)]
190#[cfg(target_pointer_width = "64")]
191pub(crate) type SRefCon = *mut core::ffi::c_void;
192#[allow(unused)]
193#[cfg(target_pointer_width = "32")]
194pub(crate) type SRefCon = i32;
195#[allow(unused)]
196pub(crate) type OSErr = i16;
197
198/// [Apple's documentation](https://developer.apple.com/documentation/foundation/nstimeintervalsince1970?language=objc)
199#[allow(non_upper_case_globals)]
200#[cfg(feature = "NSDate")]
201pub const NSTimeIntervalSince1970: crate::NSTimeInterval = 978307200.0;
202
203/// [Apple's documentation](https://developer.apple.com/documentation/foundation/nsurlresponseunknownlength?language=objc)
204#[allow(non_upper_case_globals)]
205#[cfg(feature = "NSURLResponse")]
206pub const NSURLResponseUnknownLength: core::ffi::c_longlong = -1;
objc2_foundation/lib.rs

objc2_foundation/
lib.rs
