Cross-platform INI Configuration Files (Win32/Un*x, MBCS/Unicode)

• Download source files
• Download source files (latest updates)
• Download HTML documentation (or view it online)

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 and Linux. It has been released as open-source and free using the MIT licence.

Features

• MIT Licence allows free use in all software (including GPL and commercial)
• Multi-platform (Windows 95*/98/ME/NT/2K/XP/2003, Windows CE, Linux, Unix)
• Loading and saving of INI-style configuration files
• Liberal acceptance of file format
  • Key/values with no section
  • Removal of whitespace around sections, keys and values
  • Configuration files can have any newline format on all platforms
• Optional support for multi-line values (values with embedded newline characters)
• Optional support for multiple keys with the same name (keys with multiple values)
• 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
• 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
• Compiles cleanly at warning level 4 (Windows/VC.NET 2003), warning level 3 (Windows/VC6) and -Wall (Linux/gcc)

Download

Get the latest information and the latest version from the homepage here. 

Usage Summary

1. Define the appropriate symbol for the converter you wish to use and include the SimpleIni.h header file. If no specific converter is defined, then the default converter is used. The default conversion mode uses SI_CONVERT_WIN32 on Windows and SI_CONVERT_GENERIC on all other platforms. If you are using ICU then SI_CONVERT_ICU is supported on all platforms.
2. Declare an instance the appropriate class, e.g. CSimpleIni for TCHAR, CSimpleIniA for char, CSimpleIniW for wchar_t. Other types (e.g. unsigned short, unsigned char) are also possible.
3. Call LoadFile() to load and parse the INI configuration file
4. Access the data of the file using the following functions:
   

   GetAllSections	Return all section names
   GetAllKeys	Return all key names for a section
   GetSection	Return all key names and values in a section
   GetSectionSize	Return the number of keys in a section
   GetValue	Return a value for a section & key
   GetAllValues	Return all values for a section & key
   SetValue	Add or update a value for a section & key
   Delete	Remove a section, or a key from a section

5. Call Save() or SaveFile() to save the INI configuration data (as necessary).

Examples

These snippets are included with the distribution in the file snippets.cpp.

LOADING DATA

Load from a data file:

CSimpleIniA ini(a_bIsUtf8, a_bUseMultiKey, a_bUseMultiLine);
SI_Error rc = ini.LoadFile(a_pszFile);
if (rc < 0) return false;

Load from a string:

std::string strData;
rc = ini.Load(strData.c_str(), strData.size());
if (rc < 0) return false;

GETTING SECTIONS AND KEYS

Get all sections:

CSimpleIniA::TNamesDepend sections;
ini.GetAllSections(sections);

Get all keys in a section:

CSimpleIniA::TNamesDepend keys;
ini.GetAllKeys("section-name", keys);

GETTING VALUES

Get the value of a key:

const char * pszValue = ini.GetValue("section-name", 
    "key-name", NULL /*default*/);

Get the value of a key which may have multiple values. If bHasMultipleValues is true, then just one value has been returned.

bool bHasMultipleValues;
pszValue = ini.GetValue("section-name", "key-name", 
    NULL /*default*/, &bHasMultipleValues);

Get all values of a key with multiple values:

CSimpleIniA::TNamesDepend values;
ini.GetAllValues("section-name", "key-name", values);

Sort the values into the original load order:

values.sort(CSimpleIniA::Entry::LoadOrder());

Output all of the items:

CSimpleIniA::TNamesDepend::const_iterator i;
for (i = values.begin();; i != values.end(); ++i) { 
    printf("key-name = '%s'\n", i->pItem);
}

MODIFYING DATA

Adding a new section:

rc = ini.SetValue("new-section", NULL, NULL);
if (rc < 0) return false;
printf("section: %s\n", rc == SI_INSERTED ? 
    "inserted" : "updated");

Adding a new key ("new-section" will be added automatically if it doesn't already exist):

rc = ini.SetValue("new-section", "new-key", "value");
if (rc < 0) return false;
printf("key: %s\n", rc == SI_INSERTED ? 
    "inserted" : "updated");

Changing the value of a key:

rc = ini.SetValue("section", "key", "updated-value");
if (rc < 0) return false;
printf("key: %s\n", rc == SI_INSERTED ? 
    "inserted" : "updated");

DELETING DATA

Deleting a key from a section. Optionally the entire section may be deleted if it is now empty:

bool bDeleteSectionIfEmpty = false;
ini.Delete("section-name", "key-name", 
    true /*delete the section if empty*/);

Deleting an entire section and all keys in it:

ini.Delete("section-name", NULL);

SAVING DATA

Save the data to a string:

rc = ini.Save(strData);
if (rc < 0) return false;

Save the data back to the file:

rc = ini.SaveFile(a_pszFile);
if (rc < 0) return false;

MIT Licence

The licence text below is the boilerplate "MIT Licence" used from here.

Copyright (c) 2006, Brodie Thiesfield

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.