<gh_stars>0
A small, fast Java\+Script library for arbitrary-\/precision decimal arithmetic.

The little sister to \href{https://github.com/MikeMcl/bignumber.js/}{\tt bignumber.\+js}. See also \href{https://github.com/MikeMcl/decimal.js/}{\tt decimal.\+js}, and \href{https://github.com/MikeMcl/big.js/wiki}{\tt here} for the difference between them.

\subsection*{Features}


\begin{DoxyItemize}
\item Faster, smaller and easier-\/to-\/use than Java\+Script versions of Java\textquotesingle{}s Big\+Decimal
\item Only 2.\+7 KB minified and gzipped
\item Simple A\+PI
\item Replicates the {\ttfamily to\+Exponential}, {\ttfamily to\+Fixed} and {\ttfamily to\+Precision} methods of Java\+Script\textquotesingle{}s Number type
\item Includes a {\ttfamily sqrt} method
\item Stores values in an accessible decimal floating point format
\item No dependencies
\item Comprehensive \href{http://mikemcl.github.io/big.js/}{\tt documentation} and test set
\end{DoxyItemize}

\subsection*{Load}

The library is the single Java\+Script file {\itshape big.\+js} (or {\itshape big.\+min.\+js}, which is {\itshape big.\+js} minified).

It can be loaded via a script tag in an H\+T\+ML document for the browser \begin{DoxyVerb}<script src='./relative/path/to/big.js'></script>
\end{DoxyVerb}


or as a Common\+JS, \href{http://nodejs.org}{\tt Node.\+js} or A\+MD module using {\ttfamily require}. \begin{DoxyVerb}var Big = require('big.js');
\end{DoxyVerb}


For Node.\+js, the library is available from the npm registry\+: \begin{DoxyVerb}$ npm install big.js
\end{DoxyVerb}


\subsection*{Use}

{\itshape In all examples below, {\ttfamily var}, semicolons and {\ttfamily to\+String} calls are not shown. If a commented-\/out value is in quotes it means {\ttfamily to\+String} has been called on the preceding expression.}

The library exports a single function\+: Big, the constructor of Big number instances. It accepts a value of type Number, String or Big number Object. \begin{DoxyVerb}x = new Big(123.4567)
y = Big('123456.7e-3')             // 'new' is optional
z = new Big(x)
x.eq(y) && x.eq(z) && y.eq(z)      // true
\end{DoxyVerb}


A Big number is immutable in the sense that it is not changed by its methods. \begin{DoxyVerb}0.3 - 0.1                          // 0.19999999999999998
x = new Big(0.3)
x.minus(0.1)                       // "0.2"
x                                  // "0.3"
\end{DoxyVerb}


The methods that return a Big number can be chained. \begin{DoxyVerb}x.div(y).plus(z).times(9).minus('1.234567801234567e+8').plus(976.54321).div('2598.11772')
x.sqrt().div(y).pow(3).gt(y.mod(z))    // true
\end{DoxyVerb}


Like Java\+Script\textquotesingle{}s Number type, there are {\ttfamily to\+Exponential}, {\ttfamily to\+Fixed} and {\ttfamily to\+Precision} methods. \begin{DoxyVerb}x = new Big(255.5)
x.toExponential(5)                 // "2.55500e+2"
x.toFixed(5)                       // "255.50000"
x.toPrecision(5)                   // "255.50"
\end{DoxyVerb}


The maximum number of decimal places and the rounding mode used to round the results of the {\ttfamily div}, {\ttfamily sqrt} and {\ttfamily pow} (with negative exponent) methods is determined by the value of the {\ttfamily DP} and {\ttfamily RM} properties of the {\ttfamily Big} number constructor. ~\newline
 The other methods always give the exact result. ~\newline
 (From {\itshape v3.\+0.\+0}, multiple Big number constructors can be created, see Change Log below.) \begin{DoxyVerb}Big.DP = 10
Big.RM = 1

x = new Big(2);
y = new Big(3);
z = x.div(y)                       // "0.6666666667"
z.sqrt()                           // "0.8164965809"
z.pow(-3)                          // "3.3749999995"
z.times(z)                         // "0.44444444448888888889"
z.times(z).round(10)               // "0.4444444445"
\end{DoxyVerb}


The value of a Big number is stored in a decimal floating point format in terms of a coefficient, exponent and sign. \begin{DoxyVerb}x = new Big(-123.456);
x.c                                // [1,2,3,4,5,6]    coefficient (i.e. significand)
x.e                                // 2                exponent
x.s                                // -1               sign
\end{DoxyVerb}


For further information see the \href{http://mikemcl.github.io/big.js/}{\tt A\+PI} reference from the {\itshape doc} folder.

\subsection*{Test}

The {\itshape test} directory contains the test scripts for each Big number method.

The tests can be run with Node or a browser.

To test a single method, from a command-\/line shell at the {\itshape test} directory, use e.\+g. \begin{DoxyVerb}$ node toFixed
\end{DoxyVerb}


To test all the methods \begin{DoxyVerb}$ node every-test
\end{DoxyVerb}


For the browser, see {\itshape single-\/test.\+html} and {\itshape every-\/test.\+html} in the {\itshape test/browser} directory.

{\itshape big-\/vs-\/number.\+html} enables some of the methods of big.\+js to be compared with those of Java\+Script\textquotesingle{}s Number type.

\subsection*{Performance}

The {\itshape perf} directory contains two applications and a {\itshape lib} directory containing the Big\+Decimal libraries used by both.

{\itshape big-\/vs-\/bigdecimal.\+html} tests the performance of big.\+js against the Java\+Script translations of two versions of Big\+Decimal, its use should be more or less self-\/explanatory. (The G\+WT version doesn\textquotesingle{}t work in IE 6.)


\begin{DoxyItemize}
\item G\+WT\+: java.\+math.\+Big\+Decimal \href{https://github.com/iriscouch/bigdecimal.js}{\tt https\+://github.\+com/iriscouch/bigdecimal.\+js}
\item I\+C\+U4J\+: com.\+ibm.\+icu.\+math.\+Big\+Decimal \href{https://github.com/dtrebbien/BigDecimal.js}{\tt https\+://github.\+com/dtrebbien/\+Big\+Decimal.\+js}
\end{DoxyItemize}

The Big\+Decimal in Node\textquotesingle{}s npm registry is the G\+WT version. Despite its seeming popularity I have found it to have some serious bugs, see the Node script {\itshape perf/lib/bigdecimal\+\_\+\+G\+W\+T/bugs.\+js} for examples of flaws in its {\itshape remainder}, {\itshape divide} and {\itshape compare\+To} methods.

{\itshape bigtime.\+js} is a Node command-\/line application which tests the performance of big.\+js against the G\+WT version of Big\+Decimal from the npm registry.

For example, to compare the time taken by the big.\+js {\ttfamily plus} method and the Big\+Decimal {\ttfamily add} method\+: \begin{DoxyVerb}$ node bigtime plus 10000 40
\end{DoxyVerb}


This will time 10000 calls to each, using operands of up to 40 random digits and will check that the results match.

For help\+: \begin{DoxyVerb}$ node bigtime -h
\end{DoxyVerb}


\subsection*{Build}

I.\+e. minify.

For Node, if uglify-\/js is installed globally ( {\ttfamily npm install uglify-\/js -\/g} ) then \begin{DoxyVerb}uglifyjs -o ./big.min.js ./big.js
\end{DoxyVerb}


will create {\itshape big.\+min.\+js}.

The {\itshape big.\+min.\+js} already present was created with {\itshape Microsoft Ajax Minifier 5.\+11}.

\subsection*{Type\+Script}

The \href{https://github.com/borisyankov/DefinitelyTyped}{\tt Definitely\+Typed} project has a Type\+Script \href{https://github.com/borisyankov/DefinitelyTyped/blob/master/big.js/big.js.d.ts}{\tt definitions file} for big.\+js.

The definitions file can be added to your project via the \href{https://www.nuget.org/packages/big.js.TypeScript.DefinitelyTyped/0.0.1}{\tt big.\+js.\+Type\+Script.\+Definitely\+Typed} Nu\+Get package or via \href{http://definitelytyped.org/tsd/}{\tt tsd}. \begin{DoxyVerb}tsd query big.js --action install
\end{DoxyVerb}


Any questions about the Type\+Script definitions file should be addressed to the Definitely\+Typed project.

\subsection*{Feedback}

Feedback is welcome.

Bugs/comments/questions? Open an issue, or email

Michael \href{mailto:<EMAIL>}{\tt <EMAIL>}

Bitcoin donation to\+: {\bfseries 1\+Dpp\+G\+R\+Q\+Sj\+V\+S\+Mg\+Gxuyg\+D\+E\+H\+Qu\+W\+Ed\+Ti\+V\+Ez\+J\+YG} Thank you

\subsection*{Licence}

See L\+I\+C\+E\+N\+CE.

\subsection*{Change Log}

\paragraph*{3.\+1.\+3}


\begin{DoxyItemize}
\item Minor documentation updates.
\end{DoxyItemize}

\paragraph*{3.\+1.\+2}


\begin{DoxyItemize}
\item R\+E\+A\+D\+ME typo.
\end{DoxyItemize}

\paragraph*{3.\+1.\+1}


\begin{DoxyItemize}
\item A\+PI documentation update, including F\+AQ additions.
\end{DoxyItemize}

\paragraph*{3.\+1.\+0}


\begin{DoxyItemize}
\item Renamed and exposed {\ttfamily T\+O\+\_\+\+E\+X\+P\+\_\+\+N\+EG} and {\ttfamily T\+O\+\_\+\+E\+X\+P\+\_\+\+P\+OS} as {\ttfamily Big.\+E\+\_\+\+N\+EG} and {\ttfamily Big.\+E\+\_\+\+P\+OS}.
\end{DoxyItemize}

\paragraph*{3.\+0.\+2}


\begin{DoxyItemize}
\item Remove $\ast$.npmignore$\ast$, use {\ttfamily files} field in {\itshape package.\+json} instead.
\end{DoxyItemize}

\paragraph*{3.\+0.\+1}


\begin{DoxyItemize}
\item Added {\ttfamily sub}, {\ttfamily add} and {\ttfamily mul} aliases.
\item Clean-\/up after lint.
\end{DoxyItemize}

\paragraph*{3.\+0.\+0}


\begin{DoxyItemize}
\item 10/12/14 Added \href{http://mikemcl.github.io/big.js/#faq}{\tt multiple constructor functionality}.
\item No breaking changes or other additions, but a major code reorganisation, so {\itshape v3} seemed appropiate.
\end{DoxyItemize}

\paragraph*{2.\+5.\+2}


\begin{DoxyItemize}
\item 1/11/14 Added bower.\+json.
\end{DoxyItemize}

\paragraph*{2.\+5.\+1}


\begin{DoxyItemize}
\item 8/06/14 Amend R\+E\+A\+D\+ME requires.
\end{DoxyItemize}

\paragraph*{2.\+5.\+0}


\begin{DoxyItemize}
\item 26/01/14 Added {\ttfamily to\+J\+S\+ON} method so serialization uses {\ttfamily to\+String}.
\end{DoxyItemize}

\paragraph*{2.\+4.\+1}


\begin{DoxyItemize}
\item 17/10/13 Conform signed zero to I\+E\+E\+EE 754 (2008).
\end{DoxyItemize}

\paragraph*{2.\+4.\+0}


\begin{DoxyItemize}
\item 19/09/13 Throw instances of {\ttfamily Error}.
\end{DoxyItemize}

\paragraph*{2.\+3.\+0}


\begin{DoxyItemize}
\item 16/09/13 Added {\ttfamily cmp} method.
\end{DoxyItemize}

\paragraph*{2.\+2.\+0}


\begin{DoxyItemize}
\item 11/07/13 Added \textquotesingle{}round up\textquotesingle{} mode.
\end{DoxyItemize}

\paragraph*{2.\+1.\+0}


\begin{DoxyItemize}
\item 26/06/13 Allow e.\+g. {\ttfamily .1} and {\ttfamily 2.}.
\end{DoxyItemize}

\paragraph*{2.\+0.\+0}


\begin{DoxyItemize}
\item 12/05/13 Added {\ttfamily abs} method and replaced {\ttfamily cmp} with {\ttfamily eq}, {\ttfamily gt}, {\ttfamily gte}, {\ttfamily lt}, and {\ttfamily lte} methods.
\end{DoxyItemize}

\paragraph*{1.\+0.\+1}


\begin{DoxyItemize}
\item Changed default value of M\+A\+X\+\_\+\+DP to 1\+E6
\end{DoxyItemize}

\paragraph*{1.\+0.\+0}


\begin{DoxyItemize}
\item 7/11/2012 Initial release 
\end{DoxyItemize}