refactor(embind): split enum and string_enum classes

Author: FelixNumworks

site/source/docs/api_reference/bind.h.rst

@@ -804,12 +804,11 @@ Enums
       A typedef of ``EnumType`` (a typename for the class).
 
 
-   .. cpp:function::  enum_(const char* name, bool asString = false)
+   .. cpp:function::  enum_(const char* name)
 
       Constructor.
 
       :param const char* name:
-      :param bool asString: *Experimental.* If true, the enum values are represented by plain strings in JavaScript, which is handy for basic operations like comparison and serialization.
 
 
    .. cpp:function::  enum_& value(const char* name, EnumType value)
@@ -821,6 +820,37 @@ Enums
       :returns: A reference to the current object. This allows chaining of multiple enum values in the :cpp:func:`EMSCRIPTEN_BINDINGS` block.
 
 
+.. cpp:class:: string_enum_
+
+   .. code-block:: cpp
+
+      //prototype
+      template<typename EnumType>
+      class string_enum_
+
+   Registers an enum, just like :cpp:class:`enum_`, but here the values are represented as plain strings in JavaScript. This is closer to how typescript implements enums, and is handier for basic operations like comparison and serialization. See :ref:`embind-enums` for more information.
+
+
+   .. cpp:type:: enum_type
+
+      A typedef of ``EnumType`` (a typename for the class).
+
+
+   .. cpp:function::  string_enum_(const char* name)
+
+      Constructor.
+
+      :param const char* name:
+
+
+   .. cpp:function::  string_enum_& value(const char* name, EnumType value)
+
+      Registers an enum value.
+
+      :param const char* name: The name of the enumerated value.
+      :param EnumType value: The type of the enumerated value.
+      :returns: A reference to the current object. This allows chaining of multiple enum values in the :cpp:func:`EMSCRIPTEN_BINDINGS` block.
+
 
 Constants
 =========

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

@@ -825,21 +825,27 @@ type.
     Module.OldStyle.ONE;
     Module.NewStyle.TWO;
 
-If you set the `asString` parameter to `true` when registering the enum, the enum values will be represented as plain strings in JavaScript.
+You can alternatively use the :cpp:class:`string_enum_` class to register your enum values. In this case, they will be represented as plain strings in JavaScript. This is closer to how typescript implements enums, and is handier for basic operations like comparison and serialization.
 
 .. code:: cpp
 
