jau::io::ByteStream_File Class Reference

File based byte input stream, including named file descriptor. More...

#include <byte_stream.hpp>

Inheritance diagram for jau::io::ByteStream_File:

Collaboration diagram for jau::io::ByteStream_File:

Public Member Functions
	ByteStream_File (const ByteStream_File &)=delete
	ByteStream_File (const int dirfd, const std::string &path, iomode_t iomode=iomode_t::rw, const jau::io::fs::fmode_t fmode=fs::fmode_t::def_file_prot, lb_endian_t byteOrder=lb_endian_t::little) noexcept
	Construct a stream based byte stream from filesystem path and parent directory file descriptor, either an existing or new file.
	ByteStream_File (const int fd, iomode_t mode=iomode_t::rw, lb_endian_t byteOrder=lb_endian_t::little) noexcept
	Construct a stream based byte stream by duplicating given file descriptor.
	ByteStream_File (const std::string &path, iomode_t iomode=iomode_t::rw, const jau::io::fs::fmode_t fmode=fs::fmode_t::def_file_prot, lb_endian_t byteOrder=lb_endian_t::little) noexcept
	Construct a stream based byte stream from filesystem path, either an existing or new file.
	~ByteStream_File () noexcept override
bool	available (size_t n) noexcept override
	Return whether n bytes are available in the input stream, if has_content_size() or using an asynchronous source.
bool	canRewind () const noexcept override
	Return true if implementation supports random rewinding the stream, i.e.
void	close () noexcept override
	Close the stream if supported by the underlying mechanism.
size_type	contentSize () const noexcept override
	Returns the content_size if known.
size_t	discard (size_t N) noexcept override
	Discard the next N bytes of the data.
int	fd () const noexcept
	Returns the file descriptor if is_open(), otherwise -1 for no file descriptor.
void	flush () noexcept override
	Synchronizes all output operations, or do nothing.
bool	hasContentSize () const noexcept override
	Returns true if implementation is aware of content_size(), otherwise false.
std::string	id () const noexcept override
	return the id of this data source
bool	isOpen () const noexcept override
	Checks if the stream has an associated file.
size_type	mark () const noexcept override
	Returns the markpos set via setMark() or ByteStream::npos if unset.
size_type	markReadLimit () const noexcept override
	Returns the readLimit set via setMark().
ByteStream_File &	operator= (const ByteStream_File &)=delete
size_t	peek (void *, size_t, size_type) noexcept override
	Read from the source but do not modify the internal offset.
size_type	position () const noexcept override
	Returns the position indicator, similar to e.g.
size_t	read (void *, size_t) noexcept override
	Read from the source.
size_type	seek (size_type newPos) noexcept override
	Sets position indicator for output-streams or input-streams with known length, similar to e.g.
bool	seekMark () noexcept override
	Seeks stream position to markpos as set via setMark().
bool	setMark (size_type readLimit) noexcept override
	Set markpos to current position, allowing the stream to be seekMark().
const jau::io::fs::file_stats &	stats () const noexcept
std::string	toString () const noexcept override
size_t	write (const void *, size_t) noexcept override
	Write to the data sink.
Public Member Functions inherited from jau::io::ByteStream
	ByteStream (iomode_t mode, lb_endian_t byteOrder=lb_endian_t::little) noexcept
	~ByteStream () noexcept override=default
constexpr lb_endian_t	byteOrder () const noexcept
	Returns endian byte-order of stream storage.
constexpr bool	canRead () const noexcept
	Returns true in case stream has iomode::read capabilities.
constexpr bool	canWrite () const noexcept
	Returns true in case stream has iomode::write capabilities.
constexpr iomode_t	mode () const noexcept
bool	peek (uint8_t &out) noexcept
	Peek one byte at current position.
bool	read (uint8_t &bits) noexcept
	Read one byte, uint8_t
bool	readS16 (int16_t &bits) noexcept
	Read int16_t.
bool	readS32 (int32_t &bits) noexcept
	Read int32_t.
bool	readS64 (int64_t &bits) noexcept
	Read int64_t.
