SdFat: StdioStream Class Reference

SdFat

Public Member Functions | List of all members
StdioStream Class Reference

StdioStream implements a minimal stdio stream. More...

`#include <StdioStream.h>`

Inheritance diagram for StdioStream:
[legend]
Collaboration diagram for StdioStream:
[legend]

## Public Member Functions
void | clearerr ()
int | fclose ()
int | feof ()
int | ferror ()
int | fflush ()
int | fgetc ()
char * | fgets (char *str, size_t num, size_t *len=0)
bool | fopen (const char *path, const char *mode)
int | fputc (int c)
int | fputs (const char *str)
size_t | fread (void *ptr, size_t size, size_t count)
int | fseek (int32_t offset, int origin)
int32_t | ftell ()
size_t | fwrite (const void *ptr, size_t size, size_t count)
int | getc ()
size_t | print (char c)
size_t | print (const __FlashStringHelper *str)
size_t | print (const char *str)
size_t | print (double val, uint8_t prec=2)
size_t | print (float val, uint8_t prec=2)
template<typename T >
size_t | print (T val)
int | printDec (char n)
int | printDec (double value, uint8_t prec)
int | printDec (float value, uint8_t prec)
int | printDec (int16_t n)
int | printDec (int32_t n)
int | printDec (signed char n)
int | printDec (uint16_t n)
int | printDec (uint32_t n)
int | printDec (unsigned char n)
int | printField (double value, char term, uint8_t prec=2)
int | printField (float value, char term, uint8_t prec=2)
template<typename T >
int | printField (T value, char term)
int | printHex (uint32_t n)
int | printHexln (uint32_t n)
size_t | println ()
size_t | println (double val, uint8_t prec=2)
size_t | println (float val, uint8_t prec=2)
template<typename T >
size_t | println (T val)
int | putc (int c)
int | putCRLF ()
bool | rewind ()
| StdioStream ()
int | ungetc (int c)

## Detailed Description

StdioStream implements a minimal stdio stream.

StdioStream does not support subdirectories or long file names.

## Constructor & Destructor Documentation

## ◆ StdioStream()

StdioStream::StdioStream | ( |  | ) |
| inline

Constructor

## Member Function Documentation

## ◆ clearerr()

void StdioStream::clearerr | ( |  | ) |
| inline

Clear the stream's end-of-file and error indicators.

## ◆ fclose()

int StdioStream::fclose | ( |  | ) |

Close a stream.

A successful call to the fclose function causes the stream to be flushed and the associated file to be closed. Any unwritten buffered data is written to the file; any unread buffered data is discarded. Whether or not the call succeeds, the stream is disassociated from the file.

Returns
  zero if the stream was successfully closed, or EOF if any any errors are detected.

Copyright (c) 2011-2020 Bill Greiman This file is part of the SdFat library for SD memory cards.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

## ◆ feof()

int StdioStream::feof | ( |  | ) |
| inline

Test the stream's end-of-file indicator.

Returns
  non-zero if and only if the end-of-file indicator is set.

## ◆ ferror()

int StdioStream::ferror | ( |  | ) |
| inline

Test the stream's error indicator.

Returns
  return non-zero if and only if the error indicator is set.

## ◆ fflush()

int StdioStream::fflush | ( |  | ) |

Flush the stream.

If stream is an output stream or an update stream in which the most recent operation was not input, any unwritten data is written to the file; otherwise the call is an error since any buffered input data would be lost.

Returns
  sets the error indicator for the stream and returns EOF if an error occurs, otherwise it returns zero.

## ◆ fgetc()

int StdioStream::fgetc | ( |  | ) |
| inline

Get a byte from the stream.

Returns
  If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the end-of-file indicator for the stream is set and the fgetc function returns EOF. Otherwise, the fgetc function returns the next character from the input stream.

## ◆ fgets()

char * StdioStream::fgets | ( | char * | str,
|  | size_t | num,
|  | size_t * | len = `0`
| ) |  |

Get a string from a stream.

