# SFBPrint.h File Reference

Support for basic formatted printing. More...

`#include "SFBConstants.h"`
`#include "SFBAlarm.h"`
`#include "SFBReactor.h"`
`#include "SFBFrame.h"`

Include dependency graph for SFBPrint.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures
struct | FacePrinter
| A FacePrinter is capable of performing low-level printing operations to some assigned (physical or 'virtual') face. More...
## Functions
void | print (const char *str)
| Same as facePrint(u8 face, const char * str) with `face` set to ALL_FACES.
void | print (const u8 *str, u32 len)
| Same as facePrint(u8 face, const u8 * str,u32 len) with `face` set to ALL_FACES.
void | print (int decimal)
| Same as facePrint(u8 face, int decimal) with `face` set to ALL_FACES.
void | print (unsigned int decimal)
| Same as facePrint(u8 face, unsigned long decimal) with `face` set to ALL_FACES.
void | print (long decimal)
| Same as facePrint(u8 face, long decimal) with `face` set to ALL_FACES.
void | print (unsigned long decimal)
| Same as facePrint(u8 face, unsigned long decimal) with `face` set to ALL_FACES.
void | print (long decimal, int code)
| Same as facePrint(u8 face, unsigned long decimal, int code) with `face` set to ALL_FACES.
void | print (double val)
| Same as facePrint(u8 face, double val) with `face` set to ALL_FACES.
void | printFace ()
| Same as facePrintFace(u8 face) with `face` set to ALL_FACES.
void | println ()
| Same as facePrintln(u8 face) with `face` set to ALL_FACES.
void | println (const char *str)
| Same as facePrintln(u8 face, const char * str) with `face` set to ALL_FACES.
void | println (const u8 *str, u32 len)
| Same as facePrintln(u8 face, const u8 * str,u32 len) with `face` set to ALL_FACES.
void | println (int decimal)
| Same as facePrintln(u8 face, int decimal) with `face` set to ALL_FACES.
void | println (unsigned int decimal)
| Same as facePrintln(u8 face, unsigned long decimal) with `face` set to ALL_FACES.
void | println (long decimal)
| Same as facePrintln(u8 face, long decimal) with `face` set to ALL_FACES.
void | println (unsigned long decimal)
| Same as facePrint(u8 face, unsigned long decimal) with `face` set to ALL_FACES.
void | println (long decimal, int code)
| Same as facePrintln(u8 face, unsigned long decimal, int code) with `face` set to ALL_FACES.
void | println (double val)
| Same as facePrint(u8 face, double val) with `face` set to ALL_FACES.
void | printlnCheckByte ()
| Same as facePrintlnCheckByte() with `face` set to ALL_FACES.
void | facePrint (u8 face, const char *str)
| Print the contents of a null-terminated string to the current xmit packet of face.
void | facePrint (u8 face, const u8 *str, u32 len)
| Print str, an array of bytes of length len, to the current xmit packet of face.
void | facePrint (u8 face, int decimal)
| Same as facePrint(u8 face, long decimal).
void | facePrint (u8 face, unsigned int decimal)
| Print decimal as an unsigned decimal number, to the current xmit packet of face.
void | facePrint (u8 face, long decimal)
| Print decimal as a signed decimal number, to the current xmit packet of face.
void | facePrint (u8 face, unsigned long decimal)
| Same as facePrint(u8 face, unsigned long decimal, int code) with `code` set to `DEC`.
void | facePrint (u8 face, unsigned long decimal, int code)
| Print num, in a format selected by code, to the current xmit packet of face.
void | facePrint (u8 face, double val)
| Print val in a floating-point ASCII representation, with two digits to the right of the right of the decimal point.
void | facePrintFace (u8 face)
| Print the 'face code' of face to the current xmit packet of face.
void | facePrintln (u8 face)
| Terminate the current xmit packet on face.
void | facePrintln (u8 face, const char *str)
| Same as facePrint(u8 face, const char * str) followed by facePrintln().
void | facePrintln (u8 face, const u8 *str, u32 len)
| Same as facePrint(u8 face, const u8 * str,u32 len) followed by facePrintln().
void | facePrintln (u8 face, int decimal)
| Same as facePrint(u8 face, int decimal) followed by facePrintln().
void | facePrintln (u8 face, unsigned int decimal)
| Same as facePrint(u8 face, unsigned int decimal) followed by facePrintln().
void | facePrintln (u8 face, long decimal)
| Same as facePrint(u8 face, long decimal) followed by facePrintln().
void | facePrintln (u8 face, unsigned long decimal)
| Same as facePrint(u8 face, unsigned long decimal) followed by facePrintln().
void | facePrintln (u8 face, unsigned long decimal, int code)
| Same as facePrint(u8 face, unsigned long decimal, int code) followed by facePrintln().
void | facePrintln (u8 face, double val)
| Same as facePrint(u8 face, double val) followed by facePrintln().
void | facePrintlnCheckByte (u8 face)
| Prints a 'packet check byte' and then terminates the packet via facePrintln(u8 face).
bool | faceHasPrinter (u8 face)
bool | faceFindFreeFace (u8 &foundFace)
void | faceSetPrinter (u8 face, const FacePrinter *handler)
void | faceUnsetPrinter (u8 face)
void | print_startup_initialization ()

