From 6a71cca7ea1a0c389133df9e3b421ba09beb5680 Mon Sep 17 00:00:00 2001 From: Sami Vaarala Date: Thu, 1 Dec 2016 04:13:31 +0200 Subject: [PATCH] Add a type summary document --- doc/types.rst | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 doc/types.rst diff --git a/doc/types.rst b/doc/types.rst new file mode 100644 index 00000000..f8b03401 --- /dev/null +++ b/doc/types.rst @@ -0,0 +1,125 @@ +============== +Duktape typing +============== + +Internal and external type summary +================================== + +The table below summarizes various types and how they appear in the external +API and internals. What's missing from the table: + +* ``duk_hobject`` has a flags field which allows some logical types to be + distinguished from one another. For example, bound functions have a + specific internal flag. Other structs also have flags that may be relevant + to typing but are not presented in the table. + +* The API type check function(s) are not comprehensive, but more example of + what a typical "is the value of type X" could be. + +* The C APIs for creating a value of each type are not listed. + ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| Ecmascript code | API type | API type check(s) | Internal duk_tval tag | Internal struct(s) | duk_hobject class number | Ecmascript typeof | Ecmascript Object .toString() | Notes | ++============================+=====================+========================+=======================+=========================+=====================================+===================+===============================+===================================+ +| n/a | DUK_TYPE_NONE | duk_is_valid_index() | DUK_TAG_UNUSED | n/a | n/a | n/a | n/a | Marker for "no value" when doing | +| | | | | | | | | a valus stack type lookup. | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| void 0 | DUK_TYPE_UNDEFINED | duk_is_undefined() | DUK_TAG_UNDEFINED | n/a | n/a | undefined | [object Undefined] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| null | DUK_TYPE_NULL | duk_is_null() | DUK_TAG_NULL | n/a | n/a | object (!) | [object Null] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| true | DUK_TYPE_BOOLEAN | duk_is_boolean() | DUK_TAG_BOOLEAN | n/a | n/a | boolean | [object Boolean] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| 123 | DUK_TYPE_NUMBER | duk_is_number() | DUK_TAG_FASTINT | n/a | n/a | number | [object Number] | If 48-bit signed int, and fastint | +| | | | | | | | | support enabled. | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| 123.1 | DUK_TYPE_NUMBER | duk_is_number() | DUK_TAG_NUMBER (*) | n/a | n/a | number | [object Number] | With packed duk_tval, no explicit | +| | | | | | | | | internal tag. | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| "foo" | DUK_TYPE_STRING | duk_is_string() | DUK_TAG_STRING | duk_hstring, | n/a | string | [object String] | | +| | | | | duk_hstring_external | | | | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| Symbol('foo') | DUK_TYPE_STRING | duk_is_string() | DUK_TAG_STRING | duk_hstring, | n/a | symbol | [object Symbol] | Symbols | +| | | | | duk_hstring_external | | | | (NOT FINALIZED) | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| n/a | DUK_TYPE_LIGHTFUNC | duk_is_lightfunc() | DUK_TAG_LIGHTFUNC | n/a | n/a | function | [object Function] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| ArrayBuffer.allocPlain(1) | DUK_TYPE_BUFFER | duk_is_buffer() | DUK_TAG_BUFFER | duk_hbuffer_fixed, | n/a | object | [object ArrayBuffer] | | +| | | | | duk_hbuffer_dynamic, | | | | | +| | | | | duk_hbuffer_external | | | | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| Duktape.Pointer('dummy') | DUK_TYPE_POINTER | duk_is_pointer() | DUK_TAG_POINTER | n/a | n/a | pointer | [object Pointer] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| n/a | n/a | duk_is_valid_index() | n/a | n/a | DUK_HOBJECT_CLASS_NONE | n/a | n/a | Marker for "no value" when doing | +| | | | | | | | | a class number lookup. | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| { foo: 123 } | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_OBJECT | object | [object Object] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| [ 1, 2, 3 ] | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_harray | DUK_HOBJECT_CLASS_ARRAY | object | [object Array] | duk_harray extends duk_hobject. | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| arguments | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_ARGUMENTS | object | [object Arguments] | Not an array; array-like. | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new Boolean(true) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_BOOLEAN | object | [object Boolean] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new Date() | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_DATE | object | [object Date] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new TypeError('aiee') | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_ERROR | object | [object Error] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| Math.cos | DUK_TYPE_OBJECT | duk_is_object(), | DUK_TAG_OBJECT | duk_hnatfunc | DUK_HOBJECT_CLASS_FUNCTION | function | [object Function] | duk_hnatfunc extends duk_hobject. | +| | | duk_is_function(), | | | | | | | +| | | duk_is_callable() | | | | | | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| function foo() {} | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hcompfunc | DUK_HOBJECT_CLASS_FUNCTION | function | [object Function] | duk_hcompfunc extends duk_hobject.| +| | | duk_is_function(), | | | | | | | +| | | duk_is_callable() | | | | | | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| func.bind(null, 123) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_FUNCTION | function | [object Function] | duk_hobject flag | +| | | duk_is_function(), | | | | | | DUK_HOBJECT_FLAG_BOUNDFUNC is set.| +| | | duk_is_callable() | | | | | | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| JSON | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_JSON | object | [object JSON] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| Math | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_MATH | object | [object Math] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new Number(123) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_NUMBER | object | [object Number] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| /foo/ | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_REGEXP | object | [object RegExp] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new String('foo') | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_STRING | object | [object String] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| Object(Symbol('foo')) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_SYMBOL | object | [object Symbol] | (NOT FINALIZED) | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| Function('return this')() | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_GLOBAL | object | [object global] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| n/a | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_OBJENV | object | [object ObjEnv] | Internal scope object for an | +| | | | | | | | | object environment. | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| n/a | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_DECENV | object | [object DecEnv] | Internal scope object for a | +| | | | | | | | | declarative environment. | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new Duktape.Pointer('foo') | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hobject | DUK_HOBJECT_CLASS_POINTER | object | [object Pointer] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new Duktape.Thread(func) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hthread | DUK_HOBJECT_CLASS_THREAD | object | [object Thread] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new ArrayBuffer(8) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hbufobj | DUK_HOBJECT_CLASS_ARRAYBUFFER | object | [object ArrayBuffer] | duk_hbufobj extends duk_hobject. | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new DataView(arrBuf) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hbufobj | DUK_HOBJECT_CLASS_DATAVIEW | object | [object DataView] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new Int8Array(1) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hbufobj | DUK_HOBJECT_CLASS_INT8ARRAY | object | [object Int8Array] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new Uint8Array(1) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hbufobj | DUK_HOBJECT_CLASS_UINT8ARRAY | object | [object Uint8Array] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new Uint8ClampedArray(1) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hbufobj | DUK_HOBJECT_CLASS_UINT8CLAMPEDARRAY | object | [object Uint8ClampedArray] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new Int16Array(1) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hbufobj | DUK_HOBJECT_CLASS_INT16ARRAY | object | [object Int16Array] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new Uint16Array(1) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hbufobj | DUK_HOBJECT_CLASS_UINT16ARRAY | object | [object Uint16Array] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new Int32Array(1) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hbufobj | DUK_HOBJECT_CLASS_INT32ARRAY | object | [object Int32Array] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new Uint32Array(1) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hbufobj | DUK_HOBJECT_CLASS_UINT32ARRAY | object | [object Uint32Array] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new Float32Array(1) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hbufobj | DUK_HOBJECT_CLASS_FLOAT32ARRAY | object | [object Float32Array] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+ +| new Float64Array(1) | DUK_TYPE_OBJECT | duk_is_object() | DUK_TAG_OBJECT | duk_hbufobj | DUK_HOBJECT_CLASS_FLOAT64ARRAY | object | [object Float64Array] | | ++----------------------------+---------------------+------------------------+-----------------------+-------------------------+-------------------------------------+-------------------+-------------------------------+-----------------------------------+