diff --git a/builtins/Float.roc b/builtins/Float.roc index d0e639ff90..08994cabb0 100644 --- a/builtins/Float.roc +++ b/builtins/Float.roc @@ -1,4 +1,4 @@ -api Float provides Float, FloatingPoint +api Float provides Float, FloatingPoint, InvalidSqrt, fromNum, round, ceiling, floor, div, mod, recip, sqrt, highestVal, lowestVal, highestIntVal, lowestIntVal, sin, cos, tan, asin, acos, atan ## Types @@ -29,7 +29,7 @@ api Float provides Float, FloatingPoint ## Note that although the IEEE-754 specification describes the values `Infinity`, `-Infinity`, `NaN`, and `-0.0`, Roc avoids these as follows: ## ## * @Float.sqrt returns `Err InvalidSqrt` when it would otherwise return `NaN`. -## * Division operations return `Err DivisionByZero` when they would otherwise return `Infinity` or `-Infinity`. +## * Division operations return `Err DivByZero` when they would otherwise return `Infinity` or `-Infinity`. ## * Operations that overflow crash (just like integers do) instead of returning `Infinity` or `-Infinity`. ## Under the hood, it is possible to have a zero @Float with a negative sign. However, this implementation detail intentionally conceealed. For equality purpose, `-0.0` is treated as equivalent to `0.0`, just like the spec prescribes. However, @Str.decimal always returns `0.0` when it would otherwise return `-0.0`, and both @Num.isPositive and @Num.isNegative return @False for all zero values. The only way to detect a zero with a negative sign is to convert it to @Bytes and inspect the bits directly. Float : Num FloatingPoint @@ -65,7 +65,7 @@ atan : Float -> Float ## Other Calculations (arithmetic?) -## Divide two @Float numbers. Return `Err DivisionByZero` if the +## Divide two @Float numbers. Return `Err DivByZero` if the ## second number is zero, because division by zero is undefined in mathematics. ## ## (To divide an @Int and a @Float, first convert the @Int to a @Float using one of the functions in this module.) @@ -79,14 +79,14 @@ atan : Float -> Float ## > 4.0 / -0.5 ## ## > Float.div 4.0 -0.5 -div : Float, Float -> Result Float DivisionByZero +div : Float, Float -> Result Float DivByZero ## Perform modulo on two @Float numbers. ## ## Modulo is the same as remainder when working with positive numbers, ## but if either number is negative, then modulo works differently. ## -## Return `Err DivisionByZero` if the second number is zero, because division by zero is undefined in mathematics. +## Return `Err DivByZero` if the second number is zero, because division by zero is undefined in mathematics. ## ## `a % b` is shorthand for `Float.mod a b`. ## @@ -97,10 +97,10 @@ div : Float, Float -> Result Float DivisionByZero ## > 4.0 % -0.5 ## ## > Float.mod -8 -3 -mod : Float, Float -> Result Float DivisionByZero +mod : Float, Float -> Result Float DivByZero ## Return the reciprocal of the @Float. -recip : Float -> Result Float Num.DivisionByZero +recip : Float -> Result Float Num.DivByZero recip = \float -> 1.0 / float @@ -119,46 +119,46 @@ sqrt : Float -> Result Float InvalidSqrt ## Constants -## An approximation of e. +## An approximation of e, specifically 2.718281828459045. e : Float -e = 2... #TODO fill this in, and make the docs nicer! +e = 2.718281828459045 -## An approximation of pi. +## An approximation of pi, specifically 3.141592653589793. pi : Float -pi = 3.14... #TODO fill this in, and make the docs nicer! +pi = 3.141592653589793 ## Limits -## The highest supported @Float value you can have: [TODO put the number here] +## The highest supported @Float value you can have, which is approximately 1.8 × 10^308. ## ## If you go higher than this, your running Roc code will crash - so be careful not to! -highestSupported : Float +highestVal : Float -## The lowest supported @Float value you can have: [TODO put the number here] +## The lowest supported @Float value you can have, which is approximately -1.8 × 10^308. ## ## If you go lower than this, your running Roc code will crash - so be careful not to! -lowestSupported : Float +lowestVal : Float -## The highest integer that can be represented as a @Float without -## losing precision. +## The highest integer that can be represented as a @Float without # losing precision. +## It is equal to 2^53, which is approximately 9 × 10^15. ## ## Some integers higher than this can be represented, but they may lose precision. For example: ## -## > Float.highestLosslessInt +## > Float.highestIntVal ## -## > Float.highestLosslessInt + 100 # Increasing may lose precision +## > Float.highestIntVal + 100 # Increasing may lose precision ## -## > Float.highestLosslessInt - 100 # Decreasing is fine - but watch out for lowestLosslessInt! -highestLosslessInt : Float +## > Float.highestIntVal - 100 # Decreasing is fine - but watch out for lowestLosslessInt! +highestIntVal : Float -## The lowest integer that can be represented as a @Float without -## losing precision. +## The lowest integer that can be represented as a @Float without losing precision. +## It is equal to -2^53, which is approximately -9 × 10^15. ## ## Some integers lower than this can be represented, but they may lose precision. For example: ## -## > Float.lowestLosslessInt +## > Float.lowestIntVal ## -## > Float.lowestLosslessInt - 100 # Decreasing may lose precision +## > Float.lowestIntVal - 100 # Decreasing may lose precision ## -## > Float.lowestLosslessInt + 100 # Increasing is fine - but watch out for highestLosslessInt! -lowestLosslessInt : Float +## > Float.lowestIntVal + 100 # Increasing is fine - but watch out for highestLosslessInt! +lowestIntVal : Float diff --git a/builtins/Int.roc b/builtins/Int.roc index 77ae6bdb15..1fc055f8d8 100644 --- a/builtins/Int.roc +++ b/builtins/Int.roc @@ -1,4 +1,4 @@ -api Int provides Int, Integer +api Int provides Int, Integer, divFloor, modFloor ## Types @@ -25,7 +25,7 @@ Int : Num Integer ## ## (Use @Float.div for non-flooring division.) ## -## Return `Err DivisionByZero` if the second integer is zero, because division by zero is undefined in mathematics. +## Return `Err DivByZero` if the second integer is zero, because division by zero is undefined in mathematics. ## ## `a // b` is shorthand for `Int.divFloor a b`. ## @@ -38,7 +38,7 @@ Int : Num Integer ## > Int.divFloor -8 -3 ## ## This is the same as the @// operator. -divFloor : Int, Int -> Result DivisionByZero Int +divFloor : Int, Int -> Result DivByZero Int ## Perform flooring modulo on two integers. ## @@ -49,7 +49,7 @@ divFloor : Int, Int -> Result DivisionByZero Int ## ## (Use @Float.mod for non-flooring modulo.) ## -## Return `Err DivisionByZero` if the second integer is zero, because division by zero is undefined in mathematics. +## Return `Err DivByZero` if the second integer is zero, because division by zero is undefined in mathematics. ## ## `a %% b` is shorthand for `Int.modFloor a b`. ## @@ -60,7 +60,7 @@ divFloor : Int, Int -> Result DivisionByZero Int ## > -8 %% -3 ## ## > Int.modFloor -8 -3 -divFloor : Int, Int -> Result DivisionByZero Int +modFloor : Int, Int -> Result DivByZero Int ## Bitwise diff --git a/builtins/Num.roc b/builtins/Num.roc index ebce1ce03e..89f937c7fa 100644 --- a/builtins/Num.roc +++ b/builtins/Num.roc @@ -1,4 +1,4 @@ -api Num provides Num, negate +api Num provides Num, DivByZero..., negate, abs, add, sub, mul, isOdd, isEven, isPositive, isNegative, isZero ## Types @@ -22,7 +22,7 @@ api Num provides Num, negate Num range := Num range ## Returned by division operations (@Float.div, @Float.mod, @Int.divFloor, @Int.divMod, and @Float.recip) when they attempt to divide by zero. -DivisionByZero := DivisionByZero +DivByZero := DivByZero ## Convert diff --git a/stdlib/src/frac.rs b/stdlib/src/frac.rs index 1e2d18300a..8852cf8a75 100644 --- a/stdlib/src/frac.rs +++ b/stdlib/src/frac.rs @@ -22,7 +22,7 @@ pub struct Fraction { /// that it makes Frac more error-prone to use outside of Roc. /// /// * Roc will accept any pattern of bits in this struct, and will type them as - /// Result { ok: Frac, err: DivisionByZero }. Behind the scenes, a pattern match + /// Result { ok: Frac, err: DivByZero }. Behind the scenes, a pattern match /// on this result will map all positive denominators to Ok and all zero or negative /// denominators to Err, so there is no extra memory cost to this being typed as Result. /// * Roc's reciprocal function and division operator return Result values as well. Because