The fgets function reads at most one less than the number of characters specified by num from the stream into the array pointed to by str. No additional characters are read after a new-line character (which is retained) or after end-of-file. A null character is written immediately after the last character read into the array.

Parameters

  [out] | str | Pointer to an array of where the string is copied.
  [in] | num | Maximum number of characters including the null character.
  [out] | len | If len is not null and fgets is successful, the length of the string is returned.

Returns
  str if successful. If end-of-file is encountered and no characters have been read into the array, the contents of the array remain unchanged and a null pointer is returned. If a read error occurs during the operation, the array contents are indeterminate and a null pointer is returned.

## ◆ fopen()

bool StdioStream::fopen | ( | const char * | path,
|  | const char * | mode
| ) |  |

Open a stream.

Open a file and associates the stream with it.

Parameters

  [in] | path | file to be opened.
  [in] | mode | a string that indicates the open mode.

"r" or "rb" | Open a file for reading. The file must exist.
"w" or "wb" | Truncate an existing to zero length or create an empty file for writing.
"wx" or "wbx" | Create a file for writing. Fails if the file already exists.
"a" or "ab" | Append; open or create file for writing at end-of-file.
"r+" or "rb+" or "r+b" | Open a file for update (reading and writing).
"w+" or "w+b" or "wb+" | Truncate an existing to zero length or create a file for update.
"w+x" or "w+bx" or "wb+x" | Create a file for update. Fails if the file already exists.
"a+" or "a+b" or "ab+" | Append; open or create a file for update, writing at end-of-file.

The character 'b' shall have no effect, but is allowed for ISO C standard conformance.

Opening a file with append mode causes all subsequent writes to the file to be forced to the then current end-of-file, regardless of intervening calls to the fseek function.

When a file is opened with update mode, both input and output may be performed on the associated stream. However, output shall not be directly followed by input without an intervening call to the fflush function or to a file positioning function (fseek, or rewind), and input shall not be directly followed by output without an intervening call to a file positioning function, unless the input operation encounters end-of-file.

Returns
  true for success or false for failure.

## ◆ fputc()

int StdioStream::fputc | ( | int | c | ) |
| inline

Write a byte to a stream.

Parameters

  [in] | c | the byte to be written (converted to an unsigned char).

Returns
  Upon successful completion, fputc() returns the value it has written. Otherwise, it returns EOF and sets the error indicator for the stream.

## ◆ fputs()

int StdioStream::fputs | ( | const char * | str | ) |

Write a string to a stream.

Parameters

  [in] | str | a pointer to the string to be written.

Returns
  for success, fputs() returns a non-negative number. Otherwise, it returns EOF and sets the error indicator for the stream.

## ◆ fread()

size_t StdioStream::fread | ( | void * | ptr,
|  | size_t | size,
|  | size_t | count
| ) |  |

Binary input.

Reads an array of up to count elements, each one with a size of size bytes.

Parameters

  [out] | ptr | pointer to area of at least (size*count) bytes where the data will be stored.
  [in] | size | the size, in bytes, of each element to be read.
  [in] | count | the number of elements to be read.

Returns
  number of elements successfully read, which may be less than count if a read error or end-of-file is encountered. If size or count is zero, fread returns zero and the contents of the array and the state of the stream remain unchanged.

## ◆ fseek()

int StdioStream::fseek | ( | int32_t | offset,
|  | int | origin
| ) |  |

Set the file position for the stream.

Parameters

  [in] | offset | number of offset from the origin.
  [in] | origin | position used as reference for the offset. It is specified by one of the following constants.

SEEK_SET - Beginning of file.

SEEK_CUR - Current position of the file pointer.

SEEK_END - End of file.

Returns
  zero for success. Otherwise, it returns non-zero and sets the error indicator for the stream.

## ◆ ftell()

int32_t StdioStream::ftell | ( |  | ) |

Get the current position in a stream.

Returns
  If successful, ftell return the current value of the position indicator. On failure, ftell returns −1L.

## ◆ fwrite()

