stdx_ini.h

home

STDX - Minimal INI parser Part of the STDX General Purpose C Library by marciovmf License: MIT https://github.com/marciovmf/stdx

Overview

One flat string pool owns all normalized C strings (section names, keys, values). Sections and entries are indexed by arrays for direct and iterative access.

How to compile

To compile the implementation, define X_IMPL_INI in one source file before including this header.

To customize how this module allocates memory, define X_INI_ALLOC / X_INI_REALLOC / X_INI_FREE before including.

Macro in stdx_ini.h

X_INI_VERSION_MAJOR

#define X_INI_VERSION_MAJOR 3
Macro in stdx_ini.h

X_INI_VERSION_MINOR

#define X_INI_VERSION_MINOR 0
Macro in stdx_ini.h

X_INI_VERSION_PATCH

#define X_INI_VERSION_PATCH 0
Macro in stdx_ini.h

X_INI_DEFAULT_SECTIONS_CAP

#define X_INI_DEFAULT_SECTIONS_CAP 16
Macro in stdx_ini.h

X_INI_DEFAULT_ENTRIES_CAP

#define X_INI_DEFAULT_ENTRIES_CAP 64
Macro in stdx_ini.h

X_INI_MAX_LINE

#define X_INI_MAX_LINE 4096
Enum in stdx_ini.h

XIniErrorCode

Ini parsing status.

typedef enum XIniErrorCode{
  XINI_OK=0,
  XINI_ERR_IO,
  XINI_ERR_MEMORY,
  XINI_ERR_SYNTAX,
  XINI_ERR_EXPECT_EQUALS,
  XINI_ERR_EXPECT_RBRACKET,
  XINI_ERR_UNTERMINATED_STRING
}XIniErrorCode;
Struct in stdx_ini.h

XIniError

Ini error information

typedef struct XIniError{
  XIniErrorCode code;
  int line;
  int column;
  const char *message;
}XIniError;
Struct in stdx_ini.h

XIniSection

Ini section information

typedef struct XIniSection{
  const char *name;
  int first_entry;
}XIniSection;
Struct in stdx_ini.h

XIniEntry

Ini Entry

typedef struct XIniEntry{
  int section;
  const char *key;
  const char *value;
}XIniEntry;
Struct in stdx_ini.h

XIni

Represents a parsed INI source

typedef struct XIni{
  char *pool;
  size_t pool_size;
  size_t pool_cap;
  XIniSection *sections;
  int sections_count;
  int sections_cap;
  XIniEntry *entries;
  int entries_count;
  int entries_cap;
  int global_section;
}XIni;
Function in stdx_ini.h

x_ini_load_file

Load and parse an INI file from disk.

X_INI_API bool x_ini_load_file(
 const char *path,
 XIni *out_ini,
 XIniError *err
);

Parameters

const char *path
Path to the INI file.
XIni *out_ini
Output structure receiving the parsed INI data.
XIniError *err
Optional output error information (may be NULL).

Returns

True on success, false on failure.

Function in stdx_ini.h

x_ini_load_mem

Load and parse INI data from a memory buffer.

X_INI_API bool x_ini_load_mem(
 const void *data,
 size_t size,
 XIni *out_ini,
 XIniError *err
);

Parameters

const void *data
Pointer to the INI data in memory.
size_t size
Size of the data buffer in bytes.
XIni *out_ini
Output structure receiving the parsed INI data.
XIniError *err
Optional output error information (may be NULL).

Returns

True on success, false on failure.

Function in stdx_ini.h

x_ini_free

Free all resources associated with an INI structure.

X_INI_API void x_ini_free(XIni *ini);

Parameters

XIni *ini
INI structure to free.

Returns

Nothing.

Function in stdx_ini.h

x_ini_err_str

Get a human-readable string for an INI error code.

X_INI_API const char * x_ini_err_str(XIniErrorCode code);

Parameters

XIniErrorCode code
Error code.

Returns

Pointer to a static, thread-safe error string.

Function in stdx_ini.h

x_ini_get

