Move ns_string macro to Foundation module

crates/icrate/CHANGELOG.md

@@ -10,6 +10,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## icrate Unreleased - YYYY-MM-DD
 
+### Changed
+* Moved the `ns_string!` macro to `icrate::Foundation::ns_string`. The old
+  location in the crate root is deprecated.
+
 
 ## icrate 0.0.4 - 2023-07-31
 

crates/icrate/README.md

@@ -27,8 +27,7 @@ Currently supports:
 ## Example
 
 ```rust
-use icrate::Foundation::{NSCopying, NSArray};
-use icrate::ns_string;
+use icrate::Foundation::{ns_string, NSCopying, NSArray};
 
 let string = ns_string!("world");
 println!("hello {string}");

crates/icrate/examples/basic_usage.rs

@@ -1,6 +1,5 @@
-use icrate::ns_string;
 use icrate::objc2::rc::autoreleasepool;
-use icrate::Foundation::{NSArray, NSDictionary, NSObject};
+use icrate::Foundation::{ns_string, NSArray, NSDictionary, NSObject};
 
 fn main() {
     // Create and compare NSObjects

crates/icrate/examples/browser.rs

@@ -1,7 +1,6 @@
 #![deny(unsafe_op_in_unsafe_fn)]
 
 use icrate::{
-    ns_string,
     AppKit::{
         NSApplication, NSApplicationActivationPolicyRegular, NSBackingStoreBuffered,
         NSBezelStyleShadowlessSquare, NSButton, NSColor, NSControl, NSControlTextEditingDelegate,
@@ -11,7 +10,9 @@ use icrate::{
         NSUserInterfaceLayoutOrientationVertical, NSWindow, NSWindowStyleMaskClosable,
         NSWindowStyleMaskResizable, NSWindowStyleMaskTitled,
     },
-    Foundation::{NSObject, NSObjectProtocol, NSPoint, NSRect, NSSize, NSURLRequest, NSURL},
+    Foundation::{
+        ns_string, NSObject, NSObjectProtocol, NSPoint, NSRect, NSSize, NSURLRequest, NSURL,
+    },
     WebKit::{WKNavigation, WKNavigationDelegate, WKWebView},
 };
 use objc2::{

crates/icrate/examples/delegate.rs

@@ -2,8 +2,7 @@
 #![cfg_attr(not(target_os = "macos"), allow(unused))]
 use std::ptr::NonNull;
 
-use icrate::ns_string;
-use icrate::Foundation::{NSCopying, NSObject, NSString};
+use icrate::Foundation::{ns_string, NSCopying, NSObject, NSString};
 use objc2::declare::{Ivar, IvarBool, IvarDrop, IvarEncode};
 use objc2::rc::Id;
 use objc2::runtime::AnyObject;

crates/icrate/examples/speech_synthesis.rs

@@ -10,8 +10,7 @@
 use std::thread;
 use std::time::Duration;
 
-use icrate::ns_string;
-use icrate::Foundation::{NSObject, NSString};
+use icrate::Foundation::{ns_string, NSObject, NSString};
 use objc2::mutability::InteriorMutable;
 use objc2::rc::Id;
 use objc2::{extern_class, msg_send, msg_send_id, ClassType};

crates/icrate/src/Foundation/additions/dictionary.rs

@@ -92,8 +92,7 @@ extern_methods!(
             )),
             doc = "```ignore"
         )]
-        /// use icrate::Foundation::{NSMutableDictionary, NSMutableString, NSString};
-        /// use icrate::ns_string;
+        /// use icrate::Foundation::{ns_string, NSMutableDictionary, NSMutableString, NSString};
         ///
         /// let mut dict = NSMutableDictionary::new();
         /// dict.insert(NSString::from_str("one"), NSMutableString::new());