size_t StdioStream::fwrite | ( | const void * | ptr,
|  | size_t | size,
|  | size_t | count
| ) |  |

Binary output.

Writes an array of up to count elements, each one with a size of size bytes.

Parameters

  [in] | ptr | pointer to (size*count) bytes of data to be written.
  [in] | size | the size, in bytes, of each element to be written.
  [in] | count | the number of elements to be written.

Returns
  number of elements successfully written. if this number is less than count, an error has occurred. If size or count is zero, fwrite returns zero.

## ◆ getc()

int StdioStream::getc | ( |  | ) |
| inline

Get a byte from the stream.

getc and fgetc are equivalent but getc is in-line so it is faster but require more flash memory.

Returns
  If the end-of-file indicator for the stream is set, or if the stream is at end-of-file, the end-of-file indicator for the stream is set and the fgetc function returns EOF. Otherwise, the fgetc function returns the next character from the input stream.

## ◆ print() [1/6]

size_t StdioStream::print | ( | char | c | ) |
| inline

Write a character.

Parameters

  [in] | c | the character to write.

Returns
  the number of bytes written.

## ◆ print() [2/6]

size_t StdioStream::print | ( | const __FlashStringHelper * | str | ) |

Print a string stored in flash memory.

Parameters

  [in] | str | the string to print.

Returns
  the number of bytes written.

## ◆ print() [3/6]

size_t StdioStream::print | ( | const char * | str | ) |
| inline

Write a string.

Parameters

  [in] | str | the string to be written.

Returns
  the number of bytes written.

## ◆ print() [4/6]

size_t StdioStream::print | ( | double | val,
|  | uint8_t | prec = `2`
| ) |  |
| inline

Print a floating point number.

Parameters

  [in] | prec | Number of digits after decimal point.
  [in] | val | the number to be printed.

Returns
  the number of bytes written.

## ◆ print() [5/6]

size_t StdioStream::print | ( | float | val,
|  | uint8_t | prec = `2`
| ) |  |
| inline

Print a floating point number.

Parameters

  [in] | prec | Number of digits after decimal point.
  [in] | val | the number to be printed.

Returns
  the number of bytes written.

## ◆ print() [6/6]

template<typename T >

size_t StdioStream::print | ( | T | val | ) |
| inline

Print a number.

Parameters

  [in] | val | the number to be printed.

Returns
  the number of bytes written.

## ◆ printDec() [1/9]

int StdioStream::printDec | ( | char | n | ) |
| inline

Print a char as a number.

Parameters

  [in] | n | number to be printed.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printDec() [2/9]

int StdioStream::printDec | ( | double | value,
|  | uint8_t | prec
| ) |  |
| inline

Print a double.

Parameters

  [in] | value | The number to be printed.
  [in] | prec | Number of digits after decimal point.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printDec() [3/9]

int StdioStream::printDec | ( | float | value,
|  | uint8_t | prec
| ) |  |

Print a float.

Parameters

  [in] | value | The number to be printed.
  [in] | prec | Number of digits after decimal point.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printDec() [4/9]

int StdioStream::printDec | ( | int16_t | n | ) |

Print a int16_t

Parameters

  [in] | n | number to be printed.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printDec() [5/9]

int StdioStream::printDec | ( | int32_t | n | ) |

Print a signed 32-bit integer.

Parameters

  [in] | n | number to be printed.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printDec() [6/9]

int StdioStream::printDec | ( | signed char | n | ) |

print a signed 8-bit integer

Parameters

  [in] | n | number to be printed.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printDec() [7/9]

int StdioStream::printDec | ( | uint16_t | n | ) |

print a uint16_t.

Parameters

  [in] | n | number to be printed.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printDec() [8/9]

int StdioStream::printDec | ( | uint32_t | n | ) |

Write an unsigned 32-bit number.

Parameters

  [in] | n | number to be printed.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printDec() [9/9]

int StdioStream::printDec | ( | unsigned char | n | ) |
| inline

Print an unsigned 8-bit number.

Parameters

  [in] | n | number to be print.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printField() [1/3]

