The read/write operation structure. More...

Inheritance diagram for SDL::IOStream:

Public Member Functions
constexpr	IOStream ()=default
	Default ctor.

constexpr	IOStream (const IOStreamRaw resource)
	Constructs from IOStreamParam. More...

constexpr	IOStream (const IOStream &other)=delete
	Copy constructor.

constexpr	IOStream (IOStream &&other)
	Move constructor.

constexpr	IOStream (const IOStreamRef &other)=delete

constexpr	IOStream (IOStreamRef &&other)=delete

	~IOStream ()
	Destructor.

IOStream &	operator= (IOStream other)
	Assignment operator.

constexpr IOStreamRaw	get () const
	Retrieves underlying IOStreamRaw.

constexpr IOStreamRaw	release ()
	Retrieves underlying IOStreamRaw and clear this.

constexpr auto	operator<=> (const IOStream &other) const =default
	Comparison.

constexpr bool	operator== (std::nullptr_t _) const
	Comparison.

constexpr	operator bool () const
	Converts to bool.

constexpr	operator IOStreamParam () const
	Converts to IOStreamParam.

void	Close ()
	Close and free an allocated IOStream structure. More...

PropertiesRef	GetProperties () const
	Get the properties associated with an IOStream. More...

IOStatus	GetStatus () const
	Query the stream status of an IOStream. More...

Sint64	GetSize () const
	Use this function to get the size of the data stream in an IOStream. More...

Sint64	Seek (Sint64 offset, IOWhence whence)
	Seek within an IOStream data stream. More...

Sint64	Tell () const
	Determine the current read/write offset in an IOStream data stream. More...

std::string	Read (size_t size=-1)
	Read from a data source. More...

size_t	Read (TargetBytes buf)
	Read from a data source. More...

size_t	Write (SourceBytes buf)
	Write to an IOStream data stream. More...

size_t	print (std::string_view fmt, auto... args)
	Prints formatted string. More...

size_t	println (std::string_view fmt, auto... args)
	Prints formatted string. More...

size_t	printf (SDL_PRINTF_FORMAT_STRING const char *fmt,...)
	Print to an IOStream data stream. More...

size_t	vprintf (SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap)
	Print to an IOStream data stream. More...

void	Flush ()
	Flush any buffered data in the stream. More...

StringResult	LoadFile ()
	Load all the data from an SDL data stream. More...

template<class T >
OwnArray< T >	LoadFileAs ()
	Load all the data from an SDL data stream. More...

void	SaveFile (SourceBytes data)
	Save all the data into an SDL data stream. More...

Uint8	ReadU8 ()
	Use this function to read a byte from an IOStream. More...

Sint8	ReadS8 ()
	Use this function to read a signed byte from an IOStream. More...

Uint16	ReadU16LE ()
	Use this function to read 16 bits of little-endian data from an IOStream and return in native format. More...

Sint16	ReadS16LE ()
	Use this function to read 16 bits of little-endian data from an IOStream and return in native format. More...

Uint16	ReadU16BE ()
	Use this function to read 16 bits of big-endian data from an IOStream and return in native format. More...

Sint16	ReadS16BE ()
	Use this function to read 16 bits of big-endian data from an IOStream and return in native format. More...

Uint32	ReadU32LE ()
	Use this function to read 32 bits of little-endian data from an IOStream and return in native format. More...

Sint32	ReadS32LE ()
	Use this function to read 32 bits of little-endian data from an IOStream and return in native format. More...

Uint32	ReadU32BE ()
	Use this function to read 32 bits of big-endian data from an IOStream and return in native format. More...

Sint32	ReadS32BE ()
	Use this function to read 32 bits of big-endian data from an IOStream and return in native format. More...

Uint64	ReadU64LE ()
	Use this function to read 64 bits of little-endian data from an IOStream and return in native format. More...

Sint64	ReadS64LE ()
	Use this function to read 64 bits of little-endian data from an IOStream and return in native format. More...

Uint64	ReadU64BE ()
	Use this function to read 64 bits of big-endian data from an IOStream and return in native format. More...

Sint64	ReadS64BE ()
	Use this function to read 64 bits of big-endian data from an IOStream and return in native format. More...

std::optional< Uint8 >	TryReadU8 ()
	Use this function to read a byte from an IOStreamRef. More...

std::optional< Sint8 >	TryReadS8 ()
	Use this function to read a byte from an IOStreamRef. More...

std::optional< Uint16 >	TryReadU16LE ()
	Use this function to read 16 bits of little-endian data from an IOStreamRef and return in native format. More...

std::optional< Sint16 >	TryReadS16LE ()
	Use this function to read 16 bits of little-endian data from an IOStreamRef and return in native format. More...

std::optional< Uint16 >	TryReadU16BE ()
	Use this function to read 16 bits of big-endian data from an IOStreamRef and return in native format. More...

