Struct Tagged 

pub struct Tagged<T, Tag> { /* private fields */ }

rust-tagged provides a simple way to define strongly typed wrappers over primitive types like String, i32, Uuid, chrono::DateTime, etc. It helps eliminate bugs caused by misusing raw primitives for conceptually distinct fields such as UserId, Email, ProductId, and more.

Eliminate accidental mixups between similar types (e.g. OrgId vs UserId) Enforce domain modeling in code via the type system Ergonomic .into() support for primitive conversions

Example - Simple

use tagged_core::{Tagged};

#[derive(Debug)]
struct EmailTag;

type Email = Tagged<String, EmailTag>;

fn main() {
    let email: Email = "test@example.com".into();
    println!("Email inner value: {}", email.value());

    // Convert back to String
    let raw: String = email.into();
    println!("Raw String: {raw}");
}

Implementations

impl<T, Tag> Tagged<T, Tag>

pub fn new(value: T) -> Tagged<T, Tag>

pub fn value(&self) -> &T

👎Deprecated since 0.8.0: Using .value() breaks type safety. Prefer Deref coercion (&*tagged) or Into conversion (tagged.into()) instead.

⚠️ WARNING: Avoid using .value() as it breaks type safety!

Using .value() extracts the inner value, which defeats the purpose of Tagged types. Instead, prefer:

• Using Deref coercion: let raw: &T = &*tagged;
• Using Into conversion: let raw: T = tagged.into();
• Keeping values as Tagged types throughout your codebase

Example (Avoid)

let user_id: UserId = 42.into();
let raw = user_id.value(); // ⚠️ Breaks type safety!

Example (Preferred)

let user_id: UserId = 42.into();
let raw: u32 = user_id.into(); // ✓ Maintains type safety through conversion

impl<T, Tag> Tagged<T, Tag>

where T: DeserializeOwned,

Support JSON string deserialization into Tagged<T, Tag>

Example

use tagged_core::Tagged;
use serde::Deserialize;
use std::convert::TryFrom;
 
#[derive(Debug, Deserialize)]
struct UserIdTag;
 
type UserId = Tagged<u32, UserIdTag>;
 
fn main() {
    let json = "42";
    let user_id: UserId = Tagged::from_json(json).unwrap();
    println!("User ID: {}", user_id.value());
}

pub fn from_json(json: &str) -> Result<Tagged<T, Tag>, Error>

Deserialize a JSON string into a Tagged type

Requires the serde feature to be enabled.

Errors

Returns a serde_json::Error if the JSON string cannot be deserialized into type T

Example

use tagged_core::Tagged;
use serde::Deserialize;
 
#[derive(Debug, Deserialize)]
struct UserIdTag;
 
type UserId = Tagged<u32, UserIdTag>;
 
fn main() {
    let json = "42";
    let user_id: UserId = Tagged::from_json(json).unwrap();
    println!("User ID: {}", user_id.value());
}

pub fn from_json_string(json: String) -> Result<Tagged<T, Tag>, Error>

Deserialize a JSON string from a String into a Tagged type

Requires the serde feature to be enabled.

Errors

Returns a serde_json::Error if the JSON string cannot be deserialized into type T

Example

use tagged_core::Tagged;
use serde::Deserialize;
 
#[derive(Debug, Deserialize)]
struct UserIdTag;
 
type UserId = Tagged<u32, UserIdTag>;
 
fn main() {
    let json = String::from("42");
    let user_id: UserId = Tagged::from_json_string(json).unwrap();
    println!("User ID: {}", user_id.value());
}

impl<T, Tag> Tagged<T, Tag>

where T: Serialize,

pub fn to_json(&self) -> Result<String, Error>

Serialize a Tagged type into a JSON string

Requires the serde feature to be enabled.

Errors

Returns a serde_json::Error if the value cannot be serialized to JSON

Example

use tagged_core::Tagged;
use serde::Serialize;
 
#[derive(Debug, Serialize)]
struct UserIdTag;
 
