[core] make style/conversion.hpp implementation private

22 files changed, 335 insertions, 393 deletions

diff --git a/include/mbgl/style/conversion.hpp b/include/mbgl/style/conversion.hpp
index 71c2cec237..2c83d1561b 100644
--- a/include/mbgl/style/conversion.hpp
+++ b/include/mbgl/style/conversion.hpp
@@ -1,306 +1,26 @@
 #pragma once
 
-#include <mbgl/util/optional.hpp>
-#include <mbgl/util/feature.hpp>
-#include <mbgl/util/geojson.hpp>
-
 #include <string>
 
 namespace mbgl {
 namespace style {
 namespace conversion {
 
-/*
-   The `conversion` namespace defines conversions from JSON structures conforming to the schema defined by
-   the Mapbox Style Specification, to the various C++ types that form the C++ model of that domain:
-
-       * `std::unique_ptr<Source>`
-       * `std::unique_ptr<Layer>`
-       * `Filter`
-       * `PropertyValue<T>`
-
-   A single template function serves as the public interface:
-
-       template <class T>
-       optional<T> convert(const Convertible& input, Error& error);
-
-   Where `T` is one of the above types. If the conversion fails, the result is empty, and the
-   error parameter includes diagnostic text suitable for presentation to a library user. Otherwise,
-   a filled optional is returned.
-
-   `Convertible` is a type that encapsulates a special form of polymorphism over various underlying types that
-   can serve as input to the conversion algorithm. For instance, on macOS, we need to support
-   conversion from both RapidJSON types, and a JSON structure represented with `NSArray`/`NSDictionary`/etc.
-   On Qt, we need to support conversion from RapidJSON types and QVariant.
-
-   We don't want to use traditional forms of polymorphism to accomplish this:
-
-     * Compile time polymorphism using a template parameter for the actual value type leads to
-       excessive code bloat and long compile times.
-     * Runtime polymorphism using virtual methods requires extra heap allocation and ubiquitous
-       use of std::unique_ptr, unsuitable for this performance-sensitive code.
-
-   Therefore, we're using a custom implementation of runtime polymorphism where we manually create and
-   dispatch through a table of function pointers (vtable), while keeping the storage for any of the possible
-   underlying types inline on the stack, using `std::aligned_storage`.
-
-   For a given underlying type T, an explicit specialization of `ConversionTraits<T>` must be provided. This
-   specialization must provide the following static methods:
-
-      * `isUndefined(v)` -- returns a boolean indication whether `v` is undefined or a JSON null
-
-      * `isArray(v)` -- returns a boolean indicating whether `v` represents a JSON array
-      * `arrayLength(v)` -- called only if `isArray(v)`; returns a size_t length
-      * `arrayMember(v)` -- called only if `isArray(v)`; returns `V` or `V&`
-
-      * `isObject(v)` -- returns a boolean indicating whether `v` represents a JSON object
-      * `objectMember(v, name)` -- called only if `isObject(v)`; `name` is `const char *`; return value:
-         * is true when evaluated in a boolean context iff the named member exists
-         * is convertable to a `V` or `V&` when dereferenced
-      * `eachMember(v, [] (const std::string&, const V&) -> optional<Error> {...})` -- called
-         only if `isObject(v)`; calls the provided lambda once for each key and value of the object;
-         short-circuits if any call returns an `Error`
-
-      * `toBool(v)` -- returns `optional<bool>`, absence indicating `v` is not a JSON boolean
-      * `toNumber(v)` -- returns `optional<float>`, absence indicating `v` is not a JSON number
-      * `toDouble(v)` -- returns `optional<double>`, absence indicating `v` is not a JSON number
-      * `toString(v)` -- returns `optional<std::string>`, absence indicating `v` is not a JSON string
-      * `toValue(v)` -- returns `optional<Value>`, a variant type, for generic conversion,
-        absence indicating `v` is not a boolean, number, or string. Numbers should be converted to
-        unsigned integer, signed integer, or floating point, in descending preference.
-
-   In addition, the type T must be move-constructable. And finally, `Convertible::Storage`, a typedef for
-   `std::aligned_storage_t`, must be large enough to satisfy the memory requirements for any of the
-   possible underlying types. (A static assert will fail if this is not the case.)
-
-   `Convertible` itself is movable, but not copyable. A moved-from `Convertible` is in an invalid state;
-   you must not do anything with it except let it go out of scope.
-*/
+// This is a forward-declaration only header intended to minimize dependencies and to improve
+// compilation speed. In order to specialize implementations and get access to the actual
+// implementation, include <mbgl/style/conversion_impl.hpp>.
 
 struct Error { std::string message; };
 
 template <typename T>
 class ConversionTraits;
 
-class Convertible {
-public:
-    template <typename T>
-    Convertible(T&& value) : vtable(vtableForType<std::decay_t<T>>()) {
-        static_assert(sizeof(Storage) >= sizeof(std::decay_t<T>), "Storage must be large enough to hold value type");
-        new (static_cast<void*>(&storage)) std::decay_t<T>(std::forward<T>(value));
-    }
-
-    Convertible(Convertible&& v)
-        : vtable(v.vtable)
-    {
-        if (vtable) {
-            vtable->move(std::move(v.storage), this->storage);
-        }
-    }
-
-    ~Convertible() {
-        if (vtable) {
-            vtable->destroy(storage);
-        }
-    }
-
-    Convertible& operator=(Convertible&& v) {
-        if (vtable) {
-            vtable->destroy(storage);
-        }
-        vtable = v.vtable;
-        if (vtable) {
-            vtable->move(std::move(v.storage), this->storage);
-        }
-        v.vtable = nullptr;
-        return *this;
-    }
-
-    Convertible()                              = delete;
-    Convertible(const Convertible&)            = delete;
-    Convertible& operator=(const Convertible&) = delete;
-
-    friend inline bool isUndefined(const Convertible& v) {
-        assert(v.vtable);
-        return v.vtable->isUndefined(v.storage);
-    }
-
-    friend inline bool isArray(const Convertible& v) {
-        assert(v.vtable);
-        return v.vtable->isArray(v.storage);
-    }
-
-    friend inline std::size_t arrayLength(const Convertible& v) {
-        assert(v.vtable);
-        return v.vtable->arrayLength(v.storage);
-    }
-
-    friend inline Convertible arrayMember(const Convertible& v, std::size_t i) {
-        assert(v.vtable);
-        return v.vtable->arrayMember(v.storage, i);
-    }
-
-    friend inline bool isObject(const Convertible& v) {
-        assert(v.vtable);
-        return v.vtable->isObject(v.storage);
-    }
-
-    friend inline optional<Convertible> objectMember(const Convertible& v, const char * name) {
-        assert(v.vtable);
-        return v.vtable->objectMember(v.storage, name);
-    }
-
-    friend inline optional<Error> eachMember(const Convertible& v, const std::function<optional<Error> (const std::string&, const Convertible&)>& fn) {
-        assert(v.vtable);
-        return v.vtable->eachMember(v.storage, fn);
-    }
-
-    friend inline optional<bool> toBool(const Convertible& v) {
-        assert(v.vtable);
-        return v.vtable->toBool(v.storage);
-    }
-
-    friend inline optional<float> toNumber(const Convertible& v) {
-        assert(v.vtable);
-        return v.vtable->toNumber(v.storage);
-    }
-
-    friend inline optional<double> toDouble(const Convertible& v) {
-        assert(v.vtable);
-        return v.vtable->toDouble(v.storage);
-    }
-
-    friend inline optional<std::string> toString(const Convertible& v) {
-        assert(v.vtable);
-        return v.vtable->toString(v.storage);
-    }
-
-    friend inline optional<Value> toValue(const Convertible& v) {
-        assert(v.vtable);
-        return v.vtable->toValue(v.storage);
-    }
-
-    friend inline optional<GeoJSON> toGeoJSON(const Convertible& v, Error& error) {
-        assert(v.vtable);
-        return v.vtable->toGeoJSON(v.storage, error);
-    }
-
-private:
-#if __ANDROID__
-    // Android:     JSValue* or mbgl::android::Value
-    using Storage = std::aligned_storage_t<32, 8>;
-#elif __QT__
-    // Qt:          JSValue* or QVariant
-    using Storage = std::aligned_storage_t<32, 8>;
-#else
-    // Node:        JSValue* or v8::Local<v8::Value>
-    // iOS/macOS:   JSValue* or id
-    using Storage = std::aligned_storage_t<8, 8>;
-#endif
-
-    struct VTable {
-        void (*move) (Storage&& src, Storage& dest);
-        void (*destroy) (Storage&);
-
-        bool (*isUndefined) (const Storage&);
-
-        bool        (*isArray)     (const Storage&);
-        std::size_t (*arrayLength) (const Storage&);
-        Convertible (*arrayMember) (const Storage&, std::size_t);
-
-        bool                  (*isObject)     (const Storage&);
-        optional<Convertible> (*objectMember) (const Storage&, const char *);
-        optional<Error>       (*eachMember)   (const Storage&, const std::function<optional<Error> (const std::string&, const Convertible&)>&);
-
-        optional<bool>        (*toBool)   (const Storage&);
-        optional<float>       (*toNumber) (const Storage&);
-        optional<double>      (*toDouble) (const Storage&);
-        optional<std::string> (*toString) (const Storage&);
-        optional<Value>       (*toValue)  (const Storage&);
-
-        // https://github.com/mapbox/mapbox-gl-native/issues/5623
-        optional<GeoJSON> (*toGeoJSON) (const Storage&, Error&);
-    };
-
-    // Extracted this function from the table below to work around a GCC bug with differing
-    // visibility settings for capturing lambdas: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=80947
-    template <typename T>
-    static auto vtableEachMember(const Storage& s, const std::function<optional<Error>(const std::string&, const Convertible&)>& fn) {
-        return ConversionTraits<T>::eachMember(reinterpret_cast<const T&>(s), [&](const std::string& k, T&& v) {
-            return fn(k, Convertible(std::move(v)));
-        });
-    }
-
-    template <typename T>
-    static VTable* vtableForType() {
-        using Traits = ConversionTraits<T>;
-        static VTable vtable = {
-            [] (Storage&& src, Storage& dest) {
-                auto srcValue = reinterpret_cast<T&&>(src);
-                new (static_cast<void*>(&dest)) T(std::move(srcValue));
-                srcValue.~T();
-            },
-            [] (Storage& s) {
-                reinterpret_cast<T&>(s).~T();
-            },
-            [] (const Storage& s) {
-                return Traits::isUndefined(reinterpret_cast<const T&>(s));
-            },
-            [] (const Storage& s) {
-                return Traits::isArray(reinterpret_cast<const T&>(s));
-            },
-            [] (const Storage& s) {
-                return Traits::arrayLength(reinterpret_cast<const T&>(s));
-            },
-            [] (const Storage& s, std::size_t i) {
-                return Convertible(Traits::arrayMember(reinterpret_cast<const T&>(s), i));
-            },
-            [] (const Storage& s) {
-                return Traits::isObject(reinterpret_cast<const T&>(s));
-            },
-            [] (const Storage& s, const char * key) {
-                optional<T> member = Traits::objectMember(reinterpret_cast<const T&>(s), key);
-                if (member) {
-                    return optional<Convertible>(Convertible(std::move(*member)));
-                } else {
-                    return optional<Convertible>();
-                }
-            },
-            vtableEachMember<T>,
-            [] (const Storage& s) {
-                return Traits::toBool(reinterpret_cast<const T&>(s));
-            },
-            [] (const Storage& s) {
-                return Traits::toNumber(reinterpret_cast<const T&>(s));
-            },
-            [] (const Storage& s) {
-                return Traits::toDouble(reinterpret_cast<const T&>(s));
-            },
-            [] (const Storage& s) {
-                return Traits::toString(reinterpret_cast<const T&>(s));
-            },
-            []  (const Storage& s) {
-                return Traits::toValue(reinterpret_cast<const T&>(s));
-            },
-            [] (const Storage& s, Error& err) {
-                return Traits::toGeoJSON(reinterpret_cast<const T&>(s), err);
-            }
-        };
-        return &vtable;
-    }
-
-    VTable* vtable;
-    Storage storage;
-};
+class Convertible;
 
 template <class T, class Enable = void>
 struct Converter;
 
-template <class T, class...Args>
-optional<T> convert(const Convertible& value, Error& error, Args&&...args) {
-    return Converter<T>()(value, error, std::forward<Args>(args)...);
-}
-
 } // namespace conversion
 } // namespace style
 } // namespace mbgl
