xtd::io::memory_stream Class Reference

Inheritance diagram for xtd::io::memory_stream:

Definition

Creates a stream whose backing store is memory.

class core_export_ memory_stream : public xtd::io::stream

Inheritance

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

Header

#include <xtd/io/memory_stream>

Namespace

xtd::io

Library

xtd.core

Public constructors
	memory_stream ()
	Initializes a new instance of the MemoryStream class with an expandable capacity initialized to zero.
	memory_stream (xtd::size capacity)
	Initializes a new instance of the MemoryStream class with an expandable capacity initialized as specified.

Public Properties
auto	can_read () const noexcept -> bool override
	Gets a value indicating whether the current stream supports reading.
auto	can_seek () const noexcept -> bool override
	Gets a value indicating whether the current stream supports seeking.
auto	can_write () const noexcept -> bool override
	Gets a value indicating whether the current stream supports writing.
auto	capacity () const -> xtd::size
	Gets the number of bytes allocated for this stream.
auto	capacity (xtd::size value) -> void
	Sets the number of bytes allocated for this stream.
auto	length () const -> xtd::size override
	Gets the length of the stream in bytes.
auto	position () const -> xtd::size override
	Gets the current position within the stream.
auto	position (xtd::size value) -> void override
	Sets the current position within the stream.

Public Methods
auto	flush () -> void override
	Overrides the Flush() method so that no action is performed.
auto	read (xtd::array< xtd::byte > &buffer, size offset, size count) -> xtd::size override
	Reads a block of bytes from the current stream and writes the data to a buffer.
auto	seek (std::streamoff offset, seek_origin loc) -> xtd::size
	Sets the position within the current stream to the specified value.
auto	set_length (xtd::size value) -> void override
	Sets the length of the current stream to the specified value.
auto	to_array () const -> xtd::array< xtd::byte >
	Writes the stream contents to a byte array, regardless of the Position property.
auto	write (const xtd::array< xtd::byte > &buffer, size offset, size count) -> void override
	Writes a block of bytes to the current stream using data read from a buffer.
auto	write_to (std::ostream &stream) -> void
	Writes the entire contents of this memory stream to another stream.
virtual auto	read (xtd::span< xtd::byte > &buffer) -> xtd::size
	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 auto	write (xtd::span< const xtd::byte > buffer) -> void

Additional Inherited Members
static xtd::io::null_stream	null_stream
	A Stream with no backing store.
static constexpr xtd::int32	eof
	Represnets an eof value.
virtual auto	can_timeout () const noexcept -> bool
	Gets a value that determines whether the current stream can time out.
virtual auto	is_closed () const noexcept -> bool
	Indicates if the stream is closed.
virtual auto	read_timeout () const -> xtd::int32
	Gets a value, in milliseconds, that determines how long the stream will attempt to read before timing out.
virtual auto	read_timeout (xtd::int32 value) -> void
	Sets a value, in milliseconds, that determines how long the stream will attempt to read before timing out.
virtual auto	write_timeout () const -> xtd::int32
	Gets a value, in milliseconds, that determines how long the stream will attempt to write before timing out.
virtual auto	write_timeout (xtd::int32 value) -> void
	Sets a value, in milliseconds, that determines how long the stream will attempt to write before timing out.
auto	copy_to (std::ostream &destination) -> void
	Reads the bytes from the current memory stream and writes them to another stream.
auto	copy_to (std::ostream &destination, xtd::size buffer_size) -> void
	Reads the bytes from the current memory stream and writes them to another stream, using a specified buffer size.
auto	read_at_least (xtd::array< xtd::byte > &buffer, xtd::size minimum_bytes, bool throw_on_end_of_stream=true) -> xtd::size
	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 auto	read_byte () -> xtd::int32
auto	read_exactly (xtd::array< xtd::byte > &buffer) -> void
	Reads bytes from the current stream and advances the position within the stream until the buffer is filled.
auto	read_exactly (xtd::array< xtd::byte > &buffer, xtd::size offset, xtd::size count) -> void
	Reads count number of bytes from the current stream and advances the position within the stream.
virtual auto	write_byte (xtd::byte value) -> void
	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::unique_ptr_object< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual xtd::string	to_string () const
	Returns a xtd::string that represents the current 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.
	stream ()
	Initializes a new instance of the xtd::io::stream class.
	abstract_object ()=default
	Initializes a new instance of the xtd::abstract_object class.

Constructor & Destructor Documentation

memory_stream() [1/2]

xtd::io::memory_stream::memory_stream

(

)

Initializes a new instance of the MemoryStream class with an expandable capacity initialized to zero.

Remarks

The xtd::io::memory_stream::can_read, xtd::io::memory_stream::can_seek, and xtd::io::memory_stream::can_write properties are all set to true.

The capacity of the current stream automatically increases when you use the xtd::io::memory_stream::set_length method to set the length to a value larger than the capacity of the current stream.

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

memory_stream() [2/2]

xtd::io::memory_stream::memory_stream

(

xtd::size

capacity

)

Initializes a new instance of the MemoryStream class with an expandable capacity initialized as specified.

Parameters

capacity

The initial size of the internal array in bytes.

Remarks

The xtd::io::memory_stream::can_read, xtd::io::memory_stream::can_seek, and xtd::io::memory_stream::can_write properties are all set to true.

The capacity of the current stream automatically increases when you use the xtd::io::memory_stream::set_length method to set the length to a value larger than the capacity of the current stream.

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

Member Function Documentation

can_read()

auto xtd::io::memory_stream::can_read ( ) const -> bool

nodiscardoverridevirtualnoexcept

Gets a value indicating whether the current stream supports reading.

Returns

true if the stream supports reading; otherwise, false.

Implements xtd::io::stream.

can_seek()

auto xtd::io::memory_stream::can_seek ( ) const -> bool

nodiscardoverridevirtualnoexcept

Gets a value indicating whether the current stream supports seeking.

Returns

true if the stream supports seeking; otherwise, false.

Implements xtd::io::stream.

can_write()

auto xtd::io::memory_stream::can_write ( ) const -> bool

nodiscardoverridevirtualnoexcept

Gets a value indicating whether the current stream supports writing.

Returns

true if the stream supports writing; otherwise, false.

Implements xtd::io::stream.

capacity() [1/2]

auto xtd::io::memory_stream::capacity ( ) const -> xtd::size

nodiscard

Gets the number of bytes allocated for this stream.

Returns

The length of the usable portion of the buffer for the stream.

Exceptions

xtd::argument_out_of_range_exception

A capacity is less than the current length of the stream.

Remarks

capacity is the buffer length for system-provided byte arrays. capacity cannot be set to a value less than the current length of the stream.

capacity() [2/2]

auto xtd::io::memory_stream::capacity

(

xtd::size

value

)

-> void

Sets the number of bytes allocated for this stream.

Parameters

value

The length of the usable portion of the buffer for the stream.

Exceptions

xtd::argument_out_of_range_exception

A capacity is less than the current length of the stream.

Remarks

capacity is the buffer length for system-provided byte arrays. capacity cannot be set to a value less than the current length of the stream.

length()

auto xtd::io::memory_stream::length ( ) const -> xtd::size

nodiscardoverridevirtual

Gets the length of the stream in bytes.

Returns

The length of the stream in bytes.

Implements xtd::io::stream.

position() [1/2]

auto xtd::io::memory_stream::position ( ) const -> xtd::size

nodiscardoverridevirtual

Gets the current position within the stream.

Returns

The current position within the stream.

Implements xtd::io::stream.

position() [2/2]

auto xtd::io::memory_stream::position ( xtd::size value ) -> void

overridevirtual

Sets the current position within the stream.

Parameters

value

The current position within the stream.

Implements xtd::io::stream.

flush()

auto xtd::io::memory_stream::flush ( ) -> void

overridevirtual

Overrides the Flush() method so that no action is performed.

Remarks

This method overrides the xtd::io::stream::flush method.

Because any data written to a xtd::io::memory_stream object is written into RAM, this method is redundant.

Implements xtd::io::stream.

read() [1/2]

auto xtd::io::memory_stream::read ( xtd::array< xtd::byte > & buffer, size offset, size count ) -> xtd::size

overridevirtual

Reads a block of bytes from the current stream and writes the data to a buffer.

Parameters

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

Returns

