Macros
#define	SDL_INI_MAJOR_VERSION 1
	The major version of SDL_ini.

#define	SDL_INI_MINOR_VERSION 2
	The minor version of SDL_ini.

#define	SDL_INI_MICRO_VERSION 0
	The micro/patch version of SDL_ini.

#define	SDL_INI_VERSION SDL_VERSIONNUM(SDL_INI_MAJOR_VERSION, SDL_INI_MINOR_VERSION, SDL_INI_MICRO_VERSION)
	Retrieves an integer representation of the of the SDL_ini version.

#define	SDL_INI_VERSION_ATLEAST(X, Y, Z) (SDL_INI_VERSION >= SDL_VERSIONNUM(X, Y, Z))
	Checks if SDL_ini is at least the given version.

#define	SDL_INI_IMPLEMENTATION
	In exactly one C source file, define `SDL_INI_IMPLEMENTATION` before including `SDL_ini.h`.

Typedefs
typedef void(*	INI_EnumerateSectionsCallback) (void userdata, const SDL_ini ini, const char *section)
	Callback invoked for each section name during enumeration.

typedef void(*	INI_EnumerateKeysCallback) (void userdata, const SDL_ini ini, const char section, const char key, const char *value)
	Callback invoked for each key/value pair during enumeration.

Functions
int	INI_GetVersion (void)
	Get the version of SDL_ini that is linked against.

SDL_ini *	INI_Create (void)
	Create an empty INI object.

SDL_ini *	INI_Load_IO (SDL_IOStream *src, bool closeio)
	Load an INI file from an SDL_IOStream.

SDL_ini *	INI_Load (const char *file)
	Load an INI file from a filesystem path.

SDL_ini *	INI_LoadString (const char *text)
	Load an INI from the given string.

bool	INI_Save_IO (SDL_ini ini, SDL_IOStream dst, bool closeio)
	Save an INI object to an SDL_IOStream.

bool	INI_Save (SDL_ini ini, const char file)
	Save an INI object to a filesystem path.

char *	INI_SaveString (SDL_ini *ini)
	Save an INI object to a newly allocated, NUL-terminated string.

SDL_ini *	INI_Clone (const SDL_ini *ini)
	Create an independent deep copy of an INI object.

void	INI_Destroy (SDL_ini *ini)
	Free an INI object and all associated memory.

const char *	INI_GetString (const SDL_ini ini, const char section, const char key, const char default_value)
	Get a string value from the INI.

Sint64	INI_GetInt (const SDL_ini ini, const char section, const char *key, Sint64 default_value)
	Get a signed 64-bit integer value from the INI.

float	INI_GetFloat (const SDL_ini ini, const char section, const char *key, float default_value)
	Get a floating-point value from the INI.

double	INI_GetDouble (const SDL_ini ini, const char section, const char *key, double default_value)
	Get a double-precision floating-point value from the INI.

bool	INI_GetBoolean (const SDL_ini ini, const char section, const char *key, bool default_value)
	Get a boolean value from the INI.

bool	INI_SetString (SDL_ini ini, const char section, const char key, const char value)
	Set a string value in the INI.

bool	INI_SetInt (SDL_ini ini, const char section, const char *key, Sint64 value)
	Set a signed 64-bit integer value in the INI.

bool	INI_SetFloat (SDL_ini ini, const char section, const char *key, float value)
	Set a single-precision floating-point value in the INI.

bool	INI_SetDouble (SDL_ini ini, const char section, const char *key, double value)
	Set a double-precision floating-point value in the INI.

bool	INI_SetBoolean (SDL_ini ini, const char section, const char *key, bool value)
	Set a boolean value in the INI.

bool	INI_IsDirty (const SDL_ini *ini)
	Check whether the INI has been modified since creation or last load.

void	INI_SetDirty (SDL_ini *ini, bool dirty)
	Manually set or clear the dirty flag.

bool	INI_HasSection (const SDL_ini ini, const char section)
	Check whether a section exists and contains at least one key.

