fcppt.io

Description

IO-related typedefs and functions.

Introduction I/O and endianness

Introduction

The io namespace mostly includes typedefs and functions related to the string module, see fcppt.string. There are some functions that deal with I/O and endianness at the same time, also living in the io namespace.

I/O and endianness

The functions dealing with I/O and endianness are fcppt::io::read and fcppt::io::write. They can be used to read or write objects of fundamental types from or to char based streams. All of these functions treat the data as binary data, which means they don't use the stream extractors and inserters, but they use read and write directly.

Here is an example:

  std::stringstream stream{};
 
  // Write 42u into the stream, using big endianness
  fcppt::io::write(stream, 42U, std::endian::big);
 
  // Read the written unsigned int back
  fcppt::optional::maybe_void(
      fcppt::io::read<unsigned>(stream, std::endian::big),
      [](unsigned const _result) { std::cout << _result << '\n'; });

Classes
class	fcppt::io::basic_scoped_rdbuf< Ch, Traits >
	Changes the streambuf of a stream temporarily. More...

Functions
template<typename Ch , typename Traits , typename Type >
std::basic_istream< Ch, Traits > &	fcppt::io::expect (std::basic_istream< Ch, Traits > &_stream, Type const &_value)
	Fails a stream if it does not read the expected value.
template<typename Type , typename Ch , typename Traits >
fcppt::optional::object< Type >	fcppt::io::extract (std::basic_istream< Ch, Traits > &_stream)
	Reads a value from a stream, returning an optional.
template<typename Ch , typename Traits >
fcppt::optional::object< Ch >	fcppt::io::get (std::basic_istream< Ch, Traits > &_stream)
	Gets a character from a stream.
template<typename Ch , typename Traits >
fcppt::optional::object< std::string >	fcppt::io::narrow_string (std::basic_ios< Ch, Traits > const &_ios, std::basic_string_view< Ch, Traits > const _string)
	Uses narrow on every character.Calls fcppt::io::narrow_string_locale using the locale from _ios.
template<typename Ch , typename Traits >
fcppt::optional::object< std::string >	fcppt::io::narrow_string_locale (std::basic_string_view< Ch, Traits > const _string, std::locale const &_locale)
	Uses narrow on every character.Let _string = c_1 ... c_n and d_i = narrow(c_i,0) for i = 1,...,n, where narrow is the function from std::ctype<Ch>. Then this function returns the string d_1, ..., d_n if and only if d_i != 0 for i = 1,...,n.
template<typename Ch , typename Traits >
fcppt::optional::object< Ch >	fcppt::io::peek (std::basic_istream< Ch, Traits > &_stream)
	Peeks at a character from a stream.
template<typename Type >
fcppt::optional::object< Type >	fcppt::io::read (std::istream &_stream, std::endian const _format)
	Reads an object of arithmetic type from a stream.
FCPPT_DETAIL_SYMBOL fcppt::io::optional_buffer	fcppt::io::read_chars (std::istream &stream, std::size_t count)
	Reads a number of chars.
fcppt::io::detail::widen_string	fcppt::io::widen_string (std::string _string)
	Creates a string that outputs each character by widening.
template<typename Type >
void	fcppt::io::write (std::ostream &_stream, Type const &_value, std::endian const _format)
	Writes an object of arithmetic type to a stream.
FCPPT_DETAIL_SYMBOL bool	fcppt::io::write_chars (std::ostream &stream, char const *data, std::size_t count)
	Writes a number of chars.

Function Documentation

expect()

template<typename Ch , typename Traits , typename Type >

std::basic_istream< Ch, Traits > & fcppt::io::expect ( std::basic_istream< Ch, Traits > & _stream, Type const & _value )

inline

Fails a stream if it does not read the expected value.

Tries to read a value of type Type from _stream. If the value read is unequal to _value, the failbit is set for _stream.

Template Parameters

Type	Must be a fundamental type

extract()

template<typename Type , typename Ch , typename Traits >

fcppt::optional::object< Type > fcppt::io::extract ( std::basic_istream< Ch, Traits > & _stream )

inline

Reads a value from a stream, returning an optional.

Uses operator>> to extract a value of type Type from _stream. If extracting the value fails, an empty optional is returned.

Template Parameters

Type	Must have a default constructor or a constructor for fcppt::no_init.

get()

template<typename Ch , typename Traits >

fcppt::optional::object< Ch > fcppt::io::get

(

std::basic_istream< Ch, Traits > &

_stream

)

Gets a character from a stream.

Reads a character from _stream. Returns an empty optional for end-of-file.

narrow_string()

template<typename Ch , typename Traits >

fcppt::optional::object< std::string > fcppt::io::narrow_string ( std::basic_ios< Ch, Traits > const & _ios, std::basic_string_view< Ch, Traits > const _string )

inline

Uses narrow on every character.Calls fcppt::io::narrow_string_locale using the locale from _ios.

narrow_string_locale()

template<typename Ch , typename Traits >

fcppt::optional::object< std::string > fcppt::io::narrow_string_locale	(	std::basic_string_view< Ch, Traits > const	_string,
		std::locale const &	_locale )

Uses narrow on every character.Let _string = c_1 ... c_n and d_i = narrow(c_i,0) for i = 1,...,n, where narrow is the function from std::ctype<Ch>. Then this function returns the string d_1, ..., d_n if and only if d_i != 0 for i = 1,...,n.

peek()

template<typename Ch , typename Traits >

fcppt::optional::object< Ch > fcppt::io::peek

(

std::basic_istream< Ch, Traits > &

_stream

)

Peeks at a character from a stream.

Peeks at a character from _stream. Returns an empty optional for end-of-file.

read()

template<typename Type >

fcppt::optional::object< Type > fcppt::io::read	(	std::istream &	_stream,
		std::endian const	_format )

Reads an object of arithmetic type from a stream.

Reads an arithmetic type Type from _stream using the endianness of _format. The read will be done binary. If it fails, an empty optional will be returned.

Template Parameters

Type	Must be an arithmetic type

Parameters

_stream	The stream to read from
_format	The endianness to use

Returns

If the read is successful, an optional containing the read object will be returned. Otherwise an empty optional will be returned.

read_chars()

FCPPT_DETAIL_SYMBOL fcppt::io::optional_buffer fcppt::io::read_chars	(	std::istream &	stream,
		std::size_t	count )

Reads a number of chars.

Tries to read count chars from stream.

widen_string()

fcppt::io::detail::widen_string fcppt::io::widen_string ( std::string _string )

inline

Creates a string that outputs each character by widening.

write()

template<typename Type >

void fcppt::io::write	(	std::ostream &	_stream,
		Type const &	_value,
		std::endian const	_format )

Writes an object of arithmetic type to a stream.

Writes _value to _stream using the endianness of _format. The write will be done binary.

Template Parameters

Type	Must be an arithmetic type

Parameters

_stream	The stream to write to
_value	The value to write
_format	The endianness to use

write_chars()

FCPPT_DETAIL_SYMBOL bool fcppt::io::write_chars ( std::ostream & stream, char const * data, std::size_t count )

nodiscard

Writes a number of chars.

Tries to write count chars from data to stream.

Returns

If the write operation succeeded.