-    EMSCRIPTEN_BINDINGS(my_enum_example) {
-        enum_<MyEnum>("MyEnum", true)
+    EMSCRIPTEN_BINDINGS(my_string_enum_example) {
+        string_enum_<MyEnum>("MyEnum")
             .value("ONE", MyEnum::ONE)
             .value("TWO", MyEnum::TWO)
             ;
     }
 
+You can still access enumeration values through a map registered in the Module, but you can also just use the value strings.
+
 .. code:: javascript
 
     Module.MyEnum.ONE === "ONE"; // true
 
+    const foo = function(enumValue) { /* ... */ };
+    foo(Module.MyEnum.TWO);
+    foo("TWO"); // also works
+
 .. _embind-constants:
 
 Constants

src/lib/libembind.js

@@ -2199,68 +2199,77 @@ var LibraryEmbind = {
   _embind_register_enum__docs: '/** @suppress {globalThis} */',
   _embind_register_enum__deps: ['$exposePublicSymbol', '$enumReadValueFromPointer',
     '$AsciiToString', '$registerType'],
-  _embind_register_enum: (rawType, name, size, isSigned, asString) => {
+  _embind_register_enum: (rawType, name, size, isSigned) => {
     name = AsciiToString(name);
 
-    if (asString) {
-      var valuesMap = {};
-      var reverseMap = {};
-      var keysMap = {};
-
-      registerType(rawType, {
-        name: name,
-        valuesMap,
-        reverseMap,
-        keysMap,
-        asString,
-        fromWireType: function(c) {
-          return this.reverseMap[c];
-        },
-        toWireType: function(destructors, c) {
-          return this.valuesMap[c];
-        },
-        readValueFromPointer: enumReadValueFromPointer(name, size, isSigned),
-        destructorFunction: null,
-      });
-      exposePublicSymbol(name, keysMap);
-      // Just exposes a simple dict. argCount is meaningless here,
-      delete Module[name].argCount;
-    } else {
-      function ctor() {}
-      ctor.values = {};
-
-      registerType(rawType, {
-        name,
-        constructor: ctor,
-        fromWireType: function(c) {
-          return this.constructor.values[c];
-        },
-        toWireType: (destructors, c) => c.value,
-        readValueFromPointer: enumReadValueFromPointer(name, size, isSigned),
-        destructorFunction: null,
-      });
-      exposePublicSymbol(name, ctor);
-    }
+    function ctor() {}
+    ctor.values = {};
+
+    registerType(rawType, {
+      name,
+      constructor: ctor,
+      fromWireType: function(c) {
+        return this.constructor.values[c];
+      },
+      toWireType: (destructors, c) => c.value,
+      readValueFromPointer: enumReadValueFromPointer(name, size, isSigned),
+      destructorFunction: null,
+    });
+    exposePublicSymbol(name, ctor);
   },
 
   _embind_register_enum_value__deps: ['$createNamedFunction', '$AsciiToString', '$requireRegisteredType'],
   _embind_register_enum_value: (rawEnumType, name, enumValue) => {
     var enumType = requireRegisteredType(rawEnumType, 'enum');
     name = AsciiToString(name);
 
-    if (enumType.asString) {
-      enumType.valuesMap[name] = enumValue;
-      enumType.reverseMap[enumValue] = name;
-      enumType.keysMap[name] = name;
-    } else {
-      var Enum = enumType.constructor;
-      var Value = Object.create(enumType.constructor.prototype, {
-        value: {value: enumValue},
-        constructor: {value: createNamedFunction(`${enumType.name}_${name}`, function() {})},
-      });
-      Enum.values[enumValue] = Value;
-      Enum[name] = Value;
-    }
+    var Enum = enumType.constructor;
+    var Value = Object.create(enumType.constructor.prototype, {
+      value: {value: enumValue},
+      constructor: {value: createNamedFunction(`${enumType.name}_${name}`, function() {})},
+    });
+    Enum.values[enumValue] = Value;
+    Enum[name] = Value;
+  },
+
+  _embind_register_string_enum__docs: '/** @suppress {globalThis} */',
+  _embind_register_string_enum__deps: ['$exposePublicSymbol', '$enumReadValueFromPointer',
+    '$AsciiToString', '$registerType'],
+  _embind_register_string_enum: (rawType, name, size, isSigned) => {
+    name = AsciiToString(name);
+
+    // Use a two way map to enhance speed of conversions.
+    var valuesMap = {}; // "Name" -> 1
+    var reverseMap = {}; // 1 -> "Name"
+    // Only expose the names to Js.
+    var keysMap = {}; // "Name" -> "Name"
+
+    registerType(rawType, {
+      name: name,
+      valuesMap,
+      reverseMap,
+      keysMap,
+      fromWireType: function(c) {
+        return this.reverseMap[c];
+      },
+      toWireType: function(destructors, c) {
+        return this.valuesMap[c];
+      },
+      readValueFromPointer: enumReadValueFromPointer(name, size, isSigned),
+      destructorFunction: null,
+    });
+    exposePublicSymbol(name, keysMap);
+    // Just exposes a simple dict. argCount is meaningless here,
+    delete Module[name].argCount;
+  },
+
+  _embind_register_string_enum_value__deps: ['$AsciiToString', '$requireRegisteredType'],
+  _embind_register_string_enum_value: (rawEnumType, name, enumValue) => {
+    var enumType = requireRegisteredType(rawEnumType, 'string_enum');
+    name = AsciiToString(name);
+    enumType.valuesMap[name] = enumValue;
+    enumType.reverseMap[enumValue] = name;
+    enumType.keysMap[name] = name;
   },
 
   _embind_register_constant__deps: ['$AsciiToString', '$whenDependentTypesAreResolved'],

src/lib/libembind_gen.js

@@ -723,9 +723,9 @@ var LibraryEmbind = {
   // Stub function. This is called a when extending an object and not needed for TS generation.
   _embind_create_inheriting_constructor: (constructorName, wrapperType, properties) => {},
   _embind_register_enum__deps: ['$AsciiToString', '$EnumDefinition', '$moduleDefinitions'],
-  _embind_register_enum: function(rawType, name, size, isSigned, asString) {
+  _embind_register_enum: function(rawType, name, size, isSigned) {
     name = AsciiToString(name);
-    const enumDef = new EnumDefinition(rawType, name, asString);
+    const enumDef = new EnumDefinition(rawType, name, false);
     registerType(rawType, enumDef);
     moduleDefinitions.push(enumDef);
   },
@@ -735,6 +735,20 @@ var LibraryEmbind = {
     const enumDef = requireRegisteredType(rawEnumType, name);
     enumDef.items.push([name, enumValue]);
   },
+  // String enums share almost the same structure as regular enums
+  _embind_register_string_enum__deps: ['$AsciiToString', '$EnumDefinition', '$moduleDefinitions'],
+  _embind_register_string_enum: function(rawType, name, size, isSigned) {
+    name = AsciiToString(name);
+    const enumDef = new EnumDefinition(rawType, name, true);
+    registerType(rawType, enumDef);
+    moduleDefinitions.push(enumDef);
+  },
+  _embind_register_string_enum_value__deps: ['$AsciiToString', '$requireRegisteredType'],
+  _embind_register_string_enum_value: function(rawEnumType, name, enumValue) {
+    name = AsciiToString(name);
+    const enumDef = requireRegisteredType(rawEnumType, name);
+    enumDef.items.push([name, enumValue]);
+  },
   _embind_register_constant__deps: ['$AsciiToString', '$ConstantDefinition', '$whenDependentTypesAreResolved', '$moduleDefinitions'],
   _embind_register_constant: function(name, typeId, value) {
     name = AsciiToString(name);

src/lib/libsigs.js

@@ -296,7 +296,7 @@ sigs = {
   _embind_register_class_property__sig: 'vpppppppppp',
   _embind_register_constant__sig: 'vppd',
   _embind_register_emval__sig: 'vp',
-  _embind_register_enum__sig: 'vpppii',
+  _embind_register_enum__sig: 'vpppi',
   _embind_register_enum_value__sig: 'vppi',
   _embind_register_float__sig: 'vppp',
   _embind_register_function__sig: 'vpippppii',
@@ -306,6 +306,8 @@ sigs = {
   _embind_register_smart_ptr__sig: 'vpppipppppppp',
   _embind_register_std_string__sig: 'vpp',
   _embind_register_std_wstring__sig: 'vppp',
+  _embind_register_string_enum__sig: 'vpppi',
+  _embind_register_string_enum_value__sig: 'vppi',
   _embind_register_user_type__sig: 'vpp',
   _embind_register_value_array__sig: 'vpppppp',
   _embind_register_value_array_element__sig: 'vppppppppp',

system/include/emscripten/bind.h

@@ -228,8 +228,13 @@ void _embind_register_enum(
     TYPEID enumType,
     const char* name,
     size_t size,
-    bool isSigned,
-    bool asString);
+    bool isSigned);
+
+void _embind_register_string_enum(
+    TYPEID enumType,
+    const char* name,
+    size_t size,
+    bool isSigned);
 
 void _embind_register_smart_ptr(
     TYPEID pointerType,
@@ -250,6 +255,11 @@ void _embind_register_enum_value(
     const char* valueName,
     GenericEnumValue value);
 
+void _embind_register_string_enum_value(
+    TYPEID enumType,
+    const char* valueName,
+    GenericEnumValue value);
+
 void _embind_register_constant(
     const char* name,
     TYPEID constantType,
@@ -2175,8 +2185,7 @@ class enum_ {
             internal::TypeID<EnumType>::get(),
             name,
             sizeof(EnumType),
-            std::is_signed<typename std::underlying_type<EnumType>::type>::value,
-            asString);
+            std::is_signed<typename std::underlying_type<EnumType>::type>::value);
     }
 
     enum_& value(const char* name, EnumType value) {
@@ -2193,6 +2202,39 @@ class enum_ {
     }
 };
 
+////////////////////////////////////////////////////////////////////////////////
+// STRING ENUMS
+////////////////////////////////////////////////////////////////////////////////
+
+template<typename EnumType>
+class string_enum_ {
+public:
+    typedef EnumType enum_type;
+
+    string_enum_(const char* name) {
+        using namespace internal;
+        _embind_register_string_enum(
+            internal::TypeID<EnumType>::get(),
+            name,
+            sizeof(EnumType),
+            std::is_signed<typename std::underlying_type<EnumType>::type>::value);
+    }
+
+    string_enum_& value(const char* name, EnumType value) {
+        using namespace internal;
+        // TODO: there's still an issue here.
+        // if EnumType is an unsigned long, then JS may receive it as a signed long
+        static_assert(sizeof(value) <= sizeof(internal::GenericEnumValue), "enum type must fit in a GenericEnumValue");
+
+        _embind_register_string_enum_value(
+            internal::TypeID<EnumType>::get(),
+            name,
+            static_cast<internal::GenericEnumValue>(value));
+        return *this;
+    }
+};
+
+
 ////////////////////////////////////////////////////////////////////////////////
 // CONSTANTS
 ////////////////////////////////////////////////////////////////////////////////

test/embind/embind_test.cpp

@@ -2356,7 +2356,7 @@ EMSCRIPTEN_BINDINGS(tests) {
     ;
   function("emval_test_take_and_return_EnumClass", &emval_test_take_and_return_EnumClass);
 
-  enum_<EnumStr>("EnumStr", true)
+  string_enum_<EnumStr>("EnumStr")
     .value("ONE", EnumStr::ONE)
     .value("TWO", EnumStr::TWO)
     ;
@@ -2416,7 +2416,7 @@ EMSCRIPTEN_BINDINGS(tests) {
 
   register_map<std::string, int>("StringIntMap");
   function("embind_test_get_string_int_map", embind_test_get_string_int_map);
-    
+
   register_map<int, std::string, std::greater<int>>("IntStringMapGreater");
   function("embind_test_get_int_string_greater_map", embind_test_get_int_string_greater_map);
 

test/other/embind_tsgen.cpp

@@ -186,7 +186,7 @@ EMSCRIPTEN_BINDINGS(Test) {
       .value("valueOne", Bar::kValueOne)
       .value("valueTwo", Bar::kValueTwo)
       .value("valueThree", Bar::kValueThree);
-  enum_<Baz>("Baz", true)
+  string_enum_<Baz>("Baz")
       .value("valueA", Baz::kValueA)
       .value("valueB", Baz::kValueB)
       .value("valueC", Baz::kValueC);

test/test_other.py

@@ -15056,7 +15056,7 @@ def test_embind_negative_enum_values(self):
           .value("neg", value::neg)
           .value("zero", value::zero)
           .value("pos", value::pos);
-        enum_<otherValue>("valueStr", true)
+        string_enum_<otherValue>("valueStr")
           .value("neg", otherValue::neg)
           .value("zero", otherValue::zero)
           .value("pos", otherValue::pos);