Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 16 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,10 @@ An header-only alternative to `boost::variant` for C++11 and C++14
## Introduction

Variant's basic building blocks are:
- `variant<Ts...>` - a type-safe representation for sum-types / discriminated unions
- `recursive_wrapper<T>` - 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<T>()` - a function to directly unwrap a variant's underlying type
- `mapbox::variant<Ts...>` - a type-safe representation for sum-types / discriminated unions
- `mapbox::recursive_wrapper<T>` - a helper type to represent recursive "tree-like" variants
- `mapbox::apply_visitor(visitor, myVariant)` - to invoke a custom visitor on the variant's underlying type
- `mapbox::get<T>()` - 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


Expand All @@ -34,7 +34,7 @@ struct Error {
You can represent this at type level using a variant which is either an `Error` or a `Result`:

```c++
using Response = variant<Error, Result>;
using Response = mapbox::variant<Error, Result>;

Response makeRequest() {
return Error{501, "Not Implemented"};
Expand Down Expand Up @@ -87,7 +87,7 @@ struct Object { unordered_map<string, ?> 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.
For these use cases Variant provides a `mapbox::recursive_wrapper` helper type which lets you express recursive Variants.

```c++
struct String { string value; };
Expand All @@ -100,7 +100,8 @@ struct Null { };
struct Array;
struct Object;

using Value = variant<String, Number, True, False, Null, recursive_wrapper<Array>, recursive_wrapper<Object>>;
using Value = mapbox::variant<String, Number, True, False, Null,
mapbox::recursive_wrapper<Array>, mapbox::recursive_wrapper<Object>>;

struct Array {
vector<Value> values;
Expand Down Expand Up @@ -134,13 +135,13 @@ json.match([] (Null) { print("null"); },
...);
```

To summarize: use `recursive_wrapper` to represent recursive "tree-like" representations:
To summarize: use `mapbox::recursive_wrapper` to represent recursive "tree-like" representations:

```c++
struct Empty { };
struct Node;

using Tree = variant<Empty, recursive_wrapper<Node>>;
using Tree = mapbox::variant<Empty, mapbox::recursive_wrapper<Node>>;

struct Node {
uint64_t value;
Expand All @@ -154,12 +155,12 @@ We recommend creating a new type for all but basic variant usage:

```c++
// the compiler can't tell the following two apart
using APIResult = variant<Error, Result>;
using FilesystemResult = variant<Error, Result>;
using APIResult = mapbox::variant<Error, Result>;
using FilesystemResult = mapbox::variant<Error, Result>;

// new type
struct APIResult : variant<Error, Result> {
using Base = variant<Error, Result>;
struct APIResult : mapbox::variant<Error, Result> {
using Base = mapbox::variant<Error, Result>;
using Base::Base;
}
```
Expand Down Expand Up @@ -245,6 +246,8 @@ On Windows run `scripts/build-local.bat`.
* Old versions of the code needed visitors to derive from `static_visitor`.
This is not needed any more and marked as deprecated. The `static_visitor`
class will be removed in future versions.
* The `mapbox::util` namespace is deprecated and will be removed in a future
version. See https://github.com/mapbox/variant/issues/104.


## Benchmarks
Expand Down
2 changes: 2 additions & 0 deletions include/mapbox/optional.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@
#include <mapbox/variant.hpp>

namespace mapbox {

inline
namespace util {

template <typename T>
Expand Down
2 changes: 2 additions & 0 deletions include/mapbox/recursive_wrapper.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@
#include <utility>

namespace mapbox {

inline
namespace util {

template <typename T>
Expand Down
2 changes: 2 additions & 0 deletions include/mapbox/variant.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,8 @@
#define VARIANT_VERSION (VARIANT_MAJOR_VERSION * 100000) + (VARIANT_MINOR_VERSION * 100) + (VARIANT_PATCH_VERSION)

namespace mapbox {

inline
namespace util {

// XXX This should derive from std::logic_error instead of std::runtime_error.
Expand Down
2 changes: 2 additions & 0 deletions include/mapbox/variant_io.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@
#include <mapbox/variant.hpp>

namespace mapbox {

inline
namespace util {

namespace detail {
Expand Down
2 changes: 2 additions & 0 deletions include/mapbox/variant_visitor.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
#define MAPBOX_UTIL_VARIANT_VISITOR_HPP

namespace mapbox {

inline
namespace util {

template <typename... Fns>
Expand Down