Click here to Skip to main content
Click here to Skip to main content

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

, 27 Feb 2012
Rate this:
Please Sign up or sign in to vote.
Simple reading, accessing and writing of INI configuration files on Windows/Linux/Unix using a cross-platform and fully Unicode/MBCS/UTF-8 aware library

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.

License

This article, along with any associated source code and files, is licensed under The MIT License

Share

About the Author

brofield
Web Developer
Australia Australia
Must eat, enjoy travel, thus programming since 1995. Donations of canned food gladly accepted.

Comments and Discussions

 
GeneralNon-ASCII characters PinmemberJeff Dunlap10-Jul-09 9:20 
GeneralRe: Non-ASCII characters Pinmemberbrofield11-Jul-09 1:05 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web04 | 2.8.140827.1 | Last Updated 27 Feb 2012
Article Copyright 2006 by brofield
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid