Add Text.to_decimal (#10874)

Add `Text.to_decimal`.
Also makes renames `Decimal.with_scale` to `set_scale` and makes it public.

CHANGELOG.md

@@ -31,6 +31,7 @@
   attach warnings.][10725]
 - [Support for creating Atoms in expressions.][10820]
 - [IO.print without new line][10858]
+- [Add `Text.to_decimal`.][10874]
 - [Added .floor, .ceil, .trunc to the in-memory Decimal column.][10887]
 
 [10614]: https://github.com/enso-org/enso/pull/10614
@@ -40,6 +41,7 @@
 [10725]: https://github.com/enso-org/enso/pull/10725
 [10820]: https://github.com/enso-org/enso/pull/10820
 [10858]: https://github.com/enso-org/enso/pull/10858
+[10874]: https://github.com/enso-org/enso/pull/10874
 [10887]: https://github.com/enso-org/enso/pull/10887
 
 #### Enso Language & Runtime

distribution/lib/Standard/Base/0.0.0-dev/src/Data/Decimal.enso

@@ -38,7 +38,7 @@ polyglot java import org.enso.base.numeric.Decimal_Utils
    A `Decimal` value is represented internally by a Java `BigInteger` "unscaled
    value" and a "scale value". The numerical value of the `Decimal` is
    `(unscaledValue * 10^(-scale))`. Scale values are maintained automatically by
-   the constructors and numerical operations.
+   the constructors and numerical operations, but can also be set explicitly.
 
    Scale values can allow distinctions between values that would be identical as
    `Float`s. For example, the following values have different internal
@@ -1158,11 +1158,52 @@ type Decimal
     scale : Integer
     scale self -> Integer = self.big_decimal.scale
 
-    ## PRIVATE
+    ## ADVANCED
-    with_scale : Integer -> Decimal
+       GROUP Math
-    private with_scale self new_scale:Integer -> Decimal =
+       ICON math
-        if self.scale == new_scale then self else
+       Change the scale of a Decimal.
-            Decimal.Value (self.big_decimal.setScale new_scale)
+
+       A `Decimal` value is represented internally by a Java `BigInteger` "unscaled
+       value" and a "scale value". The numerical value of the `Decimal` is
+       `(unscaledValue * 10^(-scale))`. Scale values are maintained automatically by
+       the constructors and numerical operations, but can also be set explicitly.
+
+       Scale values can allow distinctions between values that would be identical as
+       `Float`s. For example, the following values have different internal
+       representations:
+
+           a = Decimal.new "2.0"
+           b = Decimal.new "2.00"
+           a == b
+           # => True
+
+       These two values have different internal representations, but they are still
+       considered the same value by `==`.
+
+       ! Error Conditions
+
+           - If an explicit `scale` parameter is passed, and the scale is not
+             large enough to represent the number exactly, an `Arithmetic_Error`
+             is thrown.
+
+       > Example
+         Set the scale of a `Decimal`
+
+             d = dec "23.456" set_scale 4
+             d.internal_representation
+             # => [234560, 6, 4]
+
+       > Example
+         Get an error when using a scale that is too small.
+         (A scale of 2 is not enough to represent three decimal places.)
+
+             dec "23.456" set_scale 2
+             # => Arithmetic_Error
+    set_scale : Integer -> Decimal
+    set_scale self new_scale:Integer -> Decimal =
+        handle_java_exception <|
+            if self.scale == new_scale then self else
+                Decimal.Value (self.big_decimal.setScale new_scale)
 
     ## PRIVATE
     unscaled_value : Integer

distribution/lib/Standard/Base/0.0.0-dev/src/Data/Json/Extensions.enso

@@ -81,7 +81,7 @@ Decimal.from (that:JS_Object) =
         True ->
             math_context = Math_Context.new (that.at "precision")
             raw_value = Decimal.from_text (that.at "value") math_context