The total number of bytes written into the buffer. This can be less than the number of bytes requested if that number of bytes are not currently available, or zero if the end of the stream is reached before any bytes are read.

Remarks

The offset parameter gives the offset of the first byte in buffer to which data from the current stream is written. The count parameter gives the maximum number of bytes to read from the current stream. The returned value is the actual number of bytes read, or zero if the end of the stream is reached.

If the read operation is successful, the current position within the stream advances by the number of bytes read. If an exception occurs, the current position within the stream remains unchanged.

The read method will return zero only if the end of the stream is reached. In all other cases, read always reads at least one byte from the stream before returning. By definition, if no data is available from the stream upon a call to read, the read method returns zero (the end of the stream is reached automatically). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached.

Use xtd::io::binary_reader for reading primitive data types.

Implements xtd::io::stream.

seek()

auto xtd::io::memory_stream::seek	(	std::streamoff	offset,
		seek_origin	loc ) -> xtd::size

Sets the position within the current stream to the specified value.

Parameters

offset	The new position within the stream. This is relative to the loc parameter, and can be positive or negative.
loc	A value of type xtd::io::seek_origin, which acts as the seek reference point.

Returns

The new position within the stream, calculated by combining the initial reference point and the offset.

set_length()

auto xtd::io::memory_stream::set_length ( xtd::size value ) -> void

overridevirtual

Sets the length of the current stream to the specified value.

Parameters

value

The value at which to set the length.

Remarks

If the specified value is less than the current length of the stream, the stream is truncated. If after the truncation the current position within the stream is past the end of the stream, the xtd::io::memery_stream::read_byte method returns -1, the xtd::io::memery_stream::read method reads zero bytes into the provided byte array, and xtd::io::memery_stream::write and xtd::io::memery_stream::write_byte methods append specified bytes at the end of the stream, increasing its length. If the specified value is larger than the current capacity and the stream is resizable, the capacity is increased, and the current position within the stream is unchanged. If the length is increased, the contents of the stream between the old and the new length are initialized to zeros.

Implements xtd::io::stream.

to_array()

auto xtd::io::memory_stream::to_array ( ) const -> xtd::array< xtd::byte >

nodiscard

Writes the stream contents to a byte array, regardless of the Position property.

Returns

A new byte array.

Remarks

This method omits unused bytes in xtd::io::memory_stream from the array. To get the entire buffer, use the xtd::io::memory_stream::get_buffer method.

This method returns a copy of the contents of the xtd::io::memory_stream as a byte array. If the current instance was constructed on a provided byte array, a copy of the section of the array to which this instance has access is returned. See the xtd::io::memory_stream constructor for details.

write() [1/2]

auto xtd::io::memory_stream::write ( const xtd::array< xtd::byte > & buffer, size offset, size count ) -> void

overridevirtual

Writes a block of bytes to the current stream using data read from a buffer.

Parameters

buffer	The buffer to write data from.
offset	The zero-based byte offset in buffer at which to begin copying bytes to the current stream.
count	The maximum number of bytes to write.

Examples

This code example is part of a larger example provided for the xtd::io::memory_stream class.

// Write the first string to the stream.
mem_stream.write(first_string, 0 , first_string.length());

Remarks

The offset parameter gives the offset of the first byte in buffer to write from, and the count parameter gives the number of bytes to write. If the write operation is successful, the current position within the stream is advanced by the number of bytes written. If an exception occurs, the current position within the stream is unchanged.

Except for a memory_stream constructed with a byte[] parameter, write operations at the end of a memory_stream expand the memory_stream.

Implements xtd::io::stream.

write_to()

auto xtd::io::memory_stream::write_to

(

std::ostream &

stream

)

-> void

Writes the entire contents of this memory stream to another stream.

Parameters

stream

The stream to write this memory stream to.

Exceptions

xtd::bject_closed_exception

The current or target stream is closed.

Remarks

When the current stream is open, this method is equivalent to calling std::ostream::write on the underlying buffer of this stream.

read() [2/2]

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

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.

Reimplemented from xtd::io::stream.

write() [2/2]

virtual auto xtd::io::stream::write ( xtd::span< const xtd::byte > buffer ) -> void

virtual

Reimplemented from xtd::io::stream.

---

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

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