objc2_encode/
lib.rs

1//! # Objective-C type-encoding
2//!
3//! The Objective-C directive `@encode` encodes types as strings, and this is
4//! used in various places in the runtime.
5//!
6//! This crate provides the [`Encoding`] type to describe and compare these
7//! type-encodings, and the [`EncodingBox`] type which does the same, except
8//! it can be parsed from an encoding at runtime.
9//!
10//! The types from this crate is exported under the [`objc2`] crate as
11//! `objc2::encode`, so usually you would use it from there.
12//!
13//! [`objc2`]: https://crates.io/crates/objc2
14//!
15//!
16//! ## Example
17//!
18//! Parse an encoding from a string and compare it to a known encoding.
19//!
20//! ```rust
21//! use objc2_encode::{Encoding, EncodingBox};
22//! let s = "{s=i}";
23//! let enc = Encoding::Struct("s", &[Encoding::Int]);
24//! let parsed: EncodingBox = s.parse()?;
25//! assert!(enc.equivalent_to_box(&parsed));
26//! assert_eq!(enc.to_string(), s);
27//! # Ok::<(), objc2_encode::ParseError>(())
28//! ```
29//!
30//!
31//! ## Further resources
32//!
33//! - [Objective-C, Encoding and You](https://dmaclach.medium.com/objective-c-encoding-and-you-866624cc02de).
34//! - [Apple's documentation on Type Encodings](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ObjCRuntimeGuide/Articles/ocrtTypeEncodings.html).
35//! - [How are the digits in ObjC method type encoding calculated?](https://stackoverflow.com/a/11527925)
36//! - [`clang`'s source code for generating `@encode`](https://github.com/llvm/llvm-project/blob/fae0dfa6421ea6c02f86ba7292fa782e1e2b69d1/clang/lib/AST/ASTContext.cpp#L7500-L7850).
37
38#![no_std]
39#![warn(missing_docs)]
40#![warn(missing_debug_implementations)]
41#![warn(clippy::missing_errors_doc)]
42#![warn(clippy::missing_panics_doc)]
43// Update in Cargo.toml as well.
44#![doc(html_root_url = "https://docs.rs/objc2-encode/4.1.0")]
45
46#[cfg(not(feature = "alloc"))]
47compile_error!("the `alloc` feature currently must be enabled");
48
49extern crate alloc;
50#[cfg(any(feature = "std", doc))]
51extern crate std;
52
53mod encoding;
54mod encoding_box;
55mod helper;
56mod parse;
57
58// Will be used at some point when generic constants are available
59#[allow(dead_code)]
60mod static_str;
61
62pub use self::encoding::Encoding;
63pub use self::encoding_box::EncodingBox;
64pub use self::parse::ParseError;
objc2_encode/lib.rs

objc2_encode/
lib.rs