## Detailed Description

Support for basic formatted printing.

Author:
  David H. Ackley.

Date:
  (C) 2009 All rights reserved.

Code License:
  The GNU Lesser General Public License

License Note:
  All code samples shown in documentation are placed into the public domain.

## Function Documentation

void facePrint | ( | u8 | face,
|  | double | val |
| ) |  |  |

Print val in a floating-point ASCII representation, with two digits to the right of the right of the decimal point.

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | val | A double floating point value to be printed.

Side Effects:
  The currently xmit packet of face increases in length as needed to print val, if packet length and buffer space room is available.

Example:

        ...
          int signedNum = -1;
          u32 unsignedNum = signedNum;
          facePrint(WEST,signedNum,DEC);               // Prints "-1": Signed num with code DEC
          facePrint(WEST,unsignedNum,DEC);             // Prints "4294967295": Unsigned num with code DEC
          facePrint(WEST,signedNum,HEX);               // Prints "FFFFFFFF": Non-DEC codes are always
          facePrint(WEST,unsignedNum,HEX);             // Prints "FFFFFFFF": printed as unsigned
        ...

void facePrint | ( | u8 | face,
|  | unsigned long | num,
|  | int | code |
| ) |  |  |

Print num, in a format selected by code, to the current xmit packet of face.

The possible format codes are:

- DEC: Print one to ten bytes containing the base-10 representation of the 32 bits of num, using the ASCII characters '0' through '9'. See the 'd' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `DEC`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.
- HEX: Print one to eight bytes containing the base-16 representation of the 32 bits of num, using the ASCII characters '0' through '9' to represent 0 through 9, and 'A' through 'F' to represent 10 through 15. See the 'x' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `HEX`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.
- OCT: Print one to eleven bytes containing the base-8 representation of the 32 bits of num, using the ASCII characters '0' through '7' to represent 0 through 7. See the 'x' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `OCT`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.
- BIN: Print one to 32 bytes containing the base-2 representation of the 32 bits of num, using the ASCII characters '0' and '1' to represent 0 and 1. See the 'b' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `BIN`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.
- B36: Print one to six bytes containing the base-36 representation of the 32 bits of num, using the ASCII characters '0' through '9' to represent 0 through 9, and 'A' through 'Z' to represent 10 through 35. See the 't' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `B36`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.
- BELONG: Print exactly four bytes containing the 32 bits of num, with the four bytes in 'big endian order', also known as 'network order'. See the 'l' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `BELONG`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation. ]

`BELONG` is called a 'binary' code, but it must not be confused with BIN. With `BELONG`, each of the four output bytes may each contain any possible bit pattern, whereas with code BIN each output byte is either the ASCII code for '0' or the ASCII code for '1'.

- BESHORT: Print exactly two bytes containing the low-order 16 bits of num, with the two bytes in 'big endian order', also known as 'network order'. See the 'h' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `BESHORT`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.

