add notebook and update doc

.gitignore

@@ -1 +1,4 @@
 *~
+Notebooks/.ipynb_checkpoints/
+.ipynb_checkpoints/
+

Notebooks/DeepConvert.ipynb

@@ -0,0 +1,323 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# DeepConvert\n",
+    "\n",
+    "This package provides convenient literal construction of values of\n",
+    "large data types.\n",
+    "\n",
+    "It defines macros that define functions to convert all\n",
+    "numbers in an expression to a given numeric type and evaluate that\n",
+    "expression. (Like `deepcopy`, it traverses the entire expression tree.)\n",
+    "It is meant to allow a convenient way to input large\n",
+    "numbers without overflow.\n",
+    "\n",
+    "The macros `@bigfloat`, `@bigint`, and `@int128` convert numeric literals\n",
+    "in their argument to BigFloat, BigInt or Int128. See examples below.\n",
+    "\n",
+    "Two examples of non-standard AbstractString literals are exported,\n",
+    "`bf` and `bi`, which construct `BigFloat`s and\n",
+    "`BigInt`s from strings. Note that these are *not* the same as the string\n",
+    "literal `big` in Julia `Base`."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Trying to construct an array of `BigInt`s this way will not work "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {
+    "collapsed": false,
+    "scrolled": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "2-element Array{BigInt,1}:\n",
+       " -9223372036854775808\n",
+       "                    0"
+      ]
+     },
+     "execution_count": 1,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "BigInt[2^63, 2^64]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Instead we have to do something like this"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "2-element Array{BigInt,1}:\n",
+       "  9223372036854775808\n",
+       " 18446744073709551616"
+      ]
+     },
+     "execution_count": 2,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "[big\"2\"^63, big\"2\"^64]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The string macro `bi` makes this easier."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "2-element Array{BigInt,1}:\n",
+       "  9223372036854775808\n",
+       " 18446744073709551616"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "using DeepConvert\n",
+    "\n",
+    "bi\"[2^63, 2^64]\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "There is an equivalent macro `@bigint`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "2-element Array{BigInt,1}:\n",
+       "  9223372036854775808\n",
+       " 18446744073709551616"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "@bigint [2^63, 2^64]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The following calculation overflows."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "ename": "LoadError",
+     "evalue": "OverflowError: binomial(100, 50) overflows",
+     "output_type": "error",
+     "traceback": [
+      "OverflowError: binomial(100, 50) overflows",
+      "",
+      "Stacktrace:",
+      " [1] binomial(::Int64, ::Int64) at ./intfuncs.jl:903",
+      " [2] top-level scope at none:0"
+     ]
+    }
+   ],
+   "source": [
+    "binomial(100, 50)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "`Int128` is big enough."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "100891344545564193334812497256"
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "@int128 binomial(100, 50)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "There is also a string macro `bf` for `BigFloat`s"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "1.0"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "round(bf\"((1 + 2e-50) - (1 + 1e-50)) / (1e-50)\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here is another (contrived) example"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "@bigint function g(x)\n",
+    "           return 2^64 * x\n",
+    "        end;"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "3.6893488147419103232e+19"
+      ]
+     },
+     "execution_count": 9,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "g(2.0)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "BigFloat"
+      ]
+     },
+     "execution_count": 10,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "typeof(g(2.0))"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Julia 0.7.0-beta2",
+   "language": "julia",
+   "name": "julia-0.7"
+  },
+  "language_info": {
+   "file_extension": ".jl",
+   "mimetype": "application/julia",
+   "name": "julia",
+   "version": "0.7.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 1
+}

README.md

@@ -29,18 +29,18 @@ literal `big` in Julia `Base`.
 
 ```julia
 julia> BigInt[2^63, 2^64]
-2-element Array{BigInt, 1}:  # awesome, an array of BigInt's!
+2-element Array{BigInt,1}:  # awesome, an array of BigInt's!
  -9223372036854775808
                     0
 
 julia> using DeepConvert
 julia> bi"[2^63, 2^64]"
-2-element Array{BigInt, 1}:
+2-element Array{BigInt,1}:
   9223372036854775808
  18446744073709551616
 
 julia> @bigint [2^63, 2^64]
-2-element Array{BigInt, 1}:
+2-element Array{BigInt,1}:
   9223372036854775808
  18446744073709551616
 ```
@@ -55,7 +55,7 @@ julia> @int128 binomial(100, 50)
 
 ```julia
 julia> round(bf"((1 + 2e-50) - (1 + 1e-50)) / (1e-50)")
-1e+00 with 256 bits of precision
+1.0
 ```
 
 `deepbigfloat` takes an expression or string as an argument and acts on literals
@@ -123,7 +123,7 @@ Gives this,
 
 ```julia
 julia> g(2.0)
-3.6893488147419103232e+19 with 256 bits of precision
+3.6893488147419103232e+19
 ```
 
 To override the macro, you have to ask for the smaller type,