partially 0.1.0

Provides the Partial trait, and an optional macro to mirror a struct, wrapping each field in an Option
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
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

# partially


> Provides a configurable [derive macro](https://doc.rust-lang.org/reference/procedural-macros.html#derive-macros) that generates another struct with the same fields, but wrapped in `Option<T>`, and implements `Partial` to allow conditionally applying the generated struct fields to the base struct fields.

`partially` provides the `Partial` trait, which allows applying another structs values to `self`, with the intent that the other struct mirrors the fields of `self`, but wrapped in `Option<T>`.

Further, `partially_derive` (or `partially` with the `derive` feature enabled) supports automatically generating a mirrored struct with each field wrapped in `Option<T>`, **and** generates a `Partial` implementation that allows applying the `Some` fields of the mirrored struct to the base struct. I expect most folks will be most interested in using the derive macro.

## Usage


With derive:

```rust
// `partially` installed with feature `derive`
use partially::Partial;

// define a base structure, with the `Partial` derive macro
#[derive(partially_derive::Partial)]

// further, instruct the macro to derive `Default` on the generated structure
#[partially(derive(Default))]

struct Data {
    // since no field options are specified, this field will be mapped
    // to an `Option<String>` in the generated structure
    value: String,
}

// example usage
fn main() {
    // since we derived default for the generated struct, we can use that
    // to obtain a partial struct filled with `None`.
    let empty_partial = PartialData::default();

    // we can, of course, also specify values ourself
    let full_partial = PartialData {
        value: Some("modified".to_string()),
    };

    // define a "base" that we'll operate against
    let mut full = Data {
        value: "initial".to_string(),
    };

    // apply the empty partial
    full.apply_some(empty_partial);

    // note that applying the empty partial had no effect
    assert_eq!(full.value, "initial".to_string());

    // apply the full partial
    full.apply_some(full_partial);

    // note that applying the full partial modified the value
    assert_eq!(full.value, "modified".to_string());
}
```

Without derive:

```rust
use partially::Partial;

struct Base {
    value: String,
}

#[derive(Default)]

struct PartialBase {
    value: Option<String>,
}

impl partially::Partial for Base {
    type Item = PartialBase;

    #[allow(clippy::useless_conversion)]
    fn apply_some(&mut self, partial: Self::Item) {
        if let Some(value) = partial.value {
            self.value = value.into();
        }
    }
}

fn main() {
    let empty_partial = PartialBase::default();
    let full_partial = PartialBase {
        value: Some("modified".to_string()),
    };

    let mut data = Base {
        value: "initial".to_string(),
    };

    data.apply_some(empty_partial);

    assert_eq!(data.value, "initial".to_string());

    data.apply_some(full_partial);

    assert_eq!(data.value, "modified".to_string())
}

```

### Struct Options


#### derive


> Usage example: `#[partially(derive(Debug, Default))]`.

Instructs the macro to generate a `#[derive(...)]` attribute on the generated struct.

#### rename


> Usage example: `#[partially(rename = "MyGeneratedStruct")]`.

Instructs the macro to use a given identifier for the generated struct. By default, `PartialBaseStructName` is used, where `BaseStructName` is the name of the original struct.

#### crate


> Usage example: `#[partially(crate = "my_partially_crate")]`.

Instructs the macro to use a different base path for the `Partial` trait implementation. By default, `partially` is used. This can be useful if you've forked the `partially` crate.

### Field Options


#### rename


> Usage example: `#[partially(rename = "new_field_name")]`.

Instructs the macro to use a given identifier for the generated field. By default, the same name as the base struct is used.

#### omit


> Usage example: `#[partially(omit)]`.

Instructs the macro to omit the field from the generated struct. By default, no fields are omitted.

#### transparent


> Usage example: `#[partially(transparent)]`.

Instructs the macro to skip wrapping the generated field in `Option<T>`, instead transparently mirroring the field type into the generated struct.

#### as_type


> Usage example: `#[partially(as_type = "Option<f32>")]`.

Instructs the macro to use the provided type instead of `Option<T>` when generating the field. Note that the provided type will be used verbatim, so if you expect an `Option<T>` value, you'll need to manually specify that.

Note: When using `as_type`, the given type must `Into<BaseType>` where `BaseType` is the original field type. This is required for `Partial` trait implementation.