From 388b34a79efe39140b77eb79d1fd5e1002f5850b Mon Sep 17 00:00:00 2001 From: Margret Riegert Date: Thu, 10 Aug 2023 23:00:42 -0400 Subject: [PATCH 1/5] Better enum symbol casting documentation --- docs/syntax_and_semantics/enum.md | 35 ++++++++++--------------------- 1 file changed, 11 insertions(+), 24 deletions(-) diff --git a/docs/syntax_and_semantics/enum.md b/docs/syntax_and_semantics/enum.md index 2a0f55eb2..a47241c29 100644 --- a/docs/syntax_and_semantics/enum.md +++ b/docs/syntax_and_semantics/enum.md @@ -1,5 +1,7 @@ # Enums +This page is for [Crystal enums](https://crystal-lang.org/api/Enum.html). For C enums, see [C bindings enum](c_bindings/enum.md). + An enum is a set of integer values, where each value has an associated name. For example: ```crystal @@ -117,37 +119,22 @@ Class variables are allowed, but instance variables are not. ## Usage -Enums are a type-safe alternative to [Symbol](https://crystal-lang.org/api/Symbol.html). For example, an API's method can specify a [type restriction](type_restrictions.md) using an enum type: +When a method parameter has an enum [type restriction](type_restrictions.md), it accepts either an enum constant or a Symbol. The Symbol will be automatically cast to an enum constant, raising a compile-time error if casting fails. ```crystal def paint(color : Color) - case color - when Color::Red - # ... - else - # Unusual, but still can happen - raise "unknown color: #{color}" - end + puts "Painting using the color #{color}" end paint Color::Red -``` - -The above could also be implemented with a Symbol: -```crystal -def paint(color : Symbol) - case color - when :red - # ... - else - raise "unknown color: #{color}" - end -end +paint :red # automatically casts to `Color::Red` -paint :red +# compile-time error: +# expected argument #1 to 'paint' to match a member of enum Color +# +# Options are: :red, :green and :blue +paint :yellow ``` -However, if the programmer makes a typo, say `:reed`, the error will only be caught at runtime, while attempting to use `Color::Reed` will result in a compile-time error. - -The recommended thing to do is to use enums whenever possible, only use symbols for the internal implementation of an API, and avoid symbols for public APIs. But you are free to do what you want. +The same automatic casting does not apply to case statements. To use enums with case statements, see [case enum values](case.html#enum-values). From 54ed9325613c2af8afd78be3cad262ebcf5eeac0 Mon Sep 17 00:00:00 2001 From: Margret Riegert Date: Thu, 10 Aug 2023 23:03:29 -0400 Subject: [PATCH 2/5] Fix link extension --- docs/syntax_and_semantics/enum.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax_and_semantics/enum.md b/docs/syntax_and_semantics/enum.md index a47241c29..2dde94ab5 100644 --- a/docs/syntax_and_semantics/enum.md +++ b/docs/syntax_and_semantics/enum.md @@ -137,4 +137,4 @@ paint :red # automatically casts to `Color::Red` paint :yellow ``` -The same automatic casting does not apply to case statements. To use enums with case statements, see [case enum values](case.html#enum-values). +The same automatic casting does not apply to case statements. To use enums with case statements, see [case enum values](case.md#enum-values). From 38be3afd9526b5f5cd2812cee3e9fdaaf1b53d7d Mon Sep 17 00:00:00 2001 From: Margret Riegert Date: Mon, 14 Aug 2023 19:36:41 -0400 Subject: [PATCH 3/5] Update docs/syntax_and_semantics/enum.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Johannes Müller --- docs/syntax_and_semantics/enum.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/syntax_and_semantics/enum.md b/docs/syntax_and_semantics/enum.md index 2dde94ab5..1b63433a5 100644 --- a/docs/syntax_and_semantics/enum.md +++ b/docs/syntax_and_semantics/enum.md @@ -1,6 +1,7 @@ # Enums -This page is for [Crystal enums](https://crystal-lang.org/api/Enum.html). For C enums, see [C bindings enum](c_bindings/enum.md). +!!! note + This page is for [Crystal enums](https://crystal-lang.org/api/Enum.html). For C enums, see [C bindings enum](c_bindings/enum.md). An enum is a set of integer values, where each value has an associated name. For example: From 112ddbe25b233ab42dfd23f3bd0f9b8494a6084a Mon Sep 17 00:00:00 2001 From: Margret Riegert Date: Mon, 14 Aug 2023 19:36:57 -0400 Subject: [PATCH 4/5] Update docs/syntax_and_semantics/enum.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Johannes Müller --- docs/syntax_and_semantics/enum.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax_and_semantics/enum.md b/docs/syntax_and_semantics/enum.md index 1b63433a5..c7511f02c 100644 --- a/docs/syntax_and_semantics/enum.md +++ b/docs/syntax_and_semantics/enum.md @@ -120,7 +120,7 @@ Class variables are allowed, but instance variables are not. ## Usage -When a method parameter has an enum [type restriction](type_restrictions.md), it accepts either an enum constant or a Symbol. The Symbol will be automatically cast to an enum constant, raising a compile-time error if casting fails. +When a method parameter has an enum [type restriction](type_restrictions.md), it accepts either an enum constant or a [symbol](literals/symbol.md). The symbol will be automatically cast to an enum constant, raising a compile-time error if casting fails. ```crystal def paint(color : Color) From 4c6e9fc372a83ee874f19012da234fad61073648 Mon Sep 17 00:00:00 2001 From: Margret Riegert Date: Mon, 14 Aug 2023 19:37:09 -0400 Subject: [PATCH 5/5] Update docs/syntax_and_semantics/enum.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Johannes Müller --- docs/syntax_and_semantics/enum.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/syntax_and_semantics/enum.md b/docs/syntax_and_semantics/enum.md index c7511f02c..a34ee7689 100644 --- a/docs/syntax_and_semantics/enum.md +++ b/docs/syntax_and_semantics/enum.md @@ -131,11 +131,7 @@ paint Color::Red paint :red # automatically casts to `Color::Red` -# compile-time error: -# expected argument #1 to 'paint' to match a member of enum Color -# -# Options are: :red, :green and :blue -paint :yellow +paint :yellow # Error: expected argument #1 to 'paint' to match a member of enum Color ``` The same automatic casting does not apply to case statements. To use enums with case statements, see [case enum values](case.md#enum-values).