FastArduino  v1.7
C++ library to build fast but small Arduino/AVR projects
streams::istream Class Reference

Input stream wrapper to provide formatted input API, a la C++. More...

#include <fastarduino/streams.h>

Inheritance diagram for streams::istream:
Collaboration diagram for streams::istream:

Public Types

using MANIPULATOR = void(*)(istream &)
 General type of a manipulator function applicable to this input stream.
 
- Public Types inherited from streams::ios_base
using iostate = uint8_t
 Bitmask type to represent stream state flags. More...
 
using fmtflags = uint16_t
 Bitmask type to represent stream format flags. More...
 

Public Member Functions

 istream (istreambuf &streambuf)
 Construct a formatted input wrapper of streambuf. More...
 
istreamoperator= (const istream &)=delete
 
istreambufrdbuf () const
 Return the stream buffer associated with this stream.
 
int peek ()
 Return the next character in this input stream, without extracting it. More...
 
int get ()
 Extract a single character from this input stream. More...
 
istreamget (char &ch)
 Extract a single character from this input stream. More...
 
istreamget (char *str, size_t n, char delim='\n')
 Extract characters from this input stream and stores them as a C-string, until either (n - 1) characters have been extracted or the delim character is encountered. More...
 
istreamgetline (char *str, size_t n, char delim='\n')
 Extract characters from this input stream and stores them as a C-string, until either (n - 1) characters have been extracted or the delim character is encountered. More...
 
istreamignore (size_t n=1, int delim=istreambuf::EOF)
 Extract characters from this input stream and discards them, until either n characters have been extracted, or the delim character is encountered. More...
 
istreamread (char *str, size_t n)
 Read a block of data from this input stream. More...
 
istreamoperator>> (char *buf)
 Read characters from buffer into buf until one of these conditions happen: More...
 
istreamoperator>> (bool &value)
 Input and interpret next character from buffer as a boolean value. More...
 
istreamoperator>> (char &value)
 Input next character from buffer. More...
 
istreamoperator>> (int &value)
 Input and interpret next word from buffer as a signed integer value. More...
 
istreamoperator>> (unsigned int &value)
 Input and interpret next word from buffer as an unsigned integer value. More...
 
istreamoperator>> (long &value)
 Input and interpret next word from buffer as a signed long integer value. More...
 
istreamoperator>> (unsigned long &value)
 Input and interpret next word from buffer as an unsigned long integer value. More...
 
istreamoperator>> (double &value)
 Input and interpret next word from buffer as a floating point value. More...
 
istreamoperator>> (MANIPULATOR func)
 Apply a MANIPULATOR to this input stream. More...
 
- Public Member Functions inherited from streams::ios_base
iostate rdstate () const
 Return the current stream error state.
 
void setstate (iostate state)
 Set the stream error flags state in addition to currently set flags. More...
 
void clear (iostate state=goodbit)
 Set the stream error state flags by assigning them the value of state. More...
 
bool good () const
 
bool eof () const
 Return true if the associated stream has reached end-of-file. More...
 
bool fail () const
 Return true if an error has occurred on the associated stream, since last time state was reset (clear() was called). More...
 
bool bad () const
 Return true if a non-recoverable error has occurred on the associated stream. More...
 
bool operator! () const
 Return true if an error has occurred on the associated stream, since last time state was reset (clear() was called). More...
 
 operator bool () const
 Check that the current stream has no errors. More...
 
void flags (fmtflags flags)
 Set new format flags for this stream. More...
 
fmtflags flags () const
 Return the format flags currently selected in this stream. More...
 
void setf (fmtflags flags)
 Set this stream's format flags whose bits are set in flags, leaving unchanged the rest. More...
 
void setf (fmtflags flags, fmtflags mask)
 Set this stream's format flags whose bits are set in both flags and mask, and clears the format flags whose bits are set in mask but not in flags. More...
 
void unsetf (fmtflags flags)
 Clear this stream's format flags whose bits are set in flags. More...
 
char fill () const
 Return the fill character. More...
 
void fill (char fill)
 Set fill as new fill character for this stream. More...
 
void width (uint8_t width)
 Set minimum width used for displaying values. More...
 
uint8_t width () const
 Get the current minimum width value (default = 0) used for formatted output. More...
 
void precision (uint8_t precision)
 Set precision (number of digits after decimal point) used for displaying floating values. More...
 
uint8_t precision () const
 Get the current precision (default = 6) used for formatted floating values output. More...
 
ios_basecopyfmt (const ios_base &rhs)
 Copy formatting information from rhs to this stream. More...
 

Friends

template<typename FSTREAM >
void ws (FSTREAM &)
 Manipulator for an input stream, which will swallow all white spaces from that stream. More...
 

Additional Inherited Members

- Static Public Attributes inherited from streams::ios_base
static constexpr iostate eofbit = 0x01
 This bit is set if the stream has unexpectedly reached its end during an extraction. More...
 
