wrapped-vec
===========
[](https://crates.io/crates/wrapped-vec)
[](https://travis-ci.org/bobbo/wrapped-vec)
*wrapped-vec* is a Rust crate for auto-generating type definitions and boilerplate code for wrapping
Vectors in a custom type. It exports a `WrappedVec` custom-derive proc-macro that generates a named
wrapper over `Vec` for any type. For example:
``` rust
#[derive(WrappedVec)]
#[CollectionName="ExampleCollection"]
pub struct ExampleType { ... };
```
will generate
``` rust
pub struct ExampleCollection(Vec<ExampleType>)
```
A large number of useful trait impls are auto-generated, including `Iter`, `IntoIter` & `Expand`, plus a small
number of useful `Vec`-style methods like `len()`, `iter()` & `is_empty()`.
`WrappedVec` helps you avoid exposing library implementation details or creating brittle APIs that break when
plain `Vec` doesn't provide the right functionality any more. Type synonyms give collections a custom name
but don't address these issues. The common workaround of simply wrapping `Vec` with a custom type requires
manually implementing common useful collection traits such as `Iter`, which involves a lot of boilerplate.
Implementing `Deref` targetting `Vec` provides the basic `Vec` methods, but still requires manual implementation
of collection traits.
## Usage
Add `wrapped-vec` to your `Cargo.toml`:
```
wrapped-vec = "0.2"
```
Import the crate with macros:
```
#[macro_use]
use wrapped_vec;
```
Then derive your custom collection and use just like a plain `Vec`:
``` rust
#[derive(WrappedVec)]
#[CollectionName="TaskBatch"]
pub struct Task { ... };
let batch = TaskBatch::from_iter(vec![Task(), Task()]);
for task in batch {
task.doWork()
}
```
### Generated Type Documentation
`WrappedVec` automatically generates documentation for the derived `Vec` type and the methods
implemented on it. However, you may wish to override the automated documentation, which can
be done with custom attributes:
``` rust
#[derive(WrappedVec)]
#[CollectionName="TaskBatch"]
#[CollectionDoc="A batch of tasks to be run either in serial or parallel by a TaskRunner"]
pub struct Task { ... };
```
is roughly equivalent to
``` rust
/// A batch of tasks to be run either in serial or parallel by a TaskRunner
pub struct TaskBatch(Vec<Task>);
```
Documentation attributes available are:
|`CollectionDoc`|`struct CollectionName`|
|`CollectionNewDoc`|`CollectionName::new`|
|`CollectionLenDoc`|`CollectionName::len`|
|`CollectionIsEmptyDoc`|`CollectionName::is_empty`
|`CollectionIterDoc`|`CollectionName::iter`|
Documentation for trait methods are auto-populated from the parent trait documentation and not
currently overridable.
### Deriving Traits for Generated Collections
The `CollectionDerives` attribute can be used to specify traits which will be derived on the
generated collection type. Traits to be derived are specified as a comma-separated list in a
string. Omitting the `CollectionDerives` attribute, or passing an empty string, causes no trait
derivations to be generated.
``` rust
#[derive(Clone, Debug, WrappedVec)]
#[CollectionName="TaskBatch"]
#[CollectionDerives="Clone, Debug"]
pub struct Task { ... };
```
will generate
``` rust
#[derive(Clone, Debug)]
pub struct TaskBatch(Vec<Task>);
```
## License
Licensed under either of
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
### Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
additional terms or conditions.