Nat documentation and fromText() utility
#517
Conversation
kentosugama
changed the title
kentosugama
changed the title
fromText() utility
src/Nat.mo
Outdated
| @@ -1,72 +1,299 @@ | |||
| /// Natural numbers | |||
| /// Utility functions for working with natural numbers. | |||
There was a problem hiding this comment.
Update: (Just saw that it is mentioned below). But maybe it is useful to mention it also in the header that the numbers have infinite precision, in symmetry with the documentation Int.mo.
src/Nat.mo
Outdated
|
|
||
| module { | ||
|
|
||
| /// Infinite precision natural numbers. | ||
| public type Nat = Prim.Types.Nat; | ||
|
|
||
| /// Conversion. | ||
| public let toText : Nat -> Text = Int.toText; | ||
| /// Converts a natural number to its textual representation. |
There was a problem hiding this comment.
Detail (unsure whether worth mentioning): Without underscore formatting for thousand digit separators.
| /// ```motoko include=import | ||
| /// Nat.fromText "1234" // => ?1234 | ||
| /// ``` | ||
| public func fromText(text : Text) : ?Nat { |
There was a problem hiding this comment.
Just noticed that we do not have this function in Int. Maybe it would be useful to offer it there two (and even combine the implementation, similar to toText).
There was a problem hiding this comment.
#520 Yeah that sounds good!
| /// to the existing `==` operator) is so that you can use it as a function | ||
| /// value to pass to a higher order function. It is not possible to use `==` | ||
| /// as a function value at the moment. | ||
| /// |
There was a problem hiding this comment.
Great comment. Maybe we should also improve Int with this explanation.
| /// let buffer1 = Buffer.Buffer<Nat>(3); | ||
| /// let buffer2 = Buffer.Buffer<Nat>(3); | ||
| /// Buffer.equal(buffer1, buffer2, Nat.equal) // => true | ||
| /// ``` |
There was a problem hiding this comment.
And nice example demonstrating where it makes really sense to use the equal function.
| public func compare(x : Nat, y : Nat) : { #less; #equal; #greater } { | ||
| if (x < y) { #less } else if (x == y) { #equal } else { #greater } | ||
| }; | ||
|
|
||
| /// Returns the sum of `x` and `y`, `x + y`. | ||
| /// | ||
| /// Example: |
There was a problem hiding this comment.
Maybe it could help to mention (again): No overflow since Nat has infinite precision. Same for mul().
| /// ```motoko include=import | ||
| /// import Array "mo:base/Array"; | ||
| /// Array.foldLeft([2, 3, 1], 1, Nat.mul) // => 6 | ||
| /// ``` | ||
| public func mul(x : Nat, y : Nat) : Nat { x * y }; | ||
|
|
||
| /// Returns the division of `x` by `y`, `x / y`. | ||
| /// Traps when `y` is zero. |
There was a problem hiding this comment.
| /// Traps when `y` is zero. | |
| /// Returns the unsigned integer division of `x` by `y`, `x / y`. | |
| /// Rounds the quotient towards zero, which is the same as truncating the decimal places of the quotient. |
| /// Note: The reason why this function is defined in this library (in addition | ||
| /// to the existing `/` operator) is so that you can use it as a function | ||
| /// value to pass to a higher order function. It is not possible to use `/` | ||
| /// as a function value at the moment. | ||
| public func div(x : Nat, y : Nat) : Nat { x / y }; | ||
|
|
||
| /// Returns the remainder of `x` divided by `y`, `x % y`. | ||
| /// Traps when `y` is zero. |
There was a problem hiding this comment.
Similar to div, the remainder of the unsigned integer division.
| public func rem(x : Nat, y : Nat) : Nat { x % y }; | ||
|
|
||
| /// Returns `x` to the power of `y`, `x ** y`. | ||
| /// |
There was a problem hiding this comment.
| /// | |
| /// Traps when `y > 2 ** 32`. | |
| /// No overflow since `Nat` has infinite precision. |
There was a problem hiding this comment.
Oh! Didn't know that
|
@luc-blaeser Thanks for the feedback as always |
No description provided.