bool	INI_HasKey (const SDL_ini ini, const char section, const char *key)
	Check whether a key exists in a section.

bool	INI_HasValue (const SDL_ini ini, const char section, const char *key)
	Check whether a key exists and has a non-empty value.

bool	INI_RemoveKey (SDL_ini ini, const char section, const char *key)
	Delete a key from a section.

bool	INI_RemoveSection (SDL_ini ini, const char section)
	Delete an entire section and all its keys.

void	INI_EnumerateSections (const SDL_ini ini, INI_EnumerateSectionsCallback callback, void userdata)
	Enumerate all sections in the INI.

void	INI_EnumerateKeys (const SDL_ini ini, const char section, INI_EnumerateKeysCallback callback, void *userdata)
	Enumerate all key/value pairs in a section.

bool	INI_Merge (SDL_ini dest, const SDL_ini src)
	Merge all sections and keys from src into dest.

bool	INI_Merge_IO (SDL_ini dest, SDL_IOStream src, bool closeio)
	Load an INI from an SDL_IOStream and merge it into dest.

bool	INI_MergeFile (SDL_ini dest, const char file)
	Load an INI from a file and merge it into dest.

SDL_ini *	INI_LoadMultiple (const char **files)
	Load multiple INI files, merging them in order.

int	INI_GetSectionCount (const SDL_ini *ini)
	Return the number of sections in the INI.

const char *	INI_GetSection (const SDL_ini *ini, int index)
	Return the name of the section at the given index.

int	INI_GetKeyCount (const SDL_ini ini, const char section)
	Return the number of key/value entries in a section (comments and blank lines are not counted).

const char *	INI_GetKey (const SDL_ini ini, const char section, int index)
	Return the key name at the given index within a section.

const char *	INI_GetKeyValue (const SDL_ini ini, const char section, int index)
	Return the value at the given key index within a section.

Detailed Description

Macro Definition Documentation

◆ SDL_INI_MAJOR_VERSION

#define SDL_INI_MAJOR_VERSION 1

The major version of SDL_ini.

See also: SDL_INI_VERSION; SDL_INI_VERSION_ATLEAST

◆ SDL_INI_MINOR_VERSION

#define SDL_INI_MINOR_VERSION 2

The minor version of SDL_ini.

See also: SDL_INI_VERSION; SDL_INI_VERSION_ATLEAST

◆ SDL_INI_MICRO_VERSION

#define SDL_INI_MICRO_VERSION 0

The micro/patch version of SDL_ini.

See also: SDL_INI_VERSION; SDL_INI_VERSION_ATLEAST

◆ SDL_INI_VERSION

#define SDL_INI_VERSION SDL_VERSIONNUM(SDL_INI_MAJOR_VERSION, SDL_INI_MINOR_VERSION, SDL_INI_MICRO_VERSION)

Retrieves an integer representation of the of the SDL_ini version.

◆ SDL_INI_VERSION_ATLEAST

#define SDL_INI_VERSION_ATLEAST	(	X,
		Y,
		Z
	)	(SDL_INI_VERSION >= SDL_VERSIONNUM(X, Y, Z))

Checks if SDL_ini is at least the given version.

◆ SDL_INI_IMPLEMENTATION

#define SDL_INI_IMPLEMENTATION

In exactly one C source file, define SDL_INI_IMPLEMENTATION before including SDL_ini.h.

#define SDL_INI_IMPLEMENTATION

#include "SDL_ini.h"

SDL_ini.h

In all other files, just include the header normally:

#include "SDL_ini.h"

See also: INI_Create()

Typedef Documentation

◆ INI_EnumerateSectionsCallback

typedef void(* INI_EnumerateSectionsCallback) (void *userdata, const SDL_ini *ini, const char *section)

Callback invoked for each section name during enumeration.

Parameters

userdata	user-provided pointer.
section	the section name (empty string for the global section).

◆ INI_EnumerateKeysCallback

typedef void(* INI_EnumerateKeysCallback) (void *userdata, const SDL_ini *ini, const char *section, const char *key, const char *value)

