Introduction
This page describes all the basic operations you'd ever want to do to list and map elements. If you do any serious Dekiscripting, you'll probably end up needing to use most of all of these.
For the most part, this page is a compendium of information that is available elsewhere on this wiki, but it seemed useful to collect in one place. If there's any common list or map operation that I've missed, please let me know.
Here are some places to go to find the official documentation on much of this stuff: Dekiscript Syntax, Map literals, List literals, Concatenation Operators, Dekiscript functions and variables, list.splice(), list.select(), map.select(), map.keyvalues().
Creating Lists and Maps
This is simple stuff. We'll use these examples as fodder for our various manipulations later on this page.
Lists
var myList = [ "zero", "one", "two", "three" ];
Maps
var myMap = { one:1, two:2, three:3 };
If you want to use a key name stored in a variable, simply enclose it in parentheses:
var keyName = "one";
var myMap = { (keyName):1, two:2, three:3 };
Accessing Elements
By "accessing", we mean using an element in a right-side expression. These forms are not used to set element values, only read them.
Lists
Accessing a list element is straightforward:
var listElement = myList[0]; // = "zero"
Of course, the subscript can be any expression:
var subscript = 0; var listElement = myList[subscript+1]; // = "one"
Maps
There are two ways to access map elements. If the key is a known constant:
var mapElement = myMap.one; // = 1
If the keyname is stored in a variable, then use list-like syntax:
var keyName = "one";
var mapElement = myMap[keyName]; // = 1
Size of a list or map
For both lists and maps, the syntax for finding the number of elements is the same:
var myListLength = #myList; var myMapLength = #myMap;
For a list, then, the easiest way to access the last element is:
var myLastElement = myList[#myList-1];
The list.splice() function
We now need to take a moment to talk about the list.splice() built-in function, which is going to get a workout when we start modifying lists below. In the examples below. This function does two things:
- Remove element(s) if desired from a specified index in a list
- Insert element(s) if desired to that same index
The key thing to remember here is that the insertions and deletions occur at the same index. By combining insertions and deletions, we can do most of what we'd want, even though it wouldn't necessarily be the first thing we'd think to try.
Adding New Elements
The primary (but not the only) way to add a new element to either a list or map is to concatenate a list with the new element(s).
Lists
To add a new element to a list:
let myList ..= [ "four" ];
Of course you can add more than one at a time:
let myList ..= [ "four", "five" ];
We can also use the all-powerful list.splice() function if we want to add new item(s) to a specific point in the list:
{{ var myList = [ "one", "two", "three", "four" ]; | [ "one", "one point five", "two", "three", "four" ] |
Maps
The approach is similar:
let myMap ..= { four:4 };
let myMap ..= { five:5, six:6 };
And remember that the keyname can be an expression if enclosed in parentheses:
var keyName = "four";
let myMap ..= { (keyName):4 };
Modifying Existing Elements
Lists
Modification of list elements can be done with list.splice(). By removing an element and then inserting a new one at the same location, we can get the job done. To capitalize the item at index 2:
let myList = list.splice(myList, 2, 1, [ toupper(myList[2]) ]);
That's a little ungainly, but it works.
Maps
You can modify a map element by concatenating a list with the new value:
let myMap ..= { one:"uno" };
If the key already exists, this will re-assign the value. So I could increment a numeric value like this:
let myMap ..= { one:myMap.one+1 };
Deleting Elements
You can't delete elements using operators; instead, you'll need to dip into Dekiscript's bag of built-in functions.
Lists
There are two ways to remove elements from a list. If you'd like to so based on the index (or indices) of the elements, then use list.splice(). Let's remove the second element from our list:
let myList = list.splice(myList, 1, 1);
To remove elements based on their value, use list.select(). Let's remove all elements with value "one":
let myList = list.select(myList, "$ != 'one'");
Maps
For maps, we'll have to depend on map.select(). To remove one element, we'll define a test that matches on everything but the one we want to remove. So let's remove element "one" based on its key:
let myMap = map.select(myMap, "$.key != 'one'");
Now let's remove all elements with the value "1":
let myMap = map.select(myMap, "$.value != 1");
Not very pretty, but it gets the job done in a pinch. Of course, you can do a lot more with list.splice(), list.select(), and map.select() then just remove individual items from a list or map.
Conversion between Lists and Maps
There are a lot of ways to convert between lists and maps; the best way depends on the exact structure of your list or map, and what you're trying to accomplish. Here are some common examples.
To perform a basic conversion from a map to a list, use map.keyvalues(). This creates a list of maps as follows:
{{ var myMap = { one:1, two:2, three:3 };
var myList = map.keyvalues(myMap);
myList;
}}
| [ { key : "one", value : 1 }, { key : "two", value : 2 }, { key : "three", value : 3 } ] |
This is actually a pretty useful form, since we can then use list.sort() to sort it by value.
Going from a list to a map is actually a bit trickier, and heavily dependent on what you're trying to do. Most solutions will require iterating through the list, and creating a map entry for each. Here's an example:
{{ var myList = [ "zero", "one", "two", "three" ]; | myList=[ "zero", "one", "two", "three" ] myMap={ one : 1, three : 3, two : 2, zero : 0 } |
- Tag page
- What links here
