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

X_INI_VERSION_MAJOR

#define X_INI_VERSION_MAJOR 1
Macro

X_INI_VERSION_MINOR

#define X_INI_VERSION_MINOR 1
Macro

X_INI_VERSION_PATCH

#define X_INI_VERSION_PATCH 0
Macro

X_INI_DEFAULT_SECTIONS_CAP

#define X_INI_DEFAULT_SECTIONS_CAP 16
Macro

X_INI_DEFAULT_ENTRIES_CAP

#define X_INI_DEFAULT_ENTRIES_CAP 64
Macro

X_INI_MAX_LINE

#define X_INI_MAX_LINE 4096
Enum

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

XIniError

Ini error information

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

XIniSection

Ini section information

typedef struct XIniSection{
  const char *name;
  int first_entry;
}XIniSection;
Struct

XIniEntry

Ini Entry

typedef struct XIniEntry{
  int section;
  const char *key;
  const char *value;
}XIniEntry;
Struct

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.