Callback invoked for each key/value pair during enumeration.

Parameters

userdata	user-provided pointer.
key	the key name.
value	the associated value.

Function Documentation

◆ INI_GetVersion()

int INI_GetVersion ( void )

Get the version of SDL_ini that is linked against.

Returns: the version number as SDL_VERSIONNUM(major, minor, micro).

◆ INI_Create()

SDL_ini * INI_Create ( void )

Create an empty INI object.

Returns: a new SDL_ini on success, or NULL on failure; call SDL_GetError() for more information.

See also: INI_Destroy()

◆ INI_Load_IO()

SDL_ini * INI_Load_IO	(	SDL_IOStream *	src,
		bool	closeio
	)

Load an INI file from an SDL_IOStream.

Parameters

src	the SDL_IOStream to read from.
closeio	if true, the stream is closed after reading.

Returns: a new SDL_ini on success, or NULL on failure; call SDL_GetError() for more information.

See also: INI_Save_IO(); INI_Load()

◆ INI_Load()

SDL_ini * INI_Load ( const char * file )

Load an INI file from a filesystem path.

Parameters

file	the path to the INI file.

Returns: a new SDL_ini on success, or NULL on failure; call SDL_GetError() for more information.

See also: INI_Save()

◆ INI_LoadString()

SDL_ini * INI_LoadString ( const char * text )

Load an INI from the given string.

Parameters

text	the string containing the ini data.

Returns: a new SDL_ini on success, or NULL on failure; call SDL_GetError() for more information.

See also: INI_Load()

◆ INI_Save_IO()

bool INI_Save_IO	(	SDL_ini *	ini,
		SDL_IOStream *	dst,
		bool	closeio
	)

Save an INI object to an SDL_IOStream.

Parameters

ini	the SDL_ini to write.
dst	the SDL_IOStream to write to.
closeio	if true, the stream is closed after writing.

Returns: true on success or false on failure; call SDL_GetError() for more information.

See also: INI_Load_IO(); INI_Save()

◆ INI_Save()

bool INI_Save	(	SDL_ini *	ini,
		const char *	file
	)

Save an INI object to a filesystem path.

Parameters

ini	the SDL_ini to write.
file	the path to write to.

Returns: true on success or false on failure; call SDL_GetError() for more information.

See also: INI_Load()

◆ INI_SaveString()

char * INI_SaveString ( SDL_ini * ini )

Save an INI object to a newly allocated, NUL-terminated string.

Parameters

ini	the SDL_ini to write.

Returns: a NUL-terminated string on success (free with SDL_free), or NULL on failure.

See also: INI_LoadString()

◆ INI_Clone()

SDL_ini * INI_Clone ( const SDL_ini * ini )

Create an independent deep copy of an INI object.

All sections, keys, values, comments, and blank lines are duplicated. The clone starts with a clean dirty flag.

Parameters

ini	the SDL_ini to clone.

Returns: a new SDL_ini on success, or NULL on failure; call SDL_GetError() for more information.

See also: INI_Create()

◆ INI_Destroy()

void INI_Destroy ( SDL_ini * ini )

Free an INI object and all associated memory.

Parameters

ini	the SDL_ini to destroy. NULL is safely ignored.

See also: INI_Create(); INI_Load()

◆ INI_GetString()

const char * INI_GetString	(	const SDL_ini *	ini,
		const char *	section,
		const char *	key,
		const char *	default_value
	)

Get a string value from the INI.

Parameters

ini	the SDL_ini to query.
section	section name (NULL or "" for the global section).
key	the key to look up.
default_value	returned when the key is not found.

Returns: the value string, or default_value if not found.

◆ INI_GetInt()

Sint64 INI_GetInt	(	const SDL_ini *	ini,
		const char *	section,
		const char *	key,
		Sint64	default_value
	)

Get a signed 64-bit integer value from the INI.

Parameters

ini	the SDL_ini to query.
section	section name (NULL or "" for the global section).
key	the key to look up.
default_value	returned when the key is not found.