Retrieve a string value from the INI data.

X_INI_API const char * x_ini_get(
 const XIni *ini,
 const char *section,
 const char *key,
 const char *def_value
);

Parameters

const XIni *ini
Parsed INI data.
const char *section
Section name.
const char *key
Key name.
const char *def_value
Default value returned if the key is not found.

Returns

Pointer to the value string, or def_value if not found.

Function in stdx_ini.h

x_ini_get_i32

Retrieve a 32-bit integer value from the INI data.

X_INI_API int32_t x_ini_get_i32(
 const XIni *ini,
 const char *section,
 const char *key,
 int32_t def_value
);

Parameters

const XIni *ini
Parsed INI data.
const char *section
Section name.
const char *key
Key name.
int32_t def_value
Default value returned if the key is not found or cannot be parsed.

Returns

Parsed integer value, or def_value on failure.

Function in stdx_ini.h

x_ini_get_u32

Retrieve an unsigne 32-bit integer value from the INI data.

X_INI_API uint32_t x_ini_get_u32(
 const XIni *ini,
 const char *section,
 const char *key,
 uint32_t def_value
);

Parameters

const XIni *ini
Parsed INI data.
const char *section
Section name.
const char *key
Key name.
uint32_t def_value
Default value returned if the key is not found or cannot be parsed.

Returns

Parsed integer value, or def_value on failure.

Function in stdx_ini.h

x_ini_get_f32

Retrieve a 32-bit floating-point value from the INI data.

X_INI_API float x_ini_get_f32(
 const XIni *ini,
 const char *section,
 const char *key,
 float def_value
);

Parameters

const XIni *ini
Parsed INI data.
const char *section
Section name.
const char *key
Key name.
float def_value
Default value returned if the key is not found or cannot be parsed.

Returns

Parsed floating-point value, or def_value on failure.

Function in stdx_ini.h

x_ini_get_bool

Retrieve a boolean value from the INI data.

X_INI_API bool x_ini_get_bool(
 const XIni *ini,
 const char *section,
 const char *key,
 bool def_value
);

Parameters

const XIni *ini
Parsed INI data.
const char *section
Section name.
const char *key
Key name.
bool def_value
Default value returned if the key is not found or cannot be parsed.

Returns

Parsed boolean value, or def_value on failure.

Function in stdx_ini.h

x_ini_set

Set a string value in the INI data.

X_INI_API bool x_ini_set(
 XIni *ini,
 const char *section,
 const char *key,
 const char *value
);

Parameters

XIni *ini
Parsed INI data.
const char *section
Section name.
const char *key
Key name.
const char *value
Value string.

Returns

True on success, false on failure.

Function in stdx_ini.h

x_ini_set_i32

Set a 32-bit integer value in the INI data.

X_INI_API bool x_ini_set_i32(
 XIni *ini,
 const char *section,
 const char *key,
 int32_t value
);

Parameters

XIni *ini
Parsed INI data.
const char *section
Section name.
const char *key
Key name.
int32_t value
Integer value.

Returns

True on success, false on failure.

Function in stdx_ini.h

x_ini_set_u32

Set an unsigned 32-bit integer value in the INI data.

X_INI_API bool x_ini_set_u32(
 XIni *ini,
 const char *section,
 const char *key,
 uint32_t value
);

Parameters

XIni *ini
Parsed INI data.
const char *section
Section name.
const char *key
Key name.
uint32_t value
Integer value.

Returns

True on success, false on failure.

Function in stdx_ini.h

x_ini_set_u32_hex

Set an unsigned 32-bit integer value in hexadecimal form in the INI data.

X_INI_API bool x_ini_set_u32_hex(
 XIni *ini,
 const char *section,
 const char *key,
 uint32_t value
);

Parameters

XIni *ini
Parsed INI data.
const char *section
Section name.
const char *key
Key name.
uint32_t value
Integer value.

Returns

True on success, false on failure.

Function in stdx_ini.h

x_ini_set_f32

Set a 32-bit floating-point value in the INI data.

