# SFBPrintf.h File Reference

Support for simple packet-customized printf- and scanf-like functions. More...

`#include "SFBTypes.h"`
`#include <stdarg.h>`

Include dependency graph for SFBPrintf.h:

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

Go to the source code of this file.

## Enumerations
enum | { LOGLEVEL_NONE, LOGLEVEL_QUIET, LOGLEVEL_NORMAL, LOGLEVEL_VERBOSE, LOGLEVEL_DEBUG }
## Functions
void | setLogLevel (int n)
int | getLogLevel ()
void | setLogFace (u8 face)
u8 | getLogFace ()
void | pprintf (const char *format,...)
| Convenience shorthand for printing to all available physical faces.
void | facePrintf (u8 face, const char *format,...)
| Formatted printing to the specified face.
void | vfacePrintf (u8 face, const char *format, va_list &ap)
| Formatted printing to the specified face, through a supplied `va_list`.
u32 | packetScanf (u8 *packet, const char *format,...)
| Formatted reading from a packet into individual variables.
u32 | vPacketScanf (u8 *packet, const char *format, va_list &ap)
void | vfaceLogf (int includeTimestamp, int level, u8 face, const char *format, va_list &ap)
void | logf (int level, const char *format,...)
void | logNormal (const char *format,...)
void | logVerbose (const char *format,...)
void | logDebug (const char *format,...)
void | logQuiet (const char *format,...)
void | msgf (int level, const char *format,...)
void | msgNormal (const char *format,...)
void | msgVerbose (const char *format,...)
void | msgDebug (const char *format,...)
void | msgQuiet (const char *format,...)

## Detailed Description

Support for simple packet-customized printf- and scanf-like functions.

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 facePrintf | ( | u8 | face,
|  | const char * | format,
|  |  | ... |
| ) |  |  |

Formatted printing to the specified face.

Parameters:

  | face | the face code to which the printing shall be directed. This may be a "physical face" code like WEST, an "extended face" code like BRAIN or ALL_FACES or NO_FACES, or a sketch-defined "virtual face" code (such as produced by faceFindFreeFace() and faceSetPrinter()).
  | format | a null-terminated string controlling what is to be printed; see below.
  | ... | a variable sequence of arguments of sufficient number and appropriate types to supply to all of the "% codes" in format with the data they need.

facePrintf() performs simple formatted printing, in the same general style as the C language `printf` functions, but with many restrictions -- for example, there is only limited support for 'field widths'. There are also a few SFB-specific extensions. This documentation presumes familiarity with the use of `printf-like` functions in general, and only documents the specifics of the SFB format codes.

Quick format reference. The following 'percent escape' codes are recognized:

- %c: Print 8 bit character into exactly one output byte.
- %h: Print 16 bit value into exactly two output bytes in 'big endian' network order.
- %l: Print 32 bit value into exactly four output bytes in 'big endian' network order.
- %b: Print 32 bit value in base 2 (using only the characters '0' and '1').
- %o: Print 32 bit value in base 8 (using only the characters '0' through '7').
- %d: Print 32 bit value in base 10 (using only the characters '0' through '9').
- %x: Print 32 bit value in base 16 (using only the characters '0' through '9' and 'A' through 'F' for 10 to 15).
- %t: Print 32 bit value in base 36 (using only the characters '0' through '9' and 'A' through 'Z' for 10 to 35).
- %F: Print the 'face code' (e.g., 'N' for North) in one output byte
- %f: Print double value in floating point with two decimal places.
- %s: Print null-terminated string given a (const char *) pointer to the first byte
- %p: Print a packet given a (const u8 *) pointer to the packet
- %%: Print a percent sign
- %\n: Print a checkbyte and then a newline (as by printlnCheckbyte).

The '#' modifier character may be added to certain conversions to achieve special purposes, as follows:

- For the %d code, '#' causes the argument to be printed as an unsigned value rather than signed.
- For the %b, %o, %x, and %t codes, '#' causes the argument to be printed as a signed value rather than unsigned.
- For the %c code, '#' causes a 'non-printing' char arg to be printed as four bytes -- a '[', two hex digits, and a ']' -- rather than printing the char value directly.
- For the %p code, '#' causes any 'non-printing' bytes (or '%' bytes) of the packet to be printed as three bytes each -- a '%', followed by two hex digits -- rather than printing the byte values directly.

Since 0.9.7, there is limited support for field widths (a.k.a. padding and filling), with the following restrictions:

- Padding is supported only on the formatted integer conversions --%b, %o, %d, %x, and %t,
- Only padding on the left is supported (so, only 'right-justified columns').
- Padding is always either spaces or zeros; spaces are used unless the field width begins with a '0'.

XXX Still need formatting details; examples.

Blinks:
  E_API_NULL_POINTER if format is null.

Blinks:
  E_API_BAD_FACE if face is not a valid (physical, extended, or defined virtual) face.

Blinks:
  E_API_BAD_FORMAT_CODE if an unrecognized "%" code is encountered in format. (Also occurs if a single "%" is the last character in format.)

Since:
  0.9.7 for field widths

Examples:
  brn.cpp, hallucination.cpp, and log.cpp.

u32 packetScanf | ( | u8 * | packet,
|  | const char * | format,
|  |  | ... |
| ) |  |  |

Formatted reading from a packet into individual variables.

Scanning starts at the current packetCursor() of packet, not necessarily at the beginning, and the packetCursor() of packet is advanced as scanning proceeds.

Parameters:

  | packet | The packet that is to be scanned.
  | format | a null-terminated string controlling what is to be printed; see below.
  | ... | a variable sequence of pointer arguments of sufficient number and appropriate types through which to store values for all the "% codes" in format that require arguments.

With the exceptions of %s, %f, and %p, which are not supported, packetScanf supports the same format codes as facePrintf prints, which see for further description of the format conversions. Note that the pointed-to variables must be appropriate (sizes at least) for the converted type! For example,

      void MyBHandler(u8 * packet) {
        u32 fourBytes; u16 twoBytes; u8 oneByte;
        if (packetScanf(packet,"b%c%d%h",&oneByte,&fourBytes,&twoBytes) != 4)
           return;
        ..
      }

is correct since the sizes of the `oneByte`, `fourBytes`, and `twoBytes` variables match the specified sizes of %c, %d, and %h, respectively.

Since 0.9.9, there is some support for field widths, limited to the %b, %o, %d, %x, and %t conversions only.

packetScanf returns the number of successful matches it made, where a 'match' counts as either a successful '% conversion' or a successful match of a single literal byte of the format string. E.g., given a packet containing "fg123h", `packetScanf`(packet,"fg%dh",&u32var) will return 4 -- one for the 'f', one for the 'g', one for the '%d', and one for the 'h'. (But watch out! Given the same packet, `packetScanf`(packet,"fg%dh\n",&u32var) will return 5 -- including one for the successful matching of the end-of-packet!)

XXX Still need formatting details; examples.

Since:
  0.9.9 for field widths

Examples:
  eeprom1.cpp, pingpong.cpp, and pingpong2.cpp.

void pprintf | ( | const char * | format,
|  |  | ... |
| ) |  |  |

Convenience shorthand for printing to all available physical faces.

Equivalent to facePrintf(ALL_FACES, format, ...), which see for details of the possible format codes.

void vfacePrintf | ( | u8 | face,
|  | const char * | format,
|  | va_list & | ap |
| ) |  |  |

Formatted printing to the specified face, through a supplied `va_list`.

See facePrintf(u8 face, const char * format, ...) for details of arguments face and format.