SDL::IOStreamRef Struct Reference

Handle to a non owned iOStream. More...

Inheritance diagram for SDL::IOStreamRef:

Public Member Functions
constexpr	IOStreamRef (const IOStreamRef &other)
	Copy constructor.
constexpr	IOStreamRef (IOStreamRef &&other)
	Move constructor.
constexpr	~IOStreamRef ()=default
	Default constructor.
IOStreamRef &	operator= (IOStreamRef other)
	Assignment operator.
void	reset (SDL_IOStream *newResource={})
	Close and free an allocated IOStreamBase structure.
void	Close ()
	Close and free an allocated IOStreamBase structure.
	IOStreamBase (StringParam file, StringParam mode)
	Use this function to create a new IOStreamBase structure for reading from and/or writing to a named file.
	IOStreamBase (const IOStreamInterface &iface, void *userdata)
	Create a custom IOStreamBase.
Public Member Functions inherited from SDL::IOStreamBase
	IOStreamBase (StringParam file, StringParam mode)
	Use this function to create a new IOStreamBase structure for reading from and/or writing to a named file.
	IOStreamBase (const IOStreamInterface &iface, void *userdata)
	Create a custom IOStreamBase.
PropertiesRef	GetProperties () const
	Get the properties associated with an IOStreamBase.
IOStatus	GetStatus () const
	Query the stream status of an IOStreamBase.
Sint64	GetSize () const
	Use this function to get the size of the data stream in an IOStreamBase.
Sint64	Seek (Sint64 offset, IOWhence whence)
	Seek within an IOStreamBase data stream.
Sint64	Tell () const
	Determine the current read/write offset in an IOStreamBase 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 IOStreamBase data stream.
size_t	print (std::string_view fmt, auto... args)
size_t	println (std::string_view fmt, auto... args)
size_t	printf (SDL_PRINTF_FORMAT_STRING const char *fmt,...)
	Print to an IOStreamBase data stream.
size_t	vprintf (SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap)
	Print to an IOStreamBase 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 IOStreamBase.
Sint8	ReadS8 ()
	Use this function to read a signed byte from an IOStreamBase.
Uint16	ReadU16LE ()
	Use this function to read 16 bits of little-endian data from an IOStreamBase and return in native format.
Sint16	ReadS16LE ()
	Use this function to read 16 bits of little-endian data from an IOStreamBase and return in native format.
Uint16	ReadU16BE ()
	Use this function to read 16 bits of big-endian data from an IOStreamBase and return in native format.
Sint16	ReadS16BE ()
	Use this function to read 16 bits of big-endian data from an IOStreamBase and return in native format.
Uint32	ReadU32LE ()
	Use this function to read 32 bits of little-endian data from an IOStreamBase and return in native format.
Sint32	ReadS32LE ()
	Use this function to read 32 bits of little-endian data from an IOStreamBase and return in native format.
Uint32	ReadU32BE ()
	Use this function to read 32 bits of big-endian data from an IOStreamBase and return in native format.
Sint32	ReadS32BE ()
	Use this function to read 32 bits of big-endian data from an IOStreamBase and return in native format.
Uint64	ReadU64LE ()
	Use this function to read 64 bits of little-endian data from an IOStreamBase and return in native format.
Sint64	ReadS64LE ()
	Use this function to read 64 bits of little-endian data from an IOStreamBase and return in native format.
Uint64	ReadU64BE ()
	Use this function to read 64 bits of big-endian data from an IOStreamBase and return in native format.
Sint64	ReadS64BE ()
	Use this function to read 64 bits of big-endian data from an IOStreamBase and return in native format.
void	WriteU8 (Uint8 value)
	Use this function to write a byte to an IOStreamBase.
void	WriteS8 (Sint8 value)
	Use this function to write a signed byte to an IOStreamBase.
void	WriteU16LE (Uint16 value)
	Use this function to write 16 bits in native format to an IOStreamBase as little-endian data.
void	WriteS16LE (Sint16 value)
	Use this function to write 16 bits in native format to an IOStreamBase as little-endian data.
void	WriteU16BE (Uint16 value)
	Use this function to write 16 bits in native format to an IOStreamBase as big-endian data.
void	WriteS16BE (Sint16 value)
	Use this function to write 16 bits in native format to an IOStreamBase as big-endian data.
void	WriteU32LE (Uint32 value)
	Use this function to write 32 bits in native format to an IOStreamBase as little-endian data.
void	WriteS32LE (Sint32 value)
	Use this function to write 32 bits in native format to an IOStreamBase as little-endian data.
void	WriteU32BE (Uint32 value)
	Use this function to write 32 bits in native format to an IOStreamBase as big-endian data.
void	WriteS32BE (Sint32 value)
	Use this function to write 32 bits in native format to an IOStreamBase as big-endian data.