X_INI_API bool x_ini_set_f32(
 XIni *ini,
 const char *section,
 const char *key,
 float value
);

Parameters

XIni *ini
Parsed INI data.
const char *section
Section name.
const char *key
Key name.
float value
Floating-point value.

Returns

True on success, false on failure.

Function in stdx_ini.h

x_ini_set_bool

Set a boolean value in the INI data.

X_INI_API bool x_ini_set_bool(
 XIni *ini,
 const char *section,
 const char *key,
 bool value
);

Parameters

XIni *ini
Parsed INI data.
const char *section
Section name.
const char *key
Key name.
bool value
Boolean value.

Returns

True on success, false on failure.

Function in stdx_ini.h

x_ini_remove

Remove a key from the INI data.

X_INI_API bool x_ini_remove(
 XIni *ini,
 const char *section,
 const char *key
);

Parameters

XIni *ini
Parsed INI data.
const char *section
Section name.
const char *key
Key name.

Returns

True if the key was removed, false if it was not found or arguments are invalid.

Function in stdx_ini.h

x_ini_remove_section

Remove a section and all of its keys from the INI data.

X_INI_API bool x_ini_remove_section(
 XIni *ini,
 const char *section
);

Parameters

XIni *ini
Parsed INI data.
const char *section
Section name.

Returns

True if the section was removed, false if it was not found or arguments are invalid.

Function in stdx_ini.h

x_ini_write_file

Write INI data to a file.

X_INI_API bool x_ini_write_file(
 const char *path,
 const XIni *ini,
 XIniError *err
);

Parameters

const char *path
Path to the INI file.
const XIni *ini
INI data to write.
XIniError *err
Optional output error information (may be NULL).

Returns

True on success, false on failure.

Function in stdx_ini.h

x_ini_section_count

Get the number of sections in the INI data.

X_INI_API int x_ini_section_count(const XIni *ini);

Parameters

const XIni *ini
Parsed INI data.

Returns

Number of sections.

Function in stdx_ini.h

x_ini_section_name

Get the name of a section by index.

X_INI_API const char * x_ini_section_name(
 const XIni *ini,
 int section_index
);

Parameters

const XIni *ini
Parsed INI data.
int section_index
Zero-based section index.

Returns

Section name string.

Function in stdx_ini.h

x_ini_key_count

Get the number of keys in a section.

X_INI_API int x_ini_key_count(
 const XIni *ini,
 int section_index
);

Parameters

const XIni *ini
Parsed INI data.
int section_index
Zero-based section index.

Returns

Number of keys in the section.

Function in stdx_ini.h

x_ini_key_name

Get the name of a key by section and key index.

X_INI_API const char * x_ini_key_name(
 const XIni *ini,
 int section_index,
 int key_index
);

Parameters

const XIni *ini
Parsed INI data.
int section_index
Zero-based section index.
int key_index
Zero-based key index within the section.

Returns

Key name string.

Function in stdx_ini.h

x_ini_value_at

Get the value of a key by section and key index.

X_INI_API const char * x_ini_value_at(
 const XIni *ini,
 int section_index,
 int key_index
);

Parameters

const XIni *ini
Parsed INI data.
int section_index
Zero-based section index.
int key_index
Zero-based key index within the section.

Returns

Value string at the specified position.

Macro in stdx_ini.h

X_INI_ALLOC

Internal macro for allocating memory. To override how this header allocates memory, define this macro with a different implementation before including this header.

#define X_INI_ALLOC(sz) malloc(sz)

Parameters

sz
The size of memory to alloc.
Macro in stdx_ini.h

X_INI_REALLOC

Internal macro for resizing memory. To override how this header resizes memory, define this macro with a different implementation before including this header.

#define X_INI_REALLOC(p, sz) realloc((p), (sz))

Parameters

sz
The size of memory to resize.
Macro in stdx_ini.h

X_INI_FREE

Internal macro for freeing memory. To override how this header frees memory, define this macro with a different implementation before including this header.

#define X_INI_FREE(p) free(p)

Parameters

p
The address of memory region to free.