static constexpr iostate failbit = 0x02
 This bit is set when an input or operation failed due to a formatting error during extraction.
 
static constexpr iostate badbit = 0x04
 This bit is set when an irrecoverable stream error has occurred, e.g. More...
 
static constexpr iostate goodbit = 0
 No error; always 0.
 
static constexpr fmtflags dec = 0x0001
 Read or write integral values using decimal (0..9) base format.
 
static constexpr fmtflags bin = 0x0002
 Read or write integral values using binary (0,1) base format.
 
static constexpr fmtflags oct = 0x0004
 Read or write integral values using octal (0..7) base format.
 
static constexpr fmtflags hex = 0x0008
 Read or write integral values using hexadecimal (0..9,A..F) base format.
 
static constexpr fmtflags basefield = dec | bin | oct | hex
 Bitmask constant used with setf(fmtflags, fmtflags) when changing the output base format. More...
 
static constexpr fmtflags left = 0x0010
 Pad all output to width() characters, with fill() character appended at the end so that the output appears left-adjusted.
 
static constexpr fmtflags right = 0x0020
 Pad all output to width() characters, with fill() character added at the beginning so that the output appears right-adjusted.
 
static constexpr fmtflags adjustfield = left | right
 Bitmask constant used with setf(fmtflags, fmtflags) when changing the output adjustment. More...
 
static constexpr fmtflags scientific = 0x0040
 Write floating point values in fixed-point notation.
 
static constexpr fmtflags fixed = 0x0080
 Write floating point values in scientific notation.
 
static constexpr fmtflags floatfield = scientific | fixed
 Bitmask constant used with setf(fmtflags, fmtflags) when changing the floating point output representation. More...
 
static constexpr fmtflags boolalpha = 0x0200
 Read or write bool values as alphabetic string (true or false).
 
static constexpr fmtflags showbase = 0x0400
 Write integral values prefixed by their base: More...
 
static constexpr fmtflags showpos = 0x1000
 Write non-negative numerical values preceded by +.
 
static constexpr fmtflags skipws = 0x2000
 Skip leading spaces on certain extraction (read) operations.
 
static constexpr fmtflags unitbuf = 0x4000
 Flush output after each insertion operation.
 
static constexpr fmtflags uppercase = 0x8000U
 Write uppercase letters instead of lowercase in certain insertion operations. More...
 
static constexpr uint8_t MAX_PRECISION = 16
 The maximum allowed precision. More...
 

Detailed Description

Input stream wrapper to provide formatted input API, a la C++.

Definition at line 356 of file streams.h.

Constructor & Destructor Documentation

◆ istream()

streams::istream::istream ( istreambuf streambuf)
inlineexplicit

Construct a formatted input wrapper of streambuf.

Parameters
streambufthe input streambuf to be wrapped

Definition at line 363 of file streams.h.

Member Function Documentation

◆ peek()

int streams::istream::peek ( )
inline

Return the next character in this input stream, without extracting it.

The method blocks until one character is available in the underlying istreambuf.

See also
istreambuf::sgetc()

Definition at line 381 of file streams.h.

◆ get() [1/3]

int streams::istream::get ( )
inline

Extract a single character from this input stream.

The method blocks until one character is available in the underlying istreambuf.

See also
istreambuf::sbumpc()

Definition at line 394 of file streams.h.

◆ get() [2/3]

istream& streams::istream::get ( char &  ch)
inline

Extract a single character from this input stream.

The method blocks until one character is available in the underlying istreambuf.

See also
get()
istreambuf::sbumpc()

Definition at line 408 of file streams.h.

◆ get() [3/3]

istream& streams::istream::get ( char *  str,
size_t  n,
char  delim = '\n' 
)
inline

Extract characters from this input stream and stores them as a C-string, until either (n - 1) characters have been extracted or the delim character is encountered.

The delimiting character is not extracted from the stream and also not added to str. A null character \0 is automatically appended to str.

See also
getline()

Definition at line 422 of file streams.h.

◆ getline()

istream& streams::istream::getline ( char *  str,
size_t  n,
char  delim = '\n' 
)
inline

Extract characters from this input stream and stores them as a C-string, until either (n - 1) characters have been extracted or the delim character is encountered.

The delimiting character is extracted from the stream but is not added to str. A null character \0 is automatically appended to str.

See also
get(char*, size_t, char)

Definition at line 442 of file streams.h.

◆ ignore()

istream& streams::istream::ignore ( size_t  n = 1,
int  delim = istreambuf::EOF 
)
inline

Extract characters from this input stream and discards them, until either n characters have been extracted, or the delim character is encountered.

The delimiting character, if found, is also discarded. If n is 0, then all characters are discarded (no number limit) until delim is encountered.

Definition at line 461 of file streams.h.

◆ read()

istream& streams::istream::read ( char *  str,
size_t  n 
)
inline

Read a block of data from this input stream.

