The read/write operation structure. More...

Inheritance diagram for SDL::IOStream:

Public Member Functions
constexpr	IOStream (IOStreamRaw resource) noexcept
	Constructs from raw IOStream.
constexpr	IOStream (const IOStream &other)=delete
	Copy constructor.
constexpr	IOStream (IOStream &&other) noexcept
	Move constructor.
constexpr	IOStream (const IOStreamRef &other)=delete
constexpr	IOStream (IOStreamRef &&other)=delete
	~IOStream ()
	Destructor.
constexpr IOStream &	operator= (IOStream &&other) noexcept
	Assignment operator.
IOStream &	operator= (const IOStream &other)=delete
	Assignment operator.
void	Close ()
	Close and free an allocated IOStream structure.
PropertiesRef	GetProperties () const
	Get the properties associated with an IOStream.
IOStatus	GetStatus () const
	Query the stream status of an IOStream.
Sint64	GetSize () const
	Use this function to get the size of the data stream in an IOStream.
Sint64	Seek (Sint64 offset, IOWhence whence)
	Seek within an IOStream data stream.
Sint64	Tell () const
	Determine the current read/write offset in an IOStream data stream.
std::string	Read (size_t size=-1)
	Read from a data source.
size_t	Read (TargetBytes buf)
	Read from a data source.
size_t	Write (SourceBytes buf)
	Write to an IOStream data stream.
size_t	print (std::string_view fmt, auto... args)
	Prints formatted string.
size_t	println (std::string_view fmt, auto... args)
	Prints formatted string.
size_t	printf (SDL_PRINTF_FORMAT_STRING const char *fmt,...)
	Print to an IOStream data stream.
size_t	vprintf (SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap)
	Print to an IOStream data stream.
void	Flush ()
	Flush any buffered data in the stream.
StringResult	LoadFile ()
	Load all the data from an SDL data stream.
template<class T>
OwnArray< T >	LoadFileAs ()
	Load all the data from an SDL data stream.
void	SaveFile (SourceBytes data)
	Save all the data into an SDL data stream.
Uint8	ReadU8 ()
	Use this function to read a byte from an IOStream.
Sint8	ReadS8 ()
	Use this function to read a signed byte from an IOStream.
Uint16	ReadU16LE ()
	Use this function to read 16 bits of little-endian data from an IOStream and return in native format.
Sint16	ReadS16LE ()
	Use this function to read 16 bits of little-endian data from an IOStream and return in native format.
Uint16	ReadU16BE ()
	Use this function to read 16 bits of big-endian data from an IOStream and return in native format.
Sint16	ReadS16BE ()
	Use this function to read 16 bits of big-endian data from an IOStream and return in native format.
Uint32	ReadU32LE ()
	Use this function to read 32 bits of little-endian data from an IOStream and return in native format.
Sint32	ReadS32LE ()
	Use this function to read 32 bits of little-endian data from an IOStream and return in native format.
Uint32	ReadU32BE ()
	Use this function to read 32 bits of big-endian data from an IOStream and return in native format.
Sint32	ReadS32BE ()
	Use this function to read 32 bits of big-endian data from an IOStream and return in native format.
Uint64	ReadU64LE ()
	Use this function to read 64 bits of little-endian data from an IOStream and return in native format.
Sint64	ReadS64LE ()
	Use this function to read 64 bits of little-endian data from an IOStream and return in native format.
Uint64	ReadU64BE ()
	Use this function to read 64 bits of big-endian data from an IOStream and return in native format.
Sint64	ReadS64BE ()
	Use this function to read 64 bits of big-endian data from an IOStream and return in native format.
std::optional< Uint8 >	TryReadU8 () const
	Use this function to read a byte from an IOStreamRef.
std::optional< Sint8 >	TryReadS8 () const
	Use this function to read a byte from an IOStreamRef.
std::optional< Uint16 >	TryReadU16LE () const
	Use this function to read 16 bits of little-endian data from an IOStreamRef and return in native format.
std::optional< Sint16 >	TryReadS16LE () const
	Use this function to read 16 bits of little-endian data from an IOStreamRef and return in native format.
std::optional< Uint16 >	TryReadU16BE () const
	Use this function to read 16 bits of big-endian data from an IOStreamRef and return in native format.
std::optional< Sint16 >	TryReadS16BE () const
	Use this function to read 16 bits of big-endian data from an IOStreamRef and return in native format.
std::optional< Uint32 >	TryReadU32LE () const
	Use this function to read 32 bits of little-endian data from an IOStreamRef and return in native format.
std::optional< Sint32 >	TryReadS32LE () const
	Use this function to read 32 bits of little-endian data from an IOStreamRef and return in native format.
std::optional< Uint32 >	TryReadU32BE () const
	Use this function to read 32 bits of big-endian data from an IOStreamRef and return in native format.