int StdioStream::printField | ( | double | value,
|  | char | term,
|  | uint8_t | prec = `2`
| ) |  |
| inline

Print a number followed by a field terminator.

Parameters

  [in] | value | The number to be printed.
  [in] | term | The field terminator.
  [in] | prec | Number of digits after decimal point.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printField() [2/3]

int StdioStream::printField | ( | float | value,
|  | char | term,
|  | uint8_t | prec = `2`
| ) |  |
| inline

Print a number followed by a field terminator.

Parameters

  [in] | value | The number to be printed.
  [in] | term | The field terminator.
  [in] | prec | Number of digits after decimal point.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printField() [3/3]

template<typename T >

int StdioStream::printField | ( | T | value,
|  | char | term
| ) |  |
| inline

Print a number followed by a field terminator.

Parameters

  [in] | value | The number to be printed.
  [in] | term | The field terminator.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printHex()

int StdioStream::printHex | ( | uint32_t | n | ) |

Print HEX

Parameters

  [in] | n | number to be printed as HEX.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ printHexln()

int StdioStream::printHexln | ( | uint32_t | n | ) |
| inline

Print HEX with CRLF

Parameters

  [in] | n | number to be printed as HEX.

Returns
  The number of bytes written or -1 if an error occurs.

## ◆ println() [1/4]

size_t StdioStream::println | ( |  | ) |
| inline

Write a CR/LF.

Returns
  two, the number of bytes written, for success or zero for failure.

## ◆ println() [2/4]

size_t StdioStream::println | ( | double | val,
|  | uint8_t | prec = `2`
| ) |  |
| inline

Print a floating point number followed by CR/LF.

Parameters

  [in] | val | the number to be printed.
  [in] | prec | Number of digits after decimal point.

Returns
  the number of bytes written.

## ◆ println() [3/4]

size_t StdioStream::println | ( | float | val,
|  | uint8_t | prec = `2`
| ) |  |
| inline

Print a floating point number followed by CR/LF.

Parameters

  [in] | val | the number to be printed.
  [in] | prec | Number of digits after decimal point.

Returns
  the number of bytes written.

## ◆ println() [4/4]

template<typename T >

size_t StdioStream::println | ( | T | val | ) |
| inline

Print an item followed by CR/LF

Parameters

  [in] | val | the item to be printed.

Returns
  the number of bytes written.

## ◆ putc()

int StdioStream::putc | ( | int | c | ) |
| inline

Write a byte to a stream.

putc and fputc are equivalent but putc is in-line so it is faster but require more flash memory.

Parameters

  [in] | c | the byte to be written (converted to an unsigned char).

Returns
  Upon successful completion, fputc() returns the value it has written. Otherwise, it returns EOF and sets the error indicator for the stream.

## ◆ putCRLF()

int StdioStream::putCRLF | ( |  | ) |
| inline

Write a CR/LF.

Returns
  two, the number of bytes written, for success or -1 for failure.

## ◆ rewind()

bool StdioStream::rewind | ( |  | ) |

Set position of a stream to the beginning.

The rewind function sets the file position to the beginning of the file. It is equivalent to fseek(0L, SEEK_SET) except that the error indicator for the stream is also cleared.

Returns
  true for success or false for failure.

## ◆ ungetc()

int StdioStream::ungetc | ( | int | c | ) |

Push a byte back into an input stream.

Parameters

  [in] | c | the byte (converted to an unsigned char) to be pushed back.

One character of push-back is guaranteed. If the ungetc function is called too many times without an intervening read or file positioning operation on that stream, the operation may fail.

A successful intervening call to a file positioning function (fseek, fsetpos, or rewind) discards any pushed-back characters for the stream.

Returns
  Upon successful completion, ungetc() returns the byte pushed back after conversion. Otherwise it returns EOF.

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

- ArduinoSdFat/libraries/SdFat/src/iostream/StdioStream.h
- ArduinoSdFat/libraries/SdFat/src/iostream/StdioStream.cpp