Extracts exactly n characters and copies them to str. The method blocks until n characters have been read.

Definition at line 477 of file streams.h.

◆ operator>>() [1/9]

istream& streams::istream::operator>> ( char *  buf)
inline

Read characters from buffer into buf until one of these conditions happen:

  • a space has been encountered (not read)
  • width() - 1 characters have been read An ‘’\0'character is added in last position of @p buf. Ifskipws()` is in action, then any white spaces read from the input will be skipped and the first non white space character will be copied first to buf.
    Parameters
    bufthe char array to be filled from the input stream; it must have a minimum size of width().
    Returns
    this formatted input

Definition at line 495 of file streams.h.

◆ operator>>() [2/9]

istream& streams::istream::operator>> ( bool &  value)
inline

Input and interpret next character from buffer as a boolean value.

If read character is '0' then, it will be interpreted as false, any other value will be interpreted as true. If skipws() is in action, then any white spaces read from the input will be skipped and the first non white space character will be used to determine the value to set to value.

bool b;
in >> b;
Parameters
valuethe boolean value read from the input stream
Returns
this formatted input

Definition at line 520 of file streams.h.

◆ operator>>() [3/9]

istream& streams::istream::operator>> ( char &  value)
inline

Input next character from buffer.

If skipws() is in action, then any white spaces read from the input will be skipped and the first non white space character will be used to determine the value to set to value.

char c;
in >> c;
Parameters
valuethe next character read from the input stream
Returns
this formatted input

Definition at line 540 of file streams.h.

◆ operator>>() [4/9]

istream& streams::istream::operator>> ( int &  value)
inline

Input and interpret next word from buffer as a signed integer value.

If skipws() is in action, then any white spaces read from the input will be skipped and the first non white space character will be used to determine the value to set to value.

int i;
in >> i;
Parameters
valuethe integer value read from the input stream
Returns
this formatted input

Definition at line 559 of file streams.h.

◆ operator>>() [5/9]

istream& streams::istream::operator>> ( unsigned int &  value)
inline

Input and interpret next word from buffer as an unsigned integer value.

If skipws() is in action, then any white spaces read from the input will be skipped and the first non white space character will be used to determine the value to set to value.

unsigned int i;
in >> i;
Parameters
valuethe unsigned integer value read from the input stream
Returns
this formatted input

Definition at line 579 of file streams.h.

◆ operator>>() [6/9]

istream& streams::istream::operator>> ( long &  value)
inline

Input and interpret next word from buffer as a signed long integer value.

If skipws() is in action, then any white spaces read from the input will be skipped and the first non white space character will be used to determine the value to set to value.

long i;
in >> i;
Parameters
valuethe long integer value read from the input stream
Returns
this formatted input

Definition at line 599 of file streams.h.

◆ operator>>() [7/9]

istream& streams::istream::operator>> ( unsigned long &  value)
inline

Input and interpret next word from buffer as an unsigned long integer value.

If skipws() is in action, then any white spaces read from the input will be skipped and the first non white space character will be used to determine the value to set to value.

unsigned long i;
in >> i;
Parameters
valuethe unsigned long integer value read from the input stream
Returns
this formatted input

Definition at line 619 of file streams.h.

◆ operator>>() [8/9]

istream& streams::istream::operator>> ( double &  value)
inline

Input and interpret next word from buffer as a floating point value.

If skipws() is in action, then any white spaces read from the input will be skipped and the first non white space character will be used to determine the value to set to value.

double d;
in >> d;
Parameters
valuethe floating point value read from the input stream
Returns
this formatted input

Definition at line 639 of file streams.h.

◆ operator>>() [9/9]

istream& streams::istream::operator>> ( MANIPULATOR  func)
inline

Apply a MANIPULATOR to this input stream.

A manipulator may:

  • change formatting option (base)
  • call some method of this input stream
unsigned int value;
// Read next integral value from `in`; this value is expected to be
represented in hexadecimal in the input, e.g. 0xABCD.
in >> hex >> value;
Parameters
functhe manipulator to apply to this input stream
Returns
this formatted input

Definition at line 671 of file streams.h.

Friends And Related Function Documentation

◆ ws

template<typename FSTREAM >
void ws ( FSTREAM &  stream)
friend

Manipulator for an input stream, which will swallow all white spaces from that stream.

The following sample code puts the next non white space character of in into c:

char c;
in >> ws >> c;

Definition at line 705 of file streams.h.


The documentation for this class was generated from the following files:
streams::istream::ws
friend void ws(FSTREAM &)
Manipulator for an input stream, which will swallow all white spaces from that stream.
Definition: streams.h:705
streams::hex
void hex(FSTREAM &stream)
Manipulator for an output or input stream, which will set the base, used to represent (output) or int...
Definition: ios.h:774
streams::ios_base::hex
static constexpr fmtflags hex
Read or write integral values using hexadecimal (0..9,A..F) base format.
Definition: ios.h:218