docs/javascript_new-api_data-structures.md

   1 # Data Structures - JavaScript API
   2
   3 ## Introduction
   4
   5 JavaScript offers only limited types of collections to hold and iterate over
   6 data. Despite the ongoing efforts in ES6 and newer, these new data structures
   7 and access methods, such as `for … of`, are not available in the still supported
   8 Internet Explorer 11.
   9
  10 ## `Dictionary`
  11
  12 Represents a simple key-value map, but unlike the use of plain objects, will
  13 always to guarantee to iterate over directly set values only.
  14
  15 _In supported browsers this will use a native `Map` internally, otherwise a plain object._
  16
  17 ### `set(key: string, value: any)`
  18
  19 Adds or updates an item using the provided key. Numeric keys will be converted
  20 into strings.
  21
  22 ### `delete(key: string)`
  23
  24 Removes an item from the collection.
  25
  26 ### `has(key: string): boolean`
  27
  28 Returns true if the key is contained in the collection.
  29
  30 ### `get(key: string): any`
  31
  32 Returns the value for the provided key, or `undefined` if the key was not found.
  33 Use `.has()` to check for key existence.
  34
  35 ### `forEach(callback: (value: any, key: string) => void)`
  36
  37 Iterates over all items in the collection in an arbitrary order and invokes the
  38 supplied callback with the value and the key.
  39
  40 ### `size: number`
  41
  42 This read-only property counts the number of items in the collection.
  43
  44 ## `List`
  45
  46 Represents a list of unique values.
  47
  48 _In supported browsers this will use a native `Set` internally, otherwise an array._
  49
  50 ### `add(value: any)`
  51
  52 Adds a value to the list. If the value is already part of the list, this method
  53 will silently abort.
  54
  55 ### `clear()`
  56
  57 Resets the collection.
  58
  59 ### `delete(value: any): boolean`
  60
  61 Attempts to remove a value from the list, it returns true if the value has been
  62 part of the list.
  63
  64 ### `forEach(callback: (value: any) => void)`
  65
  66 Iterates over all values in the list in an arbitrary order and invokes the
  67 supplied callback for each value.
  68
  69 ### `has(value: any): boolean`
  70
  71 Returns true if the provided value is part of this list.
  72
  73 ### `size: number`
  74
  75 This read-only property counts the number of items in the list.
  76
  77 ## `ObjectMap`
  78
  79 !!! info "This class uses a `WeakMap` internally, the keys are only weakly referenced and do not prevent garbage collection."
  80
  81 Represents a collection where any kind of objects, such as class instances or
  82 DOM elements, can be used as key. These keys are weakly referenced and will not
  83 prevent garbage collection from happening, but this also means that it is not
  84 possible to enumerate or iterate over the stored keys and values.
  85
  86 This class is especially useful when you want to store additional data for
  87 objects that may get disposed on runtime, such as DOM elements. Using any regular
  88 data collections will cause the object to be referenced indefinitely, preventing
  89 the garbage collection from removing orphaned objects.
  90
  91 ### `set(key: Object, value: Object)`
  92
  93 Adds the key with the provided value to the map, if the key was already part
  94 of the collection, its value is overwritten.
  95
  96 ### `delete(key: Object)`
  97
  98 Attempts to remove a key from the collection. The method will abort silently if
  99 the key is not part of the collection.
 100
 101 ### `has(key: Object): boolean`
 102
 103 Returns true if there is a value for the provided key in this collection.
 104
 105 ### `get(key: Object): Object | undefined`
 106
 107 Retrieves the value of the provided key, or `undefined` if the key was not found.