std::optional< Sint16 >	TryReadS16BE ()
	Use this function to read 16 bits of big-endian data from an IOStreamRef and return in native format. More...

std::optional< Uint32 >	TryReadU32LE ()
	Use this function to read 32 bits of little-endian data from an IOStreamRef and return in native format. More...

std::optional< Sint32 >	TryReadS32LE ()
	Use this function to read 32 bits of little-endian data from an IOStreamRef and return in native format. More...

std::optional< Uint32 >	TryReadU32BE ()
	Use this function to read 32 bits of big-endian data from an IOStreamRef and return in native format. More...

std::optional< Sint32 >	TryReadS32BE ()
	Use this function to read 32 bits of big-endian data from an IOStreamRef and return in native format. More...

std::optional< Uint64 >	TryReadU64LE ()
	Use this function to read 64 bits of little-endian data from an IOStreamRef and return in native format. More...

std::optional< Sint64 >	TryReadS64LE ()
	Use this function to read 64 bits of little-endian data from an IOStreamRef and return in native format. More...

std::optional< Uint64 >	TryReadU64BE ()
	Use this function to read 64 bits of big-endian data from an IOStreamRef and return in native format. More...

std::optional< Sint64 >	TryReadS64BE ()
	Use this function to read 64 bits of big-endian data from an IOStreamRef and return in native format. More...

void	WriteU8 (Uint8 value)
	Use this function to write a byte to an IOStream. More...

void	WriteS8 (Sint8 value)
	Use this function to write a signed byte to an IOStream. More...

void	WriteU16LE (Uint16 value)
	Use this function to write 16 bits in native format to an IOStream as little-endian data. More...

void	WriteS16LE (Sint16 value)
	Use this function to write 16 bits in native format to an IOStream as little-endian data. More...

void	WriteU16BE (Uint16 value)
	Use this function to write 16 bits in native format to an IOStream as big-endian data. More...

void	WriteS16BE (Sint16 value)
	Use this function to write 16 bits in native format to an IOStream as big-endian data. More...

void	WriteU32LE (Uint32 value)
	Use this function to write 32 bits in native format to an IOStream as little-endian data. More...

void	WriteS32LE (Sint32 value)
	Use this function to write 32 bits in native format to an IOStream as little-endian data. More...

void	WriteU32BE (Uint32 value)
	Use this function to write 32 bits in native format to an IOStream as big-endian data. More...

void	WriteS32BE (Sint32 value)
	Use this function to write 32 bits in native format to an IOStream as big-endian data. More...

void	WriteU64LE (Uint64 value)
	Use this function to write 64 bits in native format to an IOStream as little-endian data. More...

void	WriteS64LE (Sint64 value)
	Use this function to write 64 bits in native format to an IOStream as little-endian data. More...

void	WriteU64BE (Uint64 value)
	Use this function to write 64 bits in native format to an IOStream as big-endian data. More...

void	WriteS64BE (Sint64 value)
	Use this function to write 64 bits in native format to an IOStream as big-endian data. More...

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. More...

static IOStream	FromMem (TargetBytes mem)
	Use this function to prepare a read-write memory buffer for use with IOStream. More...

static IOStream	FromConstMem (SourceBytes mem)
	Use this function to prepare a read-only memory buffer for use with IOStream. More...

static IOStream	FromDynamicMem ()
	Use this function to create an IOStream that is backed by dynamically allocated memory. More...

static IOStream	Open (const IOStreamInterface &iface, void *userdata)
	Create a custom IOStream. More...

Detailed Description

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

constexpr SDL::IOStream::IOStream ( const IOStreamRaw resource )

inlineexplicitconstexpr

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

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

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

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:: This function is not thread safe.

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

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

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

◆ ReadS8()

Sint8 SDL::IOStream::ReadS8 ( )

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

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU8()

Uint8 SDL::IOStream::ReadU8 ( )

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

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ TryReadS16BE()

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

inline

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

inline

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

inline

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

inline

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

inline

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

inline

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

inline

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

inline

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

inline

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

inline

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

inline

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

inline

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

inline

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

inline

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 class was generated from the following file:

SDL3pp/SDL3pp_iostream.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ IOStream()

Member Function Documentation

◆ LoadFileAs()

◆ print()

◆ printf()

◆ println()

◆ Read()

◆ ReadS8()

◆ ReadU8()

◆ TryReadS16BE()

◆ TryReadS16LE()

◆ TryReadS32BE()

◆ TryReadS32LE()

◆ TryReadS64BE()

◆ TryReadS64LE()

◆ TryReadS8()

◆ TryReadU16BE()

◆ TryReadU16LE()

◆ TryReadU32BE()

◆ TryReadU32LE()

◆ TryReadU64BE()

◆ TryReadU64LE()

◆ TryReadU8()