std::optional< Sint32 >	TryReadS32BE () const
	Use this function to read 32 bits of big-endian data from an IOStreamRef and return in native format.
std::optional< Uint64 >	TryReadU64LE () const
	Use this function to read 64 bits of little-endian data from an IOStreamRef and return in native format.
std::optional< Sint64 >	TryReadS64LE () const
	Use this function to read 64 bits of little-endian data from an IOStreamRef and return in native format.
std::optional< Uint64 >	TryReadU64BE () const
	Use this function to read 64 bits of big-endian data from an IOStreamRef and return in native format.
std::optional< Sint64 >	TryReadS64BE () const
	Use this function to read 64 bits of big-endian data from an IOStreamRef and return in native format.
void	WriteU8 (Uint8 value)
	Use this function to write a byte to an IOStream.
void	WriteS8 (Sint8 value)
	Use this function to write a signed byte to an IOStream.
void	WriteU16LE (Uint16 value)
	Use this function to write 16 bits in native format to an IOStream as little-endian data.
void	WriteS16LE (Sint16 value)
	Use this function to write 16 bits in native format to an IOStream as little-endian data.
void	WriteU16BE (Uint16 value)
	Use this function to write 16 bits in native format to an IOStream as big-endian data.
void	WriteS16BE (Sint16 value)
	Use this function to write 16 bits in native format to an IOStream as big-endian data.
void	WriteU32LE (Uint32 value)
	Use this function to write 32 bits in native format to an IOStream as little-endian data.
void	WriteS32LE (Sint32 value)
	Use this function to write 32 bits in native format to an IOStream as little-endian data.
void	WriteU32BE (Uint32 value)
	Use this function to write 32 bits in native format to an IOStream as big-endian data.
void	WriteS32BE (Sint32 value)
	Use this function to write 32 bits in native format to an IOStream as big-endian data.
void	WriteU64LE (Uint64 value)
	Use this function to write 64 bits in native format to an IOStream as little-endian data.
void	WriteS64LE (Sint64 value)
	Use this function to write 64 bits in native format to an IOStream as little-endian data.
void	WriteU64BE (Uint64 value)
	Use this function to write 64 bits in native format to an IOStream as big-endian data.
void	WriteS64BE (Sint64 value)
	Use this function to write 64 bits in native format to an IOStream as big-endian data.
constexpr	ResourceBase (RawPointer resource)
	Constructs from resource pointer.
constexpr	ResourceBase (std::nullptr_t=nullptr)
	Constructs null/invalid.
Public Member Functions inherited from SDL::ResourceBase< IOStreamRaw >
constexpr	ResourceBase (RawPointer resource)
	Constructs from resource pointer.
constexpr	operator bool () const
	Converts to bool.
constexpr auto	operator<=> (const ResourceBase &other) const=default
	Comparison.
constexpr RawConstPointer	operator-> () const noexcept
	member access to underlying resource pointer.
constexpr RawPointer	get () const noexcept
	Retrieves underlying resource pointer.
constexpr RawPointer	release () noexcept
	Retrieves underlying resource pointer and clear this.

Static Public Member Functions
static IOStream	FromFile (StringParam file, StringParam mode)
	Use this function to create a new IOStream structure for reading from and/or writing to a named file.
static IOStream	FromMem (TargetBytes mem)
	Use this function to prepare a read-write memory buffer for use with IOStream.
static IOStream	FromConstMem (SourceBytes mem)
	Use this function to prepare a read-only memory buffer for use with IOStream.
static IOStream	FromDynamicMem ()
	Use this function to create an IOStream that is backed by dynamically allocated memory.
static IOStream	Open (const IOStreamInterface &iface, void *userdata)
	Create a custom IOStream.

Additional Inherited Members
Public Types inherited from SDL::ResourceBase< IOStreamRaw >
using	RawPointer
	The underlying raw pointer type.
using	RawConstPointer
	The underlying const raw pointer type.

Detailed Description

The read/write operation structure.

This operates as an opaque handle. There are several APIs to create various types of I/O streams, or an app can supply an IOStreamInterface to IOStream.Open() to provide their own stream implementation behind this struct's abstract interface.

Since: This struct is available since SDL 3.2.0.

Category:: Resource

Constructor & Destructor Documentation

◆ IOStream()

SDL::IOStream::IOStream ( IOStreamRaw resource )

inlineexplicitconstexprnoexcept

Constructs from raw IOStream.

Parameters

resource a IOStreamRaw to be wrapped.

This assumes the ownership, call release() if you need to take back.

Member Function Documentation

◆ LoadFileAs()

template<class T>

OwnArray< T > SDL::IOStream::LoadFileAs ( )

inline

Load all the data from an SDL data stream.

The data is allocated with a zero byte at the end (null terminated) for convenience. This extra byte is not included in the value reported on the returned string.

Returns: the data in bytes

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: LoadFile; IOStream.SaveFile

