docs: CommonCode description of rust codec

src/rust_ffi/src/codec/common_code.rs

@@ -16,20 +16,42 @@ impl PartialEq for CommonCode {
 }
 
 impl fmt::Display for CommonCode {
+    /// Output CommonCode for debug.
+    ///   Format:  XXXXXXXXX (length 9)
+    ///   Example: 1A9BF0C00
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "{:09X}", self.code)
     }
 }
 
 impl CommonCode {
+    /// Check if the input `u64` value is a valid common code.
+    #[inline]
+    pub(crate) fn check(common_code: u64) -> bool {
+        codec_ffi::common_code_check(common_code)
+    }
+
+    /// Creates an unchecked common code, which is not safe and is only used
+    /// during encoding conversion (to ensure no errors).
+    #[inline]
     pub(crate) fn new(common_code: u64) -> CommonCode {
         CommonCode {
             code: common_code
         }
     }
 
+    /// Create common code from raw `u64`, and will be checked for validity.
+    /// # Example
+    /// ```
+    /// use klotski_ffi::CommonCode;
+    ///
+    /// match CommonCode::from(0x1_A9BF_0C00) {
+    ///     Ok(code) => println!("result: {}", code),
+    ///     Err(err) => println!("error: {}", err),
+    /// }
+    /// ```
     pub fn from(common_code: u64) -> Result<CommonCode, &'static str> {
-        match codec_ffi::common_code_check(common_code) {
+        match CommonCode::check(common_code) {
             true => Ok(CommonCode {
                 code: common_code
             }),
@@ -37,32 +59,105 @@ impl CommonCode {
         }
     }
 
+    /// Create common code from raw `&str`, and will be checked for validity.
+    /// # Example
+    /// ```
+    /// use klotski_ffi::CommonCode;
+    ///
+    /// match CommonCode::from_str("1A9BF0C00") {
+    ///     Ok(code) => println!("result: {}", code),
+    ///     Err(err) => println!("error: {}", err),
+    /// }
+    ///
+    /// match CommonCode::from_str("1a9bf0c") {
+    ///     Ok(code) => println!("result: {}", code),
+    ///     Err(err) => println!("error: {}", err),
+    /// }
+    /// ```
     pub fn from_str(common_code: &str) -> Result<CommonCode, &'static str> {
         Ok(CommonCode {
             code: codec_ffi::common_code_from_string(common_code)?
         })
     }
+}
 
+impl CommonCode {
     // TODO: from RawCode (u64 / RawCode)
     // TODO: from ShortCode (u32 / String / CommonCode)
+}
+
+impl CommonCode {
+    /// Return the original `u64` type common code value.
+    /// # Example
+    /// ```
+    /// use klotski_ffi::CommonCode;
+    ///
+    /// let code = CommonCode::from_str("1A9BF0C00").expect("invalid common code");
+    /// println!("original: {}", code.unwrap());
+    /// ```
+    #[inline]
+    pub fn unwrap(&self) -> u64 {
+        self.code
+    }
 
+    /// Returns the common code encoded as a string.
+    /// # Example
+    /// ```
+    /// use klotski_ffi::CommonCode;
+    ///
+    /// let code = CommonCode::from(0x1_A9BF_0C00).expect("invalid common code");
+    /// println!("common code string: {}", code.to_string());
+    /// ```
+    #[inline]
     pub fn to_string(&self) -> String {
         codec_ffi::common_code_to_string_unsafe(self.code)
     }
 
+    /// Returns the common code encoded as a shorten string, based on the
+    /// provisions of the common code, it is allowed to omit the last `0`
+    /// of the string (but at least one byte length must be reserved).
+    /// # Example
+    /// ```
+    /// use klotski_ffi::CommonCode;
+    ///
+    /// let code = CommonCode::from(0x1_A9BF_0C00).expect("invalid common code");
+    /// println!("common code shorten string: {}", code.to_string_shorten());
+    /// ```
+    #[inline]
     pub fn to_string_shorten(&self) -> String {
         codec_ffi::common_code_to_string_shorten_unsafe(self.code)
     }
 
+    /// Convert CommonCode to RawCode type.
+    /// # Example
+    /// ```
+    /// use klotski_ffi::CommonCode;
+    ///
+    /// let common_code = CommonCode::from_str("1A9BF0C00").unwrap();
+    /// let raw_code = common_code.to_raw_code();
+    /// println!("{} => {}", common_code, raw_code);
+    /// ```
+    #[inline]
+    pub fn to_raw_code(&self) -> RawCode {
+        RawCode::new(
+            codec_ffi::common_code_to_raw_code_unsafe(self.code)
+        )
+    }
+
+    /// Convert CommonCode to ShortCode type, note that it will take a long time if there
+    /// is no warm-up index.
+    /// # Example
+    /// ```
+    /// use klotski_ffi::CommonCode;
+    ///
+    /// let common_code = CommonCode::from_str("1A9BF0C00").unwrap();
+    /// let short_code = common_code.to_short_code();
+    /// println!("{} => {}", common_code, short_code);
+    /// ```
+    #[inline]
     pub fn to_short_code(&self) -> ShortCode {
         ShortCode::new(
             codec_ffi::common_code_to_short_code_unsafe(self.code)
         )
     }
-
-    // TODO: to RawCode
-
-    pub fn unwrap(&self) -> u64 {
-        self.code
-    }
 }