bool	readU16 (uint16_t &bits) noexcept
	Read uint16_t.
bool	readU32 (uint32_t &bits) noexcept
	Read incoming uint32_t.
bool	readU64 (uint64_t &bits) noexcept
	Read incoming uint64_t.
bool	readU64Raw (uint64_t &bits) noexcept
	Read incoming uint64_t w/o considering bigEndian, i.e.
virtual size_type	remaining () const noexcept
	Returns the remaining bytes, i.e.
void	setImmutable () noexcept
	Clears iomode_t::write from mode()
bool	write (uint8_t in) noexcept
	Write one byte, uint8_t.
bool	writeS16 (int16_t bits) noexcept
	Write the given int16_t.
bool	writeS32 (int32_t bits) noexcept
	Write the given int32_t.
bool	writeS64 (int64_t bits) noexcept
	Write the given int64_t.
bool	writeU16 (uint16_t bits) noexcept
	Write the given uint16_t.
bool	writeU32 (uint32_t bits) noexcept
	Write the given uint32_t.
bool	writeU64 (uint64_t bits) noexcept
	Write the given uint64_t.
bool	writeU64Raw (uint64_t bits) noexcept
	Write the given uint64_t w/o considering bigEndian, i.e.
Public Member Functions inherited from jau::io::IOStateCap
	IOStateCap () noexcept
	IOStateCap (const IOStateCap &o) noexcept=default
	IOStateCap (IOStateCap &&o) noexcept=default
virtual	~IOStateCap () noexcept=default
void	addState (const iostate_t state) noexcept
	Adds given state flags to existing rdstate() bits.
virtual void	assignState (const iostate_t state=iostate_t::goodbit) noexcept
	Assigns given state to current value.
bool	bad () const noexcept
	Checks if a non-recoverable error has occurred.
void	clear (const iostate_t state=iostate_t::goodbit) noexcept
	Clears state flags by assignment to the given value.
void	clearStateFlags (const iostate_t clr) noexcept
	Clears given state flags from current value.
bool	eof () const noexcept
	Checks if end-of-file has been reached.
bool	fail () const noexcept
	Checks if an error has occurred.
bool	good () const noexcept
	Checks if no error nor eof() has occurred i.e.
	operator bool () const noexcept
	Checks if no error has occurred, synonym of !fail().
bool	operator! () const noexcept
	Checks if an error has occurred, synonym of fail().
IOStateCap &	operator= (const IOStateCap &o) noexcept=default
IOStateCap &	operator= (IOStateCap &&o) noexcept=default
virtual iostate_t	rdstate () const noexcept
	Returns the current state flags.
void	setstate (const iostate_t state) noexcept
	Sets state flags, by keeping its previous bits.
bool	timeout () const noexcept
	Checks if a timeout (non-recoverable) has occurred.

Additional Inherited Members
Public Types inherited from jau::io::ByteStream
typedef uint64_t	size_type
	uint64_t size data type, bit position and count
Static Public Attributes inherited from jau::io::ByteStream
static constexpr size_type	npos = std::numeric_limits<size_type>::max()
	Invalid position constant, denoting unset mark() or invalid position.
Protected Member Functions inherited from jau::io::ByteStream
size_t	discardRead (size_t n) noexcept
	Fallback slow discard implementation usind read() in case of unknown stream size.
Protected Member Functions inherited from jau::io::IOStateCap
constexpr void	addstate_impl (iostate_t state) const noexcept
constexpr iostate_t	rdstate_impl () const noexcept
Protected Attributes inherited from jau::io::ByteStream
lb_endian_t	m_byteOrder
iomode_t	m_iomode

Detailed Description

File based byte input stream, including named file descriptor.

Implementation mimics std::ifstream via OS level file descriptor (FD) operations, giving more flexibility, allowing reusing existing FD and enabling openat() operations.

If source path denotes a named file descriptor, i.e. jau::fs::file_stats::is_fd() returns true, has_content_size() returns false and available() returns true as long the stream is open and EOS hasn't occurred.

Definition at line 741 of file byte_stream.hpp.

