# bind.h (under-construction)

The C++ APIs in bind.h define

Guide documentation for this API can be found in Embind.

## How to use this API

### Defines

EMSCRIPTEN_BINDINGS(name)

  This define is used to bind C++ classes, functions and other constructs to JavaScript. It is used differently depending on the construct being mapped — see the embind guide for examples.

  Parameters:

    name – This is a label to mark a group of related bindings (for example `EMSCRIPTEN_BINDINGS(physics)`, `EMSCRIPTEN_BINDINGS(components)`, etc.)

type sharing_policy
  type sharing_policy::NONE
  type sharing_policy::INTRUSIVE
  type sharing_policy::BY_EMVAL

## Policies

Currently only `allow_raw_pointers` policy is supported. Eventually we hope to implement Boost.Python-like raw pointer policies for managing object ownership.

type arg
  static int index

        // Prototype
        static constexpr int index

type ret_val
  static int index

        // Prototype
        static constexpr int index

type allow_raw_pointers

  This policy is used to allow raw pointers.

  type Transform::type

type allow_raw_pointer

## select_overload and select_const

typename std::add_pointer<Signature>::type select_overload(typename std::add_pointer<Signature>::type fn)

      // Prototype
      template<typename Signature>
      typename std::add_pointer<Signature>::type select_overload(typename std::add_pointer<Signature>::type fn)

  Parameters:

    typename std::add_pointer<Signature>::type fn –

typename internal::MemberFunctionType<ClassType, Signature>::type select_overload()

      // Prototype
      template<typename Signature, typename ClassType>
      typename internal::MemberFunctionType<ClassType, Signature>::type select_overload(Signature (ClassType::*fn))

  Parameters:

    Signature (ClassType::*fn) –

auto select_const()

      // Prototype
      template<typename ClassType, typename ReturnType, typename... Args>
      auto select_const(ReturnType (ClassType::*method)(Args...) const)

  Parameters:

    ReturnType (ClassType::*method)(Args...) const –

typename internal::CalculateLambdaSignature<LambdaType>::type optional_override(const LambdaType &fp)

      // Prototype
      template<typename LambdaType>
      typename internal::CalculateLambdaSignature<LambdaType>::type optional_override(const LambdaType& fp)

  Parameters:

    const LambdaType& fp –

## Functions

void function()

      //prototype
      template<typename ReturnType, typename... Args, typename... Policies>
      void function(const char* name, ReturnType (*fn)(Args...), Policies...)

  Registers a function to export to JavaScript. This is called from within an `EMSCRIPTEN_BINDINGS()` block.

  For example to export the function `lerp()`

      // quick_example.cpp
      #include <emscripten/bind.h>

      using namespace emscripten;

      float lerp(float a, float b, float t) {
         return (1 - t) * a + t * b;
      }

      EMSCRIPTEN_BINDINGS(my_module) {
         function("lerp", &lerp);
      }

  Parameters:

    - const char* name – The name of the function to export (e.g. `"lerp"`).

    - ReturnType (*fn)(Args...) – Function pointer address for the exported function (e.g. `&lerp`).

    - Policies... – Policy for managing raw pointer object ownership. Currently must be `allow_raw_pointers`.

## Value tuples

class value_array : public internal::noncopyable
  type class_type

    A typedef of `ClassType`, the typename of the templated type for the class.

  value_array(const char *name)

    Constructor.

    Parameters:

      const char* name –

  ~value_array()

    Destructor.

  value_array &element(ElementType InstanceType::* field)
    Parameters:

      ElementType InstanceType::*field – Note that `ElementType` and `InstanceType` are typenames (templated types).

  value_array &element(Getter getter, Setter setter)
    Parameters:

      - Getter getter – Note that `Getter` is a typename (templated type).

      - Setter setter – Note that `Setter` is a typename (templated type).

  value_array &element(index<Index>)
    Parameters:

      index<Index> – Note that `Index` is an integer template parameter.

## Value structs

class value_object : public internal::noncopyable
  type class_type

    A typedef of `ClassType`, the typename of the templated type for the class.

  value_object(const char *name)

    Constructor.

    Parameters:

      const char* name –

  ~value_object()

    Destructor.

  value_object &field(const char *fieldName, FieldType InstanceType::* field)
    Parameters:

      - const char* fieldName –

      - FieldType InstanceType::*field –

  value_object &field(const char *fieldName, Getter getter, Setter setter)
    Parameters:

      - const char* fieldName –

      - Getter getter – Note that `Getter` is a typename (templated type).

      - Setter setter – Note that `Setter` is a typename (templated type).

  value_object &field(const char *fieldName, index<Index>)
    Parameters:

      - const char* fieldName –

      - index<Index> – Note that `Index` is an integer template parameter.

