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

В картах типы как ключей, так и значений определяются пользователем. Доступ к элементам карты по ключу позволяет использовать различные возможности обработки карт, от получения значения по ключу до отдельного фильтрации ключей и значений. На этой странице мы предоставляем описания функций обработки карт из стандартной библиотеки.

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

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

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

fun main() {
//sampleStart
    val numbersMap = mapOf("one" to 1, "two" to 2, "three" to 3)
    println(numbersMap.get("one"))
    println(numbersMap["one"])
    println(numbersMap.getOrDefault("four", 10))
    println(numbersMap["five"])               // null
    //numbersMap.getValue("six")      // exception!
//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 (+) и 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 (-=) на изменяемых картах см. ниже в разделе Операции записи для карт.

Операции записи для карт

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

Существуют определённые правила, определяющие операции записи для карт:

• Значения могут обновляться. В свою очередь, ключи никогда не меняются: после добавления элемента его ключ остается постоянным.
• Для каждого ключа всегда существует единственное связанное с ним значение. Вы можете добавлять и удалять целые записи.

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

Добавление и обновление записей

Чтобы добавить новую пару ключ-значение в изменяемую карту, используйте put(). При добавлении новой записи в LinkedHashMap (стандартная реализация карты) она добавляется так, что при итерации по карте появляется последней. В отсортированных картах позиции новых элементов определяются порядком их ключей.

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

Чтобы добавить несколько записей одновременно, используйте putAll(). Ее аргументом может быть Map или группа Pair: Iterable, Sequence, или Array.

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
}

И put() и putAll() перезаписывают значения, если заданные ключи уже существуют в карте. Таким образом, вы можете использовать их для обновления значений элементов карты.

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
}

Вы также можете добавлять новые записи в карты с помощью сокращенной формы оператора. Есть два способа:

• Оператор plusAssign (+=)
• Псевдоним оператора [] для set().

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

При вызове с ключом, присутствующим в карте, операторы перезаписывают значения соответствующих записей.

Удаление записей

Чтобы удалить запись из изменяемой карты, используйте функцию remove(). При вызове remove() вы можете передать либо ключ, либо целую пару ключ-значение. Если вы укажете ключ и значение, элемент с этим ключом будет удален только в том случае, если его значение совпадает со вторым аргументом.

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
}

Вы также можете удалять записи из изменяемой карты по их ключам или значениям. Для этого вызовите remove() для ключей или значений карты, передав ключ или значение элемента. При вызове по значениям remove() удаляет только первый элемент с заданным значением.

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
}

Оператор minusAssign (-=) также доступен для изменяемых карт.

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
}