Reader Class Reference

This is an abstract class defining a generic interface to read numbers and strings from a sequential stream of bytes (such as a serial device). More...

#include <Reader.h>

Inheritance diagram for Reader:

Public Member Functions
	Reader ()
	Constructor. It sets the default timeout to 1 second.
virtual int	read ()=0
	Pure virtual function that reads and removes the next byte from the input stream. More...
virtual int	peek ()=0
	Pure virtual function that examines the next byte from the input stream, without removing it. More...
virtual bool	available ()=0
	Pure virtual function that determines if data is available in the input stream. More...
void	setTimeout (unsigned long milliseconds)
	Sets maximum milliseconds to wait for stream data, default is 1 second. More...
bool	find (const char *target)
	Read data from the input stream until the target string is found. More...
bool	find (const char *target, size_t length)
	Read data from the stream until the target string of given length is found. More...
bool	findUntil (const char *target, const char *terminator)
	Read data from the stream until the target string is found, or the terminator string is found, or the function times out. More...
bool	findUntil (const char *target, size_t targetLen, const char *terminate, size_t termLen)
	Read data from the stream until the target string of given length is found, or the terminator string of given length is found, or the function times out. More...
bool	readLong (long *result)
	Return the first valid long integer value from the stream. More...
bool	readFloat (float *result)
	Return the first valid float value from the stream. More...
bool	readLong (long *result, char skipChar)
	Return the first valid long integer value from the stream, ignoring selected characters. More...
bool	readFloat (float *result, char skipChar)
	Return the first valid float value from the stream, ignoring selected characters. More...
size_t	readBytes (char *buffer, size_t length)
	Read characters from the input stream into a buffer, terminating if length characters have been read or the function times out. The result is NOT null-termimated. More...
size_t	readBytesUntil (char terminator, char *buffer, size_t length)
	Read characters from the input stream into a buffer, terminating when the terminator charactor is encountered, or if length characters have been read, or if the function times out. The result is NOT null-terminated. More...
size_t	readBytes (uint8_t *buffer, size_t length)
	Read bytes (uint8_t) from the input stream into a buffer, terminating if length bytes have been read or the function times out. More...
size_t	readBytesUntil (uint8_t terminator, uint8_t *buffer, size_t length)
	Read bytes (uint8_t) from the input stream into a buffer, terminating when the terminator byte is encountered, or if length bytes have been read, or if the function times out. More...
size_t	readLine (char *buffer, size_t length)
	Read characters from the input stream into a buffer, until it reaches EOL, or if length characters have been read, or if it times out. The result IS null-termimated. More...
void	consumeWhiteSpace ()
	Consumes whitespace characters until the first non-whitespace character is encountered or the function times out.

Detailed Description

This is an abstract class defining a generic interface to read numbers and strings from a sequential stream of bytes (such as a serial device).

It implements functions to convert a sequence of bytes into various integers and floating point numbers (so it is not a pure interface class). These functions depend on a small set of lower-level functions that are purely abstract and must be implemented by classes deriving from Reader.

Serial0 is an example of a class that derives from Reader by implementating the purely abstract functions in Reader.

Note

Use of the timeout feature requires linking against SystemClock.cpp and calling initSystemClock() from your start-up code. If you do not wish to use the system clock and link against SystemClock.cpp, then define the macro USE_READER_WITHOUT_SYSTEM_CLOCK. This means that calls will never timeout, and you are likely to lock your system if you read input that doesn't naturally terminate parsing (e.g., if you read numbers and the last number isn't followed by a newline).

Member Function Documentation

available()

virtual bool Reader::available ( )

pure virtual

Pure virtual function that determines if data is available in the input stream.

Returns

True if data is available in the stream before timeout expires; false if timeout expires before any data appears in the stream.

Implemented in Serial1, Serial2, Serial3, and Serial0.

find() [1/2]

bool Reader::find ( const char *  target )

inline

Read data from the input stream until the target string is found.

• target is the string the function seeks in the input stream.

Returns

true if target string is found before timeout, false otherwise.

find() [2/2]

bool Reader::find ( const char *  target, size_t  length  )

inline

Read data from the stream until the target string of given length is found.

• target is a string, the first length bytes of which the function seeks in the input stream.
• length is the number of bytes of the string to use for comparison.

Returns

true if target string of given length is found, false if the function times out before finding the target string.

findUntil() [1/2]

bool Reader::findUntil	(	const char *	target,
		const char *	terminator
	)

Read data from the stream until the target string is found, or the terminator string is found, or the function times out.

This function is like find() but the search ends if the terminator string is found first.

• target is the string the function seeks in the input stream.
• terminator is the string that stops the search.

Returns

true if target string is found before the terminator is encountered and before the function times out; false otherwise.

findUntil() [2/2]

bool Reader::findUntil	(	const char *	target,
		size_t	targetLen,
		const char *	terminate,
		size_t	termLen
	)

Read data from the stream until the target string of given length is found, or the terminator string of given length is found, or the function times out.