## Smart pointers

type default_smart_ptr_trait

      //prototype
      template<typename PointerType>
      struct default_smart_ptr_trait

  static sharing_policy get_sharing_policy()
  static void *share(void *v)
    Parameters:

      void* v –

  static PointerType *construct_null()
    Returns:

      Note that the `PointerType` returned is a typename (templated type).

type smart_ptr_trait

      //prototype
      template<typename PointerType>
      struct smart_ptr_trait : public default_smart_ptr_trait<PointerType>

  typedef PointerType::element_type element_type

        //prototype
        typedef typename PointerType::element_type element_type;

    A typedef for the PointerType::element_type, where `PointerType` is a typename (templated type).

  static element_type *get(const PointerType &ptr)
    Parameters:

      const PointerType& ptr – Note that `PointerType` is a typename (templated type)

template<typename PointeeType>
using smart_ptr_trait<std::shared_ptr<PointeeType>>

      //prototype
      template<typename PointeeType>
      struct smart_ptr_trait<std::shared_ptr<PointeeType>>

  type PointerType

    A typedef to std::shared_ptr<PointeeType>, where `PointeeType` is a typename (templated type).

  type element_type

    A typedef for the `PointerType::element_type`.

  static element_type *get(const PointerType &ptr)
    Parameters:

      const PointerType& ptr –

  static sharing_policy get_sharing_policy()
  static std::shared_ptr<PointeeType> *share(PointeeType *p, EM_VAL v)
    Parameters:

      - PointeeType* p – Note that `PointeeType` is a typename (templated type).

      - EM_VAL v –

  static PointerType *construct_null()

## Classes

class wrapper : public T, public internal::WrapperBase

      //prototype
      template<typename T>
      class wrapper : public T, public internal::WrapperBase

  type class_type

    A typedef of `T`, the typename of the templated type for the class.

  wrapper(val &&wrapped, Args&&... args)

        //prototype
        template<typename... Args>
        explicit wrapper(val&& wrapped, Args&&... args)
          : T(std::forward<Args>(args)...)
          , wrapped(std::forward<val>(wrapped))

    Constructor.

    Parameters:

      - val&& wrapped –

      - Args&&... args – Note that `Args` is a typename (templated type).

  ~wrapper()

    Destructor.

  ReturnType call(const char *name, Args&&... args) const

    Constructor.

    Parameters:

      - const char* name –

      - Args&&... args – Note that `Args` is a typename (templated type).

    Returns:

      Note that `ReturnType` is a typename (templated type).

EMSCRIPTEN_WRAPPER(T)
  Parameters:

    T –

type base
  type class_type

    A typedef of `BaseClass`, the typename of the templated type for the class.

  static void verify()

    Note, is templated function which takes typename `ClassType`.

  static internal::TYPEID get()

        template<typename ClassType>
        using Upcaster = BaseClass* (*)(ClassType*);

        template<typename ClassType>
        using Downcaster = ClassType* (*)(BaseClass*);

  static Upcaster<ClassType> getUpcaster()

        //prototype
        template<typename ClassType>
        static Upcaster<ClassType> getUpcaster()

  static Downcaster<ClassType> getDowncaster()

        //prototype
        template<typename ClassType>
        static Downcaster<ClassType> getDowncaster()

  static To *convertPointer(From *ptr)

        //prototype
        template<typename From, typename To>
        static To* convertPointer(From* ptr)

    Parameters:

      From* ptr –

type pure_virtual
  type Transform

    Note that this is a templated struct taking typename parameter `InputType` and integer `Index`.

    type type

      This is a typedef to the parent struct typename parameter `InputType`.

type constructor

  Note that this is a template struct taking typename `... ConstructorArgs`.

