# Mapbox Variant

An header-only alternative to `boost::variant` for C++11 and C++14

[![Build Status](https://secure.travis-ci.org/mapbox/variant.svg)](https://travis-ci.org/mapbox/variant)
[![Build status](https://ci.appveyor.com/api/projects/status/v9tatx21j1k0fcgy)](https://ci.appveyor.com/project/Mapbox/variant)
[![Coverage Status](https://coveralls.io/repos/mapbox/variant/badge.svg?branch=master&service=github)](https://coveralls.io/r/mapbox/variant?branch=master)

## Introduction

Variant's basic building blocks are:

- `variant` - a type-safe representation for sum-types / discriminated unions
- `recursive_wrapper` - a helper type to represent recursive "tree-like" variants
- `apply_visitor(visitor, myVariant)` - to invoke a custom visitor on the variant's underlying type
- `get()` - a function to directly unwrap a variant's underlying type
- `.match([](Type){})` - a variant convenience member function taking an arbitrary number of lambdas creating a visitor behind the scenes and applying it to the variant

### Basic Usage - HTTP API Example

Suppose you want to represent a HTTP API response which is either a JSON result or an error:

```c++
struct Result {
  Json object;
};

struct Error {
  int32_t code;
  string message;
};
```

You can represent this at type level using a variant which is either an `Error` or a `Result`:

```c++
using Response = variant;

Response makeRequest() {
  return Error{501, "Not Implemented"};
}

Response ret = makeRequest();
```

To see which type the `Response` holds you pattern match on the variant unwrapping the underlying value:

```c++
ret.match([] (Result r) { print(r.object); },
          [] (Error e)  { print(e.message); });
```

Instead of using the variant's convenience `.match` pattern matching function you can create a type visitor functor and use `apply_visitor` manually:

```c++
struct ResponseVisitor {
  void operator()(Result r) const {
    print(r.object);
  }

  void operator()(Error e) const {
    print(e.message);
  }
};

ResponseVisitor visitor;
apply_visitor(visitor, ret);
```

In both cases the compiler makes sure you handle all types the variant can represent at compile.

### Recursive Variants - JSON Example

[JSON](http://www.json.org/) consists of types `String`, `Number`, `True`, `False`, `Null`, `Array` and `Object`.

```c++
struct String { string value; };
struct Number { double value; };
struct True   { };
struct False  { };
struct Null   { };
struct Array  { vector values; };
struct Object { unordered_map values; };
```

This works for primitive types but how do we represent recursive types such as `Array` which can hold multiple elements and `Array` itself, too?

For these use cases Variant provides a `recursive_wrapper` helper type which lets you express recursive Variants.

```c++
struct String { string value; };
struct Number { double value; };
struct True   { };
struct False  { };
struct Null   { };

// Forward declarations only
struct Array;
struct Object;

using Value = variant, recursive_wrapper