pack 0.4.0

Solver for packing puzzle.
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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169

# Packing Puzzle[![Build Status](https://travis-ci.org/fifth-postulate/packing-puzzle.svg?branch=master)](https://travis-ci.org/fifth-postulate/packing-puzzle)[![Coverage Status](https://coveralls.io/repos/github/fifth-postulate/packing-puzzle/badge.svg?branch=master)](https://coveralls.io/github/fifth-postulate/packing-puzzle?branch=master)[![pack on crates.io](https://img.shields.io/crates/v/pack.svg)](https://crates.io/crates/pack)
Solver for [packing problems][packing].

## installation
You can use this library by adding a dependency to your `Cargo.toml`

```toml
[dependencies]
pack = "*"
```

If you want to fix a specific version, feel free to enter a version number.

## Slothouber-Graatsma Puzzle
The [Slohouber-Graatsma puzzle][puzzle] asks for

> packing six 1 × 2 × 2 blocks and three 1 × 1 × 1 blocks into a 3 × 3 × 3 box.

We are going to solve it with the `pack` library.

First we announce the use of the external crate.

```rust
extern crate pack;
```

We need to a few things before we can start solving the puzzle. One is a
`pack::puzzle::solver::Target`. A target designates the volume to pack. A target
is created with a vector of `pack::puzzle::piece::Position`s.

```rust
fn brick3x3x3() -> Target {
    Target::new(vec!(
        Position::new(0, 0, 0),
        Position::new(1, 0, 0),
        Position::new(2, 0, 0),
        Position::new(0, 1, 0),
        Position::new(1, 1, 0),
        Position::new(2, 1, 0),
        Position::new(0, 2, 0),
        Position::new(1, 2, 0),
        Position::new(2, 2, 0),

        Position::new(0, 0, 1),
        Position::new(1, 0, 1),
        Position::new(2, 0, 1),
        Position::new(0, 1, 1),
        Position::new(1, 1, 1),
        Position::new(2, 1, 1),
        Position::new(0, 2, 1),
        Position::new(1, 2, 1),
        Position::new(2, 2, 1),

        Position::new(0, 0, 2),
        Position::new(1, 0, 2),
        Position::new(2, 0, 2),
        Position::new(0, 1, 2),
        Position::new(1, 1, 2),
        Position::new(2, 1, 2),
        Position::new(0, 2, 2),
        Position::new(1, 2, 2),
        Position::new(2, 2, 2),
    ))
}
```

Because bricks are often used as targets, there is a utility
`pack::util::target::brick` function that does exactly that. The above code
could be replaced with `brick(3, 3, 3)`.


One other thing we need is a `pack::puzzle::pieces::Bag` of
`pack::puzzle::piece:Template`s. A template is a shape that can be oriented in
different ways by iterating over them. A bag is a container to hold templates.

Templates are created by providing the vector of positions they occupy.

```rust
fn slothouber_graatsma_bag() -> Bag {
    Bag::new(vec!(
        Template::new(vec!(
            Position::new(0, 0, 0),
            Position::new(1, 0, 0),
            Position::new(0, 1, 0),
            Position::new(1, 1, 0),
        )),
        Template::new(vec!(
            Position::new(0, 0, 0),
            Position::new(1, 0, 0),
            Position::new(0, 1, 0),
            Position::new(1, 1, 0),
        )),
        Template::new(vec!(
            Position::new(0, 0, 0),
            Position::new(1, 0, 0),
            Position::new(0, 1, 0),
            Position::new(1, 1, 0),
        )),
        Template::new(vec!(
            Position::new(0, 0, 0),
            Position::new(1, 0, 0),
            Position::new(0, 1, 0),
            Position::new(1, 1, 0),
        )),
        Template::new(vec!(
            Position::new(0, 0, 0),
            Position::new(1, 0, 0),
            Position::new(0, 1, 0),
            Position::new(1, 1, 0),
        )),
        Template::new(vec!(
            Position::new(0, 0, 0),
            Position::new(1, 0, 0),
            Position::new(0, 1, 0),
            Position::new(1, 1, 0),
        )),

        Template::new(vec!(
            Position::new(0, 0, 0),
        )),
        Template::new(vec!(
            Position::new(0, 0, 0),
        )),
        Template::new(vec!(
            Position::new(0, 0, 0),
        )),
    ))
}
```

Finally we need to tell the `solve` function what to do when they find a
solution. This can be done by passing a clojure. For this example we will just
print the solution.

Our `main` function could look like the following code.

```rust
fn main(){
    let target = brick(3, 3, 3);
    let bag = slothouber_graatsma_bag();

    solve(&target, bag, &mut |solution|{
        println!("{}", solution)
    });
}
```

Running it will print a solution to the Slothouber-Graatsma puzzle.
The full source for this example can be found in
[examples/slothouber-graatsma.rs][example]. For a more extensive documentation
see the [wiki][].

## Development
If you are interested in contributing to this library please read
[CONTRIBUTING.md][contributing].


### Running clippy
Follow the installation instruction for [clippy][] and run the following command.
```sh
cargo +nightly clippy
```

[packing]: https://en.wikipedia.org/wiki/Packing_problems
[puzzle]: https://en.wikipedia.org/wiki/Slothouber%E2%80%93Graatsma_puzzle
[example]: examples/slothouber-graatsma.rs
[wiki]: https://github.com/fifth-postulate/packing-puzzle/wiki
[contributing]: CONTRIBUTING.md
[clippy]: https://github.com/rust-lang-nursery/rust-clippy