SimpleIni
SimpleIni Documentation
Library SimpleIni
File SimpleIni.h
Author Brodie Thiesfield
Source https://github.com/brofield/simpleini
Version 4.22

Jump to the CSimpleIni interface documentation.

INTRODUCTION

This component allows an INI-style configuration file to be used on both Windows and Linux/Unix. It is fast, simple and source code using this component will compile unchanged on either OS.

FEATURES

  • MIT Licence allows free use in all software (including GPL and commercial)
  • multi-platform (Windows CE/9x/NT..10/etc, Linux, MacOSX, 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
  • should compile cleanly without warning usually at the strictest warning level
  • it has been tested with the following compilers:
    • Windows/VC6 (warning level 3)
    • Windows/VC.NET 2003 (warning level 4)
    • Windows/VC 2005 (warning level 4)
    • Windows/VC 2019 (warning level 4)
    • Linux/gcc (-Wall)
    • Mac OS/c++ (-Wall)

USAGE SUMMARY

  1. Decide if you will be using utf8 or MBCS files, and working with the data in utf8, wchar_t or ICU chars.
  2. If you will only be using straight utf8 files and access the data via the char interface, then you do not need any conversion library and could define SI_NO_CONVERSION. Note that no conversion also means no validation of the data. If no converter is specified then the default converter is SI_NO_CONVERSION on Mac/Linux and SI_CONVERT_WIN32 on Windows. If you need widechar support on Mac/Linux then use either SI_CONVERT_GENERIC or SI_CONVERT_ICU. These are also supported on all platforms.
  3. Define the appropriate symbol for the converter you wish to use and include the SimpleIni.h header file.
  4. Declare an instance of the appropriate class. Note that the following definitions are just shortcuts for commonly used types. Other types (PRUnichar, unsigned short, unsigned char) are also possible.
    Interface Case-sensitive Load UTF-8 Load MBCS Typedef
    SI_NO_CONVERSION
    char No Yes No CSimpleIniA
    char Yes Yes No CSimpleIniCaseA
    SI_CONVERT_GENERIC
    char No Yes Yes #1 CSimpleIniA
    char Yes Yes Yes CSimpleIniCaseA
    wchar_t No Yes Yes CSimpleIniW
    wchar_t Yes Yes Yes CSimpleIniCaseW
    SI_CONVERT_WIN32
    char No No #2 Yes CSimpleIniA
    char Yes Yes Yes CSimpleIniCaseA
    wchar_t No Yes Yes CSimpleIniW
    wchar_t Yes Yes Yes CSimpleIniCaseW
    SI_CONVERT_ICU
    char No Yes Yes CSimpleIniA
    char Yes Yes Yes CSimpleIniCaseA
    UChar No Yes Yes CSimpleIniW
    UChar Yes Yes Yes CSimpleIniCaseW
    #1 On Windows you are better to use CSimpleIniA with SI_CONVERT_WIN32.
    #2 Only affects Windows. On Windows this uses MBCS functions and so may fold case incorrectly leading to uncertain results.
  5. Set all the options that you require, see all the Set*() options below. The SetUnicode() option is very common and can be specified in the constructor.
  6. Call LoadData() or LoadFile() to load and parse the INI configuration file
  7. Access and modify the data of the file using the following functions
    GetAllSections Return all section names
    GetAllKeys Return all key names within a section
    GetAllValues Return all values within a section & key
    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
    SetValue Add or update a value for a section & key
    Delete Remove a section, or a key from a section
    SectionExists Does a section exist?
    KeyExists Does a key exist?
  8. Call Save() or SaveFile() to save the INI configuration data

IO STREAMS

SimpleIni supports reading from and writing to STL IO streams. Enable this by defining SI_SUPPORT_IOSTREAMS before including the SimpleIni.h header file. Ensure that if the streams are backed by a file (e.g. ifstream or ofstream) then the flag ios_base::binary has been used when the file was opened.

MULTI-LINE VALUES

Values that span multiple lines are created using the following format. 

<pre>
key = <<<ENDTAG
.... multiline value ....
ENDTAG
</pre>

Note the following:

  • The text used for ENDTAG can be anything and is used to find where the multi-line text ends.
  • The newline after ENDTAG in the start tag, and the newline before ENDTAG in the end tag is not included in the data value.
  • The ending tag must be on it's own line with no whitespace before or after it.
  • The multi-line value is modified at load so that each line in the value is delimited by a single '\n' character on all platforms. At save time it will be converted into the newline format used by the current platform.

COMMENTS

Comments are preserved in the file within the following restrictions:

  • Every file may have a single "file comment". It must start with the first character in the file, and will end with the first non-comment line in the file.
  • Every section may have a single "section comment". It will start with the first comment line following the file comment, or the last data entry. It ends at the beginning of the section.
  • Every key may have a single "key comment". This comment will start with the first comment line following the section start, or the file comment if there is no section name.
  • Comments are set at the time that the file, section or key is first created. The only way to modify a comment on a section or a key is to delete that entry and recreate it with the new comment. There is no way to change the file comment.

SAVE ORDER

The sections and keys are written out in the same order as they were read in from the file. Sections and keys added to the data after the file has been loaded will be added to the end of the file when it is written. There is no way to specify the location of a section or key other than in first-created, first-saved order.

NOTES

  • To load UTF-8 data on Windows 95, you need to use Microsoft Layer for Unicode, or SI_CONVERT_GENERIC, or SI_CONVERT_ICU.
  • When using SI_CONVERT_GENERIC, ConvertUTF.c must be compiled and linked.
  • When using SI_CONVERT_ICU, ICU header files must be on the include path and icuuc.lib must be linked in.
  • To load a UTF-8 file on Windows AND expose it with SI_CHAR == char, you should use SI_CONVERT_GENERIC.
  • The collation (sorting) order used for sections and keys returned from iterators is NOT DEFINED. If collation order of the text is important then it should be done yourself by either supplying a replacement SI_STRLESS class, or by sorting the strings external to this library.
  • Usage of the <mbstring.h> header on Windows can be disabled by defining SI_NO_MBCS. This is defined automatically on Windows CE platforms.
  • Not thread-safe so manage your own locking

CONTRIBUTIONS

Many thanks to the following contributors:

  • 2010/05/03: Tobias Gehrig: added GetDoubleValue()
  • See list of many contributors in github

MIT LICENCE

The licence text below is the boilerplate "MIT Licence" used from: http://www.opensource.org/licenses/mit-license.php

Copyright (c) 2006-2024, 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.

Generated by doxygen 1.9.1