Gleam List Functions

The gleam/list module provides a comprehensive set of functions for processing lists. These functions cover searching, grouping, combining, and transforming — handling the most common list operations without requiring you to write custom recursion.

Building and Combining Lists

import gleam/list

let a = [1, 2, 3]
let b = [4, 5, 6]

let combined = list.append(a, b)       // [1, 2, 3, 4, 5, 6]
let flat = list.flatten([[1,2],[3,4]]) // [1, 2, 3, 4]
let repeated = list.repeat(0, 4)       // [0, 0, 0, 0]
let range = list.range(1, 6)           // [1, 2, 3, 4, 5]

list.range(1, 6)
──────────────────────────────────────────────────
Start at 1, stop before 6:
[1, 2, 3, 4, 5]

Searching and Finding

let fruits = ["apple", "banana", "cherry", "date"]

let found = list.find(fruits, fn(f) { string.starts_with(f, "c") })
// Ok("cherry")

let pos = list.index_of(fruits, "banana")
// Ok(1)

let has = list.contains(fruits, "mango")
// False

let any_long = list.any(fruits, fn(f) { string.length(f) > 5 })
// True  (banana=6, cherry=6)

let all_short = list.all(fruits, fn(f) { string.length(f) < 10 })
// True

Grouping and Partitioning

let numbers = [1, 2, 3, 4, 5, 6, 7, 8]

let #(evens, odds) = list.partition(numbers, fn(n) { n % 2 == 0 })
// evens = [2, 4, 6, 8]
// odds  = [1, 3, 5, 7]

list.partition Visual
──────────────────────────────────────────────────
[1, 2, 3, 4, 5, 6, 7, 8]
       │
  split by n % 2 == 0
  ┌────┴────┐
  │         │
[2,4,6,8] [1,3,5,7]
evens      odds

import gleam/list

let words = ["cat", "car", "dog", "can", "dig"]

let grouped = list.group(words, fn(w) { string.slice(w, 0, 1) })
// Map with keys "c" and "d"
// "c" → ["cat", "car", "can"]
// "d" → ["dog", "dig"]

Transforming with Index

let items = ["Mon", "Tue", "Wed"]

let indexed = list.index_map(items, fn(item, i) {
  int.to_string(i + 1) <> ". " <> item
})
// ["1. Mon", "2. Tue", "3. Wed"]

Zipping and Unzipping

let names  = ["Alice", "Bob", "Carol"]
let scores = [90, 78, 95]

let pairs = list.zip(names, scores)
// [#("Alice", 90), #("Bob", 78), #("Carol", 95)]

let #(ns, ss) = list.unzip(pairs)
// ns = ["Alice", "Bob", "Carol"]
// ss = [90, 78, 95]

Taking and Dropping

let data = [10, 20, 30, 40, 50]

list.take(data, 3)     // [10, 20, 30]
list.drop(data, 2)     // [30, 40, 50]

list.take_while(data, fn(n) { n < 35 })  // [10, 20, 30]
list.drop_while(data, fn(n) { n < 35 })  // [40, 50]

Unique and Deduplication

let dupes = [1, 2, 2, 3, 1, 4, 3]
let unique = list.unique(dupes)
// [1, 2, 3, 4]

flat_map — map then flatten

let sentences = ["hello world", "foo bar"]
let words = list.flat_map(sentences, fn(s) { string.split(s, " ") })
// ["hello", "world", "foo", "bar"]

flat_map Diagram
──────────────────────────────────────────────────
["hello world", "foo bar"]
  ↓ map each to split result
[["hello","world"], ["foo","bar"]]
  ↓ flatten
["hello", "world", "foo", "bar"]

Practical Example — Leaderboard

import gleam/list
import gleam/io

type Player { Player(name: String, score: Int) }

pub fn top_3(players: List(Player)) -> List(Player) {
  players
  |> list.sort(fn(a, b) {
       case a.score > b.score {
         True  -> order.Lt
         False -> case a.score < b.score { True -> order.Gt; False -> order.Eq }
       }
     })
  |> list.take(3)
}

pub fn main() {
  let players = [
    Player("Arun", 450),
    Player("Bhavna", 820),
    Player("Chetan", 610),
    Player("Deepa", 910),
    Player("Eshan", 730)
  ]
  let board = top_3(players)
  list.each(board, fn(p) {
    io.println(p.name <> ": " <> int.to_string(p.score))
  })
  // Deepa: 910
  // Bhavna: 820
  // Eshan: 730
}

Quick Reference

list Module Cheat Sheet
──────────────────────────────────────────────────
Building:   append, flatten, repeat, range, zip
Searching:  find, contains, any, all, index_of
Selecting:  take, drop, take_while, drop_while, filter
Transforming: map, flat_map, index_map, map_fold
Grouping:   partition, group, chunk
Combining:  fold, fold_right
Info:       length, first, last, is_empty
Other:      reverse, sort, unique, shuffle, unzip

The list module removes the need to write custom recursion for routine operations. Use these functions first — they are well-tested, readable, and efficient. Write custom recursion only when the standard functions do not cover your specific logic.