Constructor & Destructor Documentation

ByteStream_File() [1/4]

ByteStream_File::ByteStream_File ( const std::string & path, iomode_t iomode = iomode_t::rw, const jau::io::fs::fmode_t fmode = fs::fmode_t::def_file_prot, lb_endian_t byteOrder = lb_endian_t::little )

noexcept

Construct a stream based byte stream from filesystem path, either an existing or new file.

In case the file already exists and iomode has iomode_t::atend, the underlying file offset is positioned at the end of the file.

In case the given path is a local file URI starting with file://, see jau::io::uri::is_local_file_protocol(), the leading file:// is cut off and the remainder being used.

Parameters

path	the path to the file, maybe a local file URI
iomode	determines whether file should be opened iomode_t::read, iomode_t::write or iomode_t::rw (default)
fmode	file protection mode for a new file, otherwise ignored. Defaults to fs::fmode_t::def_file_prot.
byteOrder	endian byte-order of stream storage, defaults to lb_endian_t::little. Only affects multi-byte r/w operations, e.g. readU16(), writeU16(), etc

Definition at line 517 of file byte_stream.cpp.

Here is the caller graph for this function:

ByteStream_File() [2/4]

ByteStream_File::ByteStream_File ( const int dirfd, const std::string & path, iomode_t iomode = iomode_t::rw, const jau::io::fs::fmode_t fmode = fs::fmode_t::def_file_prot, lb_endian_t byteOrder = lb_endian_t::little )

noexcept

Construct a stream based byte stream from filesystem path and parent directory file descriptor, either an existing or new file.

In case the file already exists and iomode has iomode_t::atend, the underlying file offset is positioned at the end of the file.

In case the given path is a local file URI starting with file://, see jau::io::uri::is_local_file_protocol(), the leading file:// is cut off and the remainder being used.

Parameters

dirfd	parent directory file descriptor
path	the path to the file, maybe a local file URI
iomode	determines whether file should be opened iomode_t::read, iomode_t::write or iomode_t::rw (default)
fmode	file protection mode for a new file, otherwise ignored. Defaults to fs::fmode_t::def_file_prot.
byteOrder	endian byte-order of stream storage, defaults to lb_endian_t::little. Only affects multi-byte r/w operations, e.g. readU16(), writeU16(), etc

Definition at line 435 of file byte_stream.cpp.

ByteStream_File() [3/4]

ByteStream_File::ByteStream_File ( const int fd, iomode_t mode = iomode_t::rw, lb_endian_t byteOrder = lb_endian_t::little )

noexcept

Construct a stream based byte stream by duplicating given file descriptor.

In case the given path is a local file URI starting with file://, see jau::io::uri::is_local_file_protocol(), the leading file:// is cut off and the remainder being used.

Parameters

fd	file descriptor to duplicate leaving the given fd untouched
iomode	determines whether file descriptor is iomode_t::read, iomode_t::write or iomode_t::rw (default)
byteOrder	endian byte-order of stream storage, defaults to lb_endian_t::little. Only affects multi-byte r/w operations, e.g. readU16(), writeU16(), etc

Definition at line 406 of file byte_stream.cpp.

ByteStream_File() [4/4]

jau::io::ByteStream_File::ByteStream_File ( const ByteStream_File & )

delete

~ByteStream_File()

jau::io::ByteStream_File::~ByteStream_File ( )

inlineoverridenoexcept

Definition at line 812 of file byte_stream.hpp.

Member Function Documentation

operator=()

ByteStream_File & jau::io::ByteStream_File::operator= ( const ByteStream_File & )

delete

stats()

const jau::io::fs::file_stats & jau::io::ByteStream_File::stats ( ) const

inlinenoexcept

Definition at line 814 of file byte_stream.hpp.

fd()

int jau::io::ByteStream_File::fd ( ) const

inlinenoexcept

Returns the file descriptor if is_open(), otherwise -1 for no file descriptor.

See also

is_open()

Definition at line 821 of file byte_stream.hpp.

Here is the caller graph for this function:

isOpen()