Returns: the parsed value, or default_value if not found.

See also: INI_GetString()

◆ INI_GetFloat()

float INI_GetFloat	(	const SDL_ini *	ini,
		const char *	section,
		const char *	key,
		float	default_value
	)

Get a floating-point value from the INI.

Parameters

ini	the SDL_ini to query.
section	section name (NULL or "" for the global section).
key	the key to look up.
default_value	returned when the key is not found.

Returns: the parsed value, or default_value if not found.

See also: INI_GetString()

◆ INI_GetDouble()

double INI_GetDouble	(	const SDL_ini *	ini,
		const char *	section,
		const char *	key,
		double	default_value
	)

Get a double-precision floating-point value from the INI.

Parameters

ini	the SDL_ini to query.
section	section name (NULL or "" for the global section).
key	the key to look up.
default_value	returned when the key is not found.

Returns: the parsed value, or default_value if not found.

See also: INI_GetString()

◆ INI_GetBoolean()

bool INI_GetBoolean	(	const SDL_ini *	ini,
		const char *	section,
		const char *	key,
		bool	default_value
	)

Get a boolean value from the INI.

Recognises "1", "true", "yes", "on" as true and "0", "false", "no", "off" as false (case-insensitive).

Parameters

ini	the SDL_ini to query.
section	section name (NULL or "" for the global section).
key	the key to look up.
default_value	returned when the key is not found or is unrecognised.

Returns: the parsed value, or default_value if not found.

See also: INI_GetString()

◆ INI_SetString()

bool INI_SetString	(	SDL_ini *	ini,
		const char *	section,
		const char *	key,
		const char *	value
	)

Set a string value in the INI.

The section is created if it does not exist.

Names are validated so that the document can round-trip through INI_Save() and INI_Load(). The call fails, with SDL_GetError() set, when:

the key begins with '[', ';' or '#'
the key contains '='
the key or section name contains a newline or carriage return
the section name contains ']'
the key or section name has leading or trailing whitespace (the parser trims names, so such names could never be read back)

Parameters

ini	the SDL_ini to modify.
section	section name (NULL or "" for the global section).
key	the key to set.
value	the string value. Providing NULL will set an empty string.

Returns: true on success or false on failure; call SDL_GetError() for more information.

◆ INI_SetInt()

bool INI_SetInt	(	SDL_ini *	ini,
		const char *	section,
		const char *	key,
		Sint64	value
	)

Set a signed 64-bit integer value in the INI.

Parameters

ini	the SDL_ini to modify.
section	section name (NULL or "" for the global section).
key	the key to set.
value	the integer value.

Returns: true on success or false on failure.

See also: INI_SetString()

◆ INI_SetFloat()

bool INI_SetFloat	(	SDL_ini *	ini,
		const char *	section,
		const char *	key,
		float	value
	)

Set a single-precision floating-point value in the INI.

Parameters

ini	the SDL_ini to modify.
section	section name (NULL or "" for the global section).
key	the key to set.
value	the float value.

Returns: true on success or false on failure.

See also: INI_SetString()

◆ INI_SetDouble()

bool INI_SetDouble	(	SDL_ini *	ini,
		const char *	section,
		const char *	key,
		double	value
	)

Set a double-precision floating-point value in the INI.

Parameters

ini	the SDL_ini to modify.
section	section name (NULL or "" for the global section).
key	the key to set.
value	the double value.

Returns: true on success or false on failure.

See also: INI_SetString()

◆ INI_SetBoolean()

bool INI_SetBoolean	(	SDL_ini *	ini,
		const char *	section,
		const char *	key,
		bool	value
	)

Set a boolean value in the INI.

Written as "true" or "false".

Parameters

ini	the SDL_ini to modify.
section	section name (NULL or "" for the global section).
key	the key to set.
value	the boolean value.

Returns: true on success or false on failure.

See also: INI_SetString()

◆ INI_IsDirty()

bool INI_IsDirty ( const SDL_ini * ini )

