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

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

Additional Inherited Members
Static Public Attributes inherited from xtd::io::stream
static xtd::io::null_stream	null_stream
	A Stream with no backing store.
static constexpr int32	eof
	Represnets an eof value.
Public Member Functions inherited from xtd::io::stream
virtual bool	can_timeout () const noexcept
	Gets a value that determines whether the current stream can time out.
virtual bool	is_closed () const noexcept
	Indicates if the stream is closed.
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.
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 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.
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	write (xtd::span< const xtd::byte > buffer)
virtual void	write_byte (xtd::byte value)
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::io::stream
	stream ()
	Initializes a new instance of the xtd::io::stream class.
Protected Member Functions inherited from xtd::abstract_object
	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()

bool xtd::io::memory_stream::can_read ( ) const

overridevirtualnoexcept

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()

bool xtd::io::memory_stream::can_seek ( ) const

overridevirtualnoexcept

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()

bool xtd::io::memory_stream::can_write ( ) const

overridevirtualnoexcept

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]

xtd::size xtd::io::memory_stream::capacity

(

)

const

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]

void xtd::io::memory_stream::capacity

(

xtd::size

value

)

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()

xtd::size xtd::io::memory_stream::length ( ) const

overridevirtual

Gets the length of the stream in bytes.

Returns

The length of the stream in bytes.

Implements xtd::io::stream.

position() [1/2]

xtd::size xtd::io::memory_stream::position ( ) const

overridevirtual

Gets the current position within the stream.

Returns

The current position within the stream.

Implements xtd::io::stream.

position() [2/2]

void xtd::io::memory_stream::position ( xtd::size  value )

overridevirtual

Sets the current position within the stream.

Parameters

value

The current position within the stream.

Implements xtd::io::stream.

flush()

void xtd::io::memory_stream::flush ( )

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()

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

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()

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

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()

void xtd::io::memory_stream::set_length ( xtd::size  value )

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()

xtd::array< xtd::byte > xtd::io::memory_stream::to_array

(

)

const

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()

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

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()

void xtd::io::memory_stream::write_to

(

std::ostream &

stream

)

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.

---

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

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