WWW-www.enlightenment.org pushed a commit to branch master. http://git.enlightenment.org/website/www-content.git/commit/?id=1497a84ba4371efb4fbeec6b4014630a52e4b455
commit 1497a84ba4371efb4fbeec6b4014630a52e4b455 Author: Lauro Moura <[email protected]> Date: Fri Nov 27 07:39:51 2015 -0800 Wiki page containers changed with summary [created] by Lauro Moura --- pages/api/javascript/eina/containers.txt | 137 +++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) diff --git a/pages/api/javascript/eina/containers.txt b/pages/api/javascript/eina/containers.txt new file mode 100644 index 0000000..2df60ab --- /dev/null +++ b/pages/api/javascript/eina/containers.txt @@ -0,0 +1,137 @@ +====== Javascript binding API - Eina Containers ====== + +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 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 in the middle of the collection while ''efl.Array'' objects are contiguous memory arrays, with fast data access (compared to Lists) but costly to insert or delete items in the middle of the collection. + +<note important> +Apart from the constructors, both containers have the exact same API. +</note> + +==== Constructors ==== + +Syntax + +<code javascript> +new efl.List(typename); +new efl.Array(typename); +</code> + +In order to create a collection of items, you call the respective constructor passing the name of the type that will be stored on that collection. 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. + +=== push(value) === + +Syntax + +<code javascript> +var size = obj.push(item) +</code> + +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: + +<code javascript> +var mylist = new efl.List("int"); +mylist.push(3); +var myarray = new efl.Array("string"); +var new_size = myarray.push("Foobar"); +</code> + +<note warning> +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. +<code javascript> +var obj = new efl.List("float"); +obj.push("44"); // CRASH!!!! +</code> +</note> + +=== container[index] === + +Syntax + +<code javascript> +var myvar = obj[index]; +</code> + +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: + +<code javascript> +mylist[42] // Gets the 42nd element +mylist[0] // Gets the first element. +</code> + +<note important> +Trying to access an element with an index out of bounds will return ''undefined''. +</note> + +=== container[index] = value === + +Syntax + +<code javascript> +obj[index] = value; +var v = (obj[index] = value); +</code> + +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. + +<note important> +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. +<code javascript> +var obj = new efl.List("int"); +obj[42] = 42; // Obj now has 42 undefined's leading up to 42 in the last position. +</code> +</note> + +Usage example: + +<code javascript> +var obj = new efl.List("int"); +obj.push(3) // [3] +obj.push(2) // [3,2] +obj[0] = 42; // [42, 2] +</code> + +<note warning> +As with pushing elements, trying to push an element of a different type from the one given to the constructor will raise TypeError. +</note> + +=== pop() === + +Syntax + +<code javascript> +var value = obj.pop(); +</code> + +Behaves like Javascript ''Array.pop()'', removing the last element of the list and returning it. + +Example code: +<code javascript> +// obj is [1,2,3,4,5] +var value = obj.pop(); // value now is 5 and obj is [1,2,3,4] +</code> + +<note important> +Trying to pop an item from an empty list will return undefined and leave the list empty. +</note> + +=== Getting the number of Elements === + +=== Printing the elements === \ No newline at end of file --