This function is like find() but the search ends if the terminator string is found first.

• target is the string the function seeks in the input stream.
• targetLen is the number of bytes in target that the function seeks in the input stream.
• terminator is the string that stops the search.
• termLen is the number of bytes in the terminator that

Returns

true if target string is found before the terminator is encountered and before the function times out; false otherwise.

peek()

virtual int Reader::peek ( )

pure virtual

Pure virtual function that examines the next byte from the input stream, without removing it.

Returns

the next byte, or -1 if there is nothing to read in the input stream before timeout expires.

Implemented in Serial1, Serial2, Serial3, and Serial0.

read()

virtual int Reader::read ( )

pure virtual

Pure virtual function that reads and removes the next byte from the input stream.

Returns

the next byte, or -1 if there is nothing to read in the input stream before timeout expires.

Implemented in Serial1, Serial2, Serial3, and Serial0.

readBytes() [1/2]

size_t Reader::readBytes	(	char *	buffer,
		size_t	length
	)

Read characters from the input stream into a buffer, terminating if length characters have been read or the function times out. The result is NOT null-termimated.

• buffer a pointer to where the characters read will be stored.
• length the maximum number of characters to read.

Returns

the number of characters placed in the buffer (0 means no data were read prior to timeout).

readBytes() [2/2]

size_t Reader::readBytes ( uint8_t *  buffer, size_t  length  )

inline

Read bytes (uint8_t) from the input stream into a buffer, terminating if length bytes have been read or the function times out.

• buffer a pointer to where the bytes read will be stored.
• length the maximum number of bytes to read.

Returns

the number of bytes placed in the buffer (0 means no data were read prior to timeout).

readBytesUntil() [1/2]

size_t Reader::readBytesUntil	(	char	terminator,
		char *	buffer,
		size_t	length
	)

Read characters from the input stream into a buffer, terminating when the terminator charactor is encountered, or if length characters have been read, or if the function times out. The result is NOT null-terminated.

• terminator a character that when encountered causes the function to return.
• buffer a pointer to where the characters read will be stored.
• length the maximum number of characters to read.

Returns

the number of characters placed in the buffer (0 means no data were read prior to timeout or detecting the terminator character).

readBytesUntil() [2/2]

size_t Reader::readBytesUntil ( uint8_t  terminator, uint8_t *  buffer, size_t  length  )

inline

Read bytes (uint8_t) from the input stream into a buffer, terminating when the terminator byte is encountered, or if length bytes have been read, or if the function times out.

• terminator a byte that when encountered causes the function to return.
• buffer a pointer to where the bytes read will be stored.
• length the maximum number of bytes to read.

Returns

the number of bytes placed in the buffer (0 means no data were read prior to timeout or detecting the terminator character).

readFloat() [1/2]

bool Reader::readFloat

(

float *

result

)

Return the first valid float value from the stream.

Initial characters that are not digits (or the minus sign) are skipped; the float is terminated by the first character that is not a digit.

• result is a pointer to where the float will be stored.

Returns

true if a valid float is found prior to timeout; false otherwise.

readFloat() [2/2]

bool Reader::readFloat	(	float *	result,
		char	skipChar
	)

Return the first valid float value from the stream, ignoring selected characters.

Initial characters that are not digits (or the minus sign) are skipped; the float is terminated by the first character that is not a digit and is not one of the skip characters. This allows format characters (typically commas) to be ignored on input.

• result is a pointer to where the float will be stored.
• skipChar is a character that will be ignored on input.

Returns

true if a valid float is found prior to timeout; false otherwise.

readLine()

size_t Reader::readLine	(	char *	buffer,
		size_t	length
	)

Read characters from the input stream into a buffer, until it reaches EOL, or if length characters have been read, or if it times out. The result IS null-termimated.

• buffer a pointer to where the characters read will be stored.
• length the maximum number of characters to read.

Returns

the number of characters placed in the buffer (0 means no data were read prior to timeout or detecting EOL).

readLong() [1/2]

bool Reader::readLong

(

long *

result

)

Return the first valid long integer value from the stream.

Initial characters that are not digits (or the minus sign) are skipped; the integer is terminated by the first character that is not a digit.

• result is a pointer to where the long integer will be stored.

Returns

true if a valid integer is found prior to timeout; false otherwise.

readLong() [2/2]

bool Reader::readLong	(	long *	result,
		char	skipChar
	)

Return the first valid long integer value from the stream, ignoring selected characters.

Initial characters that are not digits (or the minus sign) are skipped; the integer is terminated by the first character that is not a digit and is not one of the skip characters. This allows format characters (typically commas) to be ignored on input.

• result is a pointer to where the long integer will be stored.
• skipChar is a character that will be ignored on input.

Returns

true if a valid long integer is found prior to timeout; false otherwise.

setTimeout()

void Reader::setTimeout ( unsigned long  milliseconds )

inline

Sets maximum milliseconds to wait for stream data, default is 1 second.

• milliseconds the length of the timeout period in milliseconds.

---

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

• Reader.h
• Reader.cpp