class class_

  Note that this is a templated class with typename parameters `ClassType` and `BaseSpecifier`.

  type class_type

    A typedef of `ClassType` (a typename for the class).

  type base_specifier

    A typedef of `BaseSpecifier` (a typename for the class).

  type HELPNEEDEDHERE

        class_() = delete;

  explicit class_(const char *name)

        //prototype
        EMSCRIPTEN_ALWAYS_INLINE explicit class_(const char* name)

    Constructor.

    Parameters:

      const char* name –

  const class_ &smart_ptr(const char *name) const

        //prototype
        template<typename PointerType>
        EMSCRIPTEN_ALWAYS_INLINE const class_& smart_ptr(const char* name) const

    Parameters:

      const char* name –

    Returns:

      A `const` reference to the current object. This allows chaining of the `class_` functions that define the binding in the `EMSCRIPTEN_BINDINGS()` block.

  const class_ &constructor() const

        //prototype
        template<typename... ConstructorArgs, typename... Policies>
        EMSCRIPTEN_ALWAYS_INLINE const class_& constructor(Policies... policies) const

    Zero-argument form of the class constructor. This invokes the natural constructor with the arguments specified in the template. See External constructors for more information.

    Parameters:

      Policies... policies – Policy for managing raw pointer object ownership. Currently must be `allow_raw_pointers`.

    Returns:

      A `const` reference to the current object. This allows chaining of the `class_` functions that define the binding in the `EMSCRIPTEN_BINDINGS()` block.

  const class_ &constructor(Callable callable, Policies...) const

        //prototype
        template<typename Signature = internal::DeduceArgumentsTag, typename Callable, typename... Policies>
        EMSCRIPTEN_ALWAYS_INLINE const class_& constructor(Callable callable, Policies...) const

    Class constructor for objects that use a factory function to create the object. This method will accept either a function pointer, `std::function` object or function object which will return a newly constructed object. When the `Callable` is a function object the function signature must be explicitly specified in the `Signature` template parameter in the format `ReturnType (Args...)`. For `Callable` types other than function objects the method signature will be deduced.

    The following are all valid calls to `constructor`:

        using namespace std::placeholders;
        myClass1.constructor(&my_factory);
        myClass2.constructor(std::function<ClassType2(float, float)>(&class2_factory));
        myClass3.constructor<ClassType3(const val&)>(std::bind(Class3Functor(), _1));

    See External constructors for more information.

    Parameters:

      - Callable callable – Note that `Callable` may be either a member function pointer, function pointer, `std::function` or function object.

      - Policies... policies – Policy for managing raw pointer object ownership. Currently must be `allow_raw_pointers`.

    Returns:

      A `const` reference to the current object. This allows chaining of the `class_` functions that define the binding in the `EMSCRIPTEN_BINDINGS()` block.

  const class_ &smart_ptr_constructor() const

        //prototype
        template<typename SmartPtr, typename... Args, typename... Policies>
        EMSCRIPTEN_ALWAYS_INLINE const class_& smart_ptr_constructor(const char* smartPtrName, SmartPtr (*factory)(Args...), Policies...) const

    Parameters:

      - const char* smartPtrName –

      - SmartPtr (*factory)(Args...) –

      - Policies... policies – Policy for managing raw pointer object ownership. Currently must be `allow_raw_pointers`.

    Returns:

      A `const` reference to the current object. This allows chaining of the `class_` functions that define the binding in the `EMSCRIPTEN_BINDINGS()` block.

  const class_ &allow_subclass() const

        //prototype
         template<typename WrapperType, typename PointerType, typename... ConstructorArgs>
        EMSCRIPTEN_ALWAYS_INLINE const class_& allow_subclass(
          const char* wrapperClassName,
          const char* pointerName,
          ::emscripten::constructor<ConstructorArgs...> = ::emscripten::constructor<>()
        ) const

    Parameters:

      - const char* wrapperClassName –

      - const char* pointerName –

      - emscripten::constructor<ConstructorArgs...> constructor) –

    Returns:

      A `const` reference to the current object. This allows chaining of the `class_` functions that define the binding in the `EMSCRIPTEN_BINDINGS()` block.

  const class_ &allow_subclass(const char *wrapperClassName, ::emscripten::constructor<ConstructorArgs...> constructor) const

        //prototype
        template<typename WrapperType, typename... ConstructorArgs>
        EMSCRIPTEN_ALWAYS_INLINE const class_& allow_subclass(
          const char* wrapperClassName,
          ::emscripten::constructor<ConstructorArgs...> constructor = ::emscripten::constructor<>()
        ) const

    Parameters:

      - const char* wrapperClassName –

      - ::emscripten::constructor<ConstructorArgs...> constructor) –

    Returns:

      A `const` reference to the current object. This allows chaining of the `class_` functions that define the binding in the `EMSCRIPTEN_BINDINGS()` block.

  const class_ &function() const

        //prototype
        template<typename Signature = internal::DeduceArgumentsTag, typename Callable, typename... Policies>
        EMSCRIPTEN_ALWAYS_INLINE const class_& function(const char* methodName, Callable callable, Policies...) const

    This method is for declaring a method belonging to a class.

    On the JavaScript side this is a function that gets bound as a property of the prototype. For example `.function("myClassMember", &MyClass::myClassMember)` would bind `myClassMember` to `MyClass.prototype.myClassMember` in the JavaScript. This method will accept either a pointer-to-member-function, function pointer, `std::function` object or function object. When the `Callable` is not a pointer-to-member-function it must accept the `ClassType` as the first (`this`) parameter. When the `Callable` is a function object the function signature must be explicitly specified in the `Signature` template parameter in the format `ReturnType (Args...)`. For `Callable` types other than function objects the method signature will be deduced.

    A method name specified in the human-readable well-known symbol format (e.g., `@@iterator`) is bound using the named `Symbol` for JavaScript (e.g., `Symbol.iterator`).

    The following are all valid calls to `function`:

        using namespace std::placeholders;
        myClass.function("myClassMember", &MyClass::myClassMember)
            .function("myFreeFunction", &my_free_function)
            .function("myStdFunction", std::function<float(ClassType&, float, float)>(&my_function))
            .function<val(const MyClass&)>("myFunctor", std::bind(&my_functor_taking_this, _1));

    Parameters:

      - const char* methodName –

      - Callable callable – Note that `Callable` may be either a member function pointer, function pointer, `std::function` or function object.

      - typename... Policies – Policy for managing raw pointer object ownership. Currently must be `allow_raw_pointers`.

    Returns:

      A `const` reference to the current object. This allows chaining of the `class_` functions that define the binding in the `EMSCRIPTEN_BINDINGS()` block.

  const class_ &iterable() const

        // prototype
        template<typename ElementType>
        EMSCRIPTEN_ALWAYS_INLINE const class_& iterable(const char* sizeMethodName, const char* getMethodName) const

    Makes a bound class iterable in JavaScript by installing `Symbol.iterator`. This enables use with `for...of` loops, `Array.from()`, and spread syntax.

    Template Parameters:

      ElementType – The type of elements yielded by the iterator.

    Parameters:

      - sizeMethodName – Name of the bound method that returns the number of elements.

      - getMethodName – Name of the bound method that retrieves an element by index.

    Returns:

      A `const` reference to the current object. This allows chaining of the `class_` functions that define the binding in the `EMSCRIPTEN_BINDINGS()` block.

        class_<MyContainer>("MyContainer")
           .function("size", &MyContainer::size)
           .function("get", &MyContainer::get)
           .iterable<int>("size", "get");

        const container = new Module.MyContainer();
        for (const item of container) { /* ... */ }
        const arr = Array.from(container);

  const class_ &property() const

        //prototype
        template<typename FieldType, typename = typename std::enable_if<!std::is_function<FieldType>::value>::type>
        EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, const FieldType ClassType::*field) const

    Parameters:

      - const char* fieldName –

      - const FieldType ClassType::*field –

    Returns:

      A `const` reference to the current object. This allows chaining of the `class_` functions that define the binding in the `EMSCRIPTEN_BINDINGS()` block.

  const class_ &property(const char *fieldName, FieldType ClassType::* field) const

        //prototype
        template<typename FieldType, typename = typename std::enable_if<!std::is_function<FieldType>::value>::type>
        EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, FieldType ClassType::*field) const

    Parameters:

      - const char* fieldName –

      - FieldType ClassType::*field –

    Returns:

      A `const` reference to the current object. This allows chaining of the `class_` functions that define the binding in the `EMSCRIPTEN_BINDINGS()` block.

  const class_ &property(const char *fieldName, Getter getter) const

        //prototype
        template<typename PropertyType = internal::DeduceArgumentsTag, typename Getter>
        EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, Getter getter) const;

    Declare a read-only property with the specified `fieldName` on the class using the specified `getter` to retrieve the property value. `Getter` may be either a class method, a function, a `std::function` or a function object. When `Getter` is not pointer-to-member-function, it must accept an instance of the `ClassType` as the `this` argument. When `Getter` is a function object, the property type must be specified as a template parameter as it cannot be deduced, e.g.: `myClass.property<int>("myIntProperty", MyIntGetterFunctor());`

    Parameters:

      - const char* fieldName –

      - Getter getter – Note that `Getter` is a function template typename.

    Returns:

      A `const` reference to the current object. This allows chaining of the `class_` functions that define the binding in the `EMSCRIPTEN_BINDINGS()` block.

  const class_ &property(const char *fieldName, Getter getter, Setter setter) const

        //prototype
        template<typename PropertyType = internal::DeduceArgumentsTag, typename Getter, typename Setter>
        EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, Getter getter, Setter setter) const

    This is a function template taking typenames `Setter` and `Getter`: `template<typename Getter, typename Setter>` which declares a read-write property with the specified `fieldName` on the class. `Getter` and `Setter` may be either a class method, a function, a `std::function` or a function object. When `Getter` or `Setter` is not pointer-to-member-function, it must accept an instance of the `ClassType` as the `this` argument. When `Getter` or `Setter` is a function object, the property type must be specified as a template parameter as it cannot be deduced, e.g.: `myClass.property<int>("myIntProperty", MyIntGetterFunctor(), MyIntSetterFunctor());`

    Parameters:

      - const char* fieldName –

      - Getter getter – Note that `Getter` is a function template typename.

      - Setter setter – Note that `Setter` is a function template typename.

    Returns:

      A `const` reference to the current object. This allows chaining of the `class_` functions that define the binding in the `EMSCRIPTEN_BINDINGS()` block.

  const class_ &class_function() const

        //prototype
        template<typename ReturnType, typename... Args, typename... Policies>
        EMSCRIPTEN_ALWAYS_INLINE const class_& class_function(const char* methodName, ReturnType (*classMethod)(Args...), Policies...) const

    This method is for declaring a static function belonging to a class.

    On the JavaScript side this is a function that gets bound as a property of the constructor. For example `.class_function("myStaticFunction", &MyClass::myStaticFunction)` binds `myStaticFunction` to `MyClass.myStaticFunction`.

    A method name specified in the human-readable well-known symbol format (e.g., `@@species`) is bound using the named `Symbol` for JavaScript (e.g., `Symbol.species`).

    Parameters:

      - const char* methodName –

      - ReturnType (*classMethod)(Args...) –

      - Policies... – Policy for managing raw pointer object ownership. Currently must be `allow_raw_pointers`.

    Returns:

      A `const` reference to the current object. This allows chaining of the `class_` functions that define the binding in the `EMSCRIPTEN_BINDINGS()` block.

  const class_ &class_property(const char *fieldName, FieldType *field) const

        //prototype
        template<typename FieldType>
        EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, FieldType *field) const

    Parameters:

      - const char* fieldName –

      - FieldType ClassType::*field –

    Returns:

      A `const` reference to the current object. This allows chaining of the `class_` functions that define the binding in the `EMSCRIPTEN_BINDINGS()` block.

