template class mrpt::config::simpleini::CSimpleIniTempl

Simple INI file reader.

This can be instantiated with the choice of unicode or native characterset, and case sensitive or insensitive comparisons of section and key names. The supported combinations are pre-defined with the following typedefs:

Interface

Case-sensitive

Typedef

char No CSimpleIniA char Yes CSimpleIniCaseA wchar_t No CSimpleIniW wchar_t Yes CSimpleIniCaseW ========= ============== ===============

Note that using other types for the SI_CHAR is supported. For instance, unsigned char, unsigned short, etc. Note that where the alternative type is a different size to char/wchar_t you may need to supply new helper classes for SI_STRLESS and SI_CONVERTER.

#include </home/jlblanco/mrpt/libs/config/src/simpleini/SimpleIni.h>

template <class SI_CHAR, class SI_STRLESS, class SI_CONVERTER>
class CSimpleIniTempl
{
public:
    // typedefs

    typedef std::multimap<Entry, const SI_CHAR*, typename Entry::KeyOrder> TKeyVal;
    typedef std::map<Entry, TKeyVal, typename Entry::KeyOrder> TSection;
    typedef std::list<Entry> TNamesDepend;

    // structs

    struct Entry;

    // classes

    class Converter;
    class FileWriter;
    class OutputWriter;
    class StreamWriter;
    class StringWriter;

    // construction

    CSimpleIniTempl(bool a_bMultiKey = false, bool a_bMultiLine = false);
    CSimpleIniTempl(const CSimpleIniTempl<SI_CHAR, SI_STRLESS, SI_CONVERTER>& o);

    //
methods

    void SetMultiKey(bool a_bAllowMultiKey = true);
    bool IsMultiKey() const;
    void SetMultiLine(bool a_bAllowMultiLine = true);
    bool IsMultiLine() const;
    CSimpleIniTempl<SI_CHAR, SI_STRLESS, SI_CONVERTER>& operator = (const CSimpleIniTempl<SI_CHAR, SI_STRLESS, SI_CONVERTER>& o);
    void Reset();
    SI_Error LoadFile(const char* a_pszFile);
    SI_Error LoadFile(FILE* a_fpFile);
    SI_Error Load(std::istream& a_istream);
    SI_Error Load(const std::string& a_strData);
    SI_Error Load(const char* a_pData, size_t a_uDataLen);
    SI_Error SaveFile(const char* a_pszFile) const;
    SI_Error SaveFile(FILE* a_pFile) const;
    SI_Error Save(OutputWriter& a_oOutput) const;
    SI_Error Save(std::ostream& a_ostream) const;
    SI_Error Save(std::string& a_sBuffer) const;
    void GetAllSections(TNamesDepend& a_names) const;
    bool GetAllKeys(const SI_CHAR* a_pSection, TNamesDepend& a_names) const;
    bool GetAllValues(const SI_CHAR* a_pSection, const SI_CHAR* a_pKey, TNamesDepend& a_values) const;
    int GetSectionSize(const SI_CHAR* a_pSection) const;
    const TKeyVal* GetSection(const SI_CHAR* a_pSection) const;

    const SI_CHAR* GetValue(
        const SI_CHAR* a_pSection,
        const SI_CHAR* a_pKey,
        const SI_CHAR* a_pDefault = nullptr,
        bool* a_pHasMultiple = nullptr
        ) const;

    SI_Error SetValue(
        const SI_CHAR* a_pSection,
        const SI_CHAR* a_pKey,
        const SI_CHAR* a_pValue,
        const SI_CHAR* a_pComment = nullptr
        );

    bool Delete(
        const SI_CHAR* a_pSection,
        const SI_CHAR* a_pKey,
        bool a_bRemoveEmpty = false
        );

    Converter GetConverter() const;
};

Typedefs

typedef std::multimap<Entry, const SI_CHAR*, typename Entry::KeyOrder> TKeyVal

map keys to values

typedef std::map<Entry, TKeyVal, typename Entry::KeyOrder> TSection

map sections to key/value map

typedef std::list<Entry> TNamesDepend

set of dependent string pointers.

Note that these pointers are dependent on memory owned by CSimpleIni.

Construction

CSimpleIniTempl(bool a_bMultiKey = false, bool a_bMultiLine = false)

Default constructor.

Parameters:

a_bMultiKey	See the method SetMultiKey() for details.
a_bMultiLine	See the method SetMultiLine() for details.

CSimpleIniTempl(const CSimpleIniTempl<SI_CHAR, SI_STRLESS, SI_CONVERTER>& o)

