kotlin.collectionsのflatten()の使い方

kotlin.collectionsにflatten()というfunctionがあります。
公式ドキュメントには「与えられたコレクション・配列内の全てのコレクション・配列から、全ての要素の単一リストを返す」と記載されています。
つまり、ネストされているコレクション・配列をフラットなリストに変換するためのfunctionです。

利用シーンとしては、タブ形式などで月ごとに表示されたデータがあり、それらを編集し、まとめて保存したいときなどが考えられます。

以下は、簡易的な日付データを例に、ネストされているリストにflatten()を適用すると、リストの構造がどのように変化するかを示したサンプルとなります。

// 日付クラス
data class Date(val month: Int, val day: Int)

// 月ごとの日付リスト
val january: List<Date> = (1..31).map { Date(1, it) }
val february: List<Date> = (1..28).map { Date(2, it) }
val march: List<Date> = (1..31).map { Date(3, it) }
val april: List<Date> = (1..30).map { Date(4, it) }
val may: List<Date> = (1..31).map { Date(5, it) }
val june: List<Date> = (1..30).map { Date(6, it) }
val july: List<Date> = (1..31).map { Date(7, it) }
val august: List<Date> = (1..31).map { Date(8, it) }
val september: List<Date> = (1..30).map { Date(9, it) }
val october: List<Date> = (1..31).map { Date(10, it) }
val november: List<Date> = (1..30).map { Date(11, it) }
val december: List<Date> = (1..31).map { Date(12, it) }

// 月ごとの日付リストのリスト = 1年間の日付リスト
val annualDateList: List<List<Date>> = listOf(january, february, march, april, may, june, july, august, september, october, november, december)

/********** ネストされている日付データ **********/
println(annualDateList)
// => [[Date(month=1, day=1), Date(month=1, day=2), …, Date(month=1, day=31)], [Date(month=2, day=1), …, Date(month=12, day=31)]]

println("1年: ${annualDateList.size}ヶ月")
// => 1年: 12ヶ月

annualDateList.forEach { println("${it.first().month}月: ${it.size}日") }
// => 1月: 31日
// => 2月: 28日
// => …
// => 12月: 31日

/********** フラットな日付データ **********/
println(annualDateList.flatten())
// => [Date(month=1, day=1), Date(month=1, day=2),  …, Date(month=1, day=31), Date(month=2, day=1), …, Date(month=12, day=31)]
// これは `annualDateList.flatMap { it }` と同じ

println("1年: ${annualDateList.flatten().size}日")
// => 1年: 365日