void	WriteU64LE (Uint64 value)
	Use this function to write 64 bits in native format to an IOStreamBase as little-endian data.
void	WriteS64LE (Sint64 value)
	Use this function to write 64 bits in native format to an IOStreamBase as little-endian data.
void	WriteU64BE (Uint64 value)
	Use this function to write 64 bits in native format to an IOStreamBase as big-endian data.
void	WriteS64BE (Sint64 value)
	Use this function to write 64 bits in native format to an IOStreamBase as big-endian data.
std::optional< Uint8 >	TryReadU8 ()
	Use this function to read a byte from an IOStreamBase.
std::optional< Sint8 >	TryReadS8 ()
	Use this function to read a byte from an IOStreamBase.
std::optional< Uint16 >	TryReadU16LE ()
	Use this function to read 16 bits of little-endian data from an IOStreamBase and return in native format.
std::optional< Sint16 >	TryReadS16LE ()
	Use this function to read 16 bits of little-endian data from an IOStreamBase and return in native format.
std::optional< Uint16 >	TryReadU16BE ()
	Use this function to read 16 bits of big-endian data from an IOStreamBase and return in native format.
std::optional< Sint16 >	TryReadS16BE ()
	Use this function to read 16 bits of big-endian data from an IOStreamBase and return in native format.
std::optional< Uint32 >	TryReadU32LE ()
	Use this function to read 32 bits of little-endian data from an IOStreamBase and return in native format.
std::optional< Sint32 >	TryReadS32LE ()
	Use this function to read 32 bits of little-endian data from an IOStreamBase and return in native format.
std::optional< Uint32 >	TryReadU32BE ()
	Use this function to read 32 bits of big-endian data from an IOStreamBase and return in native format.
std::optional< Sint32 >	TryReadS32BE ()
	Use this function to read 32 bits of big-endian data from an IOStreamBase and return in native format.
std::optional< Uint64 >	TryReadU64LE ()
	Use this function to read 64 bits of little-endian data from an IOStreamBase and return in native format.
std::optional< Sint64 >	TryReadS64LE ()
	Use this function to read 64 bits of little-endian data from an IOStreamBase and return in native format.
std::optional< Uint64 >	TryReadU64BE ()
	Use this function to read 64 bits of big-endian data from an IOStreamBase and return in native format.
std::optional< Sint64 >	TryReadS64BE ()
	Use this function to read 64 bits of big-endian data from an IOStreamBase and return in native format.
constexpr	Resource (T resource={})
	Constructs the underlying resource.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
	Resource (const Resource &other)=delete
	Resource (Resource &&other)=delete
Public Member Functions inherited from SDL::Resource< SDL_IOStream * >
constexpr	Resource (SDL_IOStream * resource={})
	Constructs the underlying resource.
constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.
constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.
	Resource (const Resource &other)=delete
	Resource (Resource &&other)=delete
Resource &	operator= (const Resource &other)=delete
Resource &	operator= (Resource &&other)=delete
constexpr	operator bool () const
	True if contains a valid resource.
constexpr bool	operator== (const Resource &other) const=default
	Comparison.
constexpr bool	operator== (std::nullopt_t) const
	Comparison.
constexpr bool	operator== (std::nullptr_t) const
	Comparison.
constexpr SDL_IOStream *	get () const
	Return contained resource;.
constexpr SDL_IOStream *	release (SDL_IOStream * newResource={})
	Return contained resource and empties or replace value.
constexpr const SDL_IOStream *	operator-> () const
	Access to fields.
constexpr SDL_IOStream *	operator-> ()
	Access to fields.

Detailed Description

Category:

Resource

See also

IOStreamBase

IOStream

Member Function Documentation

Close()

void SDL::IOStreamRef::Close ( )

inline

IOStreamRef.Close() closes and cleans up the IOStreamBase stream. It releases any resources used by the stream and frees the IOStreamBase itself. This returns true on success, or false if the stream failed to flush to its output (e.g. to disk).

Note that if this fails to flush the stream for any reason, this function reports an error, but the IOStreamBase is still invalid once this function returns.

This call flushes any buffered writes to the operating system, but there are no guarantees that those writes have gone to physical media; they might be in the OS's file cache, waiting to go to disk later. If it's absolutely crucial that writes go to disk immediately, so they are definitely stored even if the power fails before the file cache would have caught up, one should call IOStreamBase.Flush() before closing. Note that flushing takes time and makes the system and your app operate less efficiently, so do so sparingly.

Exceptions

Error

on failure.

Thread safety:

This function is not thread safe.

Since

This function is available since SDL 3.2.0.

See also

IOStreamBase.IOStreamBase

IOStreamBase() [1/2]

SDL::IOStreamBase::IOStreamBase ( const IOStreamInterface &  iface, void *  userdata  )

inline