## Vectors

class_<std::vector<T>> register_vector(const char *name)

      //prototype
      template<typename T>
      class_<std::vector<T>> register_vector(const char* name)

  A function to register a `std::vector<T>`.

  Parameters:

    const char* name –

## Maps

class_<std::map<K, V>> register_map(const char *name)

      //prototype
      template<typename K, typename V>
      class_<std::map<K, V>> register_map(const char* name)

  A function to register a `std::map<K, V>`.

  Parameters:

    const char* name –

## Enums

class enum_

      //prototype
      template<typename EnumType>
      class enum_

  Registers an enum to export to JavaScript. This is called from within an `EMSCRIPTEN_BINDINGS()` block and works with both C++98 enums and C++11 “enum classes”. See Enums for more information.

  type enum_type

    A typedef of `EnumType` (a typename for the class).

  enum_(const char *name, enum_value_type valueType = enum_value_type::object)

    Constructor.

    Parameters:

      - const char* name – Name of the enum in JavaScript.

      - enum_value_type valueType –

        Determines how the enumerated values are represented in JavaScript.

        Possible values:

        - `enum_value_type::object` (default): Values are JavaScript objects with a `.value` field.

        - `enum_value_type::number`: Values are plain numbers matching their corresponding C++ values.

        - `enum_value_type::string`: Values are strings containing their name.

  enum_ &value(const char *name, EnumType value)

    Registers an enum value.

    Parameters:

      - const char* name – The name of the enumerated value.

      - EnumType value – The enumerated value.

    Returns:

      A reference to the current object. This allows chaining of multiple enum values in the `EMSCRIPTEN_BINDINGS()` block.

## Constants

void constant(const char *name, const ConstantType &v)

      //prototype
      template<typename ConstantType>
      void constant(const char* name, const ConstantType& v)

  Registers a constant to export to JavaScript. This is called from within an `EMSCRIPTEN_BINDINGS()` block.

      EMSCRIPTEN_BINDINGS(my_constant_example) {
        constant("SOME_CONSTANT", SOME_CONSTANT);
      }

  Parameters:

    - const char* name – The name of the constant.

    - const ConstantType& v – The constant type. This can be any type known to embind.