CppUtilities::AdvancedIniFile Class Reference

The AdvancedIniFile class allows parsing and writing INI files. More...

#include <inifile.h>

Collaboration diagram for CppUtilities::AdvancedIniFile:

Classes
class	Field
	The AdvancedIniFile::Field class represents a field within an INI file. More...
class	Section
	The AdvancedIniFile::Section class represents a section within an INI file. More...

Public Types
using	FieldList = std::vector<Field>
using	SectionList = std::vector<Section>

Public Member Functions
SectionList::iterator	findSection (std::string_view sectionName)
	Returns an iterator to the first section with the name sectionName.
SectionList::const_iterator	findSection (std::string_view sectionName) const
	Returns an iterator to the first section with the name sectionName.
SectionList::iterator	findSection (SectionList::iterator after, std::string_view sectionName)
	Returns an iterator to the first section with the name sectionName which comes after after.
SectionList::const_iterator	findSection (SectionList::iterator after, std::string_view sectionName) const
	Returns an iterator to the first section with the name sectionName which comes after after.
SectionList::iterator	sectionEnd ()
	Returns an iterator that points one past the last section.
SectionList::const_iterator	sectionEnd () const
	Returns an iterator that points one past the last section.
std::optional< FieldList::iterator >	findField (std::string_view sectionName, std::string_view key)
	Returns an iterator to the first field within the first section with matching sectionName and key.
std::optional< FieldList::const_iterator >	findField (std::string_view sectionName, std::string_view key) const
	Returns an iterator to the first field within the first section with matching sectionName and key.
void	parse (std::istream &inputStream, IniFileParseOptions options=IniFileParseOptions::None)
	Parses all data from the specified inputStream.
void	make (std::ostream &outputStream, IniFileMakeOptions options=IniFileMakeOptions::None)
	Write the current data to the specified outputStream.

Public Attributes
SectionList	sections

Detailed Description

The AdvancedIniFile class allows parsing and writing INI files.

In contrast to IniFile this class preserves

• the difference between absence of an equal sign and an empty value after equal sign.
• the order of the fields within a section.
• alignment of equal signs via extra spaces between key and equal sign.
• comments.

In the following description the word "element" is used to refer to a section or a field.

The parsed data or data to be written is directly exposed via the "sections" member variable of this class. There are also convenience functions to find a particular element.

Since the preceding comment of an element usually belongs to it each element has a "precedingCommentBlock" member variable. If a file ends with a comment an implicit section is added at the end which contains that comment as "precedingCommentBlock". Comments are not stripped from newline and '#' characters. When altering/adding comments be sure to use newline and '#' characters as needed.

Comments appearing in the same line as an element are stored using the "followingInlineComment" member variable.

Remarks

The AdvancedIniFile class is still experimental. It might be modified in an incompatible way or even removed in the next minor or patch release.

Todo

Support "line continuation", where a backslash followed immediately by EOL (end-of-line) causes the line break to be ignored, and the "logical line" to be continued on the next actual line from the INI file.

Definition at line 79 of file inifile.h.

Member Typedef Documentation

FieldList

using CppUtilities::AdvancedIniFile::FieldList = std::vector<Field>

Definition at line 88 of file inifile.h.

SectionList

using CppUtilities::AdvancedIniFile::SectionList = std::vector<Section>

Definition at line 103 of file inifile.h.

Member Function Documentation

findField() [1/2]

std::optional< AdvancedIniFile::FieldList::iterator > CppUtilities::AdvancedIniFile::findField ( std::string_view sectionName, std::string_view key )

inline

Returns an iterator to the first field within the first section with matching sectionName and key.

Definition at line 170 of file inifile.h.

findField() [2/2]

std::optional< AdvancedIniFile::FieldList::const_iterator > CppUtilities::AdvancedIniFile::findField ( std::string_view sectionName, std::string_view key ) const

inline

Returns an iterator to the first field within the first section with matching sectionName and key.

Definition at line 186 of file inifile.h.

findSection() [1/4]

AdvancedIniFile::SectionList::iterator CppUtilities::AdvancedIniFile::findSection ( SectionList::iterator after, std::string_view sectionName )

inline

Returns an iterator to the first section with the name sectionName which comes after after.

Definition at line 138 of file inifile.h.

findSection() [2/4]

AdvancedIniFile::SectionList::const_iterator CppUtilities::AdvancedIniFile::findSection ( SectionList::iterator after, std::string_view sectionName ) const

inline

Returns an iterator to the first section with the name sectionName which comes after after.

Definition at line 146 of file inifile.h.

findSection() [3/4]

AdvancedIniFile::SectionList::iterator CppUtilities::AdvancedIniFile::findSection ( std::string_view sectionName )

inline

Returns an iterator to the first section with the name sectionName.

Definition at line 122 of file inifile.h.

findSection() [4/4]

AdvancedIniFile::SectionList::const_iterator CppUtilities::AdvancedIniFile::findSection ( std::string_view sectionName ) const

inline

Returns an iterator to the first section with the name sectionName.

Definition at line 130 of file inifile.h.

make()

void CppUtilities::AdvancedIniFile::make	(	std::ostream &	outputStream,
		IniFileMakeOptions	options = IniFileMakeOptions::None )

Write the current data to the specified outputStream.

Exceptions

Throws

an std::ios_base::failure when an IO error occurs.

Remarks

Might write garbage if comments do not contain newline and '#' characters as needed. So far there is no option to insert these characters automatically as needed.

Definition at line 412 of file inifile.cpp.

parse()

void CppUtilities::AdvancedIniFile::parse	(	std::istream &	inputStream,
		IniFileParseOptions	options = IniFileParseOptions::None )

Parses all data from the specified inputStream.

Remarks

Does not strip newline and '#' characters from comments. So far there is no option (or separate function) to help with that.

Exceptions

Throws

an std::ios_base::failure when an IO error (other than end-of-file) occurs.

Definition at line 217 of file inifile.cpp.

sectionEnd() [1/2]

AdvancedIniFile::SectionList::iterator CppUtilities::AdvancedIniFile::sectionEnd ( )

inline

Returns an iterator that points one past the last section.

Definition at line 154 of file inifile.h.

sectionEnd() [2/2]

AdvancedIniFile::SectionList::const_iterator CppUtilities::AdvancedIniFile::sectionEnd ( ) const

inline

Returns an iterator that points one past the last section.

Definition at line 162 of file inifile.h.

Member Data Documentation

sections

SectionList CppUtilities::AdvancedIniFile::sections

Definition at line 116 of file inifile.h.

---

The documentation for this class was generated from the following files:

• io/inifile.h
• io/inifile.cpp