xtd::io::stream Class Reference

Inheritance diagram for xtd::io::stream:

Definition

Provides a generic view of a sequence of bytes. This is an abstract class.

class core_export_ stream :  public xtd::abstract_object, public std::iostream;

Inheritance

xtd::object → abstract_object → xtd::io::text_writer

Header

#include <xtd/io/stream>

Namespace

xtd::io

Library

xtd.core

Examples

network_stream.cpp, tcp_client_ip_v4.cpp, and tcp_client_ip_v6.cpp.

Public Fields
static xtd::io::null_stream	null_stream
	A Stream with no backing store.
static constexpr int32	eof
	Represnets an eof value.

Public Properties
virtual bool	can_read () const noexcept=0
	When overridden in a derived class, gets a value indicating whether the current stream supports reading.
virtual bool	can_seek () const noexcept=0
	When overridden in a derived class, gets a value indicating whether the current stream supports seeking.
virtual bool	can_timeout () const noexcept
	Gets a value that determines whether the current stream can time out.
virtual bool	can_write () const noexcept=0
	Gets a value indicating whether the current stream supports writing.
virtual bool	is_closed () const noexcept
	Indicates if the stream is closed.
virtual xtd::size	length () const =0
	When overridden in a derived class, gets the length in bytes of the stream.
virtual xtd::size	position () const =0
	When overridden in a derived class, gets the position within the current stream.
virtual void	position (xtd::size value)=0
	When overridden in a derived class, sets the position within the current stream.
virtual int32	read_timeout () const
	Gets a value, in milliseconds, that determines how long the stream will attempt to read before timing out.
virtual void	read_timeout (int32 value)
	Sets a value, in milliseconds, that determines how long the stream will attempt to read before timing out.
virtual int32	write_timeout () const
	Gets a value, in milliseconds, that determines how long the stream will attempt to write before timing out.
virtual void	write_timeout (int32 value)
	Sets a value, in milliseconds, that determines how long the stream will attempt to write before timing out.

Public Methods
void	copy_to (std::ostream &destination)
	Reads the bytes from the current memory stream and writes them to another stream.
void	copy_to (std::ostream &destination, xtd::size buffer_size)
	Reads the bytes from the current memory stream and writes them to another stream, using a specified buffer size.
virtual void	flush ()=0
	When overridden in a derived class, clears all buffers for this stream and causes any buffered data to be written to the underlying device. exception xtd::io::io_exception An I/O error occurs.
virtual xtd::size	read (xtd::span< xtd::byte > &buffer)
	When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.
virtual xtd::size	read (xtd::array< xtd::byte > &buffer, xtd::size offset, xtd::size count)=0
xtd::size	read_at_least (xtd::array< xtd::byte > &buffer, xtd::size minimum_bytes, bool throw_on_end_of_stream=true)
	Reads at least a minimum number of bytes from the current stream and advances the position within the stream by the number of bytes read.
virtual int32	read_byte ()
void	read_exactly (xtd::array< xtd::byte > &buffer)
	Reads bytes from the current stream and advances the position within the stream until the buffer is filled.
void	read_exactly (xtd::array< xtd::byte > &buffer, xtd::size offset, xtd::size count)
	Reads count number of bytes from the current stream and advances the position within the stream.
virtual void	set_length (xtd::size value)=0
virtual void	write (xtd::span< const xtd::byte > buffer)
virtual void	write (const xtd::array< xtd::byte > &buffer, xtd::size offset, xtd::size count)=0
virtual void	write_byte (xtd::byte value)

Protected constructors
	stream ()
	Initializes a new instance of the xtd::io::stream class.

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
virtual xtd::size	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<class object_t >
xtd::uptr< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual xtd::string	to_string () const noexcept
	Returns a xtd::string that represents the current object.