`BESHORT` is called a 'binary' code, but it must not be confused with BIN. With `BESHORT`, each of the two output bytes may each contain any possible bit pattern, whereas with code BIN each output byte is either the ASCII code for '0' or the ASCII code for '1'.

- BYTE: Print exactly one byte containing the low-order 8 bits of num. See the 'c' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `BYTE`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.

`BYTE` is called a 'binary' code, but it must not be confused with BIN. With `BYTE`, the output byte may each contain any possible bit pattern, whereas with code BIN each output byte is either the ASCII code for '0' or the ASCII code for '1'.

In addition to those codes, it is also possible to print in other bases between 2 and 36, if there is call to do so. For example, using a code value of 13 will select printing in base 13, using the ASCII characters '0' through '9' and 'A' through 'C'.

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | num | A 32 bit number to be printed in a particular format.
  | code | What format to use (see above).

Blinks:
  E_API_FORMAT_ARG If code is an illegal code. The legal codes are BELONG, BESHORT or BYTE, or any value from 2 to 36 (which includes DEC, HEX, OCT, BIN, and B36).

Side Effects:
  The currently xmit packet of face increases in length as needed by the selected format, if packet length and buffer space room is available.

Sample all-ASCII printable packet generation:

Example:

        void myHandler(u8 *) {
          facePrint(SOUTH,"L 1234 in:");
          facePrint(SOUTH," base 10="); facePrint(SOUTH, 1234, DEC); // Prints 1234
          facePrint(SOUTH," base 16="); facePrint(SOUTH, 1234, HEX); // Prints 4D2
          facePrint(SOUTH," base 8=");  facePrint(SOUTH, 1234, OCT); // Prints 2322
          facePrint(SOUTH," base 2=");  facePrint(SOUTH, 1234, BIN); // Prints 10011010010
          facePrint(SOUTH," base 36="); facePrint(SOUTH, 1234, B36); // Prints YA
          facePrintln(SOUTH);
        }

Sample binary packet generation:

Example:

        void setup() { /\* nothing to do *\/ }
        void loop() {                                  // Print a packet containing exactly eight bytes:
          facePrint(ALL_FACES,"t");                    //  1 byte containing an ASCII 't'
          facePrint(ALL_FACES,millis(),BELONG);        // +4 bytes of board uptime in big endian
          facePrint(ALL_FACES,random(10000),BESHORT);  // +2 bytes of a random number 0..9999 in big endian
          facePrintln();                               // +1 byte containing an ASCII newline '\n'
          delay(1000);                                 // Wait a second, then do it again.
        }

void facePrint | ( | u8 | face,
|  | long | decimal |
| ) |  |  |

Print decimal as a signed decimal number, to the current xmit packet of face.

Compare to facePrint(u8 face, unsigned long decimal). If decimal is less than zero, prints a '-' followed by the value of `-decimal` (note this gives the wrong output for the 'most negative' possible number.)

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | decimal | A 32 bit number to be printed as a signed decimal value.

Side Effects:
  The currently xmit packet of face gets up to eleven bytes longer, if packet length and buffer space room is available.

Example:

        void myHandler(u8 *) {
          long num = 123-456;               // Compute something. 'int' means 'signed 32 bit value'
          facePrint(EAST,"L answer=");     // Print some text to EastFace
          facePrintln(EAST,num);           // Prints '-333' and ends the packet
        }

void facePrint | ( | u8 | face,
|  | unsigned int | decimal |
| ) |  |  |

Print decimal as an unsigned decimal number, to the current xmit packet of face.

Compare to facePrint(u8 face, int decimal).

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | decimal | A 32 bit number to be printed as an unsigned decimal value.

Side Effects:
  The currently xmit packet of face gets up to ten bytes longer, if packet length and buffer space room is available.

Example:

        void myHandler(u8 *) {
          u32 num = 123*456;             // Compute something. 'u32' means 'unsigned 32 bit value'
          facePrint(EAST,"L answer=");   // Print some text to EastFace
          facePrintln(EAST,num);         // Prints '56088' and ends the packet
        }