◆ print()

size_t SDL::IOStream::print	(	std::string_view	fmt,
		auto...	args )

inline

Prints formatted string.

Parameters

fmt	a std::format like format string
args	the arguments to be formatted

Category:: Formatted string

◆ printf()

size_t SDL::IOStream::printf	(	SDL_PRINTF_FORMAT_STRING const char *	fmt,
			... )

inline

Print to an IOStream data stream.

Warning: this is not typesafe! Prefer using print() and println()

This function does formatted printing to the stream.

Parameters

fmt	a printf() style format string.
...	additional parameters matching % tokens in the fmt string, if any.

Returns: the number of bytes written or 0 on failure; call GetError() for more information.

Thread safety:: Do not use the same IOStream from two threads at once.

Since: This function is available since SDL 3.2.0.

See also: IOStream.vprintf; IOStream.Write

◆ println()

size_t SDL::IOStream::println	(	std::string_view	fmt,
		auto...	args )

inline

Prints formatted string.

Parameters

fmt	a std::format like format string
args	the arguments to be formatted

Category:: Formatted string

◆ Read()

std::string SDL::IOStream::Read ( size_t size = -1 )

inline

Read from a data source.

This function reads up size bytes from the data source to the area pointed at by ptr. This function may read less bytes than requested.

This function will return zero when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If zero is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

size	the number of bytes to read from the data source.

Returns: the bytes, or empty string on end of file or other failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Write; IOStream.GetStatus

◆ TryReadS16BE()

std::optional< Sint16 > SDL::IOStream::TryReadS16BE ( ) const

inline

Use this function to read 16 bits of big-endian data from an IOStreamRef and return in native format.

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadS16LE()

std::optional< Sint16 > SDL::IOStream::TryReadS16LE ( ) const

inline

Use this function to read 16 bits of little-endian data from an IOStreamRef and return in native format.

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadS32BE()

std::optional< Sint32 > SDL::IOStream::TryReadS32BE ( ) const

inline

Use this function to read 32 bits of big-endian data from an IOStreamRef and return in native format.

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadS32LE()

std::optional< Sint32 > SDL::IOStream::TryReadS32LE ( ) const

inline

Use this function to read 32 bits of little-endian data from an IOStreamRef and return in native format.

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadS64BE()

std::optional< Sint64 > SDL::IOStream::TryReadS64BE ( ) const

inline

Use this function to read 64 bits of big-endian data from an IOStreamRef and return in native format.

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadS64LE()

std::optional< Sint64 > SDL::IOStream::TryReadS64LE ( ) const

inline

Use this function to read 64 bits of little-endian data from an IOStreamRef and return in native format.

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadS8()

std::optional< Sint8 > SDL::IOStream::TryReadS8 ( ) const

inline

Use this function to read a byte from an IOStreamRef.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadU16BE()

std::optional< Uint16 > SDL::IOStream::TryReadU16BE ( ) const

inline

Use this function to read 16 bits of big-endian data from an IOStreamRef and return in native format.

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadU16LE()

std::optional< Uint16 > SDL::IOStream::TryReadU16LE ( ) const

inline

Use this function to read 16 bits of little-endian data from an IOStreamRef and return in native format.

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadU32BE()

std::optional< Uint32 > SDL::IOStream::TryReadU32BE ( ) const

inline

Use this function to read 32 bits of big-endian data from an IOStreamRef and return in native format.

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadU32LE()

std::optional< Uint32 > SDL::IOStream::TryReadU32LE ( ) const

inline

Use this function to read 32 bits of little-endian data from an IOStreamRef and return in native format.

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadU64BE()

std::optional< Uint64 > SDL::IOStream::TryReadU64BE ( ) const

inline

Use this function to read 64 bits of big-endian data from an IOStreamRef and return in native format.

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadU64LE()

std::optional< Uint64 > SDL::IOStream::TryReadU64LE ( ) const

inline

Use this function to read 64 bits of little-endian data from an IOStreamRef and return in native format.

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadU8()

std::optional< Uint8 > SDL::IOStream::TryReadU8 ( ) const

inline

Use this function to read a byte from an IOStreamRef.

This function will return false when the data stream is completely read, and IOStreamRef.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStreamRef.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success, std::nullopt on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

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

SDL3pp/SDL3pp_iostream.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ IOStream()

Member Function Documentation

◆ LoadFileAs()

◆ print()

◆ printf()

◆ println()

◆ Read()

◆ TryReadS16BE()

◆ TryReadS16LE()

◆ TryReadS32BE()

◆ TryReadS32LE()

◆ TryReadS64BE()

◆ TryReadS64LE()

◆ TryReadS8()

◆ TryReadU16BE()

◆ TryReadU16LE()

◆ TryReadU32BE()

◆ TryReadU32LE()

◆ TryReadU64BE()

◆ TryReadU64LE()

◆ TryReadU8()