type UserId = Tagged<u32, UserIdTag>;
 
fn main() {
    let user_id: UserId = Tagged::from(42);
    let json = user_id.to_json().unwrap();
    println!("JSON: {}", json);
}

pub fn to_json_pretty(&self) -> Result<String, Error>

Serialize a Tagged type into a pretty-printed JSON string

Requires the serde feature to be enabled.

Errors

Returns a serde_json::Error if the value cannot be serialized to JSON

Example

use tagged_core::Tagged;
use serde::Serialize;
 
#[derive(Debug, Serialize)]
struct UserIdTag;
 
type UserId = Tagged<u32, UserIdTag>;
 
fn main() {
    let user_id: UserId = Tagged::from(42);
    let json = user_id.to_json_pretty().unwrap();
    println!("JSON: {}", json);
}

impl<T, Tag> Tagged<T, Tag>

Example - Mutation

use tagged_core::Tagged;

#[derive(Debug)]
struct Org;

type OrgName = Tagged<String, Org>;

fn main() {
    let mut name = OrgName::new("Codefonsi".into());

    name.set("New Org Name".into());

    println!("Updated Org Name: {}", name.value());
}

pub fn set(&mut self, new_value: T)

Not allowed feature - Get a mutable reference to the internal value Replace the inner value

Trait Implementations

impl<T, Tag> Clone for Tagged<T, Tag>

where T: Clone,

fn clone(&self) -> Tagged<T, Tag>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T, Tag> Debug for Tagged<T, Tag>

where T: Debug,

Example - Debug

use tagged_core::Tagged;


#[derive(Debug)]
struct UserIdTag {
    a: Tagged<u32, Self>,
    b: Tagged<u32, Self>,
}


fn main() {
    let instance = UserIdTag{a: 1.into(), b: 2.into()};

    println!("{}", instance.a);
    println!("{:?}", instance.b);
}

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T, Tag> Default for Tagged<T, Tag>

where T: Default,

fn default() -> Tagged<T, Tag>

Returns the “default value” for a type.

impl<T, Tag> Deref for Tagged<T, Tag>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &<Tagged<T, Tag> as Deref>::Target

Dereferences the value.

impl<'de, T, Tag> Deserialize<'de> for Tagged<T, Tag>

where T: Deserialize<'de>,

Available on crate feature serde only.

use serde::{Deserialize, Serialize};
use tagged_core::Tagged;
 
#[derive(Clone, Hash, Debug, PartialEq, Eq, Serialize, Deserialize)]
struct SomeCustomType {
    some_id: String
}
#[derive(Clone, Hash, Debug, PartialEq, Eq, Serialize, Deserialize)]
struct SomeCustomType2(String);
#[derive(Clone, Hash, Debug, PartialEq, Eq, Serialize, Deserialize)]
struct User {
    id: Tagged<String, Self>,
    id2: SomeCustomType,
    id3: SomeCustomType2,
}
 
 
fn main() {
    let user = User { id: "1".into() , id2: SomeCustomType { some_id: "2".into() }, id3: SomeCustomType2("3".into())};
    let j = serde_json::to_string(&user).unwrap();
    let converted_user = serde_json::from_str::<User>(&j).unwrap();
    println!("{}", j);
    println!("{:?}", converted_user);
}
/*
 Running `target/debug/examples/Serde_example`
{"id":"1","id2":{"some_id":"2"},"id3":"3"}
User { id: "1", id2: SomeCustomType { some_id: "2" }, id3: SomeCustomType2("3") }
 
Process finished with exit code 0
*/
 
/*
Problem with normal types
{"id":"1","id2":{"some_id":"2"}}
 
// rust is powerful enough to solve it using touple 
{"id":"1","id2":{"some_id":"2"},"id3":"3"}
 
// or we can use a new type called tagged that don't need a new name.
*/

fn deserialize<D>( deserializer: D, ) -> Result<Tagged<T, Tag>, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T, Tag> Display for Tagged<T, Tag>

where T: Display,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<Tag> From<&String> for Tagged<String, Tag>

