11#![ cfg( feature = "Foundation_NSString" ) ]
2- /// Creates an [`NSString`][`crate::Foundation::NSString`] from a static string .
2+ /// Create a [`NSString`] from a static [`str`] .
33///
4- /// Note: This works by placing statics in special sections, which may not
5- /// work completely reliably yet, see [#258]; until then, you should be
6- /// careful about using this in libraries intended for others to consume.
4+ /// Equivalent to the [boxed C-strings] `@"string"` syntax in Objective-C.
5+ ///
6+ /// [`NSString`]: crate::Foundation::NSString
7+ /// [boxed C-strings]: https://clang.llvm.org/docs/ObjectiveCLiterals.html#boxed-c-strings
8+ ///
9+ ///
10+ /// # Specification
11+ ///
12+ /// The macro takes any expression that evaluates to a `const` `&str`, and
13+ /// produces a `&'static NSString`.
14+ ///
15+ /// The returned string's encoding is not guaranteed to be UTF-8.
16+ ///
17+ /// Strings containing ASCII NUL is allowed, the NUL is preserved as one would
18+ /// expect.
19+ ///
20+ ///
21+ /// # Cargo features
22+ ///
23+ /// If the experimental `"unstable-static-nsstring"` feature is enabled, this
24+ /// will emit statics placed in special sections that will be replaced by dyld
25+ /// when the program starts up - which will in turn will cause the runtime
26+ /// cost of this macro to be completely non-existant!
27+ ///
28+ /// However, it is known to not be completely reliable yet, see [#258] for
29+ /// details.
730///
831/// [#258]: https://github.com/madsmtm/objc2/issues/258
932///
1033///
1134/// # Examples
1235///
13- /// This macro takes a either a `"string"` literal or `const` string slice as
14- /// the argument, and produces a `&'static NSString`:
36+ /// Creating a static `NSString`.
1537///
1638/// ```
1739/// use icrate::ns_string;
1840/// use icrate::Foundation::NSString;
1941///
2042/// let hello: &'static NSString = ns_string!("hello");
2143/// assert_eq!(hello.to_string(), "hello");
22- ///
23- /// const WORLD: &str = "world";
24- /// let world = ns_string!(WORLD);
25- /// assert_eq!(world.to_string(), WORLD);
2644/// ```
2745///
46+ /// Creating a `NSString` from a `const` `&str`.
2847///
29- /// # Unicode Strings
48+ /// ```
49+ /// # use icrate::ns_string;
50+ /// const EXAMPLE: &str = "example";
51+ /// assert_eq!(ns_string!(EXAMPLE).to_string(), EXAMPLE);
52+ /// ```
3053///
31- /// An NSString can contain strings with many different encodings, including
32- /// ASCII, UTF-8, UTF-16, and so on. This macro automatically converts your
33- /// string to the most efficient encoding, you don't have to do anything!
54+ /// Creating unicode strings.
3455///
3556/// ```
3657/// # use icrate::ns_string;
3758/// let hello_ru = ns_string!("Привет");
3859/// assert_eq!(hello_ru.to_string(), "Привет");
3960/// ```
4061///
41- /// Note that because this is implemented with `const` evaluation, massive
42- /// strings can increase compile time, and may even hit the `const` evaluation
43- /// limit.
44- ///
45- ///
46- /// # NUL handling
47- ///
48- /// Strings containing ASCII NUL is allowed, the NUL is preserved as one would
49- /// expect:
62+ /// Creating a string containing a NUL byte:
5063///
5164/// ```
5265/// # use icrate::ns_string;
53- /// let example = ns_string!("example\0");
54- /// assert_eq!(example.to_string(), "example\0");
55- ///
56- /// let example = ns_string!("exa\0mple");
57- /// assert_eq!(example.to_string(), "exa\0mple");
66+ /// assert_eq!(ns_string!("example\0").to_string(), "example\0");
67+ /// assert_eq!(ns_string!("exa\0mple").to_string(), "exa\0mple");
5868/// ```
59- ///
60- ///
61- /// # Runtime Cost
62- ///
63- /// None.
64- ///
65- /// The result is equivalent to `@"string"` syntax in Objective-C.
66- ///
67- /// Because of that, this should be preferred over [`NSString::from_str`]
68- /// where possible.
69- ///
70- /// [`NSString::from_str`]: crate::Foundation::NSString::from_str
7169#[ cfg( feature = "Foundation_NSString" ) ] // For auto_doc_cfg
7270#[ macro_export]
7371macro_rules! ns_string {
@@ -79,7 +77,7 @@ macro_rules! ns_string {
7977}
8078
8179#[ doc( hidden) ]
82- #[ cfg( feature = "apple" ) ]
80+ #[ cfg( all ( feature = "apple" , feature = "unstable-static-nsstring" ) ) ]
8381#[ macro_export]
8482macro_rules! __ns_string_inner {
8583 ( $inp: ident) => { {
@@ -177,12 +175,13 @@ macro_rules! __ns_string_inner {
177175}
178176
179177#[ doc( hidden) ]
180- #[ cfg( not( feature = "apple" ) ) ]
178+ #[ cfg( not( all ( feature = "apple" , feature = "unstable-static-nsstring" ) ) ) ]
181179#[ macro_export]
182180macro_rules! __ns_string_inner {
183181 ( $inp: ident) => { {
184- use $crate:: Foundation :: __macro_helpers:: CachedNSString ;
185- static CACHED_NSSTRING : CachedNSString = CachedNSString :: new( ) ;
186- CACHED_NSSTRING . get( $inp)
182+ static CACHED_NSSTRING : $crate:: Foundation :: __macro_helpers:: CachedId <
183+ $crate:: Foundation :: NSString ,
184+ > = $crate:: Foundation :: __macro_helpers:: CachedId :: new( ) ;
185+ CACHED_NSSTRING . get( || $crate:: Foundation :: NSString :: from_str( $inp) )
187186 } } ;
188187}
0 commit comments