core/map

Map

Map represents an associative collection of unique keys mapped to corresponding values. Autolang supports intuitive declaration using the infix to operator, fast index access, safe lookups with fallback defaults, and destructured entry iteration.

Initialization & The Infix Operator

Use mapOf() and mutableMapOf() with the infix to operator to declare key-value pairs, or initialize an empty map using Map<K, V>().

// Initialize map with infix to operator
val systemConfig = mapOf(
    "env" to "production",
    "region" to "us-east-1",
    "maxRetries" to 3
)

// Constructor initialization
val balances = Map<String, Int>()
balances.put("ACC-001", 1500)
balances.put("ACC-002", 3200)

println("System config size: " + systemConfig.size)
println("Balances size: " + balances.size)

Lookups & Mutation

Access values using bracket indexing map[key] or the get() method. Autolang provides get(key, default) for missing key fallbacks, along with update() to merge another map in-place.

val settings = Map<String, Int>()
settings.put("timeout", 30)
settings.put("retryLimit", 5)

// 1. Lookups with default fallbacks
val timeoutVal = settings.get("timeout", 10)
val cacheTtl = settings.get("cacheTtl", 3600) // Absent key -> returns fallback 3600

println("Timeout: " + timeoutVal) // 30
println("Cache TTL: " + cacheTtl) // 3600

// 2. Bulk updates and overwriting with update()
val overrides = Map<String, Int>()
overrides.put("timeout", 60)
overrides.put("concurrency", 16)

settings.update(overrides)
println("Updated timeout: " + settings.get("timeout", 0)) // 60
println("Concurrency: " + settings.get("concurrency", 0)) // 16

// 3. Compute and insert if absent
val dynamicMap = Map<String, String>()
val endpoint = dynamicMap.getOrPut("host") { "https://api.internal" }
println("Host endpoint: " + endpoint)

Iteration & Destructuring

The for loop natively destructures (key, value) pairs. You can also extract individual collections via items(), keys(), and values().

val departmentBudgets = mapOf(
    "HR" to 50000,
    "IT" to 120000,
    "Marketing" to 80000
)

// Direct destructuring iteration (key, value)
var totalBudget = 0
for ((dept, budget) in departmentBudgets) {
    totalBudget += budget
}
println("Total budget: " + totalBudget) // 250000

// Extract entries collection
val entries = departmentBudgets.items()
println("Entries count: " + entries.size())

Method Reference

Lookups & Inspection

size: Int / size(): Int: Number of key-value pairs.
containsKey(key: K): Bool: Checks whether key is present in the map.
containsValue(value: V): Bool: Checks whether value is present in the map.
get(key: K): V?: Retrieves value for key (returns null if absent).
get(key: K, defaultValue: V): V: Retrieves value for key with fallback default.
getOrPut(key: K, defaultValue: () -> V): V: Returns existing value or evaluates and stores default if absent.
keys(): Array<K>: Returns array of all keys.
values(): Array<V>: Returns array of all values.
items(): Array<MapEntry<K, V>>: Returns array of map entry items.

Mutation & Merging

put(key: K, value: V): V?: Associates key with value.
update(other: Map<K, V>): Merges all entries from another map into this map.
remove(key: K): V?: Removes key-value pair by key.
clear(): Removes all entries from the map.