+
diff --git a/include/mbgl/style/conversion/constant.hpp b/include/mbgl/style/conversion/constant.hpp
index 7d74ec42ce..40657528c4 100644
--- a/include/mbgl/style/conversion/constant.hpp
+++ b/include/mbgl/style/conversion/constant.hpp
@@ -1,6 +1,7 @@
 #pragma once
 
 #include <mbgl/style/conversion.hpp>
+#include <mbgl/style/types.hpp>
 #include <mbgl/util/color.hpp>
 #include <mbgl/util/enum.hpp>
 #include <mbgl/util/string.hpp>
@@ -30,21 +31,7 @@ struct Converter<std::string> {
 
 template <class T>
 struct Converter<T, typename std::enable_if_t<std::is_enum<T>::value>> {
-    optional<T> operator()(const Convertible& value, Error& error) const {
-        optional<std::string> string = toString(value);
-        if (!string) {
-            error.message = "value must be a string";
-            return nullopt;
-        }
-
-        const auto result = Enum<T>::toEnum(*string);
-        if (!result) {
-            error.message = "value must be a valid enumeration value";
-            return nullopt;
-        }
-
-        return *result;
-    }
+    optional<T> operator()(const Convertible& value, Error& error) const;
 };
 
 template <>
@@ -54,23 +41,7 @@ struct Converter<Color> {
 
 template <size_t N>
 struct Converter<std::array<float, N>> {
-    optional<std::array<float, N>> operator()(const Convertible& value, Error& error) const {
-        if (!isArray(value) || arrayLength(value) != N) {
-            error.message = "value must be an array of " + util::toString(N) + " numbers";
-            return nullopt;
-        }
-
-        std::array<float, N> result;
-        for (size_t i = 0; i < N; i++) {
-            optional<float> n = toNumber(arrayMember(value, i));
-            if (!n) {
-                error.message = "value must be an array of " + util::toString(N) + " numbers";
-                return nullopt;
-            }
-            result[i] = *n;
-        }
-        return result;
-    }
+    optional<std::array<float, N>> operator()(const Convertible& value, Error& error) const;
 };
 
 template <>
diff --git a/include/mbgl/style/conversion/coordinate.hpp b/include/mbgl/style/conversion/coordinate.hpp
index e11db5e32f..1346ed738a 100644
--- a/include/mbgl/style/conversion/coordinate.hpp
+++ b/include/mbgl/style/conversion/coordinate.hpp
@@ -2,6 +2,7 @@
 
 #include <mbgl/style/conversion.hpp>
 #include <mbgl/util/geo.hpp>
+#include <mbgl/util/optional.hpp>
 
 namespace mbgl {
 namespace style {
diff --git a/include/mbgl/style/conversion/custom_geometry_source_options.hpp b/include/mbgl/style/conversion/custom_geometry_source_options.hpp
index f0f505e54f..090e5b6239 100644
--- a/include/mbgl/style/conversion/custom_geometry_source_options.hpp
+++ b/include/mbgl/style/conversion/custom_geometry_source_options.hpp
@@ -2,6 +2,7 @@
 
 #include <mbgl/style/conversion.hpp>
 #include <mbgl/style/sources/custom_geometry_source.hpp>
+#include <mbgl/util/optional.hpp>
 
 namespace mbgl {
 namespace style {
diff --git a/include/mbgl/style/conversion/filter.hpp b/include/mbgl/style/conversion/filter.hpp
index 9daf6ea7a4..2d7ad0afc7 100644
--- a/include/mbgl/style/conversion/filter.hpp
+++ b/include/mbgl/style/conversion/filter.hpp
@@ -2,6 +2,7 @@
 
 #include <mbgl/style/filter.hpp>
 #include <mbgl/style/conversion.hpp>
+#include <mbgl/util/optional.hpp>
 
 namespace mbgl {
 namespace style {
diff --git a/include/mbgl/style/conversion/function.hpp b/include/mbgl/style/conversion/function.hpp
index 49825a3410..ba9acd7a3b 100644
--- a/include/mbgl/style/conversion/function.hpp
+++ b/include/mbgl/style/conversion/function.hpp
@@ -1,8 +1,8 @@
 #pragma once
 
 #include <mbgl/style/property_expression.hpp>
-#include <mbgl/style/conversion.hpp>
 #include <mbgl/style/conversion/constant.hpp>
+#include <mbgl/style/conversion.hpp>
 #include <mbgl/style/expression/expression.hpp>
 #include <mbgl/style/expression/value.hpp>
 
@@ -16,25 +16,7 @@ std::unique_ptr<expression::Expression> convertTokenStringToExpression(const std
 optional<std::unique_ptr<expression::Expression>> convertFunctionToExpression(expression::type::Type, const Convertible&, Error&, bool convertTokens);
 
 template <class T>
-optional<PropertyExpression<T>> convertFunctionToExpression(const Convertible& value, Error& error, bool convertTokens) {
-    auto expression = convertFunctionToExpression(expression::valueTypeToExpressionType<T>(), value, error, convertTokens);
-    if (!expression) {
-        return nullopt;
-    }
-
-    optional<T> defaultValue;
-
-    auto defaultValueValue = objectMember(value, "default");
-    if (defaultValueValue) {
-        defaultValue = convert<T>(*defaultValueValue, error);
-        if (!defaultValue) {
-            error.message = R"(wrong type for "default": )" + error.message;
-            return nullopt;
-        }
-    }
-
-    return PropertyExpression<T>(std::move(*expression), defaultValue);
-}
+optional<PropertyExpression<T>> convertFunctionToExpression(const Convertible& value, Error& error, bool convertTokens);
 
 } // namespace conversion
 } // namespace style
diff --git a/include/mbgl/style/conversion/geojson.hpp b/include/mbgl/style/conversion/geojson.hpp
index 403c5f953b..90c1d64197 100644
--- a/include/mbgl/style/conversion/geojson.hpp
+++ b/include/mbgl/style/conversion/geojson.hpp
@@ -1,7 +1,8 @@
 #pragma once
 
-#include <mbgl/style/conversion.hpp>
 #include <mbgl/util/geojson.hpp>
+#include <mbgl/style/conversion.hpp>
+#include <mbgl/util/optional.hpp>
 
 namespace mbgl {
 namespace style {
diff --git a/include/mbgl/style/conversion/geojson_options.hpp b/include/mbgl/style/conversion/geojson_options.hpp
index 3f625babb6..89511848dd 100644
--- a/include/mbgl/style/conversion/geojson_options.hpp
+++ b/include/mbgl/style/conversion/geojson_options.hpp
@@ -1,7 +1,8 @@
 #pragma once
 
-#include <mbgl/style/conversion.hpp>
 #include <mbgl/style/sources/geojson_source.hpp>
+#include <mbgl/style/conversion.hpp>
+#include <mbgl/util/optional.hpp>
 
 namespace mbgl {
 namespace style {
diff --git a/include/mbgl/style/conversion/layer.hpp b/include/mbgl/style/conversion/layer.hpp
index 2df6c9e381..9cf019378b 100644
--- a/include/mbgl/style/conversion/layer.hpp
+++ b/include/mbgl/style/conversion/layer.hpp
@@ -2,6 +2,7 @@
 
 #include <mbgl/style/layer.hpp>
 #include <mbgl/style/conversion.hpp>
+#include <mbgl/util/optional.hpp>
 
 #include <memory>
 
diff --git a/include/mbgl/style/conversion/light.hpp b/include/mbgl/style/conversion/light.hpp
index 289fca2e31..2f6f8628b8 100644
--- a/include/mbgl/style/conversion/light.hpp
+++ b/include/mbgl/style/conversion/light.hpp
@@ -2,6 +2,7 @@
 
 #include <mbgl/style/light.hpp>
 #include <mbgl/style/conversion.hpp>
+#include <mbgl/util/optional.hpp>
 
 namespace mbgl {
 namespace style {
diff --git a/include/mbgl/style/conversion/position.hpp b/include/mbgl/style/conversion/position.hpp
index 044c45862d..10db5c6ec1 100644
--- a/include/mbgl/style/conversion/position.hpp
+++ b/include/mbgl/style/conversion/position.hpp
@@ -1,7 +1,8 @@
 #pragma once
 
-#include <mbgl/style/conversion.hpp>
 #include <mbgl/style/position.hpp>
+#include <mbgl/style/conversion.hpp>
+#include <mbgl/util/optional.hpp>
 
 namespace mbgl {
 namespace style {
diff --git a/include/mbgl/style/conversion/property_value.hpp b/include/mbgl/style/conversion/property_value.hpp
index fa6752867b..f6f36db983 100644
--- a/include/mbgl/style/conversion/property_value.hpp
+++ b/include/mbgl/style/conversion/property_value.hpp
@@ -1,9 +1,9 @@
 #pragma once
 
 #include <mbgl/style/property_value.hpp>
-#include <mbgl/style/conversion.hpp>
 #include <mbgl/style/conversion/constant.hpp>
 #include <mbgl/style/conversion/function.hpp>
+#include <mbgl/style/conversion.hpp>
 #include <mbgl/style/expression/value.hpp>
 #include <mbgl/style/expression/is_constant.hpp>
 #include <mbgl/style/expression/is_expression.hpp>
@@ -16,53 +16,7 @@ namespace conversion {
 
 template <class T>
 struct Converter<PropertyValue<T>> {
-    optional<PropertyValue<T>> operator()(const Convertible& value, Error& error, bool allowDataExpressions, bool convertTokens) const {
-        using namespace mbgl::style::expression;
-
-        if (isUndefined(value)) {
-            return PropertyValue<T>();
-        }
-
-        optional<PropertyExpression<T>> expression;
-
-        if (isExpression(value)) {
-            ParsingContext ctx(valueTypeToExpressionType<T>());
-            ParseResult parsed = ctx.parseLayerPropertyExpression(value);
-            if (!parsed) {
-                error.message = ctx.getCombinedErrors();
-                return nullopt;
-            }
-            expression = PropertyExpression<T>(std::move(*parsed));
-        } else if (isObject(value)) {
-            expression = convertFunctionToExpression<T>(value, error, convertTokens);
-        } else {
-            optional<T> constant = convert<T>(value, error);
-            if (!constant) {
-                return nullopt;
-            }
-            return convertTokens ? maybeConvertTokens(*constant) : PropertyValue<T>(*constant);
-        }
-
-        if (!expression) {
-            return nullopt;
-        } else if (!allowDataExpressions && !(*expression).isFeatureConstant()) {
-            error.message = "data expressions not supported";
-            return nullopt;
-        } else if (!(*expression).isFeatureConstant() || !(*expression).isZoomConstant()) {
-            return { std::move(*expression) };
-        } else if ((*expression).getExpression().getKind() == Kind::Literal) {
-            optional<T> constant = fromExpressionValue<T>(
-                static_cast<const Literal&>((*expression).getExpression()).getValue());
-            if (!constant) {
-                return nullopt;
-            }
-            return PropertyValue<T>(*constant);
-        } else {
-            assert(false);
-            error.message = "expected a literal expression";
-            return nullopt;
-        }
-    }
+    optional<PropertyValue<T>> operator()(const Convertible& value, Error& error, bool allowDataExpressions, bool convertTokens) const;
 
     template <class S>
     PropertyValue<T> maybeConvertTokens(const S& t) const {
diff --git a/include/mbgl/style/conversion/source.hpp b/include/mbgl/style/conversion/source.hpp
index 2cf2e36da4..19bc1ce6b6 100644
--- a/include/mbgl/style/conversion/source.hpp
+++ b/include/mbgl/style/conversion/source.hpp
@@ -1,7 +1,8 @@
 #pragma once
 
-#include <mbgl/style/conversion.hpp>
 #include <mbgl/style/source.hpp>
+#include <mbgl/style/conversion.hpp>
+#include <mbgl/util/optional.hpp>
 
 #include <memory>
 
diff --git a/include/mbgl/style/conversion/tileset.hpp b/include/mbgl/style/conversion/tileset.hpp
index 1fb4acf70d..88661c358c 100644
--- a/include/mbgl/style/conversion/tileset.hpp
+++ b/include/mbgl/style/conversion/tileset.hpp
@@ -2,6 +2,7 @@
 
 #include <mbgl/util/tileset.hpp>
 #include <mbgl/style/conversion.hpp>
+#include <mbgl/util/optional.hpp>
 
 namespace mbgl {
 namespace style {
diff --git a/include/mbgl/style/conversion/transition_options.hpp b/include/mbgl/style/conversion/transition_options.hpp
index 0563f39ac3..a72d757d3c 100644
--- a/include/mbgl/style/conversion/transition_options.hpp
+++ b/include/mbgl/style/conversion/transition_options.hpp
@@ -2,6 +2,7 @@
 
 #include <mbgl/style/transition_options.hpp>
 #include <mbgl/style/conversion.hpp>
+#include <mbgl/util/optional.hpp>
 
 namespace mbgl {
 namespace style {
diff --git a/include/mbgl/style/conversion_impl.hpp b/include/mbgl/style/conversion_impl.hpp
new file mode 100644
index 0000000000..27b2ee1917
--- /dev/null
+++ b/include/mbgl/style/conversion_impl.hpp
@@ -0,0 +1,302 @@
+#pragma once
+
+#include <mbgl/style/conversion.hpp>
+#include <mbgl/util/optional.hpp>
+#include <mbgl/util/feature.hpp>
+#include <mbgl/util/geojson.hpp>
+
+#include <string>
+
+namespace mbgl {
+namespace style {
+namespace conversion {
+
+/*
+   The `conversion` namespace defines conversions from JSON structures conforming to the schema defined by
+   the Mapbox Style Specification, to the various C++ types that form the C++ model of that domain:
+
+       * `std::unique_ptr<Source>`
+       * `std::unique_ptr<Layer>`
+       * `Filter`
+       * `PropertyValue<T>`
+
+   A single template function serves as the public interface:
+
+       template <class T>
+       optional<T> convert(const Convertible& input, Error& error);
+
+   Where `T` is one of the above types. If the conversion fails, the result is empty, and the
+   error parameter includes diagnostic text suitable for presentation to a library user. Otherwise,
+   a filled optional is returned.
+
+   `Convertible` is a type that encapsulates a special form of polymorphism over various underlying types that
+   can serve as input to the conversion algorithm. For instance, on macOS, we need to support
+   conversion from both RapidJSON types, and a JSON structure represented with `NSArray`/`NSDictionary`/etc.
+   On Qt, we need to support conversion from RapidJSON types and QVariant.
+
+   We don't want to use traditional forms of polymorphism to accomplish this:
+
+     * Compile time polymorphism using a template parameter for the actual value type leads to
+       excessive code bloat and long compile times.
+     * Runtime polymorphism using virtual methods requires extra heap allocation and ubiquitous
+       use of std::unique_ptr, unsuitable for this performance-sensitive code.
+
+   Therefore, we're using a custom implementation of runtime polymorphism where we manually create and
+   dispatch through a table of function pointers (vtable), while keeping the storage for any of the possible
+   underlying types inline on the stack, using `std::aligned_storage`.
+
+   For a given underlying type T, an explicit specialization of `ConversionTraits<T>` must be provided. This
+   specialization must provide the following static methods:
+
+      * `isUndefined(v)` -- returns a boolean indication whether `v` is undefined or a JSON null
+
+      * `isArray(v)` -- returns a boolean indicating whether `v` represents a JSON array
+      * `arrayLength(v)` -- called only if `isArray(v)`; returns a size_t length
+      * `arrayMember(v)` -- called only if `isArray(v)`; returns `V` or `V&`
+
+      * `isObject(v)` -- returns a boolean indicating whether `v` represents a JSON object
+      * `objectMember(v, name)` -- called only if `isObject(v)`; `name` is `const char *`; return value:
+         * is true when evaluated in a boolean context iff the named member exists
+         * is convertable to a `V` or `V&` when dereferenced
+      * `eachMember(v, [] (const std::string&, const V&) -> optional<Error> {...})` -- called
+         only if `isObject(v)`; calls the provided lambda once for each key and value of the object;
+         short-circuits if any call returns an `Error`
+
+      * `toBool(v)` -- returns `optional<bool>`, absence indicating `v` is not a JSON boolean
+      * `toNumber(v)` -- returns `optional<float>`, absence indicating `v` is not a JSON number
+      * `toDouble(v)` -- returns `optional<double>`, absence indicating `v` is not a JSON number
+      * `toString(v)` -- returns `optional<std::string>`, absence indicating `v` is not a JSON string
+      * `toValue(v)` -- returns `optional<Value>`, a variant type, for generic conversion,
+        absence indicating `v` is not a boolean, number, or string. Numbers should be converted to
+        unsigned integer, signed integer, or floating point, in descending preference.
+
+   In addition, the type T must be move-constructable. And finally, `Convertible::Storage`, a typedef for
+   `std::aligned_storage_t`, must be large enough to satisfy the memory requirements for any of the
+   possible underlying types. (A static assert will fail if this is not the case.)
+
+   `Convertible` itself is movable, but not copyable. A moved-from `Convertible` is in an invalid state;
+   you must not do anything with it except let it go out of scope.
+*/
+
+template <typename T>
+class ConversionTraits;
+
+class Convertible {
+public:
+    template <typename T>
+    Convertible(T&& value) : vtable(vtableForType<std::decay_t<T>>()) {
+        static_assert(sizeof(Storage) >= sizeof(std::decay_t<T>), "Storage must be large enough to hold value type");
+        new (static_cast<void*>(&storage)) std::decay_t<T>(std::forward<T>(value));
+    }
+
+    Convertible(Convertible&& v)
+        : vtable(v.vtable)
+    {
+        if (vtable) {
+            vtable->move(std::move(v.storage), this->storage);
+        }
+    }
+
+    ~Convertible() {
+        if (vtable) {
+            vtable->destroy(storage);
+        }
+    }
+
+    Convertible& operator=(Convertible&& v) {
+        if (vtable) {
+            vtable->destroy(storage);
+        }
+        vtable = v.vtable;
+        if (vtable) {
+            vtable->move(std::move(v.storage), this->storage);
+        }
+        v.vtable = nullptr;
+        return *this;
+    }
+
+    Convertible()                              = delete;
+    Convertible(const Convertible&)            = delete;
+    Convertible& operator=(const Convertible&) = delete;
+
+    friend inline bool isUndefined(const Convertible& v) {
+        assert(v.vtable);
+        return v.vtable->isUndefined(v.storage);
+    }
+
+    friend inline bool isArray(const Convertible& v) {
+        assert(v.vtable);
+        return v.vtable->isArray(v.storage);
+    }
+
+    friend inline std::size_t arrayLength(const Convertible& v) {
+        assert(v.vtable);
+        return v.vtable->arrayLength(v.storage);
+    }
+
+    friend inline Convertible arrayMember(const Convertible& v, std::size_t i) {
+        assert(v.vtable);
+        return v.vtable->arrayMember(v.storage, i);
+    }
+
+    friend inline bool isObject(const Convertible& v) {
+        assert(v.vtable);
+        return v.vtable->isObject(v.storage);
+    }
+
+    friend inline optional<Convertible> objectMember(const Convertible& v, const char * name) {
+        assert(v.vtable);
+        return v.vtable->objectMember(v.storage, name);
+    }
+
+    friend inline optional<Error> eachMember(const Convertible& v, const std::function<optional<Error> (const std::string&, const Convertible&)>& fn) {
+        assert(v.vtable);
+        return v.vtable->eachMember(v.storage, fn);
+    }
+
+    friend inline optional<bool> toBool(const Convertible& v) {
+        assert(v.vtable);
+        return v.vtable->toBool(v.storage);
+    }
+
+    friend inline optional<float> toNumber(const Convertible& v) {
+        assert(v.vtable);
+        return v.vtable->toNumber(v.storage);
+    }
+
+    friend inline optional<double> toDouble(const Convertible& v) {
+        assert(v.vtable);
+        return v.vtable->toDouble(v.storage);
+    }
+
+    friend inline optional<std::string> toString(const Convertible& v) {
+        assert(v.vtable);
+        return v.vtable->toString(v.storage);
+    }
+
+    friend inline optional<Value> toValue(const Convertible& v) {
+        assert(v.vtable);
+        return v.vtable->toValue(v.storage);
+    }
+
+    friend inline optional<GeoJSON> toGeoJSON(const Convertible& v, Error& error) {
+        assert(v.vtable);
+        return v.vtable->toGeoJSON(v.storage, error);
+    }
+
+private:
+#if __ANDROID__
+    // Android:     JSValue* or mbgl::android::Value
+    using Storage = std::aligned_storage_t<32, 8>;
+#elif __QT__
+    // Qt:          JSValue* or QVariant
+    using Storage = std::aligned_storage_t<32, 8>;
+#else
+    // Node:        JSValue* or v8::Local<v8::Value>
+    // iOS/macOS:   JSValue* or id
+    using Storage = std::aligned_storage_t<8, 8>;
+#endif
+
+    struct VTable {
+        void (*move) (Storage&& src, Storage& dest);
+        void (*destroy) (Storage&);
+
+        bool (*isUndefined) (const Storage&);
+
+        bool        (*isArray)     (const Storage&);
+        std::size_t (*arrayLength) (const Storage&);
+        Convertible (*arrayMember) (const Storage&, std::size_t);
+
+        bool                  (*isObject)     (const Storage&);
+        optional<Convertible> (*objectMember) (const Storage&, const char *);
+        optional<Error>       (*eachMember)   (const Storage&, const std::function<optional<Error> (const std::string&, const Convertible&)>&);
+
+        optional<bool>        (*toBool)   (const Storage&);
+        optional<float>       (*toNumber) (const Storage&);
+        optional<double>      (*toDouble) (const Storage&);
+        optional<std::string> (*toString) (const Storage&);
+        optional<Value>       (*toValue)  (const Storage&);
+
+        // https://github.com/mapbox/mapbox-gl-native/issues/5623
+        optional<GeoJSON> (*toGeoJSON) (const Storage&, Error&);
+    };
+
+    // Extracted this function from the table below to work around a GCC bug with differing
+    // visibility settings for capturing lambdas: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=80947
+    template <typename T>
+    static auto vtableEachMember(const Storage& s, const std::function<optional<Error>(const std::string&, const Convertible&)>& fn) {
+        return ConversionTraits<T>::eachMember(reinterpret_cast<const T&>(s), [&](const std::string& k, T&& v) {
+            return fn(k, Convertible(std::move(v)));
+        });
+    }
+
+    template <typename T>
+    static VTable* vtableForType() {
+        using Traits = ConversionTraits<T>;
+        static VTable vtable = {
+            [] (Storage&& src, Storage& dest) {
+                auto srcValue = reinterpret_cast<T&&>(src);
+                new (static_cast<void*>(&dest)) T(std::move(srcValue));
+                srcValue.~T();
+            },
+            [] (Storage& s) {
+                reinterpret_cast<T&>(s).~T();
+            },
+            [] (const Storage& s) {
+                return Traits::isUndefined(reinterpret_cast<const T&>(s));
+            },
+            [] (const Storage& s) {
+                return Traits::isArray(reinterpret_cast<const T&>(s));
+            },
+            [] (const Storage& s) {
+                return Traits::arrayLength(reinterpret_cast<const T&>(s));
+            },
+            [] (const Storage& s, std::size_t i) {
+                return Convertible(Traits::arrayMember(reinterpret_cast<const T&>(s), i));
+            },
+            [] (const Storage& s) {
+                return Traits::isObject(reinterpret_cast<const T&>(s));
+            },
+            [] (const Storage& s, const char * key) {
+                optional<T> member = Traits::objectMember(reinterpret_cast<const T&>(s), key);
+                if (member) {
+                    return optional<Convertible>(Convertible(std::move(*member)));
+                } else {
+                    return optional<Convertible>();
+                }
+            },
+            vtableEachMember<T>,
+            [] (const Storage& s) {
+                return Traits::toBool(reinterpret_cast<const T&>(s));
+            },
+            [] (const Storage& s) {
+                return Traits::toNumber(reinterpret_cast<const T&>(s));
+            },
+            [] (const Storage& s) {
+                return Traits::toDouble(reinterpret_cast<const T&>(s));
+            },
+            [] (const Storage& s) {
+                return Traits::toString(reinterpret_cast<const T&>(s));
+            },
+            []  (const Storage& s) {
+                return Traits::toValue(reinterpret_cast<const T&>(s));
+            },
+            [] (const Storage& s, Error& err) {
+                return Traits::toGeoJSON(reinterpret_cast<const T&>(s), err);
+            }
+        };
+        return &vtable;
+    }
+
+    VTable* vtable;
+    Storage storage;
+};
+
+template <class T, class...Args>
+optional<T> convert(const Convertible& value, Error& error, Args&&...args) {
+    return Converter<T>()(value, error, std::forward<Args>(args)...);
+}
+
+} // namespace conversion
+} // namespace style
+} // namespace mbgl
diff --git a/include/mbgl/style/expression/assertion.hpp b/include/mbgl/style/expression/assertion.hpp
index 90da16b068..239cdf2ea6 100644
--- a/include/mbgl/style/expression/assertion.hpp
+++ b/include/mbgl/style/expression/assertion.hpp
@@ -1,8 +1,8 @@
 #pragma once
 
 #include <mbgl/style/expression/expression.hpp>
-#include <mbgl/style/conversion.hpp>
 #include <mbgl/style/expression/parsing_context.hpp>
+#include <mbgl/style/conversion.hpp>
 
 #include <memory>
 #include <vector>
diff --git a/include/mbgl/style/expression/case.hpp b/include/mbgl/style/expression/case.hpp
index 02dc3bc4c2..7cd007d3c7 100644
--- a/include/mbgl/style/expression/case.hpp
+++ b/include/mbgl/style/expression/case.hpp
@@ -1,8 +1,8 @@
 #pragma once
 
 #include <mbgl/style/expression/expression.hpp>
-#include <mbgl/style/conversion.hpp>
 #include <mbgl/style/expression/parsing_context.hpp>
+#include <mbgl/style/conversion.hpp>
 
 #include <memory>
 #include <vector>
diff --git a/include/mbgl/style/expression/coalesce.hpp b/include/mbgl/style/expression/coalesce.hpp
index cd60cee02e..c4216f234f 100644
--- a/include/mbgl/style/expression/coalesce.hpp
+++ b/include/mbgl/style/expression/coalesce.hpp
@@ -1,8 +1,8 @@
 #pragma once
 
 #include <mbgl/style/expression/expression.hpp>
-#include <mbgl/style/conversion.hpp>
 #include <mbgl/style/expression/parsing_context.hpp>
+#include <mbgl/style/conversion.hpp>
 
 #include <memory>
 #include <map>
diff --git a/include/mbgl/style/expression/compound_expression.hpp b/include/mbgl/style/expression/compound_expression.hpp
index ef10dadb55..b54720a258 100644
--- a/include/mbgl/style/expression/compound_expression.hpp
+++ b/include/mbgl/style/expression/compound_expression.hpp
@@ -1,10 +1,10 @@
 #pragma once
 
 #include <mbgl/style/expression/expression.hpp>
-#include <mbgl/style/conversion.hpp>
 #include <mbgl/style/expression/parsing_context.hpp>
 #include <mbgl/style/expression/type.hpp>
 #include <mbgl/style/expression/value.hpp>
+#include <mbgl/style/conversion.hpp>
 #include <mbgl/util/optional.hpp>
 
 #include <memory>
diff --git a/include/mbgl/style/expression/parsing_context.hpp b/include/mbgl/style/expression/parsing_context.hpp
index c19974a4f7..66014e33d4 100644
--- a/include/mbgl/style/expression/parsing_context.hpp
+++ b/include/mbgl/style/expression/parsing_context.hpp
@@ -7,6 +7,7 @@
 
 #include <iterator>
 #include <map>
+#include <unordered_map>
 #include <string>
 #include <vector>
 #include <memory>
diff --git a/include/mbgl/style/layer.hpp b/include/mbgl/style/layer.hpp
index e0f71d2689..3b7969ea79 100644
--- a/include/mbgl/style/layer.hpp
+++ b/include/mbgl/style/layer.hpp
@@ -3,6 +3,7 @@
 #include <mbgl/util/noncopyable.hpp>
 #include <mbgl/util/peer.hpp>
 #include <mbgl/util/immutable.hpp>
+#include <mbgl/util/optional.hpp>
 #include <mbgl/style/layer_type.hpp>
 #include <mbgl/style/types.hpp>
 #include <mbgl/style/conversion.hpp>