Rewrote Print class.

The old Print class couldn't print uint64 values, and featured
hand-hacked functionality better handled by snprintf().  Redid it
using snprintf(), using "[u]int[8,16,32,64]" types for more clarity,
and eliminated some private methods in favor of auxiliary functions in
Print.cpp.

Breaking compatibility with original implementation in three ways:

  - Print::print(double) is now accurate to 6 digits, rather
    than 2; this is consistent with the default behavior of the %f
    format specifier, and if you're using floating point, it's slow
    enough that you probably want the increased accuracy.

  - The only bases you can print a number to are 2, 8, 10, and
    16.  8, 10, and 16 already have format specifiers, and 2 is an
    important special case; others complicate matters unnecessarily.

  - Printing numbers in bases other than 10 treats them as
    unsigned quantities (i.e., won't print '-' characters).  This is
    more consistent with C++'s behavior for hexadecimal and octal
    literals (e.g., 0xFFFFFFFF has type uint32).

Updated HardwareSerial and USBSerial class documentation to reflect
the new behavior.

2 files changed, 48 insertions, 22 deletions

diff --git a/source/lang/api/serial.rst b/source/lang/api/serial.rst
index ca89b31..58002e3 100644
--- a/source/lang/api/serial.rst
+++ b/source/lang/api/serial.rst
@@ -113,25 +113,34 @@ means that you can use any of these functions on any of ``Serial1``,
 
    Print the argument's digits over the USART, in decimal format.
 
-.. cpp:function:: HardwareSerial::print(long n)
+.. cpp:function:: HardwareSerial::print(long long n)
 
    Print the argument's digits over the USART, in decimal format.
    Negative values will be prefixed with a ``'-'`` character.
 
-.. cpp:function:: HardwareSerial::print(unsigned long n)
+.. cpp:function:: HardwareSerial::print(unsigned long long n)
 
    Print the argument's digits over the USART, in decimal format.
 
-.. cpp:function:: HardwareSerial::print(long n, int base)
+.. _lang-serial-print-n-base:
 
-   Print the digits of ``n`` over the USART, in base ``base`` (which
-   may be between 2 and 16).  The ``base`` value 2 corresponds to
-   binary, 8 to octal, 10 to decimal, and 16 to hexadecimal.  Negative
-   values will be prefixed with a ``'-'`` character.
+.. cpp:function:: HardwareSerial::print(int n, int base)
+
+   Print the digits of ``n`` over the USART, in base ``base``.  The
+   ``base`` value 2 corresponds to binary, 8 to octal, 10 to decimal,
+   and 16 to hexadecimal (you can also use the symbolic constants
+   ``BIN``, ``OCT``, ``DEC``, ``HEX``).  If ``base`` is 10, negative
+   values will be prefixed with a ``'-'`` character (otherwise, ``n``
+   will be interpreted as an unsigned quantity).
+
+.. cpp:function:: HardwareSerial::print(long long n, int base)
+
+   Same behavior as the above :ref:`print(int n, int base)
+   <lang-serial-print-n-base>`, except with 64-bit values.
 
 .. cpp:function:: HardwareSerial::print(double n)
 
-   Print ``n``, accurate to 2 digits after the decimal point.
+   Print ``n``, accurate to 6 digits after the decimal point.
 
 .. _lang-serial-println:
 
@@ -155,15 +164,19 @@ means that you can use any of these functions on any of ``Serial1``,
 
    Like ``print(n)``, followed by ``"\r\n"``.
 
-.. cpp:function:: HardwareSerial::println(long n)
+.. cpp:function:: HardwareSerial::println(long long n)
 
    Like ``print(n)``, followed by ``"\r\n"``.
 
-.. cpp:function:: HardwareSerial::println(unsigned long n)
+.. cpp:function:: HardwareSerial::println(unsigned long long n)
 
    Like ``print(n)``, followed by ``"\r\n"``.
 
-.. cpp:function:: HardwareSerial::println(long n, int base)
+.. cpp:function:: HardwareSerial::println(int n, int base)
+
+   Like ``print(n, b)``, followed by ``"\r\n"``.
+
+.. cpp:function:: HardwareSerial::println(long long n, int base)
 
    Like ``print(n, b)``, followed by ``"\r\n"``.
 
diff --git a/source/lang/api/serialusb.rst b/source/lang/api/serialusb.rst
index 3bb8c00..87fa641 100644
--- a/source/lang/api/serialusb.rst
+++ b/source/lang/api/serialusb.rst
@@ -109,26 +109,35 @@ world!")``.
 
    Print the argument's digits over the USB connection, in decimal format.
 
-.. cpp:function:: USBSerial::print(long n)
+.. cpp:function:: USBSerial::print(long long n)
 
    Print the argument's digits over the USB connection, in decimal
    format.  Negative values will be prefixed with a ``'-'`` character.
 
-.. cpp:function:: USBSerial::print(unsigned long n)
+.. cpp:function:: USBSerial::print(unsigned long long n)
 
    Print the argument's digits over the USB connection, in decimal
    format.
 
-.. cpp:function:: USBSerial::print(long n, int base)
+.. _lang-serial-print-n-base:
 
-   Print the digits of ``n`` over the USB connection, in base ``base``
-   (which may be between 2 and 16).  The ``base`` value 2 corresponds
-   to binary, 8 to octal, 10 to decimal, and 16 to hexadecimal.
-   Negative values will be prefixed with a ``'-'`` character.
+.. cpp:function:: USBSerial::print(int n, int base)
+
+   Print the digits of ``n`` over USB, in base ``base``.  The ``base``
+   value 2 corresponds to binary, 8 to octal, 10 to decimal, and 16 to
+   hexadecimal (you can also use the symbolic constants ``BIN``,
+   ``OCT``, ``DEC``, ``HEX``).  If ``base`` is 10, negative values
+   will be prefixed with a ``'-'`` character (otherwise, ``n`` will be
+   interpreted as an unsigned quantity).
+
+.. cpp:function:: HardwareSerial::print(long long n, int base)
+
+   Same behavior as the above :ref:`print(int n, int base)
+   <lang-serialusb-print-n-base>`, except with 64-bit values.
 
 .. cpp:function:: USBSerial::print(double n)
 
-   Print ``n``, accurate to 2 digits after the decimal point.
+   Print ``n``, accurate to 6 digits after the decimal point.
 
 .. _lang-serialusb-println:
 
@@ -152,15 +161,19 @@ world!")``.
 
    Like ``print(n)``, followed by ``"\r\n"``.
 
-.. cpp:function:: USBSerial::println(long n)
+.. cpp:function:: USBSerial::println(long long n)
 
    Like ``print(n)``, followed by ``"\r\n"``.
 
-.. cpp:function:: USBSerial::println(unsigned long n)
+.. cpp:function:: USBSerial::println(unsigned long long n)
 
    Like ``print(n)``, followed by ``"\r\n"``.
 
-.. cpp:function:: USBSerial::println(long n, int base)
+.. cpp:function:: USBSerial::println(int n, int base)
+
+   Like ``print(n, b)``, followed by ``"\r\n"``.
+
+.. cpp:function:: USBSerial::println(long long n, int base)
 
    Like ``print(n, b)``, followed by ``"\r\n"``.