From 185c99e48114b786d9e82df500f824aaf66282dc Mon Sep 17 00:00:00 2001 From: Dnomd343 Date: Tue, 28 Feb 2023 13:44:31 +0800 Subject: [PATCH] docs: CommonCode description of rust codec --- src/rust_ffi/src/codec/common_code.rs | 109 ++++++++++++++++++++++++-- src/rust_ffi/src/codec/ffi.rs | 29 +++---- src/rust_ffi/src/codec/short_code.rs | 14 ++-- 3 files changed, 121 insertions(+), 31 deletions(-) diff --git a/src/rust_ffi/src/codec/common_code.rs b/src/rust_ffi/src/codec/common_code.rs index 34a38f7..52e1579 100644 --- a/src/rust_ffi/src/codec/common_code.rs +++ b/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 { - 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 { 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 - } } diff --git a/src/rust_ffi/src/codec/ffi.rs b/src/rust_ffi/src/codec/ffi.rs index bbf54a8..9208ebd 100644 --- a/src/rust_ffi/src/codec/ffi.rs +++ b/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 { let mut short_code: u32 = 0; unsafe { @@ -63,7 +63,7 @@ pub fn raw_code_to_short_code(raw_code: u64) -> Result { } } -// #[allow(dead_code)] +#[allow(dead_code)] pub fn short_code_to_raw_code(short_code: u32) -> Result { let mut raw_code: u64 = 0; unsafe { @@ -74,7 +74,7 @@ pub fn short_code_to_raw_code(short_code: u32) -> Result { } } -// #[allow(dead_code)] +#[allow(dead_code)] pub fn raw_code_to_common_code(raw_code: u64) -> Result { let mut common_code: u64 = 0; unsafe { @@ -85,7 +85,7 @@ pub fn raw_code_to_common_code(raw_code: u64) -> Result { } } -// #[allow(dead_code)] +#[allow(dead_code)] pub fn common_code_to_raw_code(common_code: u64) -> Result { let mut raw_code: u64 = 0; unsafe { @@ -96,7 +96,7 @@ pub fn common_code_to_raw_code(common_code: u64) -> Result { } } -// #[allow(dead_code)] +#[allow(dead_code)] pub fn short_code_to_common_code(short_code: u32) -> Result { let mut common_code: u64 = 0; unsafe { @@ -107,7 +107,7 @@ pub fn short_code_to_common_code(short_code: u32) -> Result { } } -// #[allow(dead_code)] +#[allow(dead_code)] pub fn common_code_to_short_code(common_code: u64) -> Result { let mut short_code: u32 = 0; unsafe { @@ -118,42 +118,42 @@ pub fn common_code_to_short_code(common_code: u64) -> Result } } -#[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 { } } -#[allow(dead_code)] pub fn short_code_to_string_unsafe(short_code: u32) -> String { unsafe { let mut buffer: Vec = 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 { unsafe { let mut result: u32 = 0; @@ -293,7 +291,6 @@ pub fn common_code_to_string(common_code: u64) -> Result { } } -#[allow(dead_code)] pub fn common_code_to_string_unsafe(common_code: u64) -> String { unsafe { let mut buffer: Vec = 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 { unsafe { let mut buffer: Vec = 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 { unsafe { let mut result: u64 = 0; diff --git a/src/rust_ffi/src/codec/short_code.rs b/src/rust_ffi/src/codec/short_code.rs index 1273a48..08f021f 100644 --- a/src/rust_ffi/src/codec/short_code.rs +++ b/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...) - /// Example: 4WVE1(4091296) + /// Format: XXXXX(...num...) + /// 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 - /// warm-up index. + /// Convert ShortCode to RawCode type, note that it will take a long time if there + /// 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 - /// warm-up index. + /// Convert ShortCode to CommonCode type, note that it will take a long time if there + /// is no warm-up index. /// # Example /// ``` /// use klotski_ffi::ShortCode;