Container class that has formatting methods for human-readable output. This class can be constructed and used for easy and efficient output via any communication protocol. More...

#include <PropWare/hmi/output/printer.h>

Collaboration diagram for PropWare::Printer:

Classes
struct	Format
	Passed into any of the `Printer::print` methods, this struct controls how aspects of numerical printing. More...

Public Member Functions
	Printer (PrintCapable &printCapable, const bool cooked=true)
	Construct a Printer instance that will use the given `*printCapable` instance for sending each character. More...

void	set_cooked (const bool cooked)
	Turn on or off cooked mode. More...

bool	get_cooked () const
	Determine if the printer is configured for cooked mode or not. More...

void	put_char (const char c) const
	Print a single character. More...

void	puts (const char string[]) const
	Send a null-terminated character array. More...

void	put_int (int x, const uint8_t radix=10, uint16_t width=0, const char fillChar=DEFAULT_FILL_CHAR) const
	Print a signed integer in base 10. More...

void	put_uint (unsigned int x, const uint8_t radix=10, uint16_t width=0, const char fillChar=DEFAULT_FILL_CHAR) const
	Print an unsigned integer in base 10. More...

void	put_ll (long long x, const uint8_t radix=10, uint16_t width=0, const char fillChar=DEFAULT_FILL_CHAR) const
	Print a signed integer in base 10. More...

void	put_ull (unsigned long long x, const uint8_t radix=10, uint16_t width=0, const char fillChar=DEFAULT_FILL_CHAR) const
	Print an unsigned integer in base 10. More...

void	put_float (double f, uint16_t width=0, uint16_t precision=6, const char fillChar=DEFAULT_FILL_CHAR) const
	Print a floating point number with a given width and precision. More...

template<typename T , typename... Targs>
void	printf (const char fmt[], const T first, const Targs... remaining) const
	Similar in functionality to the C-standard function printf. More...

void	printf (const char fmt[]) const

void	print (const char c, const Format &format=DEFAULT_FORMAT) const
	Print a single character. More...

void	print (const char string[], const Format &format=DEFAULT_FORMAT) const
	Print a null-terminated string. More...

void	println (const char string[]) const
	Print a null-terminated string followed by a newline (' ') More...

void	println () const
	Print a newline (' ')

void	print (const bool b, const Format &format=DEFAULT_FORMAT) const
	Print a boolean as either "true" or "false". More...

void	print (const unsigned int x, const Format &format=DEFAULT_FORMAT) const
	Print an unsigned integer with the given format. More...

void	print (const int x, const Format &format=DEFAULT_FORMAT) const
	Print a single character. More...

void	print (const unsigned long long x, const Format &format=DEFAULT_FORMAT) const
	Print an unsigned integer with the given format. More...

void	print (const long long x, const Format &format=DEFAULT_FORMAT) const
	Print a single character. More...

void	print (const double f, const Format &format=DEFAULT_FORMAT) const
	Print a single character. More...

template<typename T >
const Printer &	operator<< (const T arg) const
	The `<<` operator allows for highly optimized use of the Printer. More...

template<typename T >
Printer &	operator<< (const T arg)
	The `<<` operator allows for highly optimized use of the Printer. More...

Printer &	operator<< (const Format arg)

Static Public Attributes
static const uint16_t	DEFAULT_WIDTH = 0

static const uint16_t	DEFAULT_PRECISION = 6

static const uint8_t	DEFAULT_RADIX = 10

static const char	DEFAULT_FILL_CHAR = ' '

static const Format	DEFAULT_FORMAT

Detailed Description

Container class that has formatting methods for human-readable output. This class can be constructed and used for easy and efficient output via any communication protocol.

Printing to Terminal

To print to the standard terminal, simply use the existing object, pwOut:

pwOut.printf("Hello, world!\n");

Creating Custom Printers

To create your own Printer, you will first need an instance of any object that implements the PrintCapable interface. Your code might look something like this:

PropWare::HD44780       myLCD;
const PropWare::Printer lcdPrinter(&myLCD);
 
lcd.start(FIRST_DATA_PIN, RS, RW, EN, BITMODE, DIMENSIONS);
lcdPrinter.printf("Hello, LCD!\n");

Adding const in front of the Printer declaration allows the compiler to make some extra optimizations and is encouraged when possible.

