Crate synonym

Overview

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.

Usage

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

[dependencies]
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)]:

#[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:

#[derive(Synonym)]
#[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
Integer 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
Float f32, f64	PartialEq, PartialOrd, Clone, Default, Debug, Add, Sub, Mul, Div, AddAssign, SubAssign, MulAssign, DivAssign, FromStr, From, AsRef, Deref
String String	Eq, PartialEq, Ord, PartialOrd, Clone, Hash, Default, Debug, FromStr, From, AsRef, Deref, Borrow<str>, as_str()
Char char	Eq, PartialEq, Ord, PartialOrd, Clone, Copy, Hash, Default, Debug, FromStr, From, AsRef, Deref

Fine-tuning

Display

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

Examples

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

#[derive(Synonym)]
#[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:

[dependencies]
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.

Derive Macros

• Synonym