apply_if 1.2.0

Conditionally apply a closure to an item or return it
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

# ApplyIf: Seamless Conditionals for Builder Chains

[![CI](https://github.com/bavalpey/apply_if/actions/workflows/tests.yml/badge.svg)](https://github.com/bavalpey/apply_if/actions/workflows/tests.yml)

This crate provides the functions `apply_if` and `apply_if_some` for consuming
builders, as well as `apply_if_mut` and `apply_if_some_mut` for mutable builder
chains. They allow us to conditionally invoke builder functions while keeping
the nice chaining syntax.

# Examples

These examples use the [`derive_builder`](https://crates.io/crates/derive_builder)
crate to create a builder and show how to use the `apply_if...` functions to
conditionally invoke builder functions without breaking the chain.

## Mutable Builders

This example uses a mutable builder pattern, which is why `apply_if_mut`
and `apply_if_some_mut` are used.

```rust
extern crate derive_builder;
use derive_builder::Builder;
use apply_if::ApplyIf;

#[derive(Debug,PartialEq,Builder)]
struct Value{
  #[builder(default = 123)]
  first: i32,
  #[builder(default = 42.)]
  second: f32,
}

fn main () {
    // apply_if_mut only applies the function
    // if the condition is true
    let value = ValueBuilder::default()
        .apply_if_mut(true, |builder| builder.first(100))
        .second(1.337)
        .build()
        .unwrap();
    assert_eq!(value, Value{first: 100, second: 1.337});

    let value = ValueBuilder::default()
        .apply_if_mut(false, |builder| builder.first(100))
        .second(1.337)
        .build()
        .unwrap();
    assert_eq!(value, Value{first: 123, second: 1.337});

    // apply_if_some_mut only applies the function
    // if the optional contains a value
    
    let value = ValueBuilder::default()
        .apply_if_some_mut(Some(100), |builder,val| builder.first(val))
        .second(1.337)
        .build()
        .unwrap();
    assert_eq!(value, Value{first: 100, second: 1.337});

    let value = ValueBuilder::default()
        .apply_if_some_mut(None, |builder,val| builder.first(val))
        .second(1.337)
        .build()
        .unwrap();
    assert_eq!(value, Value{first: 123, second: 1.337});
}
```

# Immutable Builders

This example uses a consuming builder pattern, which is why `apply_if`
and `apply_if_some` are used.

```rust
extern crate derive_builder;
use derive_builder::Builder;
use apply_if::ApplyIf;

#[derive(Debug,PartialEq,Builder)]
#[builder(pattern = "immutable")]
struct Value{
  #[builder(default = 123)]
  first: i32,
  #[builder(default = 42.)]
  second: f32,
}

fn main () {
    // apply_if only applies the function
    // if the condition is true
    let value = ValueBuilder::default()
        .apply_if(true, |builder| builder.first(100))
        .second(1.337)
        .build()
        .unwrap();
    assert_eq!(value, Value{first: 100, second: 1.337});

    let value = ValueBuilder::default()
        .apply_if(false, |builder| builder.first(100))
        .second(1.337)
        .build()
        .unwrap();
    assert_eq!(value, Value{first: 123, second: 1.337});

    // apply_if_some only applies the function
    // if the optional contains a value
    let value = ValueBuilder::default()
        .apply_if_some(Some(100), |builder,val| builder.first(val))
        .second(1.337)
        .build()
        .unwrap();
    assert_eq!(value, Value{first: 100, second: 1.337});

    let value = ValueBuilder::default()
        .apply_if_some(None, |builder,val| builder.first(val))
        .second(1.337)
        .build()
        .unwrap();
    assert_eq!(value, Value{first: 123, second: 1.337});
}
```