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.
Feature Summary
Note: see the online documentation for a more complete description of the 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
- configuration files can have any newline format on all platforms
- liberal acceptance of file format
- key/values with no section
- 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
- 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 in the following compilers:
- Windows/VC6 (warning level 3)
- Windows/VC.NET 2003 (warning level 4)
- Windows/VC 2005 (warning level 4)
- Linux/gcc (-Wall)
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.15 (last updated: 27 Feb 2012)
Download simpleini-4.15.zip (about 55Kb)
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.
Examples
These snippets are included with the distribution in the file snippets.cpp.
SIMPLE USAGE
CSimpleIniA ini;
ini.SetUnicode();
ini.LoadFile("myfile.ini");
const char * pVal = ini.GetValue("section", "key", "default");
ini.SetValue("section", "key", "newvalue");
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.LoadData(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.15 (27 Feb 2012)
- Bug fix: don't fail when using the ICU converter and empty string values
4.14 (17 Mar 2011)
- Rename the Load() method to LoadData() to avoid confusion
- Add the GetDoubleValue() and SetDoubleValue() functions
4.13 (19 Apr 2010)
- Add cast to fix build error when building with VC2010
4.12 (15 Sep 2009)
- Fix build using ConvertUTF converter on 64-bit
- remove security warnings for _fwopen when building with VC2008
4.11 (30 Jun 2009)
- remove warnings when building with Borland compiler
- remove warnings when building with VC2008
- added SetSpaces method to specify if the output file should have spaces around the equals sign or not
- added an optional parameter to all SetValue methods to allow them to replace all values of an existing multi-value item. Use of this method will retain the original comment when saving the file again.
- fix bug where newlines were not converted in multi-line comments causing output files on Windows to have a mixture of CRLF and LF only line endings.
4.9 (9 Jun 2009)
- support individual comments for each value when using multiple values. comments will be preserved when the file is saved again.
- clear the list when calling "GetAll*" functions so that the returned items are only for that call
- ensure that GetAllValues returns the comment and load order for each value
- ensure that section comments have CR LF conversion done too
4.8.2 (22 Sep 2008)
Prevent copying with private copy constructor and operator=
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.
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).
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