src/rust_ffi/src/codec/ffi.rs

@@ -52,7 +52,7 @@ pub fn common_code_check(common_code: u64) -> bool {
     }
 }
 
-// #[allow(dead_code)]
+#[allow(dead_code)]
 pub fn raw_code_to_short_code(raw_code: u64) -> Result<u32, &'static str> {
     let mut short_code: u32 = 0;
     unsafe {
@@ -63,7 +63,7 @@ pub fn raw_code_to_short_code(raw_code: u64) -> Result<u32, &'static str> {
     }
 }
 
-// #[allow(dead_code)]
+#[allow(dead_code)]
 pub fn short_code_to_raw_code(short_code: u32) -> Result<u64, &'static str> {
     let mut raw_code: u64 = 0;
     unsafe {
@@ -74,7 +74,7 @@ pub fn short_code_to_raw_code(short_code: u32) -> Result<u64, &'static str> {
     }
 }
 
-// #[allow(dead_code)]
+#[allow(dead_code)]
 pub fn raw_code_to_common_code(raw_code: u64) -> Result<u64, &'static str> {
     let mut common_code: u64 = 0;
     unsafe {
@@ -85,7 +85,7 @@ pub fn raw_code_to_common_code(raw_code: u64) -> Result<u64, &'static str> {
     }
 }
 
-// #[allow(dead_code)]
+#[allow(dead_code)]
 pub fn common_code_to_raw_code(common_code: u64) -> Result<u64, &'static str> {
     let mut raw_code: u64 = 0;
     unsafe {
@@ -96,7 +96,7 @@ pub fn common_code_to_raw_code(common_code: u64) -> Result<u64, &'static str> {
     }
 }
 
-// #[allow(dead_code)]
+#[allow(dead_code)]
 pub fn short_code_to_common_code(short_code: u32) -> Result<u64, &'static str> {
     let mut common_code: u64 = 0;
     unsafe {
@@ -107,7 +107,7 @@ pub fn short_code_to_common_code(short_code: u32) -> Result<u64, &'static str> {
     }
 }
 
-// #[allow(dead_code)]
+#[allow(dead_code)]
 pub fn common_code_to_short_code(common_code: u64) -> Result<u32, &'static str> {
     let mut short_code: u32 = 0;
     unsafe {
@@ -118,42 +118,42 @@ pub fn common_code_to_short_code(common_code: u64) -> Result<u32, &'static str>
     }
 }
 
-#[allow(dead_code)]
+#[inline]
 pub fn raw_code_to_short_code_unsafe(raw_code: u64) -> u32 {
     unsafe {
         Core::raw_code_to_short_code_unsafe(raw_code)
     }
 }
 
-#[allow(dead_code)]
+#[inline]
 pub fn short_code_to_raw_code_unsafe(short_code: u32) -> u64 {
     unsafe {
         Core::short_code_to_raw_code_unsafe(short_code)
     }
 }
 
-#[allow(dead_code)]
+#[inline]
 pub fn raw_code_to_common_code_unsafe(raw_code: u64) -> u64 {
     unsafe {
         Core::raw_code_to_common_code_unsafe(raw_code)
     }
 }
 
