
                           sprintf.js - Version 1.0

                                  2007-04-13


DESCRIPTION
-----------

This is a JavaScript implementation of the sprintf() function from the
C standard library.


COPYRIGHT
---------

Copyright (C) 2007, Michael W. Hayes.  This software is distributed
under the terms of the GNU General Public License.

This file is part of sprintf.js.

sprintf.js is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

sprintf.js 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 the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with sprintf.js; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA


AUTHOR
------

Michael W. Hayes
Acquired Intelligence Inc.
1095 McKenzie Ave. #205
Victoria, BC  V8P 2L5
Canada

Email: mike@aiinc.ca

Be sure to say "sprintf.js" in the subject line when sending me email about
this package.


CONFORMS TO
-----------

GNU C Library documentation:

    http://tinyurl.com/2goxfv

With appropriate adaptations for JavaScript (see NOTES below).


COMPATIBLE BROWSERS
-------------------

Firefox 2.0.x.x
Internet Explorer 7
Opera 9.20

Please test in other browsers and let me know if it works.


USAGE
-----

Use this script in your HTML file by including the following line:

    <SCRIPT TYPE="text/javascript" SRC="sprintf.js"></SCRIPT>

If the file "sprintf.js" is not in the same folder as your HTML file, change
the SRC attribute to prepend the necessary path components.


SYNTAX
------

sprintf(format, arg1, arg2, ... argN)

    Returns the converted result as a string.

alertf(format, arg1, arg2, ... argN)

    Returns the converted result as a string, after displaying it using the
    alert() method.

The number of arguments that are required varies with the number of
conversions specified in the format string.


EXCEPTIONS
----------

sprintf() and alertf() can throw the following exceptions:

    Exception Text                  Cause
    -------------------------------------------------------------------------
    Too few arguments               Not enough argument were supplied to
                                    satisfy all of the conversions in the
                                    format string.

    Too many arguments              Not all of the arguments in the argument
                                    list were consumed by conversions.

    Null argument supplied          A null argument was supplied for a
                                    conversion, field width, or precision.

    Numeric argument required       The argument supplied to a numeric
                                    conversion or a field width or precision
                                    was not a number and not a string that
                                    could be converted to a number.

    Integer argument required       The argument supplied for a field width
                                    or precision was not an integer and not
                                    a string that could be converted to an
                                    integer.

    Argument position required      A conversion lacks an argument position
                                    but is required to have one.

    Argument position prohibited    A conversion has an argument position
                                    but is not allowed to have one.

    Illegal argument position       An argument position is out of range --
                                    it is either < 1 or beyond the index of
                                    the final argument.


NOTES
-----

This implementation of sprintf() differs from the GNU C library implementation
in the following ways:

  - The conversion %b for binary integer output is added as an extension.

  - The conversions %a, %A, %m, %n and %p do not make sense in JavaScript and
    are not implemented.

  - The conversion %u is identical to %d, since JavaScript does not have
    unsigned integers.

  - Size flags, such as "l" in "%ld", are ignored since JavaScript does not
    have variables of different sizes.

  - The argument for the %c and %C conversions is a string, since JavaScript
    does not have a "char" type.  If a string of length > 1 is supplied, the
    first character is used and the remainder is ignored.  If string of length
    zero is supplied then the conversion adds nothing to the formatted result.

  - If a non-integer argument is supplied to an integer conversion, it is
    rounded to the nearest integer.

  - If a string argument is supplied to a numeric conversion, or a numeric
    argument is supplied to a string conversion, the argument is automatically
    converted to the required type, and an exception is thrown if the
    conversion fails.

  - Thousand separation uses a comma by default, but you can change it to any
    string you like by setting the "thousandSeparator" property of the
    sprintf() function before calling it.  For example:

        sprintf.thousandSeparator = " ";           // Change it to a space
        var result = sprintf("%'.2f", 12345678);   // Use it

    The result of the conversion above is:

        12 345 678.00

  - The GNU C library's sprintf() displays "(null)" when a null argument is
    supplied to %s, but this sprintf() throws an exception instead.

  - The GNU C library's sprintf() displays helpful strings in place of certain
    degenerate floating point values; this sprintf() does too, but it uses the
    following JavaScript-ish equivalents of the GNU strings:

    GNU C Library      sprintf.js
    ---------------------------------------
    NAN                NaN
    INF                Infinity
    -INF               -Infinity


TESTING
-------

Test sprintf.js by viewing the accompanying file "test.html" in your browser.
The page is self-explanatory.

If any tests fail then please report it.  If all tests succeed and your
browser is not in the "Compatible Browsers" list above, then please let me
know by sending email to:

    mike@aiinc.ca

and be sure to say "sprintf.js" in the subject line.


REVISION HISTORY
----------------

Version 1.0   2007-04-13

    First release.  I am being bold and calling the first release 1.0 since
    the code isn't that big, it's feature complete, the test suite is big,
    and the major browsers pass all the tests.
