C++ Utilities: CppUtilities::AdvancedIniFile Class Reference

C++ Utilities 5.34.1 Useful C++ classes and routines such as argument parser, IO and conversion utilities

Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Public Attributes | List of all members
CppUtilities::AdvancedIniFile Class Reference

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

`#include <inifile.h>`

Collaboration diagram for CppUtilities::AdvancedIniFile:
[legend]

## 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 410 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 215 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