add utility functions

Author: Its-Just-Nans

src/card.rs

@@ -1,6 +1,6 @@
 //! The primary Card object as defined in RFC 9553
 
-use std::collections::HashMap;
+use std::{collections::HashMap, str::FromStr};
 
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
@@ -14,7 +14,7 @@ use crate::{
 use crate::{AddressComponent, AddressComponentKind, NameComponent};
 
 /// Represents the primary Card object as defined in RFC 9553, storing metadata and contact properties.
-#[derive(Serialize, Deserialize, Debug, Clone)]
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct Card {
     /// The JSContact type of the Card object. Must be "Card".
@@ -180,41 +180,13 @@ impl Card {
         }
     }
 
-    /// Wrapper around serde_json
-    /// # Errors
-    /// Will return an error if the input is not a valid Card object.
-    pub fn from_slice(json_slice: &[u8]) -> Result<Self, serde_json::Error> {
-        serde_json::from_slice(json_slice)
-    }
-
     /// Wrapper around serde_json
     /// # Errors
     /// Will return an error if the input is not a valid Card object.
     pub fn from_reader<R: std::io::Read>(reader: R) -> Result<Self, serde_json::Error> {
         serde_json::from_reader(reader)
     }
 
-    /// Wrapper around serde_json
-    /// # Errors
-    /// Will return an error if the input is not a valid Card object.
-    pub fn from_value(value: Value) -> Result<Self, serde_json::Error> {
-        serde_json::from_value(value)
-    }
-
-    /// Wrapper around serde_json
-    /// # Errors
-    /// Will return an error if the input is not a valid Card object.
-    pub fn try_from_str(json_string: String) -> Result<Self, serde_json::Error> {
-        serde_json::from_str(&json_string)
-    }
-
-    /// Wrapper around serde_json
-    /// # Errors
-    /// Will return an error if the input is not a valid Card object.
-    pub fn serialize_str(&self) -> Result<String, serde_json::Error> {
-        serde_json::to_string(self)
-    }
-
     /// Creates a new Card object with the latest version and the specified unique identifier.
     pub fn new_with_latest_version(uid: &str) -> Self {
         Self {
@@ -244,7 +216,7 @@ impl Card {
         };
     }
 
-    /// Get available languages in the Card object.
+    /// Get available languages from the [`Card::localizations`]
     pub fn get_available_languages(&self) -> Vec<String> {
         match &self.localizations {
             Some(localizations_map) => localizations_map.keys().cloned().collect(),
@@ -276,6 +248,39 @@ impl Card {
     }
 }
 
+impl FromStr for Card {
+    type Err = serde_json::Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        serde_json::from_str(s)
+    }
+}
+
+impl TryFrom<&[u8]> for Card {
+    type Error = serde_json::Error;
+
+    fn try_from(slice: &[u8]) -> Result<Self, Self::Error> {
+        serde_json::from_slice(slice)
+    }
+}
+
+impl TryFrom<Value> for Card {
+    type Error = String;
+
+    fn try_from(value: Value) -> Result<Self, Self::Error> {
+        let card: Card = serde_json::from_value(value.clone()).map_err(|e| e.to_string())?;
+        Ok(card)
+    }
+}
+
+impl TryFrom<Card> for String {
+    type Error = serde_json::Error;
+
+    fn try_from(card: Card) -> Result<Self, Self::Error> {
+        serde_json::to_string(&card)
+    }
+}
+
 /// Localize the Card object with jsonptr
 #[cfg(feature = "jsonptr")]
 fn localize_card(

src/lib.rs

@@ -11,26 +11,54 @@
 //! use jscontact::Card;
 //! use serde_json;
 //!
-//! let json = serde_json::json!({
+//! let json_value = serde_json::json!({
 //!     "@type": "Card",
 //!     "version": "1.0",
 //!     "uid": "1234"
 //! });
-//! let card = Card::from_value(json).unwrap();
-//!
-//! let str = card.serialize_str().unwrap();
-//!
-//! let card = Card::try_from_str(str).unwrap();
+//! let card_deserialized: Card = Card::try_from(json_value).unwrap(); // deserialize from serde::Value
+//! let card_string: String = String::try_from(card_deserialized.clone()).unwrap(); // serialize to String
+//! let card: Card = card_string.parse().unwrap(); // deserialize with parse()
+//! assert_eq!(card_deserialized, card);
 //! ```
 //!
 //! Simple creation example:
 //! ```rust
-//! use jscontact::{Card, CardKind, Name, NameComponent, NameComponentKind};
+//! use jscontact::{Card, CardKind, CardVersion, Name, NameComponent, NameComponentKind};
 //! use serde_json;
 //!
-//! let mut card = Card::new_with_latest_version("my:uri");
+//! let mut card = Card::new(CardVersion::OneDotZero, "my:uri");
 //! card.kind = Some(CardKind::Individual);
-//! let json = serde_json::to_string(&card).unwrap();
+//! let json = serde_json::to_string(&card).unwrap(); // serialize with serde
+//! ```
+//!
+//! Get localized Card:
+//! ```rust
+//! use jscontact::{Card, CardVersion, Name};
+//! use std::collections::HashMap;
+//! use serde_json::Value;
+//!
+//! // create a card
+//! let mut card = Card::new(CardVersion::OneDotZero, "my:uri");
+//! let mut name = Name::default();
+//! name.full = Some("John".to_string());
+//! card.name = Some(name);
+//!
+//! // add localization
+//! let mut translations: HashMap<String, Value> = HashMap::new();
+//! let mut name_en = Name::default();
+//! name_en.full = Some("Johny".to_string());
+//! translations.insert(
+//!     "name".to_string(),
+//!     serde_json::to_value(name_en).expect("Failed to serialize name"),
+//! );
+//! card.add_localization("en", translations);
+//!
+//! // use localized card
+//! let langs = card.get_available_languages();
+//! assert_eq!(langs, vec!["en"]);
+//! let localized = card.get_localized(&langs[0]).unwrap();
+//! assert_eq!(localized.name.unwrap().full.unwrap(), "Johny");
 //! ```
 
 #![deny(

tests/tests.rs

@@ -0,0 +1,83 @@
+mod test {
+    use jscontact::Card;
+    use serde_json::Value;
+
+    #[test]
+    fn test_usage_1() {
+        let json = r#"
+        {
+            "@type": "Card",
+            "version": "1.0",
+            "uid": "22B2C7DF-9120-4969-8460-05956FE6B065",
+            "name": {
+            "components": [{
+                    "kind": "given",
+                    "value": "John",
+                    "phonetic": "/ˈdʒɑːn/"
+                }, {
+                    "kind": "surname",
+                    "value": "Smith",
+                    "phonetic": "/smɪθ/"
+            }],
+            "phoneticSystem": "ipa"
+            }
+        }"#;
+        let card: Card = serde_json::from_str(json).unwrap();
+
+        let card_2 = json.parse().unwrap();
+
+        assert_eq!(card, card_2);
+    }
+
+    #[test]
+    fn test_usage_2() {
+        let json = r#"
+        {
+            "@type": "Card",
+            "version": "1.0",
+            "uid": "22B2C7DF-9120-4969-8460-05956FE6B065",
+            "name": {
+            "components": [{
+                    "kind": "given",
+                    "value": "John",
+                    "phonetic": "/ˈdʒɑːn/"
+                }, {
+                    "kind": "surname",
+                    "value": "Smith",
+                    "phonetic": "/smɪθ/"
+            }],
+            "phoneticSystem": "ipa"
+            }
+        }"#;
+        let card_value: Value = serde_json::from_str(json).unwrap();
+        let card: Card = serde_json::from_value(card_value.clone()).unwrap();
+
+        let card_into: Card = card_value.try_into().unwrap();
+        assert_eq!(card, card_into);
+    }
+
+    #[test]
+    fn test_localized() {
+        use jscontact::{Card, CardVersion, Name};
+        use std::collections::HashMap;
+
+        let mut card = Card::new(CardVersion::OneDotZero, "my:uri");
+        let mut name = Name::default();
+        name.full = Some("John".to_string());
+        card.name = Some(name);
+
+        let mut translations: HashMap<String, Value> = HashMap::new();
+        let mut name_en = Name::default();
+        name_en.full = Some("Johny".to_string());
+        translations.insert(
+            "name".to_string(),
+            serde_json::to_value(name_en).expect("Failed to serialize name"),
+        );
+        card.add_localization("en", translations);
+
+        let langs = card.get_available_languages();
+        assert_eq!(langs, vec!["en"]);
+        let localized = card.get_localized(&langs[0]).unwrap();
+        assert_eq!(localized.name.unwrap().full.unwrap(), "Johny");
+    }
+}