Examples: BufferedUART_Demo.cpp, Eeprom_Demo.cpp, FullDuplexSerial_Demo.cpp, HD44780_Demo.cpp, Hello_Demo.cpp, Hybrid_Demo.cpp, and StringBuilder_Demo.cpp.

Definition at line 76 of file printer.h.

Constructor & Destructor Documentation

◆ Printer()

PropWare::Printer::Printer	(	PrintCapable &	printCapable,
		const bool	cooked = `true`
	)

Construct a Printer instance that will use the given *printCapable instance for sending each character.

Parameters

printCapable	The address of any initialized communication object such as a PropWare::UART
cooked	True to turn cooked mode on, false to turn it off. See PropWare::Printer::set_cooked for more information

Definition at line 133 of file printer.h.

Member Function Documentation

◆ get_cooked()

bool PropWare::Printer::get_cooked ( ) const

Determine if the printer is configured for cooked mode or not.

Cooked mode prefixes all instances of the newline character (\n) with a carriage return (\r). This is required by many serial programs and is the default for PropGCC's serial routines. The default status for a Printer is also on. This can, however, have adverse affects if you are trying to use a printer to send raw data between two devices rather than human-readable data.

Read more on WikiPedia about cooked mode_

Returns: True when cooked mode is on

Definition at line 166 of file printer.h.

◆ operator<<() [1/2]

template<typename T >

Printer& PropWare::Printer::operator<< ( const T arg )

The << operator allows for highly optimized use of the Printer.

Using the << operator tells GCC exactly what types of arguments are being used at compilation time, and GCC can therefore include only those functions in the binary. Some similar optimizations can be made with PropWare::Printer::printf, but not as many. Unless you need special formatting (such as whitespace padding or specific widths), your code will be best optimized if you only use this method for printing, and never PropWare::Printer::printf.

Converting PropWare::Printer::printf to use the << operator:

const char name[] = "David";  // My name
const int i = 7;             //
pwOut.printf("Hello, %s! The %dth character of the alphabet is %c.\n", name, i, i + 'A' - 1);
pwOut << "Hello, " << name << "! The " << i << "th character of the alphabet is" << (char) i + 'A' - 1 << ".\n";

Parameters

[in] arg Value to be printed through the terminal

Returns: The printer instance is returned to allow chaining of the method calls

Definition at line 722 of file printer.h.

Here is the call graph for this function:

◆ operator<<() [2/2]

template<typename T >

const Printer& PropWare::Printer::operator<< ( const T arg ) const

The << operator allows for highly optimized use of the Printer.

Using the << operator tells GCC exactly what types of arguments are being used at compilation time, and GCC can therefore include only those functions in the binary. Some similar optimizations can be made with PropWare::Printer::printf, but not as many. Unless you need special formatting (such as whitespace padding or specific widths), your code will be best optimized if you only use this method for printing, and never PropWare::Printer::printf.

Converting PropWare::Printer::printf to use the << operator:

const char name[] = "David";  // My name
const int i = 7;             //
pwOut.printf("Hello, %s! The %dth character of the alphabet is %c.\n", name, i, i + 'A' - 1);
pwOut << "Hello, " << name << "! The " << i << "th character of the alphabet is" << (char) i + 'A' - 1 << ".\n";

Parameters

[in] arg Value to be printed through the terminal

Returns: The printer instance is returned to allow chaining of the method calls

Definition at line 694 of file printer.h.

Here is the call graph for this function:

◆ print() [1/8]

void PropWare::Printer::print	(	const bool	b,
		const Format &	format = `DEFAULT_FORMAT`
	)		const

Print a boolean as either "true" or "false".

Parameters

[in]	b	Boolean to be printed
	format	Unused

Definition at line 617 of file printer.h.

Here is the call graph for this function:

◆ print() [2/8]

void PropWare::Printer::print	(	const char	c,
		const Format &	format = `DEFAULT_FORMAT`
	)		const

Print a single character.

Parameters

[in]	c	Character to be printed
	format	Unused

Definition at line 580 of file printer.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ print() [3/8]

void PropWare::Printer::print	(	const char	string[],
		const Format &	format = `DEFAULT_FORMAT`
	)		const

Print a null-terminated string.

Parameters

[in]	string[]	String to be printed
	format	Unused

Definition at line 590 of file printer.h.

Here is the call graph for this function:

◆ print() [4/8]

