Lists
Table of contents
- Lists
- Indexing
- Slicing
- Adding to lists
- list.toString() -> String
- list.len() -> Number
- list.toBool() -> Boolean
- list.contains(value) -> Boolean
- list.join(String: delimiter -> Optional) -> String
- list.remove(value)
- list.pop(Number: index -> Optional) -> value
- list.reverse()
- Copying lists
- Sorting Lists
- list.forEach(Func)
- list.map(Func) -> List
- list.filter(Func) -> List
- list.reduce(Func, value: initial -> Optional) -> List
- list.find(Func, Number: start -> Optional, Number: end -> Optional) -> List
- list.findIndex(Func, Number: start -> Optional, Number: end -> Optional) -> Number
- list.splice(Number, Number, List) -> List
- list.unique() -> List
Lists
Lists in Dictu allow you to store mutliple values of any type. Lists automatically resize for you as data is added and removed. Lists are similar to arrays in languages like Python, JavaScript, and Ruby.
var list = [1, 2.3, "Mango", false, nil];
Indexing
Lists are 0-indexed, meaning that 0 is the first item in a list, and 1 is the second item. You can access an item at a specific index using square brackets.
var list = [1, 2, 3];
print(list[0]); // 1
You can use the same syntax to update a value in a list, except you must provide a value.
var list = [1, 5, 3];
list[1] = 2; // [1, 2, 3]
Slicing
If you want to return only part of a list, you slice it! To slice a list, use square brackets with the range you want to slice. The starting index is inclusive, but the ending index is exclusive. You can also use negative numbers to get characters from the end of a list. Only one index is required.
[1, 2, 3, 4, 5][1:]; // [2, 3, 4, 5]
[1, 2, 3, 4, 5][:4]; // [1, 2, 3, 4]
[1, 2, 3, 4, 5][1:4]; // [2, 3, 4]
[1, 2, 3, 4, 5][2:4]; // [3, 4]
Adding to lists
list.push(value)
To add append a new value to a list, use the .push() method.
var myList = [];
myList.push(10); // [10]
myList.push(11); // [10, 11]
list.insert(value, Number)
To insert a value into a list at a given index without replacing the value use .insert().
var x = [10, 12];
// Can insert to a list. This will not replace the value.
x.insert(11, 1); // [10, 11, 12]
+ Operator
Using the + operator on lists will join two lists and return a new list. It must be used on two values which are both lists.
var x = [10];
x + [11, 12];
print(x); // [10, 11, 12]
list.extend(List)
Similar to the + operator however this mutates the list the method is called on rather than returning a new list.
Note: values are not copied to the new list, they are just referenced. This means if the value is mutable it will mutate in the extended list as well.
var x = [];
x.extend([1, 2, 3]);
print(x); // [1, 2, 3]
x.extend([1, 2, 3]);
print(x); // [1, 2, 3, 1, 2, 3]
list.toString() -> String
Converts a list to a string.
["1", 11].toString(); // ['1', 11]
["1", [11, "1"]].toString(); // ['1', [11, '1']]
list.len() -> Number
Returns the length of the given list.
[1, 2, 3].len(); // 3
list.toBool() -> Boolean
Converts a list to a boolean. A list is a “truthy” value when it has a length greater than 0.
[].toBool(); // false
[1].toBool(); // true
[[]].toBool(); // true
list.contains(value) -> Boolean
To check if a value contains within a list we use .contains()
var myList = [1, 2, 3];
myList.contains(2); // true
myList.contains(10); // false
list.join(String: delimiter -> Optional) -> String
To convert a list of elements to a string use .join() to concatenate elements together by a given delimiter. If a delimiter is not supplied ", " is the default. Attempting to join an empty list will return an empty string.
var myList = [1, 2, 3];
print(myList.join()); // "1, 2, 3"
print(myList.join("")); // "123"
print(myList.join("-")); // "1-2-3"
print([].join("delimiter")); // ""
list.remove(value)
To remove a value from a list use .remove(). If the value does not exist within the list a runtime error occurs. Use together with list.contains().
Note: If a list contains multiple values which are the same, a call to .remove() will only remove the first occurrence, not all.
var myList = [1, 2, 3];
myList.remove(3);
print(myList); // [1, 2]
myList.remove(1);
print(myList); // [2]
list.pop(Number: index -> Optional) -> value
To remove a value from a list, with an optional index, use .pop()
var myList = [1, 2, 3];
// If no index is given, pops from the end
var someNumber = myList.pop(); // 3
print(myList); // [1, 2]
myList.pop(0); // 1
print(myList); // [2]
list.reverse()
To reverse a list we use .reverse(), this will reverse a list in-place (modifying the list) rather than generating a new list.
const myList = [1, 2, 3, 4];
myList.reverse();
print(myList); // [4, 3, 2, 1]
Copying lists
list.copy() -> List
When you are working with a mutable datatype taking a reference of a list when creating a new variable will modify the original list.
var list1 = [1, 2];
var list2 = list1;
list2[0] = 10;
print(list1); // [10, 2]
To get around this we can make copies of the list. Dictu offers the ability to both shallow and deep copy a list.
var list1 = [1, 2];
var list2 = list1.copy(); // shallow copy
list2[0] = 10;
print(list1); // [1, 2]
print(list2); // [10, 2]
list.deepCopy() -> List
To get around this, we can deepCopy the list.
var list1 = [[1, 2]];
var list2 = list1.deepCopy();
list2[0][0] = 10;
print(list1); // [[1, 2]]
print(list2); // [[10, 2]]
Sorting Lists
list.sort()
To sort numeric lists and string lists (that is lists that contain only numbers or only strings) you can use the method sort.
var list1 = [1, -1, 4, 2, 10, 5, 3];
print(list1); // [1, -1, 4, 2, 10, 5, 3]
list1.sort();
print(list1); // [-1, 1, 2, 3, 4, 5, 10]
list.sortFunc(Func)
Sorts a list with a Custom Callback, The callback function passed to .sortFunc takes two elements of the list a and b. The return value should be a number whose sign indicates the relative order of the two elements: negative if a is less than b, positive if a is greater than b, and zero if they are equal.
var list1 = [[1, "Dictu"], [-1, "SomeValue"], [5, "!"], [4, "Awesome"], [2, "is"]];
print(list1); // [[1, "Dictu"], [-1, "SomeValue"], [5, "!"], [4, "Awesome"], [2, "is"]];
list1.sortFunc(def(a,b) => a[0] - b[0]);
print(list1); // [[-1, "SomeValue"], [1, "Dictu"], [2, "is"], [4, "Awesome"], [5, "!"]]
var list1 = ["zebra", "cat", "dino", "pig"];
print(list1); // ["zebra", "cat", "dino", "pig"]
list1.sort();
print(list1); // ["cat", "dino", "pig", "zebra"]
list.forEach(Func)
To run a function on every element in a list we use .forEach. The callback function passed to .forEach expects one parameter which will be the current value.
const myList = [1, 2, 3, 4, 5];
myList.forEach(def (value) => {
print("Val: {}".format(value));
});
list.map(Func) -> List
Similar to .foreach, .map will run a function for each element within the list, however the difference is that .map returns a new list of values generated from the callback function. Map expects a single parameter which is a callback. The callback itself also expects one parameter which is the current item in the list.
print([1, 2, 3, 4, 5].map(def (x) => x * 2)); // [2, 4, 6, 8, 10]
list.filter(Func) -> List
To filter out values within a list we use .filter(). Filter expects a single parameter which is a callback and if the callback returns a truthy value it will be appended to the list. The callback itself also expects one parameter which is the current item in the list.
Note: .filter() returns a new list.
print([1, 2, 3, 4, 5].filter(def (x) => x > 2)); // [3, 4, 5]
list.reduce(Func, value: initial -> Optional) -> List
To reduce a list down to a single value we use .reduce(). Reduce expects at least one parameter which is a callback that will be executed on each item of the list. The value of the callback function is returned and saved for the next call. The callback itself also expects two parameters which is the accumulated value and the current value in the list.
print([1, 2, 3, 4, 5].reduce(def (accumulate, element) => accumulate + element)); // 15
By default the initial value for .reduce() is 0, however we can change this to be any value.
print(["Dictu ", "is", " great!"].reduce(def (accumulate, element) => accumulate + element, "")); // 'Dictu is great!'
list.find(Func, Number: start -> Optional, Number: end -> Optional) -> List
To find a single item within a list we use .find(). Find will search through each item in the list and as soon as the callback returns a truthy value, the item that satisfied the callback is returned, if none of the items satisfy the callback function then nil is returned. The optional start and end parameters change the points at which the list will be searched.
Note: The first item to satisfy the callback is returned.
print([1, 2, 3].find(def (item) => item == 2)); // 2
print([1, 2, 3, 4, 5, 6].find(def (item) => item % 2 == 0, 2)); // 4
print([1, 2, 3, 4, 5, 6].find(def (item) => item % 2 == 0, 2, 3)); // nil
list.findIndex(Func, Number: start -> Optional, Number: end -> Optional) -> Number
To find a single item within a list we use .findIndex(). Find will search through each item in the list and as soon as the callback returns a truthy value, the index at which the item that satisfied the callback is returned, if none of the items satisfy the callback function then nil is returned. The optional start and end parameters change the points at which the list will be searched.
Note: The first item to satisfy the callback is returned.
print([1, 2, 3].findIndex(def (item) => item == 2)); // 1
print([1, 2, 3, 4, 5, 6].findIndex(def (item) => item % 2 == 0, 2)); // 3
print([1, 2, 3, 4, 5, 6].findIndex(def (item) => item % 2 == 0, 2, 3)); // nil
list.splice(Number, Number, List) -> List
Splice provides a means of changing the contents of a list by removing or replacing existing elements and/or adding new elements and returns a new list reflecting the changes.
[1, 2, 3, 4, 5].splice(1, 0, [100]); // [1, 100, 2, 3, 4, 5]
[1, 2, 3, 4, 5].splice(1, 1, [100]); // [1, 100, 3, 4, 5]
[1, 2, 3, 4, 5].splice(1, 2, [100]); // [1, 100, 4, 5]
[1, 2, 3, 4, 5].splice(3, 0, [100, 101, 102]); // [1, 2, 3, 100, 101, 102, 4, 5]
list.unique() -> List
Unique returns a new list with contianing the contents of the original list deduplicated.
const l = [1, 1, 1, 2, 2, 3, 4, 5, 6, 6, 7, 8, 9, 9];
l.unique(); // [1, 2, 3, 4, 5, 6, 7, 8, 9]