Check whether the INI has been modified since creation or last load.

Parameters

ini	the SDL_ini to query.

Returns: true if any key has been set, removed, or a section removed.

See also: INI_SetDirty()

◆ INI_SetDirty()

void INI_SetDirty	(	SDL_ini *	ini,
		bool	dirty
	)

Manually set or clear the dirty flag.

Parameters

ini	the SDL_ini to modify.
dirty	the new dirty state.

See also: INI_IsDirty()

◆ INI_HasSection()

bool INI_HasSection	(	const SDL_ini *	ini,
		const char *	section
	)

Check whether a section exists and contains at least one key.

Sections that hold only comments or blank lines are not considered present.

Parameters

ini	the SDL_ini to query.
section	the section name to check for.

Returns: true if the section has at least one key, false otherwise.

See also: INI_HasKey(); INI_RemoveSection()

◆ INI_HasKey()

bool INI_HasKey	(	const SDL_ini *	ini,
		const char *	section,
		const char *	key
	)

Check whether a key exists in a section.

Parameters

ini	the SDL_ini to query.
section	section name (NULL or "" for the global section).
key	the key to look up.

Returns: true if the key exists, false otherwise.

A key with an empty value (for example key=) still counts as existing. Use INI_HasValue() to check for a key that also has a non-empty value.

See also: INI_GetString(); INI_RemoveKey(); INI_HasValue()

◆ INI_HasValue()

bool INI_HasValue	(	const SDL_ini *	ini,
		const char *	section,
		const char *	key
	)

Check whether a key exists and has a non-empty value.

Unlike INI_HasKey(), a key with an empty value (for example key=) is not considered to have a value.

Parameters

ini	the SDL_ini to query.
section	section name (NULL or "" for the global section).
key	the key to look up.

Returns: true if the key exists and its value is non-empty, false otherwise.

See also: INI_HasKey()

◆ INI_RemoveKey()

bool INI_RemoveKey	(	SDL_ini *	ini,
		const char *	section,
		const char *	key
	)

Delete a key from a section.

Parameters

ini	the SDL_ini to modify.
section	section name (NULL or "" for the global section).
key	the key to remove.

Returns: true if the key was found and removed, false otherwise.

See also: INI_RemoveSection()

◆ INI_RemoveSection()

bool INI_RemoveSection	(	SDL_ini *	ini,
		const char *	section
	)

Delete an entire section and all its keys.

Parameters

ini	the SDL_ini to modify.
section	section name (NULL or "" for the global section).

Returns: true if the section was found and removed, false otherwise.

See also: INI_RemoveKey()

◆ INI_EnumerateSections()

void INI_EnumerateSections	(	const SDL_ini *	ini,
		INI_EnumerateSectionsCallback	callback,
		void *	userdata
	)

Enumerate all sections in the INI.

Parameters

ini	the SDL_ini to enumerate.
callback	called once per section.
userdata	passed through to the callback.

◆ INI_EnumerateKeys()

void INI_EnumerateKeys	(	const SDL_ini *	ini,
		const char *	section,
		INI_EnumerateKeysCallback	callback,
		void *	userdata
	)

Enumerate all key/value pairs in a section.

Parameters

ini	the SDL_ini to enumerate.
section	section name (NULL or "" for the global section).
callback	called once per key.
userdata	passed through to the callback.

◆ INI_Merge()

bool INI_Merge	(	SDL_ini *	dest,
		const SDL_ini *	src
	)

Merge all sections and keys from src into dest.

Duplicate keys in dest are overwritten by the values from src. Sections that exist only in src are created in dest.

Parameters

dest	the destination SDL_ini.
src	the source SDL_ini to merge from.

Returns: true on success or false on failure.

See also: INI_Merge_IO(); INI_MergeFile()

◆ INI_Merge_IO()

bool INI_Merge_IO	(	SDL_ini *	dest,
		SDL_IOStream *	src,
		bool	closeio
	)

Load an INI from an SDL_IOStream and merge it into dest.

Parameters