void PropWare::Printer::print	(	const double	f,
		const Format &	format = `DEFAULT_FORMAT`
	)		const

Print a single character.

Parameters

[in]	f	Unsigned value to be printed
[in]	format	Format of the number

Definition at line 667 of file printer.h.

Here is the call graph for this function:

◆ print() [5/8]

void PropWare::Printer::print	(	const int	x,
		const Format &	format = `DEFAULT_FORMAT`
	)		const

Print a single character.

Parameters

[in]	x	Unsigned value to be printed
[in]	format	Format of the integer

Definition at line 637 of file printer.h.

Here is the call graph for this function:

◆ print() [6/8]

void PropWare::Printer::print	(	const long long	x,
		const Format &	format = `DEFAULT_FORMAT`
	)		const

Print a single character.

Parameters

[in]	x	Unsigned value to be printed
[in]	format	Format of the integer

Definition at line 657 of file printer.h.

Here is the call graph for this function:

◆ print() [7/8]

void PropWare::Printer::print	(	const unsigned int	x,
		const Format &	format = `DEFAULT_FORMAT`
	)		const

Print an unsigned integer with the given format.

Parameters

[in]	x	Unsigned value to be printed
[in]	format	Format of the integer

Definition at line 627 of file printer.h.

Here is the call graph for this function:

◆ print() [8/8]

void PropWare::Printer::print	(	const unsigned long long	x,
		const Format &	format = `DEFAULT_FORMAT`
	)		const

Print an unsigned integer with the given format.

Parameters

[in]	x	Unsigned value to be printed
[in]	format	Format of the integer

Definition at line 647 of file printer.h.

Here is the call graph for this function:

◆ printf() [1/2]

void PropWare::Printer::printf ( const char fmt[] ) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 570 of file printer.h.

Here is the call graph for this function:

◆ printf() [2/2]

template<typename T , typename... Targs>

void PropWare::Printer::printf	(	const char	fmt[],
		const T	first,
		const Targs...	remaining
	)		const

Similar in functionality to the C-standard function printf.

This method supports formatted printing using the following formats:

%i - Signed integer (32-bit max, use << for 64-bit)
%d - Signed integer (32-bit max, use << for 64-bit)
%u - Unsigned integer (32-bit max, use << for 64-bit)
%s - String
%c - Single character
%X - Hexadecimal with capital letters
%b - Binary
%f - Floating point number
%% - Literal percent sign (%)

A single space will be printed in place of unsupported formats.

Warning: Unlike the C-standard printf function, this method will not forcefully cast your parameters to the type specified in your format string. If you would like to print an int as a character, you must cast it in the method call. For instance:
const int i = 7;

pwOut.printf("The %ith letter is %c\n", i, i + 'A' - 1);

will print The 7th letter is 71. Notice that i was not cast to a char and therefore did not print as G. Instead, we need to write the above function like so:
const int i = 7;

pwOut.printf("The %ith letter is %c\n", i, (char) (i + 'A' - 1));

This is a little more work, but it enables GCC to make excellent optimizations, and doesn't require the use of separate print and printi methods, as Parallax's Simple library does.

Parameters

[in]	fmt[]	Format string such as `Hello, %s!` which can be used to print anyone's name in place of `%s`
[in]	...	Variable number of arguments passed here. Continuing with the `Hello, %s!` example, a single argument could be passed such as: pwOut.printf("Hello, %s!", "David"); and `Hello, David!` would be sent out the serial port. Multiple arguments can be used as well, such as: pwOut.printf("%i + %i = %i", 2, 3, 2 + 3); Which would print: `2 + 3 = 5`

Examples: ADXL345_Demo.cpp, Hello_Demo.cpp, MAX6675_Demo.cpp, MCP2515_Demo.cpp, MCP3xxx_Demo.cpp, MultiCogBlinky_Demo.cpp, Queue_Demo.cpp, Utility_Demo.cpp, and WatchDog_Demo.cpp.

Definition at line 497 of file printer.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ println()

void PropWare::Printer::println ( const char string[] ) const

