SimpleIni

SimpleIni Documentation

Library SimpleIni
File SimpleIni.h
Author Brodie Thiesfield [code at jellycan dot com]
Source http://code.jellycan.com/simpleini/
Version 4.15

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

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. 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_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.
  3. Call LoadData() or LoadFile() to load and parse the INI configuration file
  4. 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
  5. 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.

        key = <<<ENDTAG
        .... multiline value ....
        ENDTAG
        

Note the following:

COMMENTS

Comments are preserved in the file within the following restrictions:

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

CONTRIBUTIONS

MIT LICENCE

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

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