Classes | Macros | Typedefs | Enumerations
SimpleIni.h File Reference
#include <cstring>
#include <string>
#include <map>
#include <list>
#include <algorithm>
#include <stdio.h>
#include <wchar.h>
#include "ConvertUTF.h"
Include dependency graph for SimpleIni.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

class  CSimpleIniTempl< SI_CHAR, SI_STRLESS, SI_CONVERTER >::Converter
 
class  CSimpleIniTempl< SI_CHAR, SI_STRLESS, SI_CONVERTER >
 
struct  CSimpleIniTempl< SI_CHAR, SI_STRLESS, SI_CONVERTER >::Entry
 
class  CSimpleIniTempl< SI_CHAR, SI_STRLESS, SI_CONVERTER >::FileWriter
 
struct  CSimpleIniTempl< SI_CHAR, SI_STRLESS, SI_CONVERTER >::Entry::KeyOrder
 
struct  CSimpleIniTempl< SI_CHAR, SI_STRLESS, SI_CONVERTER >::Entry::LoadOrder
 
class  CSimpleIniTempl< SI_CHAR, SI_STRLESS, SI_CONVERTER >::OutputWriter
 
class  SI_ConvertA< SI_CHAR >
 
class  SI_ConvertW< SI_CHAR >
 
struct  SI_GenericCase< SI_CHAR >
 
struct  SI_GenericNoCase< SI_CHAR >
 
class  CSimpleIniTempl< SI_CHAR, SI_STRLESS, SI_CONVERTER >::StringWriter
 

Macros

#define CSimpleIni   CSimpleIniA
 
#define CSimpleIniCase   CSimpleIniCaseA
 
#define SI_ASSERT(x)
 
#define SI_Case   SI_GenericCase
 
#define SI_CONVERT_GENERIC
 
#define SI_NEWLINE   SI_NEWLINE_A
 
#define SI_NEWLINE_A   "\n"
 
#define SI_NEWLINE_W   L"\n"
 
#define SI_NoCase   SI_GenericNoCase
 
#define SI_UTF8_SIGNATURE   "\xEF\xBB\xBF"
 

Typedefs

typedef CSimpleIniTempl< char, SI_NoCase< char >, SI_ConvertA< char > > CSimpleIniA
 
typedef CSimpleIniTempl< char, SI_Case< char >, SI_ConvertA< char > > CSimpleIniCaseA
 
typedef CSimpleIniTempl< wchar_t, SI_Case< wchar_t >, SI_ConvertW< wchar_t > > CSimpleIniCaseW
 
typedef CSimpleIniTempl< wchar_t, SI_NoCase< wchar_t >, SI_ConvertW< wchar_t > > CSimpleIniW
 

Enumerations

enum  SI_Error {
  SI_OK = 0, SI_UPDATED = 1, SI_INSERTED = 2, SI_FAIL = -1,
  SI_NOMEM = -2, SI_FILE = -3
}
 

Macro Definition Documentation

◆ CSimpleIni

#define CSimpleIni   CSimpleIniA

Definition at line 3366 of file SimpleIni.h.

◆ CSimpleIniCase

#define CSimpleIniCase   CSimpleIniCaseA

Definition at line 3367 of file SimpleIni.h.

◆ SI_ASSERT

#define SI_ASSERT (   x)
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

  • 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)

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. 

<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.

CONTRIBUTIONS

  • 2010/05/03: Tobias Gehrig: added GetDoubleValue()

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.

Definition at line 232 of file SimpleIni.h.

◆ SI_Case

#define SI_Case   SI_GenericCase

Definition at line 2789 of file SimpleIni.h.

◆ SI_CONVERT_GENERIC

#define SI_CONVERT_GENERIC

Definition at line 2621 of file SimpleIni.h.

◆ SI_NEWLINE

#define SI_NEWLINE   SI_NEWLINE_A

Definition at line 3368 of file SimpleIni.h.

◆ SI_NEWLINE_A

#define SI_NEWLINE_A   "\n"

Definition at line 252 of file SimpleIni.h.

◆ SI_NEWLINE_W

#define SI_NEWLINE_W   L"\n"

Definition at line 253 of file SimpleIni.h.

◆ SI_NoCase

#define SI_NoCase   SI_GenericNoCase

Definition at line 2790 of file SimpleIni.h.

◆ SI_UTF8_SIGNATURE

#define SI_UTF8_SIGNATURE   "\xEF\xBB\xBF"

Definition at line 246 of file SimpleIni.h.

Typedef Documentation

◆ CSimpleIniA

typedef CSimpleIniTempl<char, SI_NoCase<char>,SI_ConvertA<char> > CSimpleIniA

Definition at line 3345 of file SimpleIni.h.

◆ CSimpleIniCaseA

typedef CSimpleIniTempl<char, SI_Case<char>,SI_ConvertA<char> > CSimpleIniCaseA

Definition at line 3347 of file SimpleIni.h.

◆ CSimpleIniCaseW

typedef CSimpleIniTempl<wchar_t, SI_Case<wchar_t>,SI_ConvertW<wchar_t> > CSimpleIniCaseW

Definition at line 3358 of file SimpleIni.h.

◆ CSimpleIniW

typedef CSimpleIniTempl<wchar_t, SI_NoCase<wchar_t>,SI_ConvertW<wchar_t> > CSimpleIniW

Definition at line 3356 of file SimpleIni.h.

Enumeration Type Documentation

◆ SI_Error

enum SI_Error
Enumerator
SI_OK 

No error.

SI_UPDATED 

An existing value was updated.

SI_INSERTED 

A new value was inserted.

SI_FAIL 

Generic failure.

SI_NOMEM 

Out of memory error.

SI_FILE 

File error (see errno for detail error)

Definition at line 235 of file SimpleIni.h.


rtabmap
Author(s): Mathieu Labbe
autogenerated on Thu Jul 25 2024 02:50:25