Readme for numerals-0.1
Specialise
==========
This is a small note on the Specialise flag.
All the language definitions (Text.Numeral.Language.*) are polymorphic
in their stringlike type. For example:
> nl :: (IsString s, Joinable s) => NumConfig s
This allows the user to choose whatever stringlike type she wants.
If you turn on the Specialise flag then specialised versions of the
language definitions will be build:
> #ifdef DO_SPECIALISE
> import qualified Data.ByteString as B
> import qualified Data.DString as DS
>
> {-# SPECIALISE nl :: NumConfig String #-}
> {-# SPECIALISE nl :: NumConfig B.ByteString #-}
> {-# SPECIALISE nl :: NumConfig DS.DString #-}
> #endif
The idea is that user code which uses any of the specialised types
will become more efficient because the overloading overhead has been
removed. Of course if we specialise the library will take longer to
compile and will be bigger.
The following will discuss some actual numbers:
Without Specialise
==================
$ cabal configure
$ time cabal build
...
5.347s
$ du -b dist/build/libHSnumerals-0.1.a
605574 dist/build/libHSnumerals-0.1.a
With Specialise
===============
$ cabal configure --flags="Specialise"
$ time cabal build
...
14.779s
$ du -b dist/build/libHSnumerals-0.1.a
2064852 dist/build/libHSnumerals-0.1.a
Conclusion
=========
If we specialise then:
* compilation will take almost 3 times longer
* the library will be at least 3 times bigger
TODO: Check for peformance gains!