#newtype #synonyms #macro-derive #alias

macro synonym

Customizable derive macro to create newtypes. It peeks into the underlying type to choose which traits should be implemented.

7 releases

0.1.1 Nov 22, 2023
0.1.0 Sep 1, 2023
0.0.5 Jun 14, 2020
0.0.3 Mar 11, 2020
0.0.2 Jan 21, 2020

#405 in Rust patterns

Download history 1201/week @ 2024-01-05 912/week @ 2024-01-12 384/week @ 2024-01-19 341/week @ 2024-01-26 542/week @ 2024-02-02 413/week @ 2024-02-09 349/week @ 2024-02-16 416/week @ 2024-02-23 642/week @ 2024-03-01 355/week @ 2024-03-08 1102/week @ 2024-03-15 1259/week @ 2024-03-22 699/week @ 2024-03-29 838/week @ 2024-04-05 1176/week @ 2024-04-12 529/week @ 2024-04-19

3,579 downloads per month

Custom license

831 lines

Crates.io Docs.rs MIT License Build Status Maintenance



The synonym library is a Rust crate designed to simplify the creation of newtypes. It provides a customizable #[derive(Synonym)] macro that automatically implements various traits based on the underlying type of your newtype. This saves you from the boilerplate code usually required when defining newtypes.


To use synonym, add it to your Cargo.toml:

synonym = "0.1.0"

Basic example

Import the Synonym trait into your Rust file:

use synonym::Synonym;

Then, define your newtype and annotate it with #[derive(Synonym)]:

pub struct MyInt(i32);

Customization with Attributes

You can customize which traits are implemented or skipped using the #[synonym(skip(...))] and #[synonym(force(...))] attributes:

#[synonym(skip(Eq, PartialEq))]
pub struct MyString(String);

Generated code

When you use #[derive(Synonym)], the library generates implementations for various traits. Here's a simplified example for a newtype MyInt(i32):

impl Eq for MyInt {}
impl PartialEq for MyInt {
    fn eq(&self, other: &Self) -> bool {
        self.0 == other.0
// ... and so on for other traits

Trait implementation table

Kind Traits / Methods Implemented
u8, u16, u32, u64, u128, usize,
i8, i16, i32, i64, i128, isize
Eq, PartialEq, Ord, PartialOrd, Clone, Copy, Hash, Default, Debug, Add, Sub, Mul, Div, AddAssign, SubAssign, MulAssign, DivAssign, FromStr, From, AsRef, Deref
f32, f64
PartialEq, PartialOrd, Clone, Default, Debug, Add, Sub, Mul, Div, AddAssign, SubAssign, MulAssign, DivAssign, FromStr, From, AsRef, Deref
Eq, PartialEq, Ord, PartialOrd, Clone, Hash, Default, Debug, FromStr, From, AsRef, Deref, Borrow<str>, as_str()
Eq, PartialEq, Ord, PartialOrd, Clone, Copy, Hash, Default, Debug, FromStr, From, AsRef, Deref



To specify how the Display trait should be implemented, you can use the #[synonym(display = "...")] attribute. Here are the available options:

  • Opaque: Formats the output as TypeName(Value).
  • Transparent: Directly uses the inner type's Display implementation.
  • UpperCase: Converts the inner value to uppercase before displaying.
  • LowerCase: Converts the inner value to lowercase before displaying.
  • OpaqueUpperCase: Formats the output as TypeName(VALUE) where VALUE is uppercase.
  • OpaqueLowerCase: Formats the output as TypeName(value) where value is lowercase.
  • Custom string: Allows for a custom format string


#[synonym(display = "UpperCase")]
struct CountryName(String);

#[synonym(display = "::<> {} <>::")]
struct Turbo(String);

Serde Support

To enable Serde support for serialization and deserialization, you'll need to enable the with_serde feature flag in your Cargo.toml:

synonym = { version = "0.1.0", features = ["with_serde"] }

With this feature enabled, the Serialize and Deserialize traits will be automatically implemented for your type.

This documentation was generated with the assistance of ChatGPT-4 by OpenAI.


Licensed under of MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)


All contributions and comments are more than welcome! Don't be afraid to open an issue or PR whenever you find a bug or have an idea to improve this crate.


~26K SLoC