Print a null-terminated string followed by a newline ('
')

Parameters

[in] string[] String to be printed

Examples: StringBuilder_Demo.cpp, and Utility_Demo.cpp.

Definition at line 599 of file printer.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ put_char()

void PropWare::Printer::put_char ( const char c ) const

Print a single character.

Parameters

[in] c Individual char to be printed

Examples: SPI_Demo.cpp.

Definition at line 175 of file printer.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ put_float()

void PropWare::Printer::put_float	(	double	f,
		uint16_t	width = `0`,
		uint16_t	precision = `6`,
		const char	fillChar = `DEFAULT_FILL_CHAR`
	)		const

Print a floating point number with a given width and precision.

Parameters

[in]	f	Number to print
[in]	width	Number of integer digits to print (includes decimal point)
[in]	precision	Number of digits to print to the right of the decimal point
[in]	fillChar	Character to print to the left of the number if the number's width is less than `width`

Definition at line 310 of file printer.h.

Here is the caller graph for this function:

◆ put_int()

void PropWare::Printer::put_int	(	int	x,
		const uint8_t	radix = `10`,
		uint16_t	width = `0`,
		const char	fillChar = `DEFAULT_FILL_CHAR`
	)		const

Print a signed integer in base 10.

Parameters

[in]	x	Integer to be printed
[in]	radix	Radix to print the integer (aka, the base of the number)
[in]	width	Minimum number of characters to print
[in]	fillChar	Character to print to the left of the number if the number's width is less than `width`

Definition at line 205 of file printer.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ put_ll()

void PropWare::Printer::put_ll	(	long long	x,
		const uint8_t	radix = `10`,
		uint16_t	width = `0`,
		const char	fillChar = `DEFAULT_FILL_CHAR`
	)		const

Print a signed integer in base 10.

Parameters

[in]	x	Integer to be printed
[in]	radix	Radix to print the integer (aka, the base of the number)
[in]	width	Minimum number of characters to print
[in]	fillChar	Character to print to the left of the number if the number's width is less than `width`

Definition at line 256 of file printer.h.

Here is the call graph for this function:

◆ put_uint()

void PropWare::Printer::put_uint	(	unsigned int	x,
		const uint8_t	radix = `10`,
		uint16_t	width = `0`,
		const char	fillChar = `DEFAULT_FILL_CHAR`
	)		const

Print an unsigned integer in base 10.

Parameters

[in]	x	Integer to be printed
[in]	radix	Radix to print the integer (aka, the base of the number)
[in]	width	Minimum number of characters to print
[in]	fillChar	Character to print to the left of the number if the number's width is less than `width`

Definition at line 222 of file printer.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ put_ull()

void PropWare::Printer::put_ull	(	unsigned long long	x,
		const uint8_t	radix = `10`,
		uint16_t	width = `0`,
		const char	fillChar = `DEFAULT_FILL_CHAR`
	)		const

Print an unsigned integer in base 10.

Parameters

[in]	x	Integer to be printed
[in]	radix	Radix to print the integer (aka, the base of the number)
[in]	width	Minimum number of characters to print
[in]	fillChar	Character to print to the left of the number if the number's width is less than `width`

Definition at line 273 of file printer.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ puts()

void PropWare::Printer::puts ( const char string[] ) const

Send a null-terminated character array.

Precondition: string[] must be terminated with a null terminator

Parameters

[in] string[] Array of data words with the final word being 0 - the null terminator

Definition at line 188 of file printer.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_cooked()

void PropWare::Printer::set_cooked ( const bool cooked )

Turn on or off cooked mode.

Cooked mode prefixes all instances of the newline character (\n) with a carriage return (\r). This is required by many serial programs and is the default for PropGCC's serial routines. The default status for a Printer is also on. This can, however, have adverse affects if you are trying to use a printer to send raw data between two devices rather than human-readable data.

Read more on WikiPedia about cooked mode_

Parameters

[in] cooked Turn on cooked mode if true, otherwise turn off

Definition at line 150 of file printer.h.

The documentation for this class was generated from the following files:

PropWare/hmi/output/printer.h
PropWare/hmi/output/printer.cpp

Classes

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Printer()

Member Function Documentation

◆ get_cooked()

◆ operator<<() [1/2]

◆ operator<<() [2/2]

◆ print() [1/8]

◆ print() [2/8]

◆ print() [3/8]

◆ print() [4/8]

◆ print() [5/8]

◆ print() [6/8]

◆ print() [7/8]

◆ print() [8/8]

◆ printf() [1/2]

◆ printf() [2/2]

◆ println()

◆ put_char()

◆ put_float()

◆ put_int()

◆ put_ll()

◆ put_uint()

◆ put_ull()

◆ puts()

◆ set_cooked()