-            raw_value.with_scale (that.at "scale")
+            raw_value.set_scale (that.at "scale")
         False -> Error.throw (Illegal_Argument.Error "Invalid JS_Object for Decimal.")
 
 ## PRIVATE

distribution/lib/Standard/Base/0.0.0-dev/src/Data/Text/Extensions.enso

@@ -1,4 +1,5 @@
 import project.Any.Any
+import project.Data.Decimal.Decimal
 import project.Data.Index_Sub_Range.Index_Sub_Range
 import project.Data.Locale.Locale
 import project.Data.Range.Range
@@ -1894,6 +1895,46 @@ Text.parse_time_of_day self format:Date_Time_Formatter=Date_Time_Formatter.iso_t
 Text.parse_time_zone : Time_Zone ! Time_Error
 Text.parse_time_zone self = Time_Zone.parse self
 
+## GROUP Conversions
+   ICON convert
+   Convert this `Text` to a `Decimal`.
+
+   Arguments:
+   - scale: the optional Decimal scale to use. See `Decimal.set_scale` for more
+     information about Decimal scales. If this argument is not used, the default
+     scale is used.
+
+   > Example
+     Convert a `Text` to a `Decimal`.
+
+         d = "23.456".to_decimal
+         d == Decimal.new "23.456"
+         # => True
+
+    ! Error Conditions
+
+        - If an explicit `scale` parameter is passed, and the scale is not
+          large enough to represent the number exactly, an `Arithmetic_Error`
+          is thrown.
+
+   > Example
+     Convert a `Text` to a `Decimal` with an explicit scale.
+
+         d = "23.456".to_decimal scale=4
+         d == Decimal.new "23.456"
+         # => True
+
+   > Example
+     Get an error when using a scale that is too small.
+
+         "23.456".to_decimal scale=2
+         # => Arithmetic_Error
+Text.to_decimal : Integer | Nothing -> Decimal
+Text.to_decimal self (scale : Integer | Nothing = Nothing) -> Decimal =
+    d_unscaled = Decimal.from_text self
+    if scale == Nothing then d_unscaled else
+        d_unscaled.set_scale scale
+
 ## ALIAS mid, slice, substring
    GROUP Selections
    ICON split

test/Base_Tests/src/Data/Decimal_Spec.enso

@@ -1047,6 +1047,29 @@ add_specs suite_builder =
             d.unscaled_value . should_equal 123456
             d.internal_representation . should_equal [123456, 6, 3]
 
+    suite_builder.group "(Decimal_Spec) Decimal.set_scale" group_builder->
+        group_builder.specify "should be able to set the scale of a decimal" <|
+            dec "23.456" . set_scale 3 . should_equal (dec "23.456")
+            dec "23.456" . set_scale 3 . internal_representation . should_equal [23456, 5, 3]
+            dec "23.456" . set_scale 4 . should_equal (dec "23.456")
+            dec "23.456" . set_scale 4 . internal_representation . should_equal [234560, 6, 4]
+
+        group_builder.specify "setting a scale that is too small should result in an error" <|
+            dec "23.456" . set_scale 2 . should_fail_with Arithmetic_Error
+
+    suite_builder.group "(Decimal_Spec) Text.to_decimal" group_builder->
+        group_builder.specify "should be able to convert a Text to a Decimal" <|
+            "23.456".to_decimal . should_equal (dec "23.456")
+
+        group_builder.specify "should be able to convert a Text to a Decimal, with scale" <|
+            "23.456".to_decimal scale=3 . should_equal (dec "23.456")
+            "23.456".to_decimal scale=3 . internal_representation . should_equal [23456, 5, 3]
+            "23.456".to_decimal scale=4 . should_equal (dec "23.456")
+            "23.456".to_decimal scale=4 . internal_representation . should_equal [234560, 6, 4]
+
+        group_builder.specify "converting a Text to a Decimal with a scale that is too small should result in an error" <|
+            "23.456".to_decimal scale=2 . should_fail_with Arithmetic_Error
+
 main filter=Nothing =
     suite = Test.build suite_builder->
         add_specs suite_builder