Операции, специфичные для карт

Получение ключей и значений

Чтобы получить значение из карты, необходимо передать его ключ в качестве аргумента функции get(). Также поддерживается сокращённый синтаксис [key]. Если указанный ключ не найден, функция возвращает null. Есть также функция getValue(), поведение которой немного отличается: она выбрасывает исключение, если ключ не найден в карте. Кроме того, есть и другие способы обработать отсутствие ключа:

• getOrElse() работает так же, как и для списков: значения для отсутствующих ключей возвращаются из заданной лямбда-функции.

• getOrDefault() возвращает указанное значение по умолчанию, если ключ не найден.

Для карт с nullable-значениями используйте следующие функции, которые явно обрабатывают отсутствующие ключи и значения null:

• getOrElseIfNull() возвращает результат для указанного значения по умолчанию, если ключ отсутствует или имеет значение null.

• getOrElseIfMissing() возвращает результат для указанного значения по умолчанию, если ключ отсутствует.

Ниже приведён пример, показывающий разницу между этими функциями:

@OptIn(ExperimentalStdlibApi::class)
fun main() {
//sampleStart
    val numbersMap = mapOf("one" to 1, "two" to 2, "three" to 3)
    println(numbersMap.get("one"))
    // 1

    println(numbersMap["one"])
    // 1

    println(numbersMap.getOrDefault("four", 10))
    // 10

    println(numbersMap["five"])
    // null
    
    val nullableMap = mapOf("one" to 1, "two" to null)
    println(nullableMap.getOrElseIfNull("two") { 0 })
    // 0

    println(nullableMap.getOrElseIfMissing("two") { 0 })
    // null

    // Throws an exception because "six" is missing from the map
    // numbersMap.getValue("six")

//sampleEnd
}

Чтобы выполнять операции со всеми ключами или значениями карты, можно получить их из свойств keys и values соответственно. keys — это множество всех ключей карты, а values — коллекция всех значений карты.

fun main() {
//sampleStart
    val numbersMap = mapOf("one" to 1, "two" to 2, "three" to 3)
    println(numbersMap.keys)
    println(numbersMap.values)
//sampleEnd
}

Фильтрация

Карты, как и другие коллекции, можно фильтровать с помощью функции filter(). При вызове filter() для карты передайте предикат, принимающий в качестве аргумента Pair. Это позволяет использовать в предикате фильтрации и ключ, и значение.

fun main() {
//sampleStart
    val numbersMap = mapOf("key1" to 1, "key2" to 2, "key3" to 3, "key11" to 11)
    val filteredMap = numbersMap.filter { (key, value) -> key.endsWith("1") && value > 10}
    println(filteredMap)
//sampleEnd
}

Есть также два специальных способа фильтрации карт: по ключам и по значениям. Для каждого из них предусмотрена функция: filterKeys() и filterValues(). Обе функции возвращают новую карту, содержащую записи, соответствующие заданному предикату. Предикат для filterKeys() проверяет только ключи элементов, а предикат для filterValues() — только значения.

fun main() {
//sampleStart
    val numbersMap = mapOf("key1" to 1, "key2" to 2, "key3" to 3, "key11" to 11)
    val filteredKeysMap = numbersMap.filterKeys { it.endsWith("1") }
    val filteredValuesMap = numbersMap.filterValues { it < 10 }

    println(filteredKeysMap)
    println(filteredValuesMap)
//sampleEnd
}

Операторы сложения и вычитания

Благодаря доступу к элементам по ключу операторы plus (+) и minus (-) работают с картами иначе, чем с другими коллекциями. plus возвращает Map, содержащую элементы обоих операндов: слева — Map, а справа — Pair или другую Map. Если правый операнд содержит записи с ключами, которые есть в левой Map, результирующая карта содержит записи из правой стороны.

fun main() {
//sampleStart
    val numbersMap = mapOf("one" to 1, "two" to 2, "three" to 3)
    println(numbersMap + Pair("four", 4))
    println(numbersMap + Pair("one", 10))
    println(numbersMap + mapOf("five" to 5, "one" to 11))
//sampleEnd
}

minus создаёт Map из записей Map слева, кроме записей с ключами из правого операнда. Таким образом, правый операнд может быть как одним ключом, так и коллекцией ключей: списком, множеством и так далее.

fun main() {
//sampleStart
    val numbersMap = mapOf("one" to 1, "two" to 2, "three" to 3)
    println(numbersMap - "one")
    println(numbersMap - listOf("two", "four"))
//sampleEnd
}

Подробнее об использовании операторов plusAssign (+=) и minusAssign (-=) для изменяемых карт см. ниже в разделе Операции записи в карты.

Операции записи в карты

Изменяемые карты предоставляют специфичные для карт операции записи. С их помощью можно изменять содержимое карты, обращаясь к значениям по ключу.

Операции записи в карты подчиняются следующим правилам:

• Значения можно обновлять. Ключи же никогда не меняются: после добавления записи её ключ остаётся неизменным.

• Каждому ключу всегда соответствует одно значение. Можно добавлять и удалять записи целиком.

Ниже описаны функции стандартной библиотеки для операций записи, доступные для изменяемых карт.

fun main() {
//sampleStart
    val numbersMap = mutableMapOf("one" to 1, "two" to 2)
    numbersMap.put("three", 3)
    println(numbersMap)
//sampleEnd
}

fun main() {
//sampleStart
    val numbersMap = mutableMapOf("one" to 1, "two" to 2, "three" to 3)
    numbersMap.putAll(setOf("four" to 4, "five" to 5))
    println(numbersMap)
//sampleEnd
}

fun main() {
//sampleStart
    val numbersMap = mutableMapOf("one" to 1, "two" to 2)
    val previousValue = numbersMap.put("one", 11)
    println("value associated with 'one', before: $previousValue, after: ${numbersMap["one"]}")
    println(numbersMap)
//sampleEnd
}

fun main() {
//sampleStart
    val numbersMap = mutableMapOf("one" to 1, "two" to 2)
    numbersMap["three"] = 3     // calls numbersMap.put("three", 3)
    numbersMap += mapOf("four" to 4, "five" to 5)
    println(numbersMap)
//sampleEnd
}

@OptIn(ExperimentalStdlibApi::class)
fun main() {
//sampleStart
    val mapForNull = mutableMapOf<String, Int?>("one" to null)
    val mapForMissing = mutableMapOf<String, Int?>("one" to null)

    // Replaces the value if "one" has a null value
    mapForNull.getOrPutIfNull("one") { 1 }

    println(mapForNull)
    // {one=1}

    // Keeps the null value because "one" exists in the map
    mapForMissing.getOrPutIfMissing("one") { 1 }

    println(mapForMissing)
    // {one=null}
//sampleEnd
}

fun main() {
//sampleStart
    val numbersMap = mutableMapOf("one" to 1, "two" to 2, "three" to 3)
    numbersMap.remove("one")
    println(numbersMap)
    numbersMap.remove("three", 4)            //doesn't remove anything
    println(numbersMap)
//sampleEnd
}

fun main() {
//sampleStart
    val numbersMap = mutableMapOf("one" to 1, "two" to 2, "three" to 3, "threeAgain" to 3)
    numbersMap.keys.remove("one")
    println(numbersMap)
    numbersMap.values.remove(3)
    println(numbersMap)
//sampleEnd
}

fun main() {
//sampleStart
    val numbersMap = mutableMapOf("one" to 1, "two" to 2, "three" to 3)
    numbersMap -= "two"
    println(numbersMap)
    numbersMap -= "five"             //doesn't remove anything
    println(numbersMap)
//sampleEnd
}