#structs-enums #macro #macro-derive #constructor #initialization #generate #functions

macro no-std derive-new

#[derive(new)] implements simple constructor functions for structs and enums

18 releases

0.6.0 Nov 7, 2023
0.5.9 Feb 8, 2021
0.5.8 Aug 18, 2019
0.5.7 Jul 11, 2019
0.3.0 Nov 19, 2016

#39 in Procedural macros

Download history 41652/week @ 2023-11-21 44757/week @ 2023-11-28 47772/week @ 2023-12-05 46166/week @ 2023-12-12 41524/week @ 2023-12-19 37516/week @ 2023-12-26 45715/week @ 2024-01-02 49077/week @ 2024-01-09 58305/week @ 2024-01-16 60734/week @ 2024-01-23 68015/week @ 2024-01-30 62841/week @ 2024-02-06 61395/week @ 2024-02-13 64101/week @ 2024-02-20 72714/week @ 2024-02-27 53565/week @ 2024-03-05

260,857 downloads per month
Used in 602 crates (197 directly)

MIT license

19KB
322 lines

A custom derive implementation for #[derive(new)]

A derive(new) attribute creates a new constructor function for the annotated type. That function takes an argument for each field in the type giving a trivial constructor. This is useful since as your type evolves you can make the constructor non-trivial (and add or remove fields) without changing client code (i.e., without breaking backwards compatibility). It is also the most succinct way to initialise a struct or an enum.

Implementation uses macros 1.1 custom derive (which works in stable Rust from 1.15 onwards).

#[no_std] is fully supported if you switch off the default feature "std".

Examples

Cargo.toml:

[dependencies]
derive-new = "0.5"

Include the macro:

  • Rust Edition 2015

    #[macro_use]
    extern crate derive_new;
    
  • Rust Edition 2018

    use derive_new::new;
    

Generating constructor for a simple struct:

#[derive(new)]
struct Bar {
    a: i32,
    b: String,
}

let _ = Bar::new(42, "Hello".to_owned());

Default values can be specified either via #[new(default)] attribute which removes the argument from the constructor and populates the field with Default::default(), or via #[new(value = "..")] which initializes the field with a given expression:

#[derive(new)]
struct Foo {
    x: bool,
    #[new(value = "42")]
    y: i32,
    #[new(default)]
    z: Vec<String>,
}

let _ = Foo::new(true);

Generic types are supported; in particular, PhantomData<T> fields will be not included in the argument list and will be initialized automatically:

use std::marker::PhantomData;

#[derive(new)]
struct Generic<'a, T: Default, P> {
    x: &'a str,
    y: PhantomData<P>,
    #[new(default)]
    z: T,
}

let _ = Generic::<i32, u8>::new("Hello");

For enums, one constructor method is generated for each variant, with the type name being converted to snake case; otherwise, all features supported for structs work for enum variants as well:

#[derive(new)]
struct Enum {
    FirstVariant,
    SecondVariant(bool, #[new(default)] u8),
    ThirdVariant { x: i32, #[new(value = "vec![1]")] y: Vec<u8> }
}

let _ = Enum::new_first_variant();
let _ = Enum::new_second_variant(true);
let _ = Enum::new_third_variant(42);

Dependencies

~340–790KB
~19K SLoC