Collection Operations

list[i] throws an error if the index is out of range. getOrNull(i) returns null instead of throwing. getOrElse(i) { ... } returns a value you compute when the index is out of range.

groupBy sorts items into buckets using a key you choose. It returns a map where each key points to a list of all the items that produced that key.

Use sorted() to order items from low to high. Use sortedBy { } to sort by a chosen property. Use sortedDescending() for high to low. All three return a new list and leave the original unchanged.

map turns each element into something else and gives back a new list of the results. filter keeps only the elements that match a condition and gives back a new list. Both leave the original list unchanged.

zip pairs up elements from two lists by position: first with first, second with second, and so on. The result stops at the shorter list, so its length equals the smaller of the two.

all checks every element matches a condition, any checks at least one does, none checks zero do. On an empty list: all is true, any is false, none is true. any() and none() with no argument just test whether the collection has elements.

Both combine elements into one result. fold takes a starting value, so it works on empty collections and can return a different type. reduce uses the first element as the start, so it throws if the collection is empty.

first() returns the first element but throws if the collection is empty. firstOrNull() returns null instead. first { predicate } returns the first matching element (throws if none); find { predicate } is the same but returns null if none match.

All three build a map from a list. associateWith uses elements as keys, associateBy makes elements the values under a chosen key, and associate lets you build both key and value. If two keys collide, the last one wins.

compareBy builds a comparator from a property. thenBy adds a tie-breaker used only when the previous keys are equal. Use thenByDescending to reverse one of those keys. Pass the result to sortedWith.

flatten takes a list of lists and merges them into one flat list. flatMap first turns each element into a list (or any iterable) and then merges all those into one flat list. Use flatten when you already have nested lists; flatMap when you produce the nested lists yourself.

chunked(n) cuts a list into non-overlapping blocks of n. windowed(size, step) slides a window of size, moving by step each time, so windows can overlap. chunked(n) equals windowed(n, n) but also keeps a smaller final chunk.

partition splits a collection into two lists based on a true/false test: a Pair where the first list holds items that match and the second holds those that don't. It does it in one pass.

mapIndexed transforms each element while also giving you its position number, starting at 0. So you can use both the index and the value to build each result.

Instead of one final value, they return the list of every intermediate accumulator value. runningFold starts with your seed; runningReduce starts with the first element. scan is just another name for runningFold.

single() returns the only element and throws if the collection is empty OR has more than one. singleOrNull() returns null in both of those cases. The predicate versions do the same but for elements matching a condition.

chunked breaks a collection into consecutive, non-overlapping pieces of a fixed size. The last piece may be smaller if items run out. A second form lets you transform each piece as it's made.

sort() and sortWith() rearrange an existing mutable list and return nothing. sorted() and sortedWith() make a new sorted list and leave the original alone. Use in-place to save memory; use copying when the original must stay intact or the list is read-only.

mapNotNull transforms each element but throws away any results that come out null. It is handy when a step can fail or skip values, letting you map and drop nulls in one pass instead of two.

flatten takes a list of lists and concatenates them into one flat list, one level deep. flatMap maps each element to a collection and then flattens in a single step — so flatMap(f) equals map(f).flatten().

zipWithNext pairs each element with the one right after it: (a,b), (b,c), (c,d). For n elements you get n-1 pairs. It is handy for comparing neighbors, like spotting where values change or computing gaps between them.

On big data, chaining maps before aggregating with a List creates extra lists; using asSequence avoids that. Summing many Ints can silently overflow, so sum into Long. minByOrNull returns the element with the smallest key; minOfOrNull returns the smallest key value itself.

x in list (or list.contains(x)) checks if an element is present. indexOf(x) returns its position or -1 if absent. indexOfFirst { } finds the position of the first element matching a condition, or -1. Sets and maps check membership much faster than lists.

take(n) keeps the first n elements; drop(n) skips them. takeLast/dropLast work from the end. The While versions cut at the first element that fails a condition. slice picks elements by index range or list. They return new collections and don't mutate.

Use groupingBy().eachCount() when you only need counts per key. It tallies directly into a map of counts instead of building lists first, so it's more efficient. Grouping also supports custom fold/reduce per group.

reversed() flips the current order into a new list. asReversed() gives a live reversed view without copying. sortedDescending() actually sorts from high to low. Reversing a list is not the same as sorting it descending.

filterIsInstance keeps only the elements that are of a given type and gives you back a list already typed as that type, so you do not have to cast each one yourself. It needs the type known at compile time to do this safely.

On a List these operators run eagerly and build all the result lists at once. On a Sequence they are lazy and produce windows/chunks on demand, so you can process huge or streaming data without holding everything in memory.

The *To versions do the same transform but write the results into a collection you supply, instead of creating a brand-new list. You use them when you want to control the destination type or gather results from several sources into one collection.