コレクションの書き込み操作

可変コレクションは、コレクションの内容を変更するための操作、例えば要素の追加や削除などをサポートしています。 このページでは、MutableCollectionのすべての実装で利用可能な書き込み操作について説明します。 ListおよびMapに特化した操作については、それぞれリストに特化した操作とマップに特化した操作を参照してください。

要素の追加

リストまたはセットに単一の要素を追加するには、add()関数を使用します。指定されたオブジェクトはコレクションの末尾に追加されます。

fun main() {
    val numbers = mutableListOf(1, 2, 3, 4)
    numbers.add(5)
    println(numbers)
}

addAll()は、引数オブジェクトのすべての要素をリストまたはセットに追加します。引数にはIterable、Sequence、またはArrayを指定できます。 レシーバーと引数の型は異なっていても構いません。例えば、Setのすべての項目をListに追加できます。

リストに対して呼び出すと、addAll()は、引数に渡されたのと同じ順序で新しい要素を追加します。 addAll()を呼び出す際に、最初の引数として要素の位置を指定することもできます。 引数コレクションの最初の要素がこの位置に挿入されます。 引数コレクションの他の要素はそれに続き、レシーバー要素を末尾にシフトします。

fun main() {
    val numbers = mutableListOf(1, 2, 5, 6)
    numbers.addAll(arrayOf(7, 8))
    println(numbers)
    numbers.addAll(2, setOf(3, 4))
    println(numbers)
}

plus演算子のインプレースバージョンであるplusAssign (+=) を使用して要素を追加することもできます。 可変コレクションに適用されると、+=は、2番目のオペランド（要素または別のコレクション）をコレクションの末尾に追加します。

fun main() {
    val numbers = mutableListOf("one", "two")
    numbers += "three"
    println(numbers)
    numbers += listOf("four", "five")    
    println(numbers)
}

要素の削除

可変コレクションから要素を削除するには、remove()関数を使用します。 remove()は要素の値を受け取り、この値の1つの出現箇所を削除します。

fun main() {
    val numbers = mutableListOf(1, 2, 3, 4, 3)
    numbers.remove(3)                    // removes the first `3`
    println(numbers)
    numbers.remove(5)                    // removes nothing
    println(numbers)
}

複数の要素を一度に削除するには、以下の関数があります:

• removeAll()は、引数コレクション内に存在するすべての要素を削除します。 あるいは、述語を引数として呼び出すこともできます。この場合、関数は述語がtrueを返すすべての要素を削除します。
• retainAll()はremoveAll()の反対です。引数コレクションからの要素を除くすべての要素を削除します。 述語とともに使用すると、それに一致する要素のみを残します。
• clear()はリストからすべての要素を削除し、空にします。

fun main() {
    val numbers = mutableListOf(1, 2, 3, 4)
    println(numbers)
    numbers.retainAll { it >= 3 }
    println(numbers)
    numbers.clear()
    println(numbers)

    val numbersSet = mutableSetOf("one", "two", "three", "four")
    numbersSet.removeAll(setOf("one", "two"))
    println(numbersSet)
}

コレクションから要素を削除するもう1つの方法は、minusAssign (-=) 演算子を使用することです。これはminusのインプレースバージョンです。 2番目の引数には、要素型の単一のインスタンスまたは別のコレクションを指定できます。 右側に単一の要素がある場合、-=は、その要素の_最初の_出現箇所を削除します。 一方、コレクションである場合は、その要素の_すべて_の出現箇所が削除されます。 例えば、リストに重複する要素が含まれている場合、それらは一度に削除されます。 2番目のオペランドには、コレクション内に存在しない要素が含まれていても構いません。そのような要素は操作の実行に影響を与えません。

fun main() {
    val numbers = mutableListOf("one", "two", "three", "three", "four")
    numbers -= "three"
    println(numbers)
    numbers -= listOf("four", "five")    
    //numbers -= listOf("four")    // does the same as above
    println(numbers)    
}

要素の更新

リストとマップは要素を更新するための操作も提供します。 それらはリストに特化した操作とマップに特化した操作で説明されています。 セットの場合、実際には要素を削除して別の要素を追加する操作であるため、更新は意味をなしません。