Copy.

Methods

void SetMultiKey(bool a_bAllowMultiKey = true)

Should multiple identical keys be permitted in the file.

If set to false then the last value encountered will be used as the value of the key. If set to true, then all values will be available to be queried. For example, with the following input:

[section]
test=value1
test=value2

Then with SetMultiKey(true), both of the values “value1” and “value2” will be returned for the key test. If SetMultiKey(false) is used, then the value for “test” will only be “value2”. This value may be changed at any time.

Parameters:

a_bAllowMultiKey

Allow multi-keys in the source?

bool IsMultiKey() const

Get the storage format of the INI data.

void SetMultiLine(bool a_bAllowMultiLine = true)

Should data values be permitted to span multiple lines in the file.

If set to false then the multi-line construct <<<TAG as a value will be returned as is instead of loading the data. This value may be changed at any time.

Parameters:

a_bAllowMultiLine

Allow multi-line values in the source?

bool IsMultiLine() const

Query the status of multi-line data.

void Reset()

Deallocate all memory stored by this object.

SI_Error LoadFile(const char* a_pszFile)

Load an INI file from disk into memory.

Parameters:

a_pszFile

Path of the file to be loaded. This will be passed to fopen() and so must be a valid path for the current platform.

Returns:

SI_Error See error definitions

SI_Error LoadFile(FILE* a_fpFile)

Load the file from a file pointer.

Parameters:

a_fpFile

Valid file pointer to read the file data from. The file will be read until end of file.

Returns:

SI_Error See error definitions

SI_Error Load(std::istream& a_istream)

Load INI file data from an istream.

Parameters:

a_istream

Stream to read from

Returns:

SI_Error See error definitions

SI_Error Load(const std::string& a_strData)

Load INI file data direct from a std::string.

Parameters:

a_strData

Data to be loaded

Returns:

SI_Error See error definitions

SI_Error Load(const char* a_pData, size_t a_uDataLen)

Load INI file data direct from memory.

Parameters:

a_pData	Data to be loaded
a_uDataLen	Length of the data in bytes

Returns:

SI_Error See error definitions

SI_Error SaveFile(const char* a_pszFile) const

Save an INI file from memory to disk.

Parameters:

a_pszFile

Path of the file to be saved. This will be passed to fopen() and so must be a valid path for the current platform.

Returns:

SI_Error See error definitions

SI_Error SaveFile(FILE* a_pFile) const

Save the INI data to a file.

See Save() for details.

Parameters:

a_pFile

Handle to a file. File should be opened for binary output.

Returns:

SI_Error See error definitions

SI_Error Save(OutputWriter& a_oOutput) const

Save the INI data.

The data will be written to the output device in a format appropriate to the current data, selected by:

SI_CHAR

FORMAT

char same format as when loaded (MBCS or UTF-8) wchar_t UTF-8 other UTF-8 ======= ==========================================

Note that comments, etc from the original data are not preserved. Only valid data contents stored in the file are written out. The order of the sections and values from the original file will be preserved.

Any data prepended or appended to the output device must use the the same format (MBCS or UTF-8). You may use the GetConverter() method to convert text to the correct format regardless of the output format being used by SimpleIni.

To add a BOM to UTF-8 data, write it out manually at the very beginning like is done in SaveFile when a_bUseBOM is true.

Parameters:

a_oOutput

Output writer to write the data to.

Returns:

SI_Error See error definitions

SI_Error Save(std::ostream& a_ostream) const

Save the INI data to an ostream.

See Save() for details.

Parameters:

a_ostream

String to have the INI data appended to.

Returns:

SI_Error See error definitions

SI_Error Save(std::string& a_sBuffer) const

Append the INI data to a string.

See Save() for details.

Parameters:

a_sBuffer

String to have the INI data appended to.

Returns:

SI_Error See error definitions

void GetAllSections(TNamesDepend& a_names) const

Retrieve all section names.

The list is returned as an STL vector of names and can be iterated or searched as necessary. Note that the collation order of the returned strings is NOT DEFINED.

NOTE! This structure contains only pointers to strings. The actual string data is stored in memory owned by CSimpleIni. Ensure that the CSimpleIni object is not destroyed or Reset() while these pointers are in use!

Parameters:

a_names

Vector that will receive all of the section names. See note above!

bool GetAllKeys(const SI_CHAR* a_pSection, TNamesDepend& a_names) const

Retrieve all unique key names in a section.

The collation order of the returned strings is NOT DEFINED. Only unique key names are returned.