Support From<&String> → Tagged<String, Tag>

fn from(s: &String) -> Tagged<String, Tag>

Converts to this type from the input type.

impl<Tag> From<&str> for Tagged<String, Tag>

Support From<&str> → Tagged<String, Tag>

fn from(s: &str) -> Tagged<String, Tag>

Converts to this type from the input type.

impl<T, Tag> From<T> for Tagged<T, Tag>

Blanket From<T> for Tagged<T, Tag>

fn from(value: T) -> Tagged<T, Tag>

Converts to this type from the input type.

impl<T, Tag> Hash for Tagged<T, Tag>

where T: Hash,

Example - Hash

fn main() {
    use tagged_core::Tagged;
    use std::collections::HashSet;

    #[derive(Clone, Hash, Debug, PartialEq, Eq)]
    struct User {
        id: Tagged<String, Self>
    }
    let mut s: HashSet<User> = HashSet::new();
    let user = User{id: "me@example.com".into()};
    s.insert(user.clone());

    assert!(s.contains(&user));
}

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a, T, Tag> IntoIterator for &'a Tagged<Vec<T>, Tag>

use tagged_core::Tagged;
 
#[derive(Debug)]
struct Org;
 
type EmployeeNames = Tagged<Vec<String>, Org>;
 
fn main() {
    let names: EmployeeNames = Tagged::new(vec!["Alice".into(), "Bob".into()]);
    names.iter().for_each(|name| println!("Name: {}", name));
}
 
/*
Name: Alice
Name: Bob
*/

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> <&'a Tagged<Vec<T>, Tag> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl<T, Tag> IntoIterator for Tagged<Vec<T>, Tag>

use tagged_core::Tagged;
 
#[derive(Debug)]
struct Org;
 
type EmployeeNames = Tagged<Vec<String>, Org>;
 
fn main() {
    let names: EmployeeNames = Tagged::new(vec!["Alice".into(), "Bob".into()]);
    names.into_iter().for_each(|name| println!("Name: {}", name));
}
 
/*
Name: Alice
Name: Bob
*/

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> <Tagged<Vec<T>, Tag> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl<T, Tag> Ord for Tagged<T, Tag>

where T: Ord,

fn cmp(&self, other: &Tagged<T, Tag>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T, Tag> PartialEq for Tagged<T, Tag>

where T: PartialEq,

fn eq(&self, other: &Tagged<T, Tag>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, Tag> PartialOrd for Tagged<T, Tag>

where T: PartialOrd,

fn partial_cmp(&self, other: &Tagged<T, Tag>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T, Tag> Serialize for Tagged<T, Tag>

where T: Serialize,

Available on crate feature serde only.

Example - Serialize

use serde::{Deserialize, Serialize};
use tagged_core::Tagged;

#[derive(Clone, Hash, Debug, PartialEq, Eq, Serialize, Deserialize)]
struct SomeCustomType {
    some_id: String
}
#[derive(Clone, Hash, Debug, PartialEq, Eq, Serialize, Deserialize)]
struct SomeCustomType2(String);
#[derive(Clone, Hash, Debug, PartialEq, Eq, Serialize, Deserialize)]
struct User {
    id: Tagged<String, Self>,
    id2: SomeCustomType,
    id3: SomeCustomType2,
}


fn main() {
    let user = User { id: "1".into() , id2: SomeCustomType { some_id: "2".into() }, id3: SomeCustomType2("3".into())};
    let j = serde_json::to_string(&user).unwrap();
    println!("{}", j);
}

/*
Problem with normal types
{"id":"1","id2":{"some_id":"2"}}

// rust is powerful enough to solve it using touple
{"id":"1","id2":{"some_id":"2"},"id3":"3"}

// or we can use a new type called tagged that don't need a new name.
*/

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<T, Tag> Taggable for Tagged<T, Tag>

type Inner = T

type Tag = Tag

fn type_name(&self) -> &'static str

impl<T, Tag> Eq for Tagged<T, Tag>

where T: Eq,