void facePrint | ( | u8 | face,
|  | const u8 * | str,
|  | u32 | len |
| ) |  |  |

Print str, an array of bytes of length len, to the current xmit packet of face.

Compare to facePrint(u8 face, const char * str). If str is a packet, you may want to consider the '%p' or '%#p' formats of facePrintf() as well.

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | str | A pointer to the byte array to append. Must be of length (at least) len; does not need to be null-terminated.

Blinks:
  E_API_NULL_POINTER if str is null.

Side Effects:
  The currently xmit packet of face gets up to len bytes longer, if packet length and buffer space room is available.

Example:

        void myHandler(u8 * packet) {
          facePrint(NORTH,"L I got a packet containing '");      // Print some text to NorthFace
          facePrint(NORTH,packet,packetLength(packet));          // Add entire contents of packet
          facePrintln(NORTH,"'");                                // Add an end quote then end the packet
        }

void facePrint | ( | u8 | face,
|  | const char * | str |
| ) |  |  |

Print the contents of a null-terminated string to the current xmit packet of face.

Compare to facePrint(u8 face, const u8 * str, u32 len).

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | str | A pointer to the null-terminate string to append.

Blinks:
  E_API_NULL_POINTER if str is null.

Side Effects:
  The currently xmit packet of face gets up to `strlen(str)` bytes longer, if packet length and buffer space room is available.

Example:

        void myHandler(u8 * packet) {
          facePrint(NORTH,"L I received a packet of length "); // Print some text to NorthFace only
          facePrintln(NORTH,packetLength(packet), DEC);        // End packet after a decimal number
        }

Examples:
  tee.cpp.

void facePrintFace | ( | u8 | face | ) |

Print the 'face code' of face to the current xmit packet of face.

See also the 'F' format of facePrintf(u8 face, const char * format,...) for another way to perform this action, and in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with this method.

Parameters:

  | face | A face code indicating which face(s) to print to. If face is NORTH, SOUTH, EAST, or WEST, then 'N', 'S', 'E', or 'W' is printed, respectively. If face is ALL_FACES, then for each eligible basic face, that face's own face code is printed to the corresponding face. If it is some other 'special' or 'virtual' face, then what is printed depends on the specific code involved.

Not so amazing sample:

Example:

        ...
          facePrintFace(NORTH);          // Prints 'N' to the NorthFace
          facePrintFace(WEST);           // Prints 'W' to the WestFace
        ...

Slightly more interesting sample:

Example:

        ...
          facePrint(ALL_FACES,"L You are my "); // These three lines print "L You are my N" to the NorthFace,
          facePrintFace(ALL_FACES);             // "L You are my S" to the SouthFace, "L You are my E" to the
          facePrintln(ALL_FACES);               // EastFace, and "L You are my W" to the WestFace (assuming
        ...                                     // they are all connected and processing packets).

void facePrintln | ( | u8 | face,
|  | double | val |
| ) |  |  |

Same as facePrint(u8 face, double val) followed by facePrintln().

void facePrintln | ( | u8 | face,
|  | unsigned long | decimal,
|  | int | code |
| ) |  |  |

Same as facePrint(u8 face, unsigned long decimal, int code) followed by facePrintln().

void facePrintln | ( | u8 | face,
|  | unsigned long | decimal |
| ) |  |  |

Same as facePrint(u8 face, unsigned long decimal) followed by facePrintln().

void facePrintln | ( | u8 | face,
|  | long | decimal |
| ) |  |  |

Same as facePrint(u8 face, long decimal) followed by facePrintln().

void facePrintln | ( | u8 | face,
|  | unsigned int | decimal |
| ) |  |  |

Same as facePrint(u8 face, unsigned int decimal) followed by facePrintln().

void facePrintln | ( | u8 | face,
|  | int | decimal |
| ) |  |  |

Same as facePrint(u8 face, int decimal) followed by facePrintln().

void facePrintln | ( | u8 | face,
|  | const u8 * | str,
|  | u32 | len |
| ) |  |  |

Same as facePrint(u8 face, const u8 * str,u32 len) followed by facePrintln().

