Merge pull request #1 from tonyhffong/master

Merging NumFormat into Formatting

Author: lindahua

.travis.yml

@@ -12,7 +12,6 @@ before_install:
   - sudo add-apt-repository ppa:staticfloat/${JULIAVERSION} -y
   - sudo apt-get update -qq -y
   - sudo apt-get install libpcre3-dev julia -y
+  - if [[ -a .git/shallow ]]; then git fetch --unshallow; fi
 script:
-  - julia -e 'Pkg.init(); run(`ln -s $(pwd()) $(Pkg.dir("Formatting"))`); Pkg.pin("Formatting"); Pkg.resolve()'
-  - julia -e 'using Formatting; @assert isdefined(:Formatting); @assert typeof(Formatting) === Module'
-  - julia runtests.jl
+  - julia -e 'versioninfo(); Pkg.init(); Pkg.clone(pwd()); Pkg.test("Formatting")'

README.md

@@ -1,6 +1,6 @@
 # Formatting
 
-A Julia package for Python-like formatting.
+This package offers Python-style general formatting and c-style numerical formatting (for speed).
 [![Build Status](https://travis-ci.org/lindahua/Formatting.jl.png?branch=master)](https://travis-ci.org/lindahua/Formatting.jl)
 
 ---------------
@@ -23,7 +23,7 @@ using Formatting
 This package depends on Julia of version 0.2 or above. It has no other dependencies. The package is MIT-licensed.
 
 
-## Types and Functions
+## Python-style Types and Functions
 
 #### Types to Represent Formats
 
@@ -106,7 +106,7 @@ One can use ``fmt`` to format a single value into a string, or ``format`` to for
     Format arguments using a format expression given by ``fe``, where ``fe`` can be either a string or an instance of ``FormatSpec``.
 
 
-## Difference from Python's Format
+#### Difference from Python's Format
 
 At this point, this package implements a subset of Python's formatting language (with slight modification). Here is a summary of the differences:
 
@@ -118,3 +118,85 @@ At this point, this package implements a subset of Python's formatting language
 
 - The package provides support for filtering (for explicitly positioned arguments), such as ``{1|>lowercase}`` by allowing one to embed the ``|>`` operator, which the Python counter part does not support.
 
+## C-style functions
+
+The c-style part of this package aims to get around the limitation that
+`@sprintf` has to take a literal string argument.
+The core part is basically a c-style print formatter using the standard
+`@sprintf` macro.
+It also adds functionalities such as commas separator (thousands), parenthesis for negatives,
+stripping trailing zeros, and mixed fractions.
+
+### Usage and Implementation
+
+The idea here is that the package compiles a function only once for each unique
+format string within the `Formatting.*` name space, so repeated use is faster.
+Unrelated parts of a session using the same format string would reuse the same
+function, avoiding redundant compilation. To avoid the proliferation of
+functions, we limit the usage to only 1 argument. Practical consideration
+would suggest that only dozens of functions would be created in a session, which
+seems manageable.
+
+Usage
+```julia
+using Formatting
+
+fmt = "%10.3f"
+s = sprintf1( fmt, 3.14159 ) # usage 1. Quite performant. Easiest to switch to.
+
+fmtrfunc = generate_formatter( fmt ) # usage 2. This bypass repeated lookup of cached function. Most performant.
+s = fmtrfunc( 3.14159 )
+
+s = format( 3.14159, precision=3 ) # usage 3. Most flexible, with some non-printf options. Least performant.
+```
+### Speed
+
+`sprintf1`: Speed penalty is about 20% for floating point and 30% for integers.
+
+If the formatter is stored and used instead (see the example using `generate_formatter` above),
+the speed penalty reduces to 10% for floating point and 15% for integers.
+
+### Commas
+
+This package also supplements the lack of thousand separator e.g. `"%'d"`, `"%'f"`, `"%'s"`.
+
+Note: `"%'s"` behavior is that for small enough floating point (but not too small),
+thousand separator would be used. If the number needs to be represented by `"%e"`, no
+separator is used.
+
+### Flexible `format` function
+
+This package contains a run-time number formatter `format` function, which goes beyond
+the standard `sprintf` functionality.
+
+An example:
+```julia
+s = format( 1234, commas=true ) # 1,234
+s = format( -1234, commas=true, parens=true ) # (1,234)
+```
+
+The keyword arguments are (Bold keywards are not printf standard)
+
+* width. Integer. Try to fit the output into this many characters. May not be successful.
+   Sacrifice space first, then commas.
+* precision. Integer. How many decimal places.
+* leftjustified. Boolean
+* zeropadding. Boolean
+* commas. Boolean. Thousands-group separator.
+* signed. Boolean. Always show +/- sign?
+* positivespace. Boolean. Prepend an extra space for positive numbers? (so they align nicely with negative numbers)
+* **parens**. Boolean. Use parenthesis instead of "-". e.g. `(1.01)` instead of `-1.01`. Useful in finance. Note that
+  you cannot use `signed` and `parens` option at the same time.
+* **stripzeros**. Boolean. Strip trailing '0' to the right of the decimal (and to the left of 'e', if any ).
+   * It may strip the decimal point itself if all trailing places are zeros.
+   * This is true by default if precision is not given, and vice versa.
+* alternative. Boolean. See `#` alternative form explanation in standard printf documentation
+* conversion. length=1 string. Default is type dependent. It can be one of `aAeEfFoxX`. See standard
+  printf documentation.
+* **mixedfraction**. Boolean. If the number is rational, format it in mixed fraction e.g. `1_1/2` instead of `3/2`
+* **mixedfractionsep**. Default `_`
+* **fractionsep**. Default `/`
+* **fractionwidth**. Integer. Try to pad zeros to the numerator until the fractional part has this width
+* **tryden**. Integer. Try to use this denominator instead of a smaller one. No-op if it'd lose precision.
+
+See the test script for more examples.

runtests.jl

@@ -2,11 +2,13 @@ module Formatting
 
     import Base.show
 
-    export 
-        FormatSpec, FormatExpr, 
-        printfmt, printfmtln, fmt, format
+    export
+        FormatSpec, FormatExpr,
+        printfmt, printfmtln, fmt, format,
+        sprintf1, generate_formatter
 
 
+    include("cformat.jl" )
     include("fmtspec.jl")
     include("fmtcore.jl")
     include("formatexpr.jl")