Learn how to organize and work with data within a Kotlin list. 

Lists

Excellent work! In this lesson, we've learned the following concepts:

-  A list is a type of Kotlin Collection that contains ordered elements.
-  An immutable list is declared with `listOf` and indicates a list whose values cannot change throughout a program.  
-  A mutable list is declared with `mutableListOf` and indicates a list whose values can be altered. 
-  Elements within a list can be accessed using their index. 
-  The `size` property returns the number of elements in a collection. 
-  Immutable lists possess read-only functionalities, meanwhile, mutable lists support both read and write functionalities. 
- The `contains()` function checks if an element exists in a given list. It returns a Boolean `true` or `false`. 
- The `add()` function appends an element to the end of a mutable list. 
- The `remove()` function removes an element from a mutable list. 
- The `random()` function generates a random element from a given list. 

You've covered a major, fundamental programming concept used in most programs to store and manipulate data. Feel free to utilize the empty **Review.kt** file and output terminal on the right to hone your understanding of lists and practice writing Kotlin code. 

Review

Elements can be accessed from any list, but only with mutable lists can we change the contents of our list by adding, replacing, or removing elements. Previously we've only created immutable lists; in this exercise, we'll learn how to create a mutable list and alter its contents. 

The syntax for declaring a mutable list is as follows:

```pseudo 
var/val listName = mutableListOf(value1, value2, value3) 
```

A mutable list is defined by the term, `mutableListOf` as opposed to `listOf` as we've seen previously. Although the syntax and structure of mutable and immutable lists are the same, the compiler knows which operations can or can't be performed on the list given the term it's defined with. 

Assume we have a list that stores a student's daily activities:

```kt
var dailyActivities = mutableListOf("going to school", "attending tennis practice", "reading") 
```

Now that it's summertime and there's no school, we would like to update the first element of our list to reflect the new season. We can take our previous knowledge of accessing elements a step further and assign a new value to an element's indexed position with the following syntax: 

```kt
dailyActivities[0] = "swimming at the beach" 
```

The value following the assignment operator will get replaced with the current value at the `0` index. Printing the value of `dailyActivities` will result in the following output and updated list:

```
[swimming at the beach, attending tennis practice, reading]
```

Creating a Mutable List 

In this section, we're going to explore the various types of collections that exist in Kotlin. A _collection_ is a group of elements that exist in a single structure. The first collection type we'll learn about is one that's most commonly used in Kotlin and many other programming languages: a list. 

A Kotlin _list_ is very much similar to a real-world list: it represents an ordered collection of elements that can contain duplicates. These elements can be of any primitive data type and represent a myriad of real-world scenarios. These can include student grades, restaurant ratings, a to-do list of tasks, and more. 

Take a look at the image on the right. After a long day of sailing through the creek, Codey is going to set up camp and rest for the night. Being the environmentally friendly Kotlin developer that they are, they've opted to make a virtual to-do list of things they need to get done before nightfall: 

```kt 
var toDo = listOf("gather wood", "start a fire", "set up tent", "eat dinner", "stargaze")
```

Printing the list would result in the following output: 

```
[gather wood, start a fire, set up tent, eat dinner, stargaze]
```

Notice how the syntax of a list in its definition is different from its output. If Kotlin isn't your first programming language, you might recognize the output syntax with square brackets to be identical to that of an array. 