void facePrintln | ( | u8 | face,
|  | const char * | str |
| ) |  |  |

Same as facePrint(u8 face, const char * str) followed by facePrintln().

void facePrintln | ( | u8 | face | ) |

Terminate the current xmit packet on face.

Normally the effect of this is to print an ASCII newline character, '
', but that behavior may be altered by the packet framing in use on the face.

Examples:
  forward.cpp, pingpong.cpp, pingpong2.cpp, and tee.cpp.

void facePrintlnCheckByte | ( | u8 | face | ) |

Prints a 'packet check byte' and then terminates the packet via facePrintln(u8 face).

A packet check byte is a single byte value that can optionally be placed as the last byte of a packet, to provide one measure of 'integrity check' that the packet data was not corrupted during transmission. The value of a packet check byte depends on on all the previous bytes in the packet, so if any bytes of the packet were garbled while in transit, it is fairly likely, though not guaranteed, that the check byte will fail to match so the error can be detected.

See the '%
' format of facePrintf(u8 face, const char * format,...) for another way to append a check byte to a packet, and see packetReadCheckByte(u8 * packet) or the '%
' format of packetScanf(u8 * packet, const char * format,...) for ways to read and verify a check byte that was appended to a packet.

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).

Side Effects:
  The currently xmit packet of face increases in length by one byte containing the computed check byte, if packet length and buffer space room is available.

void print | ( | double | val | ) |

Same as facePrint(u8 face, double val) with `face` set to ALL_FACES.

void print | ( | long | decimal,
|  | int | code |
| ) |  |  |

Same as facePrint(u8 face, unsigned long decimal, int code) with `face` set to ALL_FACES.

void print | ( | unsigned long | decimal | ) |

Same as facePrint(u8 face, unsigned long decimal) with `face` set to ALL_FACES.

void print | ( | long | decimal | ) |

Same as facePrint(u8 face, long decimal) with `face` set to ALL_FACES.

void print | ( | unsigned int | decimal | ) |

Same as facePrint(u8 face, unsigned long decimal) with `face` set to ALL_FACES.

void print | ( | int | decimal | ) |

Same as facePrint(u8 face, int decimal) with `face` set to ALL_FACES.

void print | ( | const u8 * | str,
|  | u32 | len |
| ) |  |  |

Same as facePrint(u8 face, const u8 * str,u32 len) with `face` set to ALL_FACES.

void print | ( | const char * | str | ) |

Same as facePrint(u8 face, const char * str) with `face` set to ALL_FACES.

void printFace | ( |  | ) |

Same as facePrintFace(u8 face) with `face` set to ALL_FACES.

void println | ( | double | val | ) |

Same as facePrint(u8 face, double val) with `face` set to ALL_FACES.

void println | ( | long | decimal,
|  | int | code |
| ) |  |  |

Same as facePrintln(u8 face, unsigned long decimal, int code) with `face` set to ALL_FACES.

void println | ( | unsigned long | decimal | ) |

Same as facePrint(u8 face, unsigned long decimal) with `face` set to ALL_FACES.

void println | ( | long | decimal | ) |

Same as facePrintln(u8 face, long decimal) with `face` set to ALL_FACES.

void println | ( | unsigned int | decimal | ) |

Same as facePrintln(u8 face, unsigned long decimal) with `face` set to ALL_FACES.

void println | ( | int | decimal | ) |

Same as facePrintln(u8 face, int decimal) with `face` set to ALL_FACES.

void println | ( | const u8 * | str,
|  | u32 | len |
| ) |  |  |

Same as facePrintln(u8 face, const u8 * str,u32 len) with `face` set to ALL_FACES.

void println | ( | const char * | str | ) |

Same as facePrintln(u8 face, const char * str) with `face` set to ALL_FACES.

void println | ( |  | ) |

Same as facePrintln(u8 face) with `face` set to ALL_FACES.

Examples:
  alarm1.cpp, blinkySync.cpp, and pingpong2.cpp.

void printlnCheckByte | ( |  | ) |

Same as facePrintlnCheckByte() with `face` set to ALL_FACES.