Static Public Member Functions inherited from xtd::object
template<class object_a_t , class object_b_t >
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.
template<class object_a_t , class object_b_t >
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are the same instance.
Protected Member Functions inherited from xtd::abstract_object
	abstract_object ()=default
	Initializes a new instance of the xtd::abstract_object class.

Constructor & Destructor Documentation

stream()

xtd::io::stream::stream ( )

protected

Initializes a new instance of the xtd::io::stream class.

Remarks

xtd::io::stream is the abstract base class of all streams.

Some of the more commonly used streams that inherit from xtd:io::stream are xtd:io::file_stream, and xtd:io::memory_stream.

This constructor exposes the underlying stream, which xtd::io::stream::get_buffer returns.

Member Function Documentation

can_read()

virtual bool xtd::io::stream::can_read ( ) const

pure virtualnoexcept

When overridden in a derived class, gets a value indicating whether the current stream supports reading.

Returns

true if the stream supports reading; otherwise, false.

Implemented in xtd::io::memory_stream, and xtd::net::sockets::network_stream.

can_seek()

virtual bool xtd::io::stream::can_seek ( ) const

pure virtualnoexcept

When overridden in a derived class, gets a value indicating whether the current stream supports seeking.

Returns

true if the stream supports seeking; otherwise, false.

Implemented in xtd::io::memory_stream, and xtd::net::sockets::network_stream.

can_timeout()

virtual bool xtd::io::stream::can_timeout ( ) const

virtualnoexcept

Gets a value that determines whether the current stream can time out.

Returns

A value that determines whether the current stream can time out.

Remarks

The xtd::io::stream::can_timeout property always returns false. Some stream implementations require different behavior, such as xtd::net::sockets::network_stream, which times out if network connectivity is interrupted or lost. If you are implementing a stream that must be able to time out, this property should be overridden to return true.

Reimplemented in xtd::net::sockets::network_stream.

can_write()

virtual bool xtd::io::stream::can_write ( ) const

pure virtualnoexcept

Gets a value indicating whether the current stream supports writing.

Returns

true if the stream supports writing; otherwise, false.

Implemented in xtd::io::memory_stream, and xtd::net::sockets::network_stream.

is_closed()

virtual bool xtd::io::stream::is_closed ( ) const

virtualnoexcept

Indicates if the stream is closed.

Returns

true if the stream is closed, false otherwise

length()

virtual xtd::size xtd::io::stream::length ( ) const

pure virtual

When overridden in a derived class, gets the length in bytes of the stream.

Returns

The length of the stream in bytes.

Exceptions

xtd::not_supported_exception

A class derived from xtd::io::stream does not support seeking and the length is unknown.

Implemented in xtd::io::memory_stream, and xtd::net::sockets::network_stream.

position() [1/2]

virtual xtd::size xtd::io::stream::position ( ) const

pure virtual

When overridden in a derived class, gets the position within the current stream.

Returns

The current position within the stream.

Exceptions

xtd::not_supported_exception

The stream does not support seeking.

Remarks

The stream must support seeking to get or set the position. Use the xtd::io::stream::can_seek property to determine whether the stream supports seeking.

Seeking to any location beyond the length of the stream is supported.

Implemented in xtd::io::memory_stream, and xtd::net::sockets::network_stream.

position() [2/2]

virtual void xtd::io::stream::position ( xtd::size  value )

pure virtual

When overridden in a derived class, sets the position within the current stream.

Parameters

value

The current position within the stream.

Exceptions

xtd::not_supported_exception

The stream does not support seeking.

Remarks

The stream must support seeking to get or set the position. Use the xtd::io::stream::can_seek property to determine whether the stream supports seeking.

Seeking to any location beyond the length of the stream is supported.

Implemented in xtd::io::memory_stream, and xtd::net::sockets::network_stream.

read_timeout() [1/2]

virtual int32 xtd::io::stream::read_timeout ( ) const

virtual

Gets a value, in milliseconds, that determines how long the stream will attempt to read before timing out.

Returns

A value, in milliseconds, that determines how long the stream will attempt to read before timing out.

