Document RefEncode being wrong on BOOL, and suggest Bool instead

Author: madsmtm

objc2/README.md

@@ -14,13 +14,13 @@ Objective-C objects can be messaged using the `msg_send!` macro:
 
 ```rust , no_run
 use objc2::{class, msg_send};
-use objc2::runtime::{BOOL, Object};
+use objc2::runtime::{Bool, Object};
 
 let cls = class!(NSObject);
 unsafe {
     let obj: *mut Object = msg_send![cls, new];
     let hash: usize = msg_send![obj, hash];
-    let is_kind: BOOL = msg_send![obj, isKindOfClass: cls];
+    let is_kind: Bool = msg_send![obj, isKindOfClass: cls];
     // Even void methods must have their return type annotated
     let _: () = msg_send![obj, release];
 }

objc2/src/bool.rs

@@ -99,10 +99,21 @@ impl fmt::Debug for Bool {
     }
 }
 
+// SAFETY: `Bool` is `repr(transparent)`.
 unsafe impl Encode for Bool {
     const ENCODING: Encoding<'static> = objc2_sys::BOOL::ENCODING;
 }
 
+// Note that we shouldn't delegate to `BOOL`'s  `ENCODING_REF` since `BOOL` is
+// sometimes `i8`/`u8`, and their `ENCODING_REF`s are `Encoding::String`,
+// which is incorrect for `BOOL`:
+//
+// ```objc
+// @encode(BOOL); // -> "c", "C" or "B"
+// @encode(BOOL*); // -> "^c", "^C" or "^B"
+// @encode(char); // -> "c" or "C"
+// @encode(char*); // -> "*"
+// ```
 unsafe impl RefEncode for Bool {
     const ENCODING_REF: Encoding<'static> = Encoding::Pointer(&Self::ENCODING);
 }

objc2/src/lib.rs

@@ -7,12 +7,12 @@ Objective-C objects can be messaged using the [`msg_send!`](macro.msg_send!.html
 
 ``` no_run
 # use objc2::{class, msg_send};
-# use objc2::runtime::{BOOL, Class, Object};
+# use objc2::runtime::{Bool, Class, Object};
 # unsafe {
 let cls = class!(NSObject);
 let obj: *mut Object = msg_send![cls, new];
 let hash: usize = msg_send![obj, hash];
-let is_kind: BOOL = msg_send![obj, isKindOfClass: cls];
+let is_kind: Bool = msg_send![obj, isKindOfClass: cls];
 // Even void methods must have their return type annotated
 let _: () = msg_send![obj, release];
 # }

objc2/src/message/mod.rs

@@ -165,13 +165,13 @@ pub unsafe trait MessageReceiver: private::Sealed {
     /// # Example
     /// ``` no_run
     /// # use objc2::{class, msg_send, sel};
-    /// # use objc2::runtime::{BOOL, Class, Object};
+    /// # use objc2::runtime::{Bool, Class, Object};
     /// # use objc2::MessageReceiver;
     /// let obj: &Object;
     /// # obj = unsafe { msg_send![class!(NSObject), new] };
     /// let sel = sel!(isKindOfClass:);
     /// // Verify isKindOfClass: takes one Class and returns a BOOL
-    /// let result = obj.verify_message::<(&Class,), BOOL>(sel);
+    /// let result = obj.verify_message::<(&Class,), Bool>(sel);
     /// assert!(result.is_ok());
     /// ```
     fn verify_message<A, R>(&self, sel: Sel) -> Result<(), MessageError>

objc2_encode/src/encode.rs

@@ -182,7 +182,7 @@ unsafe impl Encode for () {
 /// Using this directly is heavily discouraged, since the type of BOOL differs
 /// across platforms.
 ///
-/// Use `objc2_sys::BOOL::ENCODING` or `objc2::runtime::Bool` instead.
+/// Use `objc2::runtime::Bool::ENCODING` instead.
 unsafe impl Encode for bool {
     const ENCODING: Encoding<'static> = Encoding::Bool;
 }

objc2_sys/src/types.rs

@@ -65,6 +65,11 @@ mod inner {
 ///
 /// The type of this varies across platforms, so to convert an it into a Rust
 /// [`bool`], always compare it with [`YES`][`crate::YES`] or [`NO`][`crate::NO`].
+///
+/// Note that this type implements `objc2_encode::Encode` and
+/// `objc2_encode::RefEncode`, but the `RefEncode` implementation is wrong
+/// on some platforms! You should only use this on FFI boundaries, otherwise
+/// prefer `objc2::runtime::Bool`.
 pub type BOOL = inner::BOOL;
 
 /// An immutable pointer to a selector.