-#[allow(dead_code)]
+#[inline]
 pub fn common_code_to_raw_code_unsafe(common_code: u64) -> u64 {
     unsafe {
         Core::common_code_to_raw_code_unsafe(common_code)
     }
 }
 
-#[allow(dead_code)]
+#[inline]
 pub fn short_code_to_common_code_unsafe(short_code: u32) -> u64 {
     unsafe {
         Core::short_code_to_common_code_unsafe(short_code)
     }
 }
 
-#[allow(dead_code)]
+#[inline]
 pub fn common_code_to_short_code_unsafe(common_code: u64) -> u32 {
     unsafe {
         Core::common_code_to_short_code_unsafe(common_code)
@@ -249,7 +249,6 @@ pub fn short_code_to_string(short_code: u32) -> Result<String, &'static str> {
     }
 }
 
-#[allow(dead_code)]
 pub fn short_code_to_string_unsafe(short_code: u32) -> String {
     unsafe {
         let mut buffer: Vec<c_char> = vec![0; Core::SHORT_CODE_STR_SIZE as usize];
@@ -262,7 +261,6 @@ pub fn short_code_to_string_unsafe(short_code: u32) -> String {
     }
 }
 
-#[allow(dead_code)]
 pub fn short_code_from_string(short_code: &str) -> Result<u32, &'static str> {
     unsafe {
         let mut result: u32 = 0;
@@ -293,7 +291,6 @@ pub fn common_code_to_string(common_code: u64) -> Result<String, &'static str> {
     }
 }
 
-#[allow(dead_code)]
 pub fn common_code_to_string_unsafe(common_code: u64) -> String {
     unsafe {
         let mut buffer: Vec<c_char> = vec![0; Core::COMMON_CODE_STR_SIZE as usize];
@@ -324,7 +321,6 @@ pub fn common_code_to_string_shorten(common_code: u64) -> Result<String, &'stati
     }
 }
 
-#[allow(dead_code)]
 pub fn common_code_to_string_shorten_unsafe(common_code: u64) -> String {
     unsafe {
         let mut buffer: Vec<c_char> = vec![0; Core::COMMON_CODE_STR_SIZE as usize];
@@ -338,7 +334,6 @@ pub fn common_code_to_string_shorten_unsafe(common_code: u64) -> String {
     }
 }
 
-#[allow(dead_code)]
 pub fn common_code_from_string(common_code: &str) -> Result<u64, &'static str> {
     unsafe {
         let mut result: u64 = 0;

src/rust_ffi/src/codec/short_code.rs

@@ -17,8 +17,8 @@ impl PartialEq for ShortCode {
 
 impl fmt::Display for ShortCode {
     /// Output ShortCode for debug.
-    ///     Format:  XXXXX(...num...)
+    ///   Format:  XXXXX(...num...)
-    ///     Example: 4WVE1(4091296)
+    ///   Example: 4WVE1(4091296)
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "{}({})", self.to_string(), self.code)
     }
@@ -100,7 +100,7 @@ impl ShortCode {
     /// ```
     /// use klotski_ffi::ShortCode;
     ///
-    /// let code = ShortCode::from_str("4WVE1").expect("invalid short code");
+    /// let code = ShortCode::from(4091296).expect("invalid short code");
     /// println!("short code string: {}", code.to_string());
     /// ```
     #[inline]
@@ -108,8 +108,8 @@ impl ShortCode {
         codec_ffi::short_code_to_string_unsafe(self.code)
     }
 
-    /// Convert to RawCode type, note that it will take a long time if there is no
+    /// Convert ShortCode to RawCode type, note that it will take a long time if there
-    /// warm-up index.
+    /// is no warm-up index.
     /// # Example
     /// ```
     /// use klotski_ffi::ShortCode;
@@ -125,8 +125,8 @@ impl ShortCode {
         )
     }
 
-    /// Convert to CommonCode type, note that it will take a long time if there is no
+    /// Convert ShortCode to CommonCode type, note that it will take a long time if there
-    /// warm-up index.
+    /// is no warm-up index.
     /// # Example
     /// ```
     /// use klotski_ffi::ShortCode;