As opposed to lists, arrays in Kotlin have a fixed size, thus not being the most convenient or easily applicable [data structure](https://en.wikipedia.org/wiki/Data_structure). For that reason, we'll be focusing our time on exploring lists, but we encourage you to read up on arrays in Kotlin's [documentation](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-array/). 

An image of Codey reading a to-do list of things he needs to get done before night time. 

Introduction to Lists 

In Kotlin, the terms "mutable" and "immutable" apply not only to variables but also to collections. Much like an immutable variable representing a read-only value, an _immutable list_ contains items that must never be altered. Its syntax is as follows: 

```pseudo 
var/val listName = listOf(value1, value2, value3) 
```

- For a list to be used and referenced throughout a program, it must be stored in a variable. Make sure to use keywords `val` or `var` in your declaration as well as a descriptive list name. 
- The creation of the Kotlin list begins on the right side of the assignment operator with the term, `listOf`. This indicates an immutable list. 
- The term is then followed by a pair of parentheses that holds a collection of elements separated by commas. 
- Like variable declarations, the type of list can be inferred by the compiler or declared by the user. For example, a list of String values would be referenced as a `List<String>`.  

**Note**: Once initialized as a `List<String>`, the list can _only_ hold String values.  

Keeping the above syntax in mind, let's create an immutable list of String values that represent the countries we've visited: 

```kt
var countriesVisited = listOf("Japan", "Colombia", "Kenya", "Jordan") 
```

Since `countriesVisited`  was declared a mutable variable with the `var` keyword, we can reassign the value of `countriesVisited` to store a different list if we’d like. However, since the list was declared immutable with `listOf`, the contents of the list cannot change. They must always remain `"Japan"`, `"Colombia"`, `"Kenya"`, and `"Jordan"`. 


```kt
println(countriesVisited) 
// Prints: [Japan, Colombia, Kenya, Jordan] 
```

Lastly, when printed to the screen, the list is contained within square brackets as opposed to parentheses.  

We've learned a handful of rules and new concepts in this exercise. Don't get discouraged if it doesn't all stick right away; we'll be getting ample practice throughout this lesson. Keep going, and let's create your first Kotlin list! 📝

Creating an Immutable List 

Every collection in Kotlin contains a series of built-in functions that allow us to perform certain operations in order to retrieve information about the collection or manipulate its values. 

A function that retrieves information about a list would only require read access whereas a function that changes the contents of a list would require both read and write access. As a result of this, a mutable list supports functions that possess read and write functionalities, whereas an immutable list supports functions that possess read-only operations. Let's take a closer look:

**Mutable and immutable list functions:** 
 
```kt 
var vowels = listOf('A', 'E', 'I', 'O', 'U')
```

The `contains()` function accepts a single value within its parentheses and returns a Boolean `true` or `false` depending on whether or not that value exists within a list. It does not need to change the contents of the list, thus it can be used on an immutable list.  

```kt 
println(vowels.contains('A')) // Prints: true
println(vowels.contains('B')) // Prints: false
```

The `random()` function also only requires read-only access and returns a random element from the list: 

```kt 
println(vowels.random()) // Prints: I
```

**Mutable ONLY list functions:** 

```kt
var primeNumbers = mutableListOf(4, 5, 7, 11, 13)  
```

The `add()` function accepts a single value within its parentheses and appends that value to the end of a list: 

```kt
primeNumbers.add(17) 
println(primeNumbers) // Prints: 4, 5, 7, 11, 13, 17
```

Since this function changes the contents of the list, it can only be used on mutable lists. Similarly, the `remove()` function, also only used on mutable lists, accepts a single value within its parentheses and removes it from the list:

```kt 
primeNumbers.remove(4) 
println(primeNumbers) // Prints: 5, 7, 11, 13, 17
```

**Note**: If the value to be removed does not exist, the compiler will not throw an error and simply return `false`. 

These functions are just the tip of the iceberg of what's supported for lists in Kotlin; we encourage you to look through the documentation for [immutable lists](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/#functions) and [mutable lists](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-mutable-list/#functions) to explore other available functionalities. 

List Functions

In Kotlin, the `size` property determines the number of elements within a collection. It is not only applicable to lists but also to other collections that we'll be working with in the coming lessons. 

Similarly to the `length` property for Strings, `size` counts the number of elements in a collection and returns an Integer value. 

Take a look at the following list of major European rivers: 

```kt
val majorRivers = listOf("Volga", "Danube", "Loire", "Rhine", "Elbe") 
```

We can append `size` to `majorRivers` and retrieve the number of elements in the list:
 
```kt 
println(majorRivers.size) // Prints: 5  
```

Additionally, this code can be used to construct an informative String about our list: 

```kt
println("There are ${majorRivers.size} major rivers in Europe.") 
// Prints: There are 5 major rivers in Europe.  
```

Furthermore, `size` can be used along with an element's index to retrieve the last element of a collection: 

```kt 
println(majorRivers[majorRivers.size - 1]) // Prints: Elbe
```

- Within the brackets, `majorRivers.size` equates to `5`. Subtracting `1` from this value results in `4` which becomes the final numerical index within the brackets.
- `majorRivers[4]` returns the 4th and last element in the list, `"Elbe"`. 

This strategy is most commonly used when iterating over a collection or simply grabbing the last element of a list when we don't know how many list elements there are in total. We'll learn more about how to iterate over a collection later in the course.  

The size Property

A collection is of no use to us if we can't access or work with its contents. In order to access the elements within a list, we must reference the element's "index". An _index_ represents a numerical position within a list. 

```kt 
val oakIslandArtifacts = listOf("Lead cross", "Rhodolite garnet brooch", "Gold brooch")
```

Here's a breakdown of the indices of the above list elements: 

Element | Index
--- | ---
"Lead cross" | 0
"Rhodolite garnet brooch" | 1 
"Gold brooch" | 2

Notice how the count begins with `0` and not `1`; this is because Kotlin is a zero-based language and the count in every Kotlin collection begins with `0`.

Keeping these indexed-positions in mind, we can construct the following syntax to access an element: 

```pseudo
listName[index]
```

The name of the list is followed by square brackets which contains the index of the element we need to access. Applying this pseudo code to our previous list,  we can access each element as such: 

```kt 
oakIslandArtifacts[0] // Lead cross
oakIslandArtifacts[1] // Rhodolite garnet brooch
oakIslandArtifacts[2] // Gold brooch
```

Each statement can be wrapped in a `println()` statement to see its output or stored in a variable for later use. 

**Note**: Attempting to access an element within an index that does not exist will result in an error. For instance, if there are `2` elements within a list, and the specified index is `5`, the compiler will throw the following Out of Bound error: 

```error 
java.lang.ArrayIndexOutOfBoundsException: Index 5 out of bounds for length 2
```