==============================================================================
*41.8*	Lists and Dictionaries

So far we have used the basic types String and Number.  Vim also supports two
composite types: List and Dictionary.

A List is an ordered sequence of things.  The things can be any kind of value,
thus you can make a List of numbers, a List of Lists and even a List of mixed
items.  To create a List with three strings: >

	:let alist = ['aap', 'mies', 'noot']

The List items are enclosed in square brackets and separated by commas.  To
create an empty List: >

	:let alist = []

You can add items to a List with the add() function: >

	:let alist = []
	:call add(alist, 'foo')
	:call add(alist, 'bar')
	:echo alist
<	['foo', 'bar'] ~

List concatenation is done with +: >

	:echo alist + ['foo', 'bar']
<	['foo', 'bar', 'foo', 'bar'] ~

Or, if you want to extend a List directly: >

	:let alist = ['one']
	:call extend(alist, ['two', 'three'])
	:echo alist
<	['one', 'two', 'three'] ~

Notice that using add() will have a different effect: >

	:let alist = ['one']
	:call add(alist, ['two', 'three'])
	:echo alist
<	['one', ['two', 'three']] ~

The second argument of add() is added as a single item.


FOR LOOP

One of the nice things you can do with a List is iterate over it: >

	:let alist = ['one', 'two', 'three']
	:for n in alist
	:  echo n
	:endfor
<	one ~
	two ~
	three ~

This will loop over each element in List "alist", assigning the value to
variable "n".  The generic form of a for loop is: >

	:for {varname} in {listexpression}
	:  {commands}
	:endfor

To loop a certain number of times you need a List of a specific length.  The
range() function creates one for you: >

	:for a in range(3)
	:  echo a
	:endfor
<	0 ~
	1 ~
	2 ~

Notice that the first item of the List that range() produces is zero, thus the
last item is one less than the length of the list.
   You can also specify the maximum value, the stride and even go backwards: >

	:for a in range(8, 4, -2)
	:  echo a
	:endfor
<	8 ~
	6 ~
	4 ~

A more useful example, looping over lines in the buffer: >

	:for line in getline(1, 20)
	:  if line =~ "Date: "
	:    echo matchstr(line, 'Date: \zs.*')
	:  endif
	:endfor

This looks into lines 1 to 20 (inclusive) and echoes any date found in there.


DICTIONARIES

A Dictionary stores key-value pairs.  You can quickly lookup a value if you
know the key.  A Dictionary is created with curly braces: >

	:let uk2nl = {'one': 'een', 'two': 'twee', 'three': 'drie'}

Now you can lookup words by putting the key in square brackets: >

	:echo uk2nl['two']
<	twee ~

The generic form for defining a Dictionary is: >

	{<key> : <value>, ...}

An empty Dictionary is one without any keys: >

	{}

The possibilities with Dictionaries are numerous.  There are various functions
for them as well.  For example, you can obtain a list of the keys and loop
over them: >

	:for key in keys(uk2nl)
	:  echo key
	:endfor
<	three ~
	one ~
	two ~

You will notice the keys are not ordered.  You can sort the list to get a
specific order: >

	:for key in sort(keys(uk2nl))
	:  echo key
	:endfor
<	one ~
	three ~
	two ~

But you can never get back the order in which items are defined.  For that you
need to use a List, it stores items in an ordered sequence.


DICTIONARY FUNCTIONS

The items in a Dictionary can normally be obtained with an index in square
brackets: >

	:echo uk2nl['one']
<	een ~

A method that does the same, but without so many punctuation characters: >

	:echo uk2nl.one
<	een ~

This only works for a key that is made of ASCII letters, digits and the
underscore.  You can also assign a new value this way: >

	:let uk2nl.four = 'vier'
	:echo uk2nl
<	{'three': 'drie', 'four': 'vier', 'one': 'een', 'two': 'twee'} ~

And now for something special: you can directly define a function and store a
reference to it in the dictionary: >

	:function uk2nl.translate(line) dict
	:  return join(map(split(a:line), 'get(self, v:val, "???")'))
	:endfunction

Let's first try it