#lang scribble/doc
@; THIS FILE IS GENERATED
@(require scribble/manual)
@(require (for-label (planet neil/numspell:1:1)))
@title[#:version "0.2"]{@bold{numspell}: Spelling Numbers as English in Scheme}
@author{Neil Van Dyke}


License: @seclink["Legal" #:underline? #f]{LGPL 3} @(hspace 1) Web: @link["http://www.neilvandyke.org/numspell-scheme/" #:underline? #f]{http://www.neilvandyke.org/numspell-scheme/}

@defmodule[(planet neil/numspell:1:1)]

      

@section{Introduction}


      

The @bold{numspell} library provides the ability to ``spell'' Scheme numbers in English.  This is useful for writing numbers on banking checks and other legal documents, as well as for speech generation.


      

Most rational numbers in Scheme are presently supported.  For example:


      

@SCHEMEBLOCK[
(number->english 123456)
==> "one hundred twenty-three thousand four hundred fifty-six"
(number->english (/ 4 -6))
==> "negative two over three"
(number->english (exact->inexact (/ 4 -6)))
==> "negative zero point six six six six six six" ; (approx.)
]


      

The number names supported by @bold{numspell} are taken from a version of the @link["http://en.wikipedia.org/wiki/Names_of_large_numbers"]{Wikipedia ``Names of large numbers''} article.  Both @link["http://en.wikipedia.org/wiki/Long_and_short_scales"]{short and long scales} are supported, through different procedures, with short scale being the default.  For example:


      

@SCHEMEBLOCK[
(number->english             (expt 10 15))
==> "one quadrillion"
(number->short-scale-english (expt 10 15))
==> "one quadrillion"
(number->long-scale-english  (expt 10 15))
==> "one thousand billion"
]


      

Note: Some numbers, such as very large and very small non-integers printed by some Scheme implementations in exponential notation, are not supported by the current version of @bold{numspell}.


      

@bold{numspell} requires R5RS, SRFI-6 (string ports), and SRFI-11 (@tt{let-values}).


    
      

@section{Interface}


      

The public interface consists of a few procedures.


      

@defproc[(write-number-as-english (num any/c) (port any/c)) any/c]{}


@defproc[(write-number-as-short-scale-english (num any/c) (port any/c)) any/c]{}


@defproc[(write-number-as-long-scale-english (num any/c) (port any/c)) any/c]{
          

Spell number @schemevarfont{num} to output port @schemevarfont{port}.  If @schemevarfont{num} cannot be spelt, an error is signaled.


        }

      

@defproc[(number->english (num any/c)) any/c]{}


@defproc[(number->short-scale-english (num any/c)) any/c]{}


@defproc[(number->long-scale-english (num any/c)) any/c]{
          

Yield a string that spells number @schemevarfont{num}.  If @schemevarfont{num} cannot be spelt, an error is signaled.


        }

    
      

@section{History}


      

@itemize[

@item{Version 0.2 --- 2009-02-24 --- PLaneT @tt{(1 1)}
            

License is now LGPL 3.  Converted to author's new Scheme administration system.  Test suite moved out of main file.  A descriptive error message is now generated when scale names are exhausted by a very large number. Changed some @tt{if} to @tt{and} for PLT 4.x.


          }


@item{Version 0.1 --- 2006-05-07 --- PLaneT @tt{(1 0)}
            

Initial release.


          }



]


    

@section[#:tag "Legal"]{Legal}



Copyright (c) 2006--2009 Neil Van Dyke.  This program is Free Software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License (LGPL 3), or (at your option) any later version.  This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.  See http://www.gnu.org/licenses/ for details.  For other licenses and consulting, please contact the author.