aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/lang/api
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@leaflabs.com>2011-02-24 14:42:30 -0500
committerMarti Bolivar <mbolivar@leaflabs.com>2011-02-24 15:45:41 -0500
commit4e493c670aaabd8179976621d4b0bf3997fdc814 (patch)
treefebfef70c77381508cbcc19976c5eaf23c35ad09 /docs/source/lang/api
parent7a5627be405c5f3353f58198ec4437a7e8138dff (diff)
downloadlibrambutan-4e493c670aaabd8179976621d4b0bf3997fdc814.tar.gz
librambutan-4e493c670aaabd8179976621d4b0bf3997fdc814.zip
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.
Diffstat (limited to 'docs/source/lang/api')
-rw-r--r--docs/source/lang/api/serial.rst35
-rw-r--r--docs/source/lang/api/serialusb.rst35
2 files changed, 48 insertions, 22 deletions
diff --git a/docs/source/lang/api/serial.rst b/docs/source/lang/api/serial.rst
index ca89b31..58002e3 100644
--- a/docs/source/lang/api/serial.rst
+++ b/docs/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/docs/source/lang/api/serialusb.rst b/docs/source/lang/api/serialusb.rst
index 3bb8c00..87fa641 100644
--- a/docs/source/lang/api/serialusb.rst
+++ b/docs/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"``.