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
- 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. - 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. - Call
LoadFile()
to load and parse the INI configuration file - 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 |
- 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 );
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 , &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 );
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.