Applications do not need to use this function unless they are providing their own IOStreamBase implementation. If you just need an IOStreamBase to read/write a common data source, you should use the built-in implementations in SDL, like IOStreamBase.IOStreamBase(StringParam,StringParam) or IOFromMem(), etc.

This function makes a copy of iface and the caller does not need to keep it around after this call.

Parameters

iface	the interface that implements this IOStreamBase, initialized using SDL_INIT_INTERFACE().
userdata	the pointer that will be passed to the interface functions.

Postcondition

a valid stream on success.

Exceptions

Error

on failure.

Thread safety:

It is safe to call this function from any thread.

Since

This function is available since SDL 3.2.0.

See also

IOStreamRef.Close

SDL_INIT_INTERFACE

IOFromConstMem

IOStreamBase.IOStreamBase

IOFromMem

IOStreamBase() [2/2]

SDL::IOStreamBase::IOStreamBase ( StringParam  file, StringParam  mode  )

inline

The mode string is treated roughly the same as in a call to the C library's fopen(), even if SDL doesn't happen to use fopen() behind the scenes.

Available mode strings:

• "r": Open a file for reading. The file must exist.
• "w": Create an empty file for writing. If a file with the same name already exists its content is erased and the file is treated as a new empty file.
• "a": Append to a file. Writing operations append data at the end of the file. The file is created if it does not exist.
• "r+": Open a file for update both reading and writing. The file must exist.
• "w+": Create an empty file for both reading and writing. If a file with the same name already exists its content is erased and the file is treated as a new empty file.
• "a+": Open a file for reading and appending. All writing operations are performed at the end of the file, protecting the previous content to be overwritten. You can reposition (fseek, rewind) the internal pointer to anywhere in the file for reading, but writing operations will move it back to the end of file. The file is created if it does not exist.

NOTE: In order to open a file as a binary file, a "b" character has to be included in the mode string. This additional "b" character can either be appended at the end of the string (thus making the following compound modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+"). Additional characters may follow the sequence, although they should have no effect. For example, "t" is sometimes appended to make explicit the file is a text file.

This function supports Unicode filenames, but they must be encoded in UTF-8 format, regardless of the underlying operating system.

In Android, IOStreamBase.IOStreamBase() can be used to open content:// URIs. As a fallback, IOStreamBase.IOStreamBase() will transparently open a matching filename in the app's assets.

Closing the IOStreamBase will close SDL's internal file handle.

The following properties may be set at creation time by SDL:

• prop::IOStream.WINDOWS_HANDLE_POINTER: a pointer, that can be cast to a win32 HANDLE, that this IOStreamBase is using to access the filesystem. If the program isn't running on Windows, or SDL used some other method to access the filesystem, this property will not be set.
• prop::IOStream.STDIO_FILE_POINTER: a pointer, that can be cast to a stdio FILE *, that this IOStreamBase is using to access the filesystem. If SDL used some other method to access the filesystem, this property will not be set. PLEASE NOTE that if SDL is using a different C runtime than your app, trying to use this pointer will almost certainly result in a crash! This is mostly a problem on Windows; make sure you build SDL and your app with the same compiler and settings to avoid it.
• prop::IOStream.FILE_DESCRIPTOR_NUMBER: a file descriptor that this IOStreamBase is using to access the filesystem.
• prop::IOStream.ANDROID_AASSET_POINTER: a pointer, that can be cast to an Android NDK AAsset *, that this IOStreamBase is using to access the filesystem. If SDL used some other method to access the filesystem, this property will not be set.

Parameters

file	a UTF-8 string representing the filename to open.
mode	an ASCII string representing the mode to be used for opening the file.

Postcondition

the object is convertible to true if valid or false 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

IOStreamRef.Close

IOStreamBase.Flush

IOStreamBase.Read

IOStreamBase.Seek

IOStreamBase.Tell

IOStreamBase.Write

reset()

void SDL::IOStreamRef::reset ( SDL_IOStream *  newResource = {} )

inline

IOStreamRef.Close() closes and cleans up the IOStreamBase stream. It releases any resources used by the stream and frees the IOStreamBase itself. This returns true on success, or false if the stream failed to flush to its output (e.g. to disk).

Note that if this fails to flush the stream for any reason, this function reports an error, but the IOStreamBase is still invalid once this function returns.

This call flushes any buffered writes to the operating system, but there are no guarantees that those writes have gone to physical media; they might be in the OS's file cache, waiting to go to disk later. If it's absolutely crucial that writes go to disk immediately, so they are definitely stored even if the power fails before the file cache would have caught up, one should call IOStreamBase.Flush() before closing. Note that flushing takes time and makes the system and your app operate less efficiently, so do so sparingly.

Exceptions

Error

on failure.

Thread safety:

This function is not thread safe.

Since

This function is available since SDL 3.2.0.

See also

IOStreamBase.IOStreamBase

---

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

• SDL3pp/SDL3pp_iostream.h