branded 0.2.1

Branded types for Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

//! # Branded
//!
//! Branded types for Rust.
//!
//! Branded types are types that have a unique brand attached to them. They are particularly useful
//! for managing ID types in large domains where it is easy to confuse the IDs of different domain
//! objects. With Rust's nominal typing, branded types makes it impossible to confuse the IDs.
//!
//! Thanks to Rust's trait system, we can transparently derive traits for our branded types based on
//! the inner type, making them completely transparent to other libraries such as `serde`, and
//! `sqlx`.
//!
//! > This crate is a continuation of the now-archived [bty](https://github.com/lffg/bty) crate. It
//! > has been rewritten to be
//! > a derive macro, and to support SQLx 0.8.
//!
//! The crate provides the `Branded` trait and the `Branded` derive macro.
//!
//! ```
//! use branded::Branded;
//!
//! #[derive(Branded)]
//! pub struct UserId(String);
//! ```
//!
//! ## Serde
//!
//! The `serde` feature transparently derives the `Serialize` and `Deserialize` traits for the
//! branded type. Pass `serde` as an option to the `Branded` derive macro to enable this feature.
//!
//! ```
//! use branded::Branded;
//!
//! #[derive(Branded)]
//! #[branded(serde)]
//! pub struct UserId(String);
//! ```
//!
//! ## SQLx
//!
//! The `sqlx` feature derives the `Type`, `Encode`, and `Decode` traits for the branded type. Pass
//! `sqlx` as an option to the `Branded` derive macro to enable this feature.
//!
//! ```
//! use branded::Branded;
//!
//! #[derive(Branded)]
//! #[branded(sqlx)]
//! pub struct UserId(String);
//! ```
//!
//! ## UUID
//!
//! The `uuid` feature exposes `nil()` and `new_v4()/new_v7()` methods on the branded type. Pass
//! `uuid` as an option to the `Branded` derive macro to enable this feature. We support both UUID
//! versions 4 and 7.
//!
//! ```
//! use branded::Branded;
//!
//! #[derive(Branded)]
//! #[branded(uuidv4, uuidv7)]
//! pub struct UserId(uuid::Uuid);
//! ```

pub use branded_derive::Branded;

/// A trait for types that are a brand of some inner type.
///
/// This trait is not used for specific features internally, but you may use it if you want to write
/// generic code over all branded types.
pub trait Branded {
    /// The inner type of the brand.
    ///
    /// This type is usually best represented as an ID such as string, an integer, or a UUID, but
    /// any type is allowed.
    type Inner;

    /// Get a reference to the inner type.
    fn inner(&self) -> &Self::Inner;

    /// Convert the branded type to the inner type.
    fn into_inner(self) -> Self::Inner;
}