@@ -227,8 +226,7 @@ impl<K: Message, V: Message> NSMutableDictionary<K, V> {
     /// # Examples
     ///
     /// ```
-    /// use icrate::Foundation::{NSMutableDictionary, NSObject, NSString};
-    /// use icrate::ns_string;
+    /// use icrate::Foundation::{ns_string, NSMutableDictionary, NSObject, NSString};
     ///
     /// let mut dict = NSMutableDictionary::new();
     /// dict.insert(NSString::from_str("one"), NSObject::new());

crates/icrate/src/Foundation/additions/set.rs

@@ -254,8 +254,7 @@ extern_methods!(
         /// # Examples
         ///
         /// ```
-        /// use icrate::Foundation::{NSSet, NSString};
-        /// use icrate::ns_string;
+        /// use icrate::Foundation::{ns_string, NSSet, NSString};
         ///
         /// let strs = ["one", "two", "three"].map(NSString::from_str);
         /// let set = NSSet::from_id_slice(&strs);
@@ -272,8 +271,7 @@ extern_methods!(
         /// # Examples
         ///
         /// ```
-        /// use icrate::Foundation::{NSSet, NSString};
-        /// use icrate::ns_string;
+        /// use icrate::Foundation::{ns_string, NSSet, NSString};
         ///
         /// let strs = ["one", "two", "three"].map(NSString::from_str);
         /// let set = NSSet::from_id_slice(&strs);
@@ -384,8 +382,7 @@ impl<T: Message + PartialEq> NSMutableSet<T> {
     /// # Examples
     ///
     /// ```
-    /// use icrate::Foundation::{NSMutableSet, NSString};
-    /// use icrate::ns_string;
+    /// use icrate::Foundation::{ns_string, NSMutableSet, NSString};
     ///
     /// let mut set = NSMutableSet::new();
     ///

crates/icrate/src/Foundation/additions/string.rs

@@ -119,7 +119,7 @@ impl NSString {
     ///
     /// Prefer using the [`ns_string!`] macro when possible.
     ///
-    /// [`ns_string!`]: crate::ns_string
+    /// [`ns_string!`]: crate::Foundation::ns_string
     #[doc(alias = "initWithBytes")]
     #[doc(alias = "initWithBytes:length:encoding:")]
     #[allow(clippy::should_implement_trait)] // Not really sure of a better name

crates/icrate/src/Foundation/macros/ns_string.rs

@@ -36,8 +36,7 @@
 /// Creating a static `NSString`.
 ///
 /// ```
-/// use icrate::ns_string;
-/// use icrate::Foundation::NSString;
+/// use icrate::Foundation::{ns_string, NSString};
 ///
 /// let hello: &'static NSString = ns_string!("hello");
 /// assert_eq!(hello.to_string(), "hello");
@@ -46,29 +45,34 @@
 /// Creating a `NSString` from a `const` `&str`.
 ///
 /// ```
-/// # use icrate::ns_string;
+/// # use icrate::Foundation::ns_string;
 /// const EXAMPLE: &str = "example";
 /// assert_eq!(ns_string!(EXAMPLE).to_string(), EXAMPLE);
 /// ```
 ///
 /// Creating unicode strings.
 ///
 /// ```
-/// # use icrate::ns_string;
+/// # use icrate::Foundation::ns_string;
 /// let hello_ru = ns_string!("Привет");
 /// assert_eq!(hello_ru.to_string(), "Привет");
 /// ```
 ///
 /// Creating a string containing a NUL byte:
 ///
 /// ```
-/// # use icrate::ns_string;
+/// # use icrate::Foundation::ns_string;
 /// assert_eq!(ns_string!("example\0").to_string(), "example\0");
 /// assert_eq!(ns_string!("exa\0mple").to_string(), "exa\0mple");
 /// ```
-#[cfg(feature = "Foundation_NSString")] // For auto_doc_cfg
+// For auto_doc_cfg
+#[cfg(feature = "Foundation_NSString")]
 #[macro_export]
-macro_rules! ns_string {
+// `macro_export` places the macro in the crate root, while we'd rather have
+// it scoped under `Foundation`; so let's call this something private, and
+// export it there with `#[doc(inline)]` instead.
+#[doc(hidden)]
+macro_rules! __ns_string {
     ($s:expr) => {{
         // Immediately place in constant for better UI
         const INPUT: &str = $s;

crates/icrate/src/Foundation/mod.rs

@@ -87,6 +87,10 @@ pub use self::additions::*;
 pub use self::fixes::*;
 pub use self::generated::*;
 
+#[cfg(feature = "Foundation_NSString")]
+#[doc(inline)]
+pub use crate::__ns_string as ns_string;
+
 // Available under Foundation, so makes sense here as well:
 // https://developer.apple.com/documentation/foundation/numbers_data_and_basic_values?language=objc
 pub use objc2::ffi::{NSInteger, NSUInteger};

crates/icrate/src/lib.rs

@@ -148,3 +148,13 @@ pub mod UniformTypeIdentifiers;
 pub mod UserNotifications;
 #[cfg(feature = "WebKit")]
 pub mod WebKit;
+
+/// Deprecated alias of [`Foundation::ns_string`][crate::Foundation::ns_string].
+#[macro_export]
+#[deprecated = "use icrate::Foundation::ns_string instead"]
+#[cfg(feature = "Foundation_NSString")]
+macro_rules! ns_string {
+    ($s:expr) => {
+        $crate::Foundation::ns_string!($s)
+    };
+}

crates/icrate/tests/error.rs

@@ -1,7 +1,6 @@
 #![cfg(feature = "Foundation_NSError")]
 #![cfg(feature = "Foundation_NSString")]
-use icrate::ns_string;
-use icrate::Foundation::{NSError, NSURLErrorDomain};
+use icrate::Foundation::{ns_string, NSError, NSURLErrorDomain};
 
 #[test]
 fn basic() {

crates/icrate/tests/mutable_set.rs

@@ -2,8 +2,7 @@
 #![cfg(feature = "Foundation_NSString")]
 use objc2::rc::{__RcTestObject, __ThreadTestData};
 
-use icrate::ns_string;
-use icrate::Foundation::{self, NSMutableSet, NSSet, NSString};
+use icrate::Foundation::{self, ns_string, NSMutableSet, NSSet, NSString};
 
 #[test]
 fn test_insert() {

crates/icrate/tests/set.rs

@@ -4,8 +4,7 @@
 
 use objc2::rc::{__RcTestObject, __ThreadTestData};
 
-use icrate::ns_string;
-use icrate::Foundation::{self, NSNumber, NSObject, NSSet, NSString};
+use icrate::Foundation::{self, ns_string, NSNumber, NSObject, NSSet, NSString};
 
 #[test]
 fn test_new() {

crates/icrate/tests/string.rs

@@ -3,8 +3,7 @@ use std::ptr;
 
 use objc2::rc::autoreleasepool;
 
-use icrate::ns_string;
-use icrate::Foundation::{self, NSString};
+use icrate::Foundation::{self, ns_string, NSString};
 
 #[test]
 fn test_equality() {

crates/objc2/CHANGELOG.md

@@ -6,7 +6,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## Unreleased - YYYY-MM-DD
 
-
 ## 0.4.1 - 2023-07-31
 
 ### Added

crates/test-assembly/crates/test_ns_string/lib.rs

@@ -1,8 +1,7 @@
 //! Test the output of the `ns_string!` macro.
 #![cfg(feature = "Foundation_NSString")]
 
-use icrate::ns_string;
-use icrate::Foundation::NSString;
+use icrate::Foundation::{ns_string, NSString};
 
 // Temporary to allow testing putting string references in statics.
 // This doesn't yet compile on other platforms, but could in the future!

crates/test-ui/ui/invalid_ns_string_input.rs

@@ -1,4 +1,4 @@
-use icrate::ns_string;
+use icrate::Foundation::ns_string;
 
 fn main() {
     let _ = ns_string!(1u8);

crates/test-ui/ui/invalid_ns_string_output.rs

@@ -1,4 +1,4 @@
-use icrate::ns_string;
+use icrate::Foundation::ns_string;
 
 fn main() {
     let _: u8 = ns_string!("abc");

crates/test-ui/ui/ns_string_not_const.rs

@@ -1,4 +1,4 @@
-use icrate::ns_string;
+use icrate::Foundation::ns_string;
 
 fn main() {
     let s: &str = "abc";

crates/test-ui/ui/ns_string_output_not_const.rs

@@ -1,5 +1,4 @@
-use icrate::ns_string;
-use icrate::Foundation::NSString;
+use icrate::Foundation::{ns_string, NSString};
 
 fn main() {
     static STRING: &NSString = ns_string!("abc");