Exceptions

xtd::invalid_operation_exception

The xtd::io::stream::read_timeout method always throws an xtd::invalid_operation_exception.

Notes to Inheritors

The xtd::io::stream::read_timeout property should be overridden to provide the appropriate behavior for the stream. If the stream does not support timing out, this property should raise an xtd::invalid_operation_exception.

Reimplemented in xtd::net::sockets::network_stream.

read_timeout() [2/2]

virtual void xtd::io::stream::read_timeout ( int32  value )

virtual

Sets a value, in milliseconds, that determines how long the stream will attempt to read before timing out.

Parameters

value

A value, in milliseconds, that determines how long the stream will attempt to read before timing out.

Exceptions

xtd::invalid_operation_exception

The xtd::io::stream::read_timeout method always throws an xtd::invalid_operation_exception.

Notes to Inheritors

The xtd::io::stream::read_timeout property should be overridden to provide the appropriate behavior for the stream. If the stream does not support timing out, this property should raise an xtd::invalid_operation_exception.

Reimplemented in xtd::net::sockets::network_stream.

write_timeout() [1/2]

virtual int32 xtd::io::stream::write_timeout ( ) const

virtual

Gets a value, in milliseconds, that determines how long the stream will attempt to write before timing out.

Returns

A value, in milliseconds, that determines how long the stream will attempt to write before timing out.

Exceptions

xtd::invalid_operation_exception

The xtd::io::stream::write_timeout method always throws an xtd::invalid_operation_exception.

Notes to Inheritors

The xtd::io::stream::write_timeout property should be overridden to provide the appropriate behavior for the stream. If the stream does not support timing out, this property should raise an xtd::invalid_operation_exception.

Reimplemented in xtd::net::sockets::network_stream.

write_timeout() [2/2]

virtual void xtd::io::stream::write_timeout ( int32  value )

virtual

Sets a value, in milliseconds, that determines how long the stream will attempt to write before timing out.

Parameters

value

A value, in milliseconds, that determines how long the stream will attempt to write before timing out.

Exceptions

xtd::invalid_operation_exception

The xtd::io::stream::write_timeout method always throws an xtd::invalid_operation_exception.

Notes to Inheritors

The xtd::io::stream::write_timeout property should be overridden to provide the appropriate behavior for the stream. If the stream does not support timing out, this property should raise an xtd::invalid_operation_exception.

Reimplemented in xtd::net::sockets::network_stream.

copy_to() [1/2]

void xtd::io::stream::copy_to

(

std::ostream &

destination

)

Reads the bytes from the current memory stream and writes them to another stream.

Parameters

destination

The stream to which the contents of the current memory stream will be copied.

copy_to() [2/2]

void xtd::io::stream::copy_to	(	std::ostream &	destination,
		xtd::size	buffer_size
	)

Reads the bytes from the current memory stream and writes them to another stream, using a specified buffer size.

Parameters

destination	The stream to which the contents of the current memory stream will be copied.
buffer_size	The size of the buffer. This value must be greater than zero. The default size is 81920.

flush()

virtual void xtd::io::stream::flush ( )

pure virtual

When overridden in a derived class, clears all buffers for this stream and causes any buffered data to be written to the underlying device. exception xtd::io::io_exception An I/O error occurs.

Implemented in xtd::io::memory_stream, and xtd::net::sockets::network_stream.

read() [1/2]

virtual xtd::size xtd::io::stream::read ( xtd::span< xtd::byte > &  buffer )

virtual

When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.

Parameters

buffer

A region of memory. When this method returns, the contents of this region are replaced by the bytes read from the current source.

read() [2/2]

virtual xtd::size xtd::io::stream::read ( xtd::array< xtd::byte > &  buffer, xtd::size  offset, xtd::size  count  )

pure virtual

Implemented in xtd::io::memory_stream, and xtd::net::sockets::network_stream.

read_at_least()