bool jau::io::ByteStream_File::isOpen ( ) const

inlineoverridevirtualnoexcept

Checks if the stream has an associated file.

Implements jau::io::ByteStream.

Definition at line 823 of file byte_stream.hpp.

Here is the caller graph for this function:

close()

void ByteStream_File::close ( )

overridevirtualnoexcept

Close the stream if supported by the underlying mechanism.

Implements jau::io::ByteStream.

Definition at line 520 of file byte_stream.cpp.

Here is the caller graph for this function:

id()

std::string jau::io::ByteStream_File::id ( ) const

inlineoverridevirtualnoexcept

return the id of this data source

Returns

std::string representing the id of this data source

Reimplemented from jau::io::ByteStream.

Definition at line 825 of file byte_stream.hpp.

Here is the caller graph for this function:

hasContentSize()

bool jau::io::ByteStream_File::hasContentSize ( ) const

inlineoverridevirtualnoexcept

Returns true if implementation is aware of content_size(), otherwise false.

See also

content_size()

Implements jau::io::ByteStream.

Definition at line 827 of file byte_stream.hpp.

Here is the caller graph for this function:

contentSize()

size_type jau::io::ByteStream_File::contentSize ( ) const

inlineoverridevirtualnoexcept

Returns the content_size if known.

See also

has_content_size()

Implements jau::io::ByteStream.

Definition at line 828 of file byte_stream.hpp.

Here is the caller graph for this function:

position()

size_type jau::io::ByteStream_File::position ( ) const

inlineoverridevirtualnoexcept

Returns the position indicator, similar to e.g.

std::basic_istream.

Returns

number of bytes read or written so far.

Implements jau::io::ByteStream.

Definition at line 829 of file byte_stream.hpp.

Here is the caller graph for this function:

canRewind()

bool jau::io::ByteStream_File::canRewind ( ) const

inlineoverridevirtualnoexcept

Return true if implementation supports random rewinding the stream, i.e.

seek() below position().

If random rewind is not supported and method returns false, one can still rewind in range [mark() .. position()).

See also

seek()

setMark()

Implements jau::io::ByteStream.

Definition at line 830 of file byte_stream.hpp.

seek()

ByteStream::size_type ByteStream_File::seek ( size_type newPos )

nodiscardoverridevirtualnoexcept

Sets position indicator for output-streams or input-streams with known length, similar to e.g.

std::basic_istream.

No change occurs if fail() was set or the input-stream has no known length.

If newPos is >= stream-length, iostate::eofbit is set and position set to stream-length, otherwise iostate::eofbit is cleared.

Certain implementations may not allow random rewinding of the stream, see canRewind(). In this case, rewinding is limited to mark(), see setMark(), and may return ByteStream::npos if none set or exceeding range.

A ByteInStream's mark is cleared if > newPos.

Parameters

newPos

desired absolute byte-offset (position)

Returns

resulting position if successful (incl eofbit) or ByteStream::npos otherwise having an unchanged position().

See also

canRewind()

setMark()

Implements jau::io::ByteStream.

Definition at line 215 of file byte_stream.cpp.

Here is the caller graph for this function:

toString()

std::string ByteStream_File::toString ( ) const

overridevirtualnoexcept

Implements jau::io::ByteStream.

Definition at line 534 of file byte_stream.cpp.

Here is the caller graph for this function:

setMark()

bool ByteStream_File::setMark ( size_type readLimit )

nodiscardoverridevirtualnoexcept

Set markpos to current position, allowing the stream to be seekMark().

seek() will clear markpos if > newPos.

For implementations where seek() doesn't allow random rewinding of the stream, setMark() will allow rewinding back to markpos if not exceeding readLimit.

Parameters

readlimit

maximum number of bytes able to read before invalidating the markpos.

Returns

true if marks is set successfully, otherwise false

See also

seek()

canRewind()

Implements jau::io::ByteStream.

Definition at line 257 of file byte_stream.cpp.

mark()

size_type jau::io::ByteStream_File::mark ( ) const

inlineoverridevirtualnoexcept