NOTE! This structure contains only pointers to strings. The actual string data is stored in memory owned by CSimpleIni. Ensure that the CSimpleIni object is not destroyed or Reset() while these strings are in use!

Parameters:

a_pSection	Section to request data for
a_names	List that will receive all of the key names. See note above!

Returns:

true Section was found.

false Matching section was not found.

bool GetAllValues(const SI_CHAR* a_pSection, const SI_CHAR* a_pKey, TNamesDepend& a_values) const

Retrieve all values for a specific key.

This method can be used when multiple keys are both enabled and disabled.

NOTE! The returned values are pointers to string data stored in memory owned by CSimpleIni. Ensure that the CSimpleIni object is not destroyed or Reset while you are using this pointer!

Parameters:

a_pSection	Section to search
a_pKey	Key to search for
a_values	List to return if the key is not found

Returns:

true Key was found.

false Matching section/key was not found.

int GetSectionSize(const SI_CHAR* a_pSection) const

Query the number of keys in a specific section.

Note that if multiple keys are enabled, then this value may be different to the number of keys returned by GetAllKeys.

Parameters:

a_pSection

Section to request data for

Returns:

-1 Section does not exist in the file

>=0 Number of keys in the section

const TKeyVal* GetSection(const SI_CHAR* a_pSection) const

Retrieve all key and value pairs for a section.

The data is returned as a pointer to an STL map and can be iterated or searched as desired. Note that multiple entries for the same key may exist when multiple keys have been enabled.

NOTE! This structure contains only pointers to strings. The actual string data is stored in memory owned by CSimpleIni. Ensure that the CSimpleIni object is not destroyed or Reset() while these strings are in use!

Parameters:

a_pSection

Name of the section to return

Returns:

boolean Was a section matching the supplied name found.

const SI_CHAR* GetValue(
    const SI_CHAR* a_pSection,
    const SI_CHAR* a_pKey,
    const SI_CHAR* a_pDefault = nullptr,
    bool* a_pHasMultiple = nullptr
    ) const

Retrieve the value for a specific key.

If multiple keys are enabled (see SetMultiKey) then only the first value associated with that key will be returned, see GetAllValues for getting all values with multikey.

NOTE! The returned value is a pointer to string data stored in memory owned by CSimpleIni. Ensure that the CSimpleIni object is not destroyed or Reset while you are using this pointer!

Parameters:

a_pSection	Section to search
a_pKey	Key to search for
a_pDefault	Value to return if the key is not found
a_pHasMultiple	Optionally receive notification of if there are multiple entries for this key.

Returns:

a_pDefault Key was not found in the section

other Value of the key

SI_Error SetValue(
    const SI_CHAR* a_pSection,
    const SI_CHAR* a_pKey,
    const SI_CHAR* a_pValue,
    const SI_CHAR* a_pComment = nullptr
    )

Add or update a section or value.

This will always insert when multiple keys are enabled.

Parameters:

a_pSection	Section to add or update
a_pKey	Key to add or update. Set to nullptr to create an empty section.
a_pValue	Value to set. Set to nullptr to create an empty section.
a_pComment	Comment to be associated with the section or the key. If a_pKey is nullptr then it will be associated with the section, otherwise the key. Note that a comment may be set ONLY when the section or key is first created (i.e. when this function returns the value SI_INSERTED). If you wish to create a section with a comment then you need to create the section separately to the key. The comment string must be in full comment form already (have a comment character starting every line).

Returns:

SI_Error See error definitions

SI_UPDATED Value was updated

SI_INSERTED Value was inserted

bool Delete(
    const SI_CHAR* a_pSection,
    const SI_CHAR* a_pKey,
    bool a_bRemoveEmpty = false
    )

Delete an entire section, or a key from a section.

Note that the data returned by GetSection is invalid and must not be used after anything has been deleted from that section using this method. Note when multiple keys is enabled, this will delete all keys with that name; there is no way to selectively delete individual key/values in this situation.

Parameters:

a_pSection	Section to delete key from, or if a_pKey is nullptr, the section to remove.
a_pKey	Key to remove from the section. Set to nullptr to remove the entire section.
a_bRemoveEmpty	If the section is empty after this key has been deleted, should the empty section be removed?

Returns:

true Key or section was deleted.

false Key or section was not found.

Converter GetConverter() const

Return a conversion object to convert text to the same encoding as is used by the Save(), SaveFile() and SaveString() functions.

Use this to prepare the strings that you wish to append or prepend to the output INI data.