xtd::size xtd::io::stream::read_at_least	(	xtd::array< xtd::byte > &	buffer,
		xtd::size	minimum_bytes,
		bool	throw_on_end_of_stream = true
	)

Reads at least a minimum number of bytes from the current stream and advances the position within the stream by the number of bytes read.

Parameters

buffer	A region of memory. When this method returns, the contents of this region are replaced by the bytes read from the current stream.
minimum_bytes	The minimum number of bytes to read into the buffer.
throw_on_end_of_stream	true to throw an exception if the end of the stream is reached before reading minimumBytes of bytes; false to return less than minimum_bytes when the end of the stream is reached. The default is true.

Returns

The total number of bytes read into the buffer. This is guaranteed to be greater than or equal to minimum_bytes when throw_on_end_of_stream is true. This will be less than minimum_bytes when the end of the stream is reached and throw_on_end_of_stream is false. This can be less than the number of bytes allocated in the buffer if that many bytes are not currently available.

Exceptions

xtd::argument_out_of_range_exception	`minimum_bytes` is greater than the length of `buffer`.
xtd::io::end_of_stream_exception	`throw_on_end_of_stream` is `true` and the end of the stream is reached before reading `minimum_bytes` bytes of data.

Remarks

When minimum_bytes is 0 (zero), this read operation will be completed without waiting for available data in the stream.

read_exactly() [1/2]

void xtd::io::stream::read_exactly

(

xtd::array< xtd::byte > &

buffer

)

Reads bytes from the current stream and advances the position within the stream until the buffer is filled.

Parameters

buffer

A region of memory. When this method returns, the contents of this region are replaced by the bytes read from the current stream

Exceptions

xtd::end_of_stream_exception

The end of the stream is reached before filling the buffer.

Remarks

When buffer is empty, this read operation will be completed without waiting for available data in the stream.

read_exactly() [2/2]

void xtd::io::stream::read_exactly	(	xtd::array< xtd::byte > &	buffer,
		xtd::size	offset,
		xtd::size	count
	)

Reads count number of bytes from the current stream and advances the position within the stream.

Parameters

buffer	An array of bytes. When this method returns, the buffer contains the specified byte array with the values between offset and (offset + count - 1) replaced by the bytes read from the current stream.
offset	The byte offset in buffer at which to begin storing the data read from the current stream.
count	The number of bytes to be read from the current stream.

Exceptions

xtd::argument_out_of_range_exception	offset is outside the bounds of buffer. -or- The range specified by the combination of offset and count exceeds the length of buffer.
xtd::io::end_of_stream_exception	`throw_on_end_of_stream` is `true` and the end of the stream is reached before reading `minimum_bytes` bytes of data.

Remarks

When count is 0 (zero), this read operation will be completed without waiting for available data in the stream.

set_length()

virtual void xtd::io::stream::set_length ( xtd::size  value )

pure virtual

Implemented in xtd::io::memory_stream, and xtd::net::sockets::network_stream.

write()

virtual void xtd::io::stream::write ( const xtd::array< xtd::byte > &  buffer, xtd::size  offset, xtd::size  count  )

pure virtual

Implemented in xtd::io::memory_stream, and xtd::net::sockets::network_stream.

Member Data Documentation

null_stream

xtd::io::null_stream xtd::io::stream::null_stream

static

A Stream with no backing store.

Remarks

Use xtd::io::stream::null_stream to redirect output to a stream that will not consume any operating system resources. When the methods of xtd::io::stream that provide writing are invoked on xtd::io::stream::null_stream, the call simply returns, and no data is written. xtd::io::stream::null_stream also implements a xtd::io::stream::stream::read method that returns zero without reading data.

eof

constexpr int32 xtd::io::stream::eof

inlinestaticconstexpr

Represnets an eof value.

Remarks

Returns a value not equivalent to any valid value of stream type (EOF (-1)).

---

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

• xtd.core/include/xtd/io/stream.hpp