From 79457ceafe60915d80bec08f26d963c381568c9f Mon Sep 17 00:00:00 2001 From: Sebastian Aigner Date: Thu, 16 Nov 2023 03:04:06 +0100 Subject: [PATCH 1/2] Put emphasis on enum `entries` rather than `values()` --- docs/topics/enum-classes.md | 26 +++++++------------------- 1 file changed, 7 insertions(+), 19 deletions(-) diff --git a/docs/topics/enum-classes.md b/docs/topics/enum-classes.md index 14bd88e34c9..ca87b9a71ce 100644 --- a/docs/topics/enum-classes.md +++ b/docs/topics/enum-classes.md @@ -66,7 +66,7 @@ enum class IntArithmetics : BinaryOperator, IntBinaryOperator { fun main() { val a = 13 val b = 31 - for (f in IntArithmetics.values()) { + for (f in IntArithmetics.entries) { println("$f($a, $b) = ${f.apply(a, b)}") } } @@ -78,21 +78,21 @@ interface by default. Constants in the enum class are defined in the natural ord ## Working with enum constants -Enum classes in Kotlin have synthetic methods for listing the defined enum constants and getting an enum constant by +Enum classes in Kotlin have synthetic properties and methods for listing the defined enum constants and getting an enum constant by its name. The signatures of these methods are as follows (assuming the name of the enum class is `EnumClass`): ```kotlin EnumClass.valueOf(value: String): EnumClass -EnumClass.values(): Array +EnumClass.entries: EnumEntries // specialized List ``` -Below is an example of these methods in action: +Below is an example of them in action: ```kotlin enum class RGB { RED, GREEN, BLUE } fun main() { - for (color in RGB.values()) println(color.toString()) // prints RED, GREEN, BLUE + for (color in RGB.entries) println(color.toString()) // prints RED, GREEN, BLUE println("The first color is: ${RGB.valueOf("RED")}") // prints "The first color is: RED" } ``` @@ -101,19 +101,7 @@ fun main() { The `valueOf()` method throws an `IllegalArgumentException` if the specified name does not match any of the enum constants defined in the class. -In Kotlin 1.9.0, the `entries` property is introduced as a replacement for the `values()` function. The -`entries` property returns a pre-allocated immutable list of your enum constants. This is particularly useful when you -are working with [collections](collections-overview.md) and can help you avoid [performance issues](https://github.com/Kotlin/KEEP/blob/master/proposals/enum-entries.md#examples-of-performance-issues). - -For example: -```kotlin -enum class RGB { RED, GREEN, BLUE } - -fun main() { - for (color in RGB.entries) println(color.toString()) - // prints RED, GREEN, BLUE -} -``` +Prior to the introduction of `entries` in Kotlin 1.9.0, the `values()` function was used to retrieve an array of enum constants. Every enum constant also has properties: [`name`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-enum/name.html) and [`ordinal`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-enum/ordinal.html), for obtaining its name and @@ -172,4 +160,4 @@ printAllValues() > The `enumEntries()` function is Experimental. To use it, opt in with `@OptIn(ExperimentalStdlibApi)`, and > [set the language version to at least 1.9](gradle-compiler-options.md#attributes-common-to-jvm-and-js). > -{type="warning"} \ No newline at end of file +{type="warning"} From b9178103651f2d89087e6c6c5b607634da61fe8f Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Thu, 23 Nov 2023 17:03:41 +0100 Subject: [PATCH 2/2] sarah review --- docs/topics/enum-classes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/topics/enum-classes.md b/docs/topics/enum-classes.md index ca87b9a71ce..8fe64287ac9 100644 --- a/docs/topics/enum-classes.md +++ b/docs/topics/enum-classes.md @@ -71,7 +71,7 @@ fun main() { } } ``` -{kotlin-runnable="true"} +{kotlin-runnable="true" kotlin-min-compiler-version="1.9"} All enum classes implement the [Comparable](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-comparable/index.html) interface by default. Constants in the enum class are defined in the natural order. For more information, see [Ordering](collection-ordering.md). @@ -96,7 +96,7 @@ fun main() { println("The first color is: ${RGB.valueOf("RED")}") // prints "The first color is: RED" } ``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="rgb-enums-kotlin"} +{kotlin-runnable="true" kotlin-min-compiler-version="1.9" id="rgb-enums-kotlin"} The `valueOf()` method throws an `IllegalArgumentException` if the specified name does not match any of the enum constants defined in the class. @@ -112,7 +112,7 @@ enum class RGB { RED, GREEN, BLUE } fun main() { //sampleStart - println(RGB.RED.name) // prints RED + println(RGB.RED.name) // prints RED println(RGB.RED.ordinal) // prints 0 //sampleEnd }