====== Javascript binding API - Eina Containers ======
[[:develop:legacy:api::javascript::eina|Back to the JS Eina page]]
Currently, two data types are available: Lists and Arrays. Both represent a sequence of items and aim to have a similar interface to the native [[https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array|Javascript Arrays]] for the most common operations like push/pop and indexed get/set.
One important limitation is that when you create an Eina collection you must pass the type of object that will be stored. This is required to allow the binding do the correct conversion between Javascript types and C/C++ types due to the former's static nature.
Besides the constructor function, they differ in the way the items are stored underneath. ''efl.List'' are doubly-linked lists, with relatively fast insert/delete operations while ''efl.Array'' objects are contiguous memory regions, with fast data access (compared to Lists) but allowing to insert or delete items only at the extremities of the container.
Apart from the constructors, both containers have the exact same API.
==== Constructors ====
Syntax
new efl.List(typename);
new efl.Array(typename);
Parameters
* typename - A string with the type of the contained items for this container.
Return type
* Array/List - A newly created container, empty.
The constructor functions receive the name of the type that will be stored on the container. The following types are supported using the respective type name:
* Integers - "int"
* Floating point numbers - "float"
* Boolean values - "bool"
* Strings of characters - "string"
==== Containers methods and operations ====
The methods and operations below are supported for both types of sequences.
=== concat(container) ===
Syntax
var new_container = objA.concat(objC);
Parameters
* container - A container of the same type of the callee container, including the contained type.
Return type
* Array/List - A container of the same type of the callee.
Concatenates two containers returning the result as a new container object.
It performs a shallow copy of the container. Object **references** are copied (i.e. changes in the object will appear in both containers) and basic types are copied.
The concatenation operation will work only on the same type of containers (e.g. lists of ints with lists of ints). Wrong arguments will raise TypeError.
=== getter: container[index] ===
Syntax
var myvar = obj[index];
Parameters
* index - An integer with the 0-based index desired.
Return type
* T or ''undefined'' - When calling on a container wrapping items of type T. ''undefined'' if no object on that index.
Works like Javascript Array ''[]'' operators. The items are 0-indexed, with the first element at index 0 and the last element with index equal to the number of elements of the sequence minus 1.
Usage example:
mylist[42] // Gets the 42nd element
mylist[0] // Gets the first element.
Trying to access an element with an index out of bounds will return ''undefined''.
=== indexOf(target) ===
Syntax
var index = obj.indexOf(target);
Parameters
* target - An object/item to search for.
Return type
* integer - The index of the item in the container. -1 if not found.
Searches for ''target'' in the container and returns the index if found. If not found, return -1.
Example usage:
// obj = [100, 42, 55, 42]
var idx = obj.indexOf(42); // idx = 1
var idx2 = obj.indexOf(1000); // idx2 = -1
=== lastIndexOf(target) ===
Syntax
var index = obj.lastIndexOf(target);
Parameters
* target - An object/item to search for.
Return type
* integer - The last index of the item in the container. -1 if not found.
Searches backwards for ''target'', returning its index if found, or -1 otherwise.
Example code:
// obj = [100, 42, 55, 42]
var idx = obj.lastIndexOf(42) // idx = 3
var idx2 = obj.lastIndexOf(0) // idx2 = -1
=== length property ===
Syntax
obj.length
Return type
* integer - The number of elements on this container.
Returns the number of elements on this container.
In pure Javascript Arrays, assigning a number smaller than the size of the container to the length property will delete elements from the container. This behavior is **not** present on eina Arrays or Lists. Trying to assign a number to length will have no effect.
Example usage:
var last = obj[obj.length - 1]
=== pop() ===
Syntax
var value = obj.pop();
Return type
* T or ''undefined'' - For containers wrapping items of type T. ''undefined'' if it was an empty space or the container was empty.
Behaves like Javascript ''Array.pop()'', removing the last element of the list and returning it.
Example code:
// obj is [1,2,3,4,5]
var value = obj.pop(); // value now is 5 and obj is [1,2,3,4]
Trying to pop an item from an empty list will return undefined and leave the list empty.
=== push(value) ===
Syntax
var size = obj.push(item)
Parameters
* item - An object/item to append to the container.
Return type
* integer - The size of the container after pushing.
Works like the Javascript ''Array.push(item)'', appending the item to the end of the sequence. For lists, a new node is created at the end. For Arrays, the item is set to the end of the array, and it may grow as needed.
The method returns the size of the container after adding the new element.
Usage example:
var mylist = new efl.List("int");
mylist.push(3);
var myarray = new efl.Array("string");
var new_size = myarray.push("Foobar");
Although Javascript is weak typed, the binding functions are rather strong typed, doing minimal type conversions, like int to floats. Trying to push an element of a different type from the one provided in the constructor will raise TypeError.
var obj = new efl.List("float");
obj.push("44"); // CRASH!!!!
=== setter: container[index] = value ===
Syntax
obj[index] = value;
var v = (obj[index] = value);
Parameters
* index - An integer with the target slot on the container.
* value - An object/item to be set to the target position.
Return type
* object - The same object that was assigned (''value'').
Works like Javascript indexed setter method. It sets the value at the given index to the given value, //generally// not changing the container size (see note below). On success, the operation returns the value recently set.
Trying to set a value at an index equal or larger than the size of the container will extend the container up to that index and fill value up to the last one with ''undefined'', and setting the given value in the last position.
var obj = new efl.List("int");
obj[42] = 42; // Obj now has 42 undefined's leading up to 42 in the last position.
Usage example:
var obj = new efl.List("int");
obj.push(3) // [3]
obj.push(2) // [3,2]
obj[0] = 42; // [42, 2]
As with pushing elements, trying to push an element of a different type from the one given to the constructor will raise TypeError.
=== slice([begin,[end]]) ===
Syntax
var x = obj.slice();
var y = obj.slice(startIndex);
var z = obj.slice(startIndex, endIndex);
Parameters
* begin - An integer with the index of the start of the slice.
* end - An integer with the index of the end of the slice.
Return type
* container - A container of the same type of the callee.
The slice method retrieves portions of the container. The first argument is the index to start the slice operation (default is 0, beginning of the list) and the second argument indicates the index where the extraction should stop, not including it (defaults to the container size). In interval notation, it returns ''[begin, end)''.
It also performs a shallow copy like concat().
Example usage:
var same = obj.slice() // All elements from obj are in the returned container.
var other = obj.slice(1); // Everything but the first element.
var another = obj.slice (4, 10); // From the fifth element to the tenth.
=== toString() ===
Syntax
obj.toString();
Return type
* string - A comma-separated list of the items in this container.
Generates a comma-separated string with the representation of the items in this container.