embind: Add helper for registering a std::optional type.

site/source/docs/porting/connecting_cpp_and_javascript/embind.rst

@@ -925,14 +925,15 @@ Out of the box, *embind* provides converters for many standard C++ types:
 +---------------------+--------------------------------------------------------------------+
 
 For convenience, *embind* provides factory functions to register
-``std::vector<T>`` (:cpp:func:`register_vector`) and ``std::map<K, V>``
-(:cpp:func:`register_map`) types:
+``std::vector<T>`` (:cpp:func:`register_vector`), ``std::map<K, V>``
+(:cpp:func:`register_map`), and ``std::optional<T>`` (:cpp:func:`register_optional`) types:
 
 .. code:: cpp
 
     EMSCRIPTEN_BINDINGS(stl_wrappers) {
         register_vector<int>("VectorInt");
         register_map<int,int>("MapIntInt");
+        register_map<std::string>("OptionalString");
     }
 
 A full example is shown below:
@@ -942,6 +943,7 @@ A full example is shown below:
     #include <emscripten/bind.h>
     #include <string>
     #include <vector>
+    #include <optional>
 
     using namespace emscripten;
 
@@ -956,13 +958,20 @@ A full example is shown below:
       return m;
     }
 
+    std::optional<std::string> returnOptionalData() {
+      return "hello";
+    }
+
     EMSCRIPTEN_BINDINGS(module) {
       function("returnVectorData", &returnVectorData);
       function("returnMapData", &returnMapData);
+      function("returnOptionalData", &returnOptionalData);
 
-      // register bindings for std::vector<int> and std::map<int, std::string>.
+      // register bindings for std::vector<int>, std::map<int, std::string>, and
+      // std::optional<std::string>.
       register_vector<int>("vector<int>");
       register_map<int, std::string>("map<int, string>");
+      register_optional<std::string>("optional<string>");
     }
 
 
@@ -1009,6 +1018,12 @@ The following JavaScript can be used to interact with the above C++.
     // reset the value at the given index position
     retMap.set(10, "OtherValue");
 
+    // Using an optional<std::string>.
+    var optional = Module['returnOptionalData']();
+    if (optional.hasValue()) {
+        console.log(optional.value());
+    }
+
 
 TypeScript Definitions
 ======================

system/include/emscripten/bind.h

@@ -23,6 +23,13 @@
 #include <emscripten/val.h>
 #include <emscripten/wire.h>
 
+#ifdef __has_include
+#if __has_include(<optional>) && __cplusplus >= 201703L
+#include <optional>
+#define EMSCRIPTEN_HAS_OPTIONAL 1
+#endif
+#endif
+
 #if __has_feature(leak_sanitizer) || __has_feature(address_sanitizer)
 #include <sanitizer/lsan_interface.h>
 #endif
@@ -1906,6 +1913,36 @@ class_<std::vector<T>> register_vector(const char* name) {
         ;
 }
 
+////////////////////////////////////////////////////////////////////////////////
+// Optional
+////////////////////////////////////////////////////////////////////////////////
+
+#if defined(EMSCRIPTEN_HAS_OPTIONAL)
+namespace internal {
+
+template<typename T>
+struct OptionalAccess {
+    static bool has_value(const std::optional<T>& o) {
+        return o.has_value();
+    }
+
+    static T value(const std::optional<T> optional) {
+        return optional.value();
+    }
+};
+
+} // end namespace internal
+
+template<typename T>
+class_<std::optional<T>> register_optional(const char* name) {
+    return class_<std::optional<T>>(name)
+        .constructor<T>()
+        .function("hasValue", &internal::OptionalAccess<T>::has_value)
+        .function("value", &internal::OptionalAccess<T>::value)
+        ;
+}
+#endif
+
 ////////////////////////////////////////////////////////////////////////////////
 // MAPS
 ////////////////////////////////////////////////////////////////////////////////

test/embind/embind.test.js

@@ -1186,6 +1186,28 @@ module({
        });
     });
 
+    BaseFixture.extend("optional", function() {
+        if (!("embind_test_return_optional_string_with_value" in cm)) {
+            return;
+        }
+        test("std::optional returns works with value", function() {
+            var optional = cm.embind_test_return_optional_string_with_value();
+
+            assert.equal(true, optional.hasValue());
+            assert.equal("hello", optional.value());
+
+            optional.delete();
+        });
+
+        test("std::optional returns works with empty value", function() {
+            var optional = cm.embind_test_return_optional_string_empty();
+
+            assert.equal(false, optional.hasValue());
+
+            optional.delete();
+        });
+    });
+
     BaseFixture.extend("functors", function() {
         test("can get and call function ptrs", function() {
             var ptr = cm.emval_test_get_function_ptr();

test/embind/embind_test.cpp

@@ -10,6 +10,10 @@
 #include <emscripten/heap.h>
 #include <emscripten/em_asm.h>
 
+#if defined(EMSCRIPTEN_HAS_OPTIONAL)
+#include <optional>
+#endif
+
 using namespace emscripten;
 
 val emval_test_mallinfo() {
@@ -1282,6 +1286,16 @@ void test_string_with_vec(const std::string& p1, std::vector<std::string>& v1) {
     printf("%s\n", p1.c_str());
 }
 
+#if defined(EMSCRIPTEN_HAS_OPTIONAL)
+std::optional<std::string> embind_test_return_optional_string_with_value() {
+    return "hello";
+}
+
+std::optional<std::string> embind_test_return_optional_string_empty() {
+    return {};
+}
+#endif
+
 val embind_test_getglobal() {
     return val::global();
 }
@@ -2278,6 +2292,12 @@ EMSCRIPTEN_BINDINGS(tests) {
 
     function("test_string_with_vec", &test_string_with_vec);
 
+#if defined(EMSCRIPTEN_HAS_OPTIONAL)
+    register_optional<std::string>("OptionalString");
+    function("embind_test_return_optional_string_with_value", &embind_test_return_optional_string_with_value);
+    function("embind_test_return_optional_string_empty", &embind_test_return_optional_string_empty);
+#endif
+
     register_map<std::string, int>("StringIntMap");
     function("embind_test_get_string_int_map", embind_test_get_string_int_map);