
A cross-platform library that provides a simple API to read and write INI-style configuration files. It supports data files in ASCII, MBCS and Unicode. It is designed explicitly to be portable to any platform and has been tested on Windows, WinCE and Linux. Released as open-source and free using the MIT licence.
Full documentation
Feature Summary
- MIT Licence allows free use in all software (including GPL and commercial)
- multi-platform: Windows (from 95 to 11, CE), Linux, MacOS
- loading and saving of INI-style configuration files
- configuration files can have any newline format on all platforms
- liberal acceptance of file format
- key/values with no section, keys with no value
- removal of whitespace around sections, keys and values
- support for multi-line values (values with embedded newline characters)
- optional support for multiple keys with the same name
- optional case-insensitive sections and keys (for ASCII characters only)
- saves files with sections and keys in the same order as they were loaded
- preserves comments on the file, section and keys where possible
- supports both char or wchar_t programming interfaces
- supports both MBCS (system locale) and UTF-8 file encodings
- supports ICU as conversion library on all platforms
- system locale does not need to be UTF-8 on Linux/Unix to load UTF-8 file
- support for non-ASCII characters in section, keys, values and comments
- support for non-standard character types or file encodings via user-written converter classes
- support for adding/modifying values programmatically
- should compile with no warnings in most compilers
Documentation
Full documentation of the interface is available in doxygen format. See latest documentation here.
Installation
SimpleIni is a header-only library. No building is required to use it in your project.
Simply include SimpleIni.h in your source files:
That's it! The library is ready to use.
Build and Test
While the library itself doesn't require building, you can build and run the test suite using CMake. A top-level Makefile wraps the usual CMake workflow for local development:
make help # list targets
make check # format-check, build, and test
make format # apply clang-format
make format-check # verify formatting
make test # run ctest
make clean # remove build/
Requires cmake, a C++17 compiler, and clang-format for format targets. Test builds use -Werror. CMake remains the build system.
CI (.github/workflows/build-and-test.yml) runs make format-check on Linux only; tests run on Linux (x64 and arm64), Windows, macOS, and FreeBSD (14.4 via a VM on ubuntu-latest, currently disabled).
Direct CMake usage:
# Configure the project
cmake -S . -B build
# Build the tests (optional)
cmake --build build
# To build without tests
cmake -S . -B build -DBUILD_TESTING=OFF
cmake --build build
# Run all tests
cd build
ctest --verbose
CMake Integration
To use SimpleIni in your CMake project:
# Add SimpleIni as a subdirectory
add_subdirectory(simpleini)
# Link against your target
target_link_libraries(your_target PRIVATE SimpleIni::SimpleIni)
Or install it system-wide:
cmake -S . -B build
cmake --build build
sudo cmake --install build
Then in your CMake project:
find_package(SimpleIni REQUIRED)
target_link_libraries(your_target PRIVATE SimpleIni::SimpleIni)
Note that SI_CONVERT_GENERIC is not the default conversion mode. When enabled, UTF-8 conversion is built into the header; no additional source files are required.
Migration from ConvertUTF
Earlier releases shipped ConvertUTF.c and ConvertUTF.h for SI_CONVERT_GENERIC and expected you to compile them into your project. UTF-8 conversion is now inline in SimpleIni.h. Remove any ConvertUTF.c / ConvertUTF.h from your build and drop links to ConvertUTF.c; no replacement source files are required.
Examples
These snippets are included with the distribution in the automatic tests as ts-snippets.cpp.
SIMPLE USAGE
CSimpleIniA ini;
SI_Error rc = ini.
LoadFile(
"example.ini");
if (rc < 0) { };
ASSERT_EQ(rc, SI_OK);
const char* pv;
pv = ini.
GetValue(
"section",
"key",
"default");
ASSERT_STREQ(pv, "value");
ini.
SetValue(
"section",
"key",
"newvalue");
pv = ini.
GetValue(
"section",
"key",
"default");
ASSERT_STREQ(pv, "newvalue");
const SI_CHAR * GetValue(const SI_CHAR *a_pSection, const SI_CHAR *a_pKey, const SI_CHAR *a_pDefault=NULL, bool *a_pHasMultiple=NULL) const
Definition SimpleIni.h:2242
SI_Error SetValue(const SI_CHAR *a_pSection, const SI_CHAR *a_pKey, const SI_CHAR *a_pValue, const SI_CHAR *a_pComment=NULL, bool a_bForceReplace=false)
Definition SimpleIni.h:978
void SetUnicode(bool a_bIsUtf8=true)
Definition SimpleIni.h:515
SI_Error LoadFile(const char *a_pszFile)
Definition SimpleIni.h:1398
LOADING DATA
CSimpleIniA ini;
SI_Error rc = ini.
LoadFile(
"example.ini");
if (rc < 0) { };
ASSERT_EQ(rc, SI_OK);
const std::string example = "[section]\nkey = value\n";
CSimpleIniA ini;
if (rc < 0) { };
ASSERT_EQ(rc, SI_OK);
SI_Error LoadData(const std::string &a_strData)
Definition SimpleIni.h:652
GETTING SECTIONS AND KEYS
bool GetAllKeys(const SI_CHAR *a_pSection, TNamesDepend &a_names) const
Definition SimpleIni.h:2547
std::list< Entry > TNamesDepend
Definition SimpleIni.h:388
void GetAllSections(TNamesDepend &a_names) const
Definition SimpleIni.h:2537
GETTING VALUES
const char* pv;
ASSERT_EQ(pv, nullptr);
ASSERT_STREQ(pv, "value1");
bool hasMulti;
pv = ini.
GetValue(
"section1",
"key1",
nullptr, &hasMulti);
ASSERT_STREQ(pv, "value1");
ASSERT_EQ(hasMulti, false);
pv = ini.
GetValue(
"section1",
"key2",
nullptr, &hasMulti);
ASSERT_STREQ(pv, "value2.1");
ASSERT_EQ(hasMulti, true);
values.sort(CSimpleIniA::Entry::LoadOrder());
CSimpleIniA::TNamesDepend::const_iterator it;
for (it = values.begin(); it != values.end(); ++it) {
printf("value = '%s'\n", it->pItem);
}
bool GetAllValues(const SI_CHAR *a_pSection, const SI_CHAR *a_pKey, TNamesDepend &a_values) const
Definition SimpleIni.h:2458
MODIFYING DATA
rc = ini.
SetValue(
"section1",
nullptr,
nullptr);
if (rc < 0) { };
ASSERT_EQ(rc, SI_INSERTED);
rc = ini.
SetValue(
"section1",
nullptr,
nullptr);
if (rc < 0) { };
ASSERT_EQ(rc, SI_UPDATED);
const char* pv;
pv = ini.
GetValue(
"section2",
"key1",
"default-value");
ASSERT_STREQ(pv, "default-value");
rc = ini.
SetValue(
"section2",
"key1",
"value1");
if (rc < 0) { };
ASSERT_EQ(rc, SI_INSERTED);
pv = ini.
GetValue(
"section2",
"key1",
nullptr);
ASSERT_STREQ(pv, "value1");
rc = ini.
SetValue(
"section2",
"key1",
"value2");
if (rc < 0) { };
ASSERT_EQ(rc, SI_UPDATED);
pv = ini.
GetValue(
"section2",
"key1",
nullptr);
ASSERT_STREQ(pv, "value2");
DELETING DATA
bool done, deleteSectionIfEmpty = true;
done = ini.
Delete(
"section1",
"key1", deleteSectionIfEmpty);
ASSERT_EQ(done, true);
done = ini.
Delete(
"section1",
"key1");
ASSERT_EQ(done, false);
done = ini.
Delete(
"section2",
nullptr);
ASSERT_EQ(done, true);
done = ini.
Delete(
"section2",
nullptr);
ASSERT_EQ(done, false);
bool Delete(const SI_CHAR *a_pSection, const SI_CHAR *a_pKey, bool a_bRemoveEmpty=false)
Definition SimpleIni.h:2824
SAVING DATA
std::string data;
if (rc < 0) { };
ASSERT_EQ(rc, SI_OK);
if (rc < 0) { };
ASSERT_EQ(rc, SI_OK);
SI_Error Save(OutputWriter &a_oOutput, bool a_bAddSignature=false) const
Definition SimpleIni.h:2626
SI_Error SaveFile(const char *a_pszFile, bool a_bAddSignature=true) const
Definition SimpleIni.h:2574