feat: RawCode framework of rust codec

src/rust_ffi/src/codec/common_code.rs

@@ -16,9 +16,8 @@ impl PartialEq for CommonCode {
 }
 
 impl fmt::Display for CommonCode {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        // TODO: using hex output of CommonCode
+        write!(f, "{:09X}", self.code)
-        write!(f, "{}", self.code)
     }
 }
 
@@ -47,14 +46,13 @@ impl CommonCode {
     // TODO: from RawCode (u64 / RawCode)
     // TODO: from ShortCode (u32 / String / CommonCode)
 
-    pub fn to_string(&self, shorten: bool) -> String {
+    pub fn to_string(&self) -> String {
-        match shorten {
+        codec_ffi::common_code_to_string_unsafe(self.code)
-            true => codec_ffi::common_code_to_string_unsafe(self.code),
-            false => codec_ffi::common_code_to_string_shorten_unsafe(self.code),
-        }
     }
 
-    // TODO: to_string_shorten
+    pub fn to_string_shorten(&self) -> String {
+        codec_ffi::common_code_to_string_shorten_unsafe(self.code)
+    }
 
     pub fn to_short_code(&self) -> ShortCode {
         ShortCode::new(

src/rust_ffi/src/codec/ffi.rs

@@ -1,20 +1,21 @@
 use crate::core::Core;
 use std::ffi::{c_char, CString};
 
-#[allow(dead_code)]
+#[inline]
 pub fn short_code_enable() {
     unsafe {
         Core::short_code_enable()
     }
 }
 
-#[allow(dead_code)]
+#[inline]
 pub fn short_code_enable_fast() {
     unsafe {
         Core::short_code_enable_fast()
     }
 }
 
+#[inline]
 #[allow(dead_code)]
 pub fn is_short_code_available() -> bool {
     unsafe {
@@ -22,6 +23,7 @@ pub fn is_short_code_available() -> bool {
     }
 }
 
+#[inline]
 #[allow(dead_code)]
 pub fn is_short_code_available_fast() -> bool {
     unsafe {
@@ -29,21 +31,21 @@ pub fn is_short_code_available_fast() -> bool {
     }
 }
 
-#[allow(dead_code)]
+#[inline]
 pub fn raw_code_check(raw_code: u64) -> bool {
     unsafe {
         Core::raw_code_check(raw_code)
     }
 }
 
-#[allow(dead_code)]
+#[inline]
 pub fn short_code_check(short_code: u32) -> bool {
     unsafe {
         Core::short_code_check(short_code)
     }
 }
 
-#[allow(dead_code)]
+#[inline]
 pub fn common_code_check(common_code: u64) -> bool {
     unsafe {
         Core::common_code_check(common_code)

src/rust_ffi/src/codec/mod.rs

@@ -1,7 +1,9 @@
 mod ffi;
+mod raw_code;
 mod short_code;
 mod common_code;
 
+pub use raw_code::RawCode;
 pub use short_code::ShortCode;
 pub use common_code::CommonCode;
 
@@ -20,7 +22,8 @@ pub fn demo() {
     ShortCode::warm_up_fast();
 
     println!("{}", s.to_string());
-    println!("{:?}", s.to_common_code());
+    println!("{}", s.to_raw_code());
+    println!("{}", s.to_common_code());
 
     let c = CommonCode::from(0x1A9BF0C00).unwrap();
     println!("{}", c.unwrap());
@@ -32,8 +35,8 @@ pub fn demo() {
     let c = CommonCode::from_str("1A9BF0C").unwrap();
     println!("{}", c);
 
-    println!("{}", c.to_string(false));
+    println!("{}", c.to_string());
-    println!("{}", c.to_string(true));
+    println!("{}", c.to_string_shorten());
     println!("{}", c.to_short_code());
 
 }

src/rust_ffi/src/codec/raw_code.rs

@@ -0,0 +1,66 @@
+use std::fmt;
+use super::ffi as codec_ffi;
+use super::{ShortCode, CommonCode};
+
+pub struct RawCode {
+    code: u64
+}
+
+impl Eq for RawCode {}
+
+impl PartialEq for RawCode {
+    fn eq(&self, other: &Self) -> bool {
+        self.code == other.code
+    }
+}
+
+impl fmt::Display for RawCode {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{:015X}", self.code)
+    }
+}
+
+impl RawCode {
+    #[inline]
+    pub(crate) fn check(raw_code: u64) -> bool {
+        codec_ffi::raw_code_check(raw_code)
+    }
+
+    #[inline]
+    pub(crate) fn new(raw_code: u64) -> RawCode {
+        RawCode {
+            code: raw_code
+        }
+    }
+
+    pub fn from(raw_code: u64) -> Result<RawCode, &'static str> {
+        match RawCode::check(raw_code) {
+            true => Ok(RawCode {
+                code: raw_code
+            }),
+            _ => Err("invalid raw code"),
+        }
+    }
+
+    // TODO: from ShortCode (u32 / String / CommonCode)
+    // TODO: from CommonCode (u64 / String / CommonCode)
+
+    pub fn to_short_code(&self) -> ShortCode {
+        ShortCode::new(
+            codec_ffi::raw_code_to_short_code_unsafe(self.code)
+        )
+    }
+
+    pub fn to_common_code(&self) -> CommonCode {
+        CommonCode::new(
+            codec_ffi::raw_code_to_common_code_unsafe(self.code)
+        )
+    }
+
+    pub fn unwrap(&self) -> u64 {
+        self.code
+    }
+
+    // TODO: mirror function
+
+}

src/rust_ffi/src/codec/short_code.rs

@@ -1,4 +1,5 @@
 use std::fmt;
+use crate::codec::raw_code::RawCode;
 use super::CommonCode;
 use super::ffi as codec_ffi;
 
@@ -16,7 +17,7 @@ impl PartialEq for ShortCode {
 }
 
 impl fmt::Display for ShortCode {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "{}({})", self.to_string(), self.code)
     }
 }
@@ -45,27 +46,78 @@ impl ShortCode {
 
     // TODO: from RawCode (u64 / RawCode)
     // TODO: from CommonCode (u64 / String / CommonCode)
+}
 
+impl ShortCode {
+    #[inline]
+    pub fn unwrap(&self) -> u32 {
+        self.code
+    }
+
+    #[inline]
     pub fn to_string(&self) -> String {
         codec_ffi::short_code_to_string_unsafe(self.code)
     }
 
-    // TODO: to RawCode
+    #[inline]
+    pub fn to_raw_code(&self) -> RawCode {
+        RawCode::new(
+            codec_ffi::short_code_to_raw_code_unsafe(self.code)
+        )
+    }
 
+    #[inline]
     pub fn to_common_code(&self) -> CommonCode {
         CommonCode::new(
             codec_ffi::short_code_to_common_code_unsafe(self.code)
         )
     }
+}
 
-    pub fn unwrap(&self) -> u32 {
+impl ShortCode {
-        self.code
+    /// # Introduce
-    }
+    ///
-
+    /// The conversion of short code must rely on the index. The normal mode will
+    /// take a shorter time to build the index, but the conversion efficiency is
+    /// low. The fast mode takes more time and memory to build the index and has
+    /// a higher conversion efficiency.
+    ///
+    /// If the conversion is performed without warming up, the warm-up mechanism
+    /// will be automatically triggered, which may cause the initial conversion
+    /// to take a long time.
+    ///
+    /// This function will build the index of normal mode, if this has not been
+    /// run before, this will block for a certain amount of time, and is safe for
+    /// multi-threaded calls.
+    ///
+    /// If you are already in fast mode, it will have no effect.
+    ///
+    /// # Example
+    /// ```
+    /// use klotski_ffi::ShortCode;
+    ///
+    /// ShortCode::warm_up();
+    /// ```
+    #[inline]
     pub fn warm_up() {
         codec_ffi::short_code_enable();
     }
 
+    /// # Introduce
+    ///
+    /// This function will build the index of the fast mode, it will consume more
+    /// time and memory than normal mode (about 7 times), and it also safe for
+    /// multi-threaded calls.
+    ///
+    /// If you are already in normal mode, it will reduce part of time.
+    ///
+    /// # Example
+    /// ```
+    /// use klotski_ffi::ShortCode;
+    ///
+    /// ShortCode::warm_up_fast();
+    /// ```
+    #[inline]
     pub fn warm_up_fast() {
         codec_ffi::short_code_enable_fast();
     }

src/rust_ffi/src/lib.rs

@@ -4,4 +4,8 @@ mod metadata;
 
 pub use metadata::load_metadata as metadata;
 
+pub use codec::RawCode;
+pub use codec::ShortCode;
+pub use codec::CommonCode;
+
 pub use codec::demo;