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. Released as open-source and free using the MIT licence.

Documentation

Full documentation of the interface is available in either online documentation or as a separate download.

Downloads

The current version of SimpleIni is 4.8.1 (last updated: 18 Jun 2008)

Download simpleini-4.8.1.zip (about 45Kb)
Download Doxygen documentation (about 120Kb)
Download Textpad INI file format syntax file (about 1Kb)

Source Repository

Full source code, demo and test programs are included in the download. The homepage of the project is here, however the source repository is stored at google code.

Release Notes

Note that release 4.x breaks iterators of TNamesDepend in existing projects. Where before you would get the string of the section, key or value by derefering the iterator (i.e. pszValue = *i) you now need to dereference the pItem member of the structure (i.e. pszValue = i->pItem).

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.

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;

Change History

4.8.1 (18 Jun 2008)
Fix warning when building with gcc 4.3.1 by adding cstring header include

4.8 (4 Jun 2008)
Fixed invalid read reported by valgrind. This occurs when using SI_CONVERT_GENERIC and a UTF-8 file. Thanks to Michael Unterkalmsteiner for his contribution.

4.7 (25 Apr 2008)
Added utility accessor functions: Get/SetBoolValue, Get/SetLongValue. Thanks to Trane Commercial Systems for their contribution.

4.6 (24 Apr 2008)
Minor update. Don't use secure functions in Windows CE.

4.5 (29 Feb 2008)
Minor update. Save and restore the warning levels when building with Visual Studio. Correctly handle 0-length files and data.

4.3 (1 Jul 2007)
Fixed a bug causing multi-line values and comments to get corrupted. This affects only files with CR LF line endings (Windows) and wchar_t/ICU interface (Unicode).

4.2 (24 Jan 2007)
Fix compilation breakages on gcc. Changed comments to get same newline handling like multi-line entries.

4.1 (24 Jan 2007)
Fix compilation breakages on gcc. Changed multi-line entries so that regardless of platform the in memory value has lines separated by a single \n character and on save they are delimited by the platform newline characters. Added option to output the UTF-8 file signature to all Save and SaveFile methods.

4.0.1 (21 Jan 2007)
Minor update to fix compilation breakages on gcc and Visual Studio 2005.

4.0 (21 Jan 2007)
Saves data in the same order as it was loaded or created programmatically. Preserves and saves comments. Fix iostreams in VC6. Fix bugs with saving multi-line values.

3.0 (19 Jan 2007)
Fix compile errors in iostreams. Add iostream demo to the test program. Fix a bug in saving when multi-line values are enabled.

2.9 (11 Jan 2007)
Support for reading and writing data from iostreams (thanks to Ralph Moritz). Support for saving to a file specifying just the name (thanks to Laurent CHASTEL).

2.8 (26 Aug 2006)
Re-released under the MIT Licence to simplify licence issues. Added support for multi-line values.

2.7 (27 July 2006)
Added support for conversions using ICU. Added support for reading and writing INI files with a UTF-8 BOM. Fixed bug in GetSectionSize() when multiple keys are enabled. Changed API so that errno is no longer used, all errors are defined as local enums.

2.5 (19 June 2006)
Fixed EVC4 build. Added ability to optionally support multiple keys with the same name (multiple values for the same key).

2.4 (17 June 2006)
Added SI_NO_ERRNO and SI_NO_MBCS definitions. Automatically set them for Windows CE builds to try and make the library compatible with EVC4 and Pocket PC.

2.3 (10 June 2006)
Added CSimpleIniCase definitions. Can call LoadFile() multiple times to combine multiple INI data sets. Changed call signature of LoadFile(): the Unicode status is set prior to loading any data using either the CSimpleIni constructor, or the method SetUnicode().

2.2 (27 May 2006)
Added Delete() to remove keys and sections. Added Save() and SaveString() to write the data to any output device. Added GetConverter() to provide general purpose method of getting storage format text.

2.1 (23 May 2006)
Fix compile error when using gcc 4.

2.0 (3 May 2006)
Fix code which allowed possibility of memory leak while saving. Save sections, keys and values with no limit on string length.

1.9 (29 April 2006)
(Fix a compiler error when using VC6

Stats
Powered by Website Baker