Add functions for formatting numbers, closes #6

Author: sharkdp

README.md

@@ -2,7 +2,7 @@
 [![Latest release](http://img.shields.io/github/release/sharkdp/purescript-numbers.svg)](https://github.com/sharkdp/purescript-numbers/releases)
 [![Build status](https://travis-ci.org/sharkdp/purescript-numbers.svg?branch=master)](https://travis-ci.org/sharkdp/purescript-numbers)
 
-Functions for working with PureScripts builtin `Number` type.
+Utility functions for working with PureScripts builtin `Number` type.
 
 * [**Module documentation on Pursuit**](http://pursuit.purescript.org/packages/purescript-numbers).
 
@@ -17,13 +17,18 @@ Parsing:
 (Just 0.001)
 ```
 
-*NaN* and *infinity*:
+Formatting (`Data.Number.Format`):
 ``` purs
-> isNaN (Math.asin 2.0)
-true
+> let x = 1234.56789
 
-> isFinite (1.0 / 0.0)
-false
+> toStringWith (precision 6) x
+"1234.57"
+
+> toStringWith (fixed 3) x
+"1234.568"
+
+> toStringWith (exponential 2) x
+"1.23e+3"
 ```
 
 Approximate comparisons (`Data.Number.Approximate`):
@@ -35,6 +40,15 @@ false
 true
 ```
 
+*NaN* and *infinity*:
+``` purs
+> isNaN (Math.asin 2.0)
+true
+
+> isFinite (1.0 / 0.0)
+false
+```
+
 ## Installation
 
 ```

src/Data/Number/Format.js

@@ -0,0 +1,13 @@
+function wrap(method) {
+  return function(d) {
+    return function(num) {
+      return method.apply(num, [d]);
+    };
+  };
+}
+
+exports.toPrecisionNative   = wrap(Number.prototype.toPrecision);
+exports.toFixedNative       = wrap(Number.prototype.toFixed);
+exports.toExponentialNative = wrap(Number.prototype.toExponential);
+
+exports.toString = function(num) { return num.toString(); };

src/Data/Number/Format.purs

@@ -0,0 +1,76 @@
+-- | A module for formatting numbers as strings.
+-- |
+-- | Usage:
+-- | ``` purs
+-- | > let x = 1234.56789
+-- |
+-- | > toStringWith (precision 6) x
+-- | "1234.57"
+-- |
+-- | > toStringWith (fixed 3) x
+-- | "1234.568"
+-- |
+-- | > toStringWith (exponential 2) x
+-- | "1.23e+3"
+-- | ```
+-- |
+-- | The main method of this module is the `toStringWith` function that accepts
+-- | a `Format` argument which can be constructed through one of the smart
+-- | constructors `precision`, `fixed` and `exponential`. Internally, the
+-- | number will be formatted with JavaScripts `toPrecision`, `toFixed` or
+-- | `toExponential`.
+module Data.Number.Format
+  ( Format()
+  , precision
+  , fixed
+  , exponential
+  , toStringWith
+  , toString
+  ) where
+
+import Prelude
+
+foreign import toPrecisionNative ∷   Int → Number → String
+foreign import toFixedNative ∷       Int → Number → String
+foreign import toExponentialNative ∷ Int → Number → String
+
+-- | The `Format` data type specifies how a number will be formatted.
+data Format
+  = Precision Int
+  | Fixed Int
+  | Exponential Int
+
+-- | Create a `toPrecision`-based format from an integer. Values smaller than
+-- | `1` and larger than `21` will be clamped.
+precision ∷ Int → Format
+precision = Precision <<< clamp 1 21
+
+-- | Create a `toFixed`-based format from an integer. Values smaller than `0`
+-- | and larger than `20` will be clamped.
+fixed ∷ Int → Format
+fixed = Fixed <<< clamp 0 20
+
+-- | Create a `toExponential`-based format from an integer. Values smaller than
+-- | `0` and larger than `20` will be clamped.
+exponential ∷ Int → Format
+exponential = Exponential <<< clamp 0 20
+
+-- | Convert a number to a string with a given format.
+toStringWith ∷ Format → Number → String
+toStringWith (Precision p)   = toPrecisionNative p
+toStringWith (Fixed p)       = toFixedNative p
+toStringWith (Exponential p) = toExponentialNative p
+
+-- | Convert a number to a string via JavaScript's toString method.
+-- |
+-- | ```purs
+-- | > toString 12.34
+-- | "12.34"
+-- |
+-- | > toString 1234.0
+-- | "1234"
+-- |
+-- | > toString 1.2e-10
+-- | "1.2e-10"
+-- | ```
+foreign import toString ∷ Number → String

test/Main.purs

@@ -4,6 +4,8 @@ import Prelude
 
 import Data.Maybe (Maybe(..), fromMaybe)
 import Data.Number (nan, isNaN, infinity, isFinite, fromString)
+import Data.Number.Format (precision, fixed, exponential, toStringWith,
+                           toString)
 import Data.Number.Approximate (Fraction(..), Tolerance(..), eqRelative,
                                 eqAbsolute, (≅), (≇))
 
@@ -12,7 +14,7 @@ import Control.Monad.Eff (Eff)
 import Control.Monad.Eff.Console (CONSOLE)
 
 import Test.Unit (suite, test)
-import Test.Unit.Assert (assert, assertFalse)
+import Test.Unit.Assert (assert, assertFalse, equal)
 import Test.Unit.Console (TESTOUTPUT)
 import Test.Unit.Main (runTest)
 
@@ -71,6 +73,36 @@ main = runTest do
       assertFalse "detect NaN" $ isFinite nan
 
 
+  let pi = 3.14159
+  suite "Data.Format.toStringWith" do
+
+    test "precision" do
+      equal "3.14"    (toStringWith (precision 3) pi)
+      equal "3.1416"  (toStringWith (precision 5) pi)
+      equal "3"       (toStringWith (precision 1) pi)
+      equal "3"       (toStringWith (precision (-3)) pi)
+      equal "3.14"    (toStringWith (precision 3) pi)
+      equal "1.2e+3"  (toStringWith (precision 2) 1234.5)
+
+    test "fixed" do
+      equal "3.14"    (toStringWith (fixed 2) pi)
+      equal "3.1416"  (toStringWith (fixed 4) pi)
+      equal "3"       (toStringWith (precision 0) pi)
+      equal "3"       (toStringWith (precision (-3)) pi)
+      equal "1234.5"  (toStringWith (fixed 1) 1234.5)
+
+    test "exponential" do
+      equal "3e+0"    (toStringWith (exponential 0) pi)
+      equal "3.14e+0" (toStringWith (exponential 2) pi)
+      equal "3.14e+2" (toStringWith (exponential 2) (100.0 * pi))
+      equal "1.2e+3"  (toStringWith (exponential 1) 1234.5)
+
+  suite "Data.Format.toString" do
+
+    test "toString" do
+      equal "3.14159" (toString pi)
+      equal "10" (toString 10.0)
+
   suite "Data.Number.Approximate.eqRelative" do
     test "eqRelative" do
       assert "should return true for differences smaller 10%" $