Use Rounding_Mode instead of use_bankers flag (#12641)

Author: GregoryTravis

CHANGELOG.md

@@ -140,6 +140,8 @@
 - [Changed in-memory `Column.zip` to match `Table.zip`, removing the `function`
   parameter][12626]
 - [Added Regex_match for Postgres][12663]
+- [Replace `use_bankers` flag with `Rounding_Mode` in all `round`
+  methods][12641]
 
 [11926]: https://github.com/enso-org/enso/pull/11926
 [12031]: https://github.com/enso-org/enso/pull/12031
@@ -163,6 +165,7 @@
 [12590]: https://github.com/enso-org/enso/pull/12590
 [12626]: https://github.com/enso-org/enso/pull/12626
 [12663]: https://github.com/enso-org/enso/pull/12663
+[12641]: https://github.com/enso-org/enso/pull/12641
 
 #### Enso Language & Runtime
 

distribution/lib/Standard/Base/0.0.0-dev/docs/api/Data/Decimal.md

@@ -31,7 +31,7 @@
     - pow self exp:Standard.Base.Data.Numbers.Integer -> Standard.Base.Data.Decimal.Decimal
     - precision self -> Standard.Base.Data.Numbers.Integer
     - remainder self that:Standard.Base.Data.Decimal.Decimal -> Standard.Base.Data.Decimal.Decimal
-    - round self decimal_places:Standard.Base.Data.Numbers.Integer= use_bankers:Standard.Base.Data.Boolean.Boolean= -> Standard.Base.Data.Decimal.Decimal
+    - round self decimal_places:Standard.Base.Data.Numbers.Integer= rounding_mode:Standard.Base.Data.Numeric.Rounding_Mode.Rounding_Mode= -> Standard.Base.Data.Decimal.Decimal
     - scale self -> Standard.Base.Data.Numbers.Integer
     - set_scale self new_scale:Standard.Base.Data.Numbers.Integer -> Standard.Base.Data.Decimal.Decimal
     - signum self -> Standard.Base.Data.Numbers.Integer

distribution/lib/Standard/Base/0.0.0-dev/docs/api/Data/Numbers.md

@@ -18,7 +18,7 @@
     - min_value -> Standard.Base.Any.Any
     - negate self -> Standard.Base.Data.Numbers.Float
     - parse text:Standard.Base.Data.Text.Text locale:(Standard.Base.Data.Locale.Locale|Standard.Base.Nothing.Nothing)= format:(Standard.Base.Data.Text.Text|Standard.Base.Nothing.Nothing)= -> Standard.Base.Any.Any
-    - round self decimal_places:Standard.Base.Data.Numbers.Integer= use_bankers:Standard.Base.Data.Boolean.Boolean= -> Standard.Base.Any.Any
+    - round self decimal_places:Standard.Base.Data.Numbers.Integer= rounding_mode:Standard.Base.Data.Numeric.Rounding_Mode.Rounding_Mode= -> Standard.Base.Data.Numbers.Float
     - to_decimal self -> Standard.Base.Data.Decimal.Decimal
     - to_float self -> Standard.Base.Data.Numbers.Float
     - truncate self -> Standard.Base.Data.Numbers.Integer
@@ -47,7 +47,7 @@
     - floor self -> Standard.Base.Data.Numbers.Integer
     - negate self -> Standard.Base.Data.Numbers.Integer
     - parse text:Standard.Base.Data.Text.Text radix:Standard.Base.Data.Numbers.Integer= -> Standard.Base.Any.Any
-    - round self decimal_places:Standard.Base.Data.Numbers.Integer= use_bankers:Standard.Base.Data.Boolean.Boolean= -> Standard.Base.Any.Any
+    - round self decimal_places:Standard.Base.Data.Numbers.Integer= rounding_mode:Standard.Base.Data.Numeric.Rounding_Mode.Rounding_Mode= -> Standard.Base.Any.Any
     - to_decimal self -> Standard.Base.Data.Decimal.Decimal
     - to_float self -> Standard.Base.Data.Numbers.Float
     - truncate self -> Standard.Base.Data.Numbers.Integer

distribution/lib/Standard/Base/0.0.0-dev/docs/api/Data/Numeric/Rounding_Mode.md

@@ -1,6 +1,6 @@
 ## Enso Signatures 1.0
 ## module Standard.Base.Data.Numeric.Rounding_Mode
 - type Rounding_Mode
-    - Value rounding_mode:Standard.Base.Data.Numeric.Rounding_Mode.RoundingMode
-    - bankers -> Standard.Base.Any.Any
-    - half_up -> Standard.Base.Any.Any
+    - Bankers
+    - Half_Up
+- Standard.Base.Data.Numeric.Rounding_Mode.Rounding_Mode.from that:Standard.Base.Data.Boolean.Boolean -> Standard.Base.Data.Numeric.Rounding_Mode.Rounding_Mode

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

@@ -991,15 +991,16 @@ type Decimal
        Round to a specified number of decimal places.
 
        By default, rounding uses "symmetric round-half-up", also known as
-       "half-up." If use_bankers=True, then it uses "round-half-even", also
+       "half-up." If rounding_mode=Rounding_Mode.Bankers, then it uses "round-half-even", also
        known as "banker's rounding".
 
        Arguments:
        - decimal_places: The number of decimal places to round to. Can be
          negative, which results in rounding to positive integer powers of 10.
          Must be between Java `Integer.MIN_VALUE` and `Integer.MAX_VALUE`
          (-2147483648 and 2147483647) (inclusive).
-       - use_bankers: Rounds mid-point to nearest even number.
+       - rounding_mode: specifies how to break ties for the least significant
+         digit.
 
        ! Error Conditions
 
@@ -1032,12 +1033,12 @@ type Decimal
        > Example
          Use Banker's Rounding.
 
-             Decimal.new "2.5" . round use_bankers=True
+             Decimal.new "2.5" . round rounding_mode=Rounding_Mode.Bankers
              # => 2
-    round : Integer -> Boolean -> Decimal
-    round self (decimal_places:Integer=0) (use_bankers:Boolean=False) -> Decimal =
+    round : Integer -> Rounding_Mode -> Decimal
+    round self (decimal_places:Integer=0) (rounding_mode : Rounding_Mode = ..Half_Up) -> Decimal =
         out_of_range = decimal_places > Java_Integer.MAX_VALUE || decimal_places < Java_Integer.MIN_VALUE
-        if out_of_range.not then Decimal.Value (Decimal_Utils.round self.big_decimal decimal_places use_bankers) else
+        if out_of_range.not then Decimal.Value (Decimal_Utils.round self.big_decimal decimal_places (rounding_mode == Rounding_Mode.Bankers)) else
             message = "round decimal_places must be between "+Java_Integer.MIN_VALUE.to_text+" and "+Java_Integer.MAX_VALUE.to_text+" (inclusive), but was "+decimal_places.to_text
             Error.throw (Out_Of_Range.Error decimal_places message)
 

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

@@ -1,6 +1,7 @@
 import project.Any.Any
 import project.Data.Decimal.Decimal
 import project.Data.Locale.Locale
+import project.Data.Numeric.Rounding_Mode.Rounding_Mode
 import project.Data.Ordering.Comparable
 import project.Data.Text.Text
 import project.Error.Error
@@ -659,7 +660,7 @@ type Float
        Round to a specified number of decimal places.
 
        By default, rounding uses "symmetric round-half-up", also known as
-       "half-up." If use_bankers=True, then it uses "round-half-even", also
+       "half-up." If rounding_mode=Rounding_Mode.Bankers, then it uses "round-half-even", also
        known as "banker's rounding".
 
        If `decimal_places` > 0, `round` returns a `Float`; otherwise, it
@@ -672,7 +673,8 @@ type Float
        - decimal_places: The number of decimal places to round to. Can be
          negative, which results in rounding to positive integer powers of 10.
          Must be between -15 and 15 (inclusive).
-       - use_bankers: Rounds mid-point to nearest even number.
+       - rounding_mode: specifies how to break ties for the least significant
+         digit.
 
        ! Error Conditions
 
@@ -705,12 +707,12 @@ type Float
        > Example
          Use Banker's Rounding.
 
-            2.5 . round use_bankers=True == 2
-    round : Integer -> Boolean -> Integer | Float ! Illegal_Argument
-    round self (decimal_places:Integer=0) (use_bankers:Boolean=False) =
+            2.5 . round rounding_mode=Rounding_Mode.Bankers == 2
+    round : Integer -> Rounding_Mode -> Integer | Float ! Illegal_Argument
+    round self (decimal_places:Integer=0) (rounding_mode : Rounding_Mode = ..Half_Up) -> Float =
         report_unsupported cp = Error.throw (Illegal_Argument.Error cp.payload.message)
         Panic.catch Unsupported_Argument_Types handler=report_unsupported
-            round_float_builtin self decimal_places use_bankers
+            round_float_builtin self decimal_places (rounding_mode == Rounding_Mode.Bankers)
 
     ## GROUP Operators
        ICON operators
@@ -1074,14 +1076,15 @@ type Integer
        argument. For negative decimal places, see below.
 
        By default, rounding uses "symmetric round-half-up", also known as
-       "half-up." If use_bankers=True, then it uses "round-half-even", also
+       "half-up." If rounding_mode=Rounding_Mode.Bankers, then it uses "round-half-even", also
        known as "banker's rounding".
 
        Arguments:
        - decimal_places: The number of decimal places to round to. Can be
          negative, which results in rounding to positive integer powers of 10.
          Must be between -15 and 15 (inclusive).
-       - use_bankers: Rounds mid-point to nearest even number.
+       - rounding_mode: specifies how to break ties for the least significant
+         digit.
 
        ! Error Conditions
          If `self` is outside the range -99999999999999..99999999999999
@@ -1108,14 +1111,14 @@ type Integer
        > Example
          Round to the nearest hundred, using Banker's Rounding.
 
-            12250 . round -2 use_bankers=True == 12200
-    round self (decimal_places:Integer=0) (use_bankers:Boolean=False) -> Integer ! Illegal_Argument =
+            12250 . round -2 rounding_mode=Rounding_Mode.Bankers == 12200
+    round self (decimal_places:Integer=0) (rounding_mode : Rounding_Mode = ..Half_Up) -> Integer ! Illegal_Argument =
         ## We reject values outside the range of `long` here, so we don't also
            do this check in the Java.
         Rounding_Helpers.check_round_input self <|
             report_unsupported cp = Error.throw (Illegal_Argument.Error cp.payload.message)
             Panic.catch Unsupported_Argument_Types handler=report_unsupported
-                round_integer_builtin self decimal_places use_bankers
+                round_integer_builtin self decimal_places (rounding_mode == Rounding_Mode.Bankers)
 
     ## GROUP Operators
        ICON operators

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

@@ -42,7 +42,7 @@ type Math_Context
          specifies exact operations.
        - rounding_mode: The rounding mode to use.
     new : Integer | Unlimited -> Rounding_Mode -> Math_Context
-    new (precision : Integer | Unlimited) (rounding_mode : Rounding_Mode = Rounding_Mode.half_up) =
+    new (precision : Integer | Unlimited) (rounding_mode : Rounding_Mode = Rounding_Mode.Half_Up) =
         case precision of
-            _ : Integer -> Math_Context.Value (MathContext.new precision rounding_mode.rounding_mode)
-            _ : Unlimited -> Math_Context.Value (MathContext.new 0 rounding_mode.rounding_mode)
+            _ : Integer -> Math_Context.Value (MathContext.new precision rounding_mode.to_java_rounding_mode)
+            _ : Unlimited -> Math_Context.Value (MathContext.new 0 rounding_mode.to_java_rounding_mode)

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

@@ -1,3 +1,6 @@
+from Standard.Base import all
+import project.Errors.Deprecated.Deprecated
+
 polyglot java import java.math.RoundingMode
 
 ## A wrapper around the Java
@@ -7,17 +10,24 @@ polyglot java import java.math.RoundingMode
    `Rounding_Mode` is used to specify the method to use for rounding a value in
    operations on `Decimal`s.` See `Decimal` for more details.
 type Rounding_Mode
-    ## PRIVATE
-    Value (rounding_mode : RoundingMode)
-
     ## ICON math
        Round towards positive infinity for positive numbers, and negative
        infinity for negative numbers. (This is the default.)
-    half_up : Rounding_Mode
-    half_up = Rounding_Mode.Value RoundingMode.HALF_UP
+    Half_Up
 
     ## ICON math
        Rownd towards the nearest neighbor, with ties broken by rounding towards
        the nearest even neighbor.
-    bankers : Rounding_Mode
-    bankers = Rounding_Mode.Value RoundingMode.HALF_EVEN
+    Bankers
+
+    private to_java_rounding_mode self -> RoundingMode =
+        case self of
+            Rounding_Mode.Half_Up -> RoundingMode.HALF_UP
+            Rounding_Mode.Bankers -> RoundingMode.HALF_EVEN
+
+## PRIVATE
+   Convert deprecated `use_bankers : Boolean` arguments (passed as
+   `rounding_mode`) to `Rounding_Mode`.
+Rounding_Mode.from (that:Boolean) =
+    rounding_mode_resolved = if that then Rounding_Mode.Bankers else Rounding_Mode.Half_Up
+    Warning.attach (Deprecated.Warning "Standard.Base.Data.Numeric" "Rounding_Mode" "use_bankers:Boolean is deprecated, use Rounding_Mode instead") rounding_mode_resolved

distribution/lib/Standard/Database/0.0.0-dev/docs/api/DB_Column.md

@@ -77,15 +77,15 @@
     - read self max_rows:Standard.Table.Rows_To_Read.Rows_To_Read= -> Standard.Table.Column.Column
     - regex_match self pattern:(Standard.Database.DB_Column.DB_Column|Standard.Base.Data.Text.Text|Standard.Base.Data.Text.Regex.Regex) -> Standard.Database.DB_Column.DB_Column
     - rename self name:Standard.Base.Data.Text.Text -> Standard.Base.Any.Any
-    - round self decimal_places:Standard.Base.Data.Numbers.Integer= use_bankers:Standard.Base.Data.Boolean.Boolean= -> Standard.Base.Any.Any
-    - round_builtin self decimal_places:Standard.Base.Any.Any use_bankers:Standard.Base.Any.Any -> Standard.Base.Any.Any
-    - round_decimal self decimal_places:Standard.Base.Any.Any use_bankers:Standard.Base.Any.Any -> Standard.Base.Any.Any
-    - round_float self decimal_places:Standard.Base.Any.Any use_bankers:Standard.Base.Any.Any -> Standard.Base.Any.Any
-    - round_integer self decimal_places:Standard.Base.Any.Any use_bankers:Standard.Base.Any.Any -> Standard.Base.Any.Any
+    - round self decimal_places:Standard.Base.Data.Numbers.Integer= rounding_mode:Standard.Base.Data.Numeric.Rounding_Mode.Rounding_Mode= -> Standard.Base.Any.Any
+    - round_builtin self decimal_places:Standard.Base.Any.Any rounding_mode:Standard.Base.Any.Any -> Standard.Base.Any.Any
+    - round_decimal self decimal_places:Standard.Base.Any.Any rounding_mode:Standard.Base.Any.Any -> Standard.Base.Any.Any
+    - round_float self decimal_places:Standard.Base.Any.Any rounding_mode:Standard.Base.Any.Any -> Standard.Base.Any.Any
+    - round_integer self decimal_places:Standard.Base.Any.Any rounding_mode:Standard.Base.Any.Any -> Standard.Base.Any.Any
     - second self -> Standard.Base.Any.Any
     - short_circuit_special_floating_point self exp:Standard.Base.Any.Any -> Standard.Base.Any.Any
     - should_be_selected_by_type self value_type:Standard.Table.Value_Type.Value_Type -> Standard.Base.Data.Boolean.Boolean
-    - should_use_builtin_round self decimal_places:Standard.Base.Any.Any use_bankers:Standard.Base.Any.Any -> Standard.Base.Any.Any
+    - should_use_builtin_round self decimal_places:Standard.Base.Any.Any rounding_mode:Standard.Base.Any.Any -> Standard.Base.Any.Any
     - sort self order:Standard.Base.Data.Sort_Direction.Sort_Direction= -> Standard.Database.DB_Column.DB_Column
     - sql_type self -> Standard.Base.Any.Any
     - starts_with self other:(Standard.Database.DB_Column.DB_Column|Standard.Base.Data.Text.Text|Standard.Base.Any.Any) case_sensitivity:Standard.Base.Data.Text.Case_Sensitivity.Case_Sensitivity= -> Standard.Database.DB_Column.DB_Column