dest	the destination SDL_ini.
src	the SDL_IOStream to read from.
closeio	if true, the stream is closed after reading.

Returns: true on success or false on failure.

See also: INI_Merge()

◆ INI_MergeFile()

bool INI_MergeFile	(	SDL_ini *	dest,
		const char *	file
	)

Load an INI from a file and merge it into dest.

Parameters

dest	the destination SDL_ini.
file	the path to the INI file.

Returns: true on success or false on failure.

See also: INI_Merge()

◆ INI_LoadMultiple()

SDL_ini * INI_LoadMultiple ( const char ** files )

Load multiple INI files, merging them in order.

Later files overwrite keys from earlier files.

Parameters

files NULL-terminated array of file paths.

Returns: a new SDL_ini on success, or NULL on failure.

See also: INI_Merge()

◆ INI_GetSectionCount()

int INI_GetSectionCount ( const SDL_ini * ini )

Return the number of sections in the INI.

Parameters

ini	the SDL_ini to query.

Returns: the section count, or 0 if ini is NULL.

◆ INI_GetSection()

const char * INI_GetSection	(	const SDL_ini *	ini,
		int	index
	)

Return the name of the section at the given index.

Parameters

ini	the SDL_ini to query.
index	zero-based section index.

Returns: the section name, or NULL if out of range.

◆ INI_GetKeyCount()

int INI_GetKeyCount	(	const SDL_ini *	ini,
		const char *	section
	)

Return the number of key/value entries in a section (comments and blank lines are not counted).

Parameters

ini	the SDL_ini to query.
section	section name (NULL or "" for the global section).

Returns: the key count, or 0 if the section does not exist.

◆ INI_GetKey()

const char * INI_GetKey	(	const SDL_ini *	ini,
		const char *	section,
		int	index
	)

Return the key name at the given index within a section.

Parameters

ini	the SDL_ini to query.
section	section name (NULL or "" for the global section).
index	zero-based index among key/value entries only.

Returns: the key name, or NULL if out of range.

◆ INI_GetKeyValue()

const char * INI_GetKeyValue	(	const SDL_ini *	ini,
		const char *	section,
		int	index
	)

Return the value at the given key index within a section.

Parameters

ini	the SDL_ini to query.
section	section name (NULL or "" for the global section).
index	zero-based index among key/value entries only.

Returns: the value string, or NULL if out of range.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SDL_INI_MAJOR_VERSION

◆ SDL_INI_MINOR_VERSION

◆ SDL_INI_MICRO_VERSION

◆ SDL_INI_VERSION

◆ SDL_INI_VERSION_ATLEAST

◆ SDL_INI_IMPLEMENTATION

Typedef Documentation

◆ INI_EnumerateSectionsCallback

◆ INI_EnumerateKeysCallback

Function Documentation

◆ INI_GetVersion()

◆ INI_Create()

◆ INI_Load_IO()

◆ INI_Load()

◆ INI_LoadString()

◆ INI_Save_IO()

◆ INI_Save()

◆ INI_SaveString()

◆ INI_Clone()

◆ INI_Destroy()

◆ INI_GetString()

◆ INI_GetInt()

◆ INI_GetFloat()

◆ INI_GetDouble()

◆ INI_GetBoolean()

◆ INI_SetString()

◆ INI_SetInt()

◆ INI_SetFloat()

◆ INI_SetDouble()

◆ INI_SetBoolean()

◆ INI_IsDirty()

◆ INI_SetDirty()

◆ INI_HasSection()

◆ INI_HasKey()

◆ INI_HasValue()

◆ INI_RemoveKey()

◆ INI_RemoveSection()

◆ INI_EnumerateSections()

◆ INI_EnumerateKeys()

◆ INI_Merge()

◆ INI_Merge_IO()

◆ INI_MergeFile()

◆ INI_LoadMultiple()

◆ INI_GetSectionCount()

◆ INI_GetSection()

◆ INI_GetKeyCount()

◆ INI_GetKey()

◆ INI_GetKeyValue()