Returns the markpos set via setMark() or ByteStream::npos if unset.

Implements jau::io::ByteStream.

Definition at line 835 of file byte_stream.hpp.

Here is the caller graph for this function:

markReadLimit()

size_type jau::io::ByteStream_File::markReadLimit ( ) const

inlineoverridevirtualnoexcept

Returns the readLimit set via setMark().

If unset either 0 or implicit limit.

Implements jau::io::ByteStream.

Definition at line 836 of file byte_stream.hpp.

seekMark()

bool ByteStream_File::seekMark ( )

nodiscardoverridevirtualnoexcept

Seeks stream position to markpos as set via setMark().

markpos is kept, hence seekMark() can be called multiple times.

Returns

true if successful (incl eofbit), otherwise false with unchanged position due to I/O failure (iostate::fail set) or setMark() not set.

Implements jau::io::ByteStream.

Definition at line 262 of file byte_stream.cpp.

available()

bool ByteStream_File::available ( size_t n )

overridevirtualnoexcept

Return whether n bytes are available in the input stream, if has_content_size() or using an asynchronous source.

If !has_content_size() and not being an asynchronous source, !end_of_data() is returned.

Method may be blocking when using an asynchronous source up until the requested bytes are available.

A subsequent call to read() shall return immediately with at least the requested numbers of bytes available, if has_content_size() or using an asynchronous source.

See details of the implementing class.

Input stream operation, returns false if !is_input().

Parameters

n	byte count to wait for

Returns

true if n bytes are available, otherwise false

See also

has_content_size()

read()

ByteInStream Properties

Implements jau::io::ByteStream.

Definition at line 343 of file byte_stream.cpp.

read()

size_t ByteStream_File::read ( void * out, size_t length )

nodiscardoverridevirtualnoexcept

Read from the source.

Moves the internal offset so that every call to read will return a new portion of the source.

Use available() to try to wait for a certain amount of bytes available.

This method shall only block until min(available, length) bytes are transfered.

See details of the implementing class.

Input stream operation, returns zero if !is_input().

Parameters

out	the byte array to write the result to
length	the length of the byte array out

Returns

length in bytes that was actually read and put into out

See also

available()

ByteInStream Properties

Implements jau::io::ByteStream.

Definition at line 269 of file byte_stream.cpp.

Here is the caller graph for this function:

peek()

size_t ByteStream_File::peek ( void * out, size_t length, size_type peek_offset )

nodiscardoverridevirtualnoexcept

Read from the source but do not modify the internal offset.

Consecutive calls to peek() will return portions of the source starting at the same position.

Input stream operation, returns zero if !is_input().

Parameters

out	the byte array to write the output to
length	the length of the byte array out
peek_offset	offset from current stream position to read at

Returns

length in bytes that was actually read and put into out

Implements jau::io::ByteStream.

Definition at line 300 of file byte_stream.cpp.

discard()

size_t ByteStream_File::discard ( size_t N )

nodiscardoverridevirtualnoexcept

Discard the next N bytes of the data.

Input stream operation, returns zero if !is_input().

Parameters

N	the number of bytes to discard

Returns

number of bytes actually discarded

Implements jau::io::ByteStream.

Definition at line 243 of file byte_stream.cpp.

write()

size_t ByteStream_File::write ( const void * in, size_t length )

nodiscardoverridevirtualnoexcept

Write to the data sink.

Moves the internal offset so that every call to write will be appended to the sink.

This method is not blocking beyond the transfer length bytes.

Output stream operation, returns zero if !is_output().

Parameters

in	the input bytes to write out
length	the length of the byte array in

Returns

length in bytes that were actually written

Implements jau::io::ByteStream.

Definition at line 347 of file byte_stream.cpp.

Here is the caller graph for this function:

flush()

void ByteStream_File::flush ( )

overridevirtualnoexcept

Synchronizes all output operations, or do nothing.

Implements jau::io::ByteStream.

Definition at line 528 of file byte_stream.cpp.

---

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

• include/jau/io/byte_stream.hpp
• src/byte_stream.cpp