INIFile Class Reference
[General Purpose File Formats]

INIFile. More...

#include <INIFile.h>

List of all members.

Public Types
typedef List< Section >::Iterator	SectionIterator
typedef IteratorTraits_	LineIterator
	An iterator for the lines in an INIFile.
enum	{ MAX_LINE_LENGTH = 1048576 }
	Enum for constants. More...
Public Member Functions
bool	apply (UnaryProcessor< LineIterator > &processor)
	Apply a processor to all lines of the file.
void	setDuplicateKeyCheck (bool mode)
	Set checking for duplicate keys mode.
bool	duplicateKeyCheckEnabled () const
	Get checking mode for duplicate keys.
List< String >	getContent () const throw ()
bool	setContent (const List< String > &lines) throw ()
Constructors and Destructors
	INIFile ()
	Default constructor.
	INIFile (const String &filename)
	Constructor with filename The file is not opend.
virtual	~INIFile ()
	Destructor.
void	clear ()
	Clear the internal datastructures.
File I/O and related
bool	read ()
	Open a file and read its contents.
bool	write ()
	Writes the buffer contents to a file.
const String &	getFilename () const
	Returns the current filename.
void	setFilename (const String &filename)
	Sets a new filename.
Debugging and Diagnostics
bool	isValid () const
	Returns the current state of the instance of INIFile.
Methods for line-wise access.
The INIFile can be accessed line-wise (ignoring the section structure). Each line can be accessed via its index (starting with 0) by getLine and modified by setLine . The index has to be less than the value returned by getNumberOfLines .
LineIterator	getLine (Size line_number)
	Return the contents of the specified line.
Methods for access with an iterator.
The INIFile may be also accessed with an LineIterator.
bool	setLine (LineIterator line_it, const String &line)
	Change the contents of a line.
bool	deleteLine (LineIterator line_it)
	Delete a line.
bool	insertLine (LineIterator line_it, const String &line)
	Add a line after a given iterator.
Methods for access per section.
bool	appendLine (const String &section_name, const String &line)
	Append a line to a section.
bool	appendLine (const String &line)
	Append a line to the last section.
Size	getNumberOfLines () const
	Return number of lines.
bool	hasSection (const String &section_name) const
	Queries for a certain section.
SectionIterator	getSection (const String &section_name)
	Return an iterator to a section with a given name.
SectionIterator	getSection (Position pos)
	Return an iterator to a section at a given position.
Size	getNumberOfSections () const
	Count all sections.
LineIterator	getSectionFirstLine (const String &section_name)
	Returns an iterator to the first line of a section.
LineIterator	getSectionLastLine (const String &section_name)
	Returns an iterator to the last line of a section.
Size	getSectionLength (const String &section_name) const
	Returns the number of lines in a section.
bool	deleteSection (const String &section)
	Delete a section.
bool	appendSection (const String &section)
	Append a section.
Methods to access single entries
bool	hasEntry (const String &section, const String &key) const
	Check whether the given section contains a certain key.
String	getValue (const String &section, const String &key) const
	Query the value corresponding to a given key.
bool	setValue (const String &section, const String &key, const String &value)
	Change the value corresponding to a given key.
bool	insertValue (const String &section, const String &key, const String &value)
	Insert a new value in a given section If the key exists already or the sections doesnt exist, nothing happens.
const INIFile &	operator= (const INIFile &file) throw ()
Predicates
bool	operator== (const INIFile &inifile) const
	Equality operator.
bool	isValid (const LineIterator &it) const
	Test if the given LineIterator is valid for this instance.
bool	isValid (const SectionIterator &it) const
	Test if the given SectionIterator is valid for this instance.
Static Public Attributes
const String	UNDEFINED
	Return type for undefined keys "[UNDEFINED!]".
const String	HEADER
	Name of the HEADER section: $ "\#HEADER!" $.
Protected Attributes
bool	check_duplicate_keys_
bool	valid_
String	filename_
List< Section >	sections_
StringHashMap< SectionIterator >	section_index_

---

Detailed Description

INIFile.

This class provides support to read and evaluate the contents of Windows-style INI files.

---

Member Typedef Documentation

typedef IteratorTraits_ INIFile::LineIterator

An iterator for the lines in an INIFile. With a LineIterator it is easy to iterate over all lines in an instance of INIFile.

---

Member Enumeration Documentation

anonymous enum

Enum for constants. Enumeration values: MAX_LINE_LENGTH  Maximum line length for each entry (1048576).

---

Constructor & Destructor Documentation

INIFile::INIFile (   )

Default constructor. The state of valid_ is set to false. An instance is valid if it is read or written successfully.

INIFile::INIFile (  const String &  filename  )

Constructor with filename The file is not opend.

virtual INIFile::~INIFile (   )  [virtual]

Destructor.

---

Member Function Documentation

bool INIFile::appendLine (  const String &  section_name, const String &  line )

Append a line to a section. To add a line to the HEADER use INIFile::HEADER as section_name. If the given section does not exists, false is returned. Lines starting with "[" cannot be added (to prevent problems with section headers). If checking for duplicate keys is enabled and line contains a key, the section already contains, the method aborts and returns false, use setValue() instead. If an empty string is given as value for section_name, the last section is used. Parameters: section_name  the section to add the line line  the line to be added See also: setDuplicateKeyCheck Returns: true, if line could be added

bool INIFile::appendSection (  const String &  section  )

Append a section. If the given section does already exists, false is returned.

bool INIFile::apply (  UnaryProcessor< LineIterator > &  processor  )

Apply a processor to all lines of the file.

void INIFile::clear (   )

Clear the internal datastructures. Clear frees all allocated memory but retains the filename set for the INIFile object.

bool INIFile::deleteLine (  LineIterator  line_it  )

Delete a line. If the line does not exists, false is returned. Section headers can not be removed with this method. If the line contains a key, it will be removed. Parameters: line_number  the line to delete

bool INIFile::deleteSection (  const String &  section  )

Delete a section. If the given section does not exist, false is returned. If you remove the header, all lines of the header are removed, but the header itself still remains as section in the instance.

const String& INIFile::getFilename (   )  const

Returns the current filename.

LineIterator INIFile::getLine (  Size  line_number  )

Return the contents of the specified line. If the line_number given is not valid (less than 0 or greater/equal to the number returned by getNumberOfLines ) a non-valid iterator is returned. Use of this method is not recommended, because in the worst case, it could be O(n). Parameters: line_number,first  line starts with 0 Returns: LineIterator to the specified line

Size INIFile::getNumberOfLines (   )  const

Return number of lines.

Size INIFile::getNumberOfSections (   )  const

Count all sections. The HEADER is not counted!

SectionIterator INIFile::getSection (  Position  pos  )

Return an iterator to a section at a given position. Returns: SectionIterator iterator to the section

SectionIterator INIFile::getSection (  const String &  section_name  )

Return an iterator to a section with a given name. Returns: SectionIterator iterator to the section

LineIterator INIFile::getSectionFirstLine (  const String &  section_name  )

Returns an iterator to the first line of a section. The first line of a section is the line with the section name (in square brackets). Returns: LineIterator iterator to the first line of the section unvalid iterator, if section does not exist Parameters: section_name  the name of the section to be found

LineIterator INIFile::getSectionLastLine (  const String &  section_name  )

Returns an iterator to the last line of a section. Returns: LineIterator iterator to the last line of the section unvalid iterator, if section does not exist Parameters: section_name  the name of the section to be found

Size INIFile::getSectionLength (  const String &  section_name  )  const

Returns the number of lines in a section. Returns: Size the number of lines, or INVALID_SIZE if the section could not be found Parameters: section_name  the name of the section to be found

String INIFile::getValue (  const String &  section, const String &  key )  const

Query the value corresponding to a given key. If no value exists for the given key, or either the section or the key are not defined, UNDEFINED is returned. Parameters: section  the section name to look in for the key key  a key in the section Returns: String the value corresponding to the key in section or UNDEFINED

bool INIFile::hasEntry (  const String &  section, const String &  key )  const

Check whether the given section contains a certain key. Returns: bool true if the key could be found in the section, false if either key or section didn't exist Parameters: section  the section to look in for the key key  the key to look for

bool INIFile::hasSection (  const String &  section_name  )  const

Queries for a certain section. Parameters: section_name  the name of the section (without square brackets) Returns: bool true if the section exists (is hashed!) false if the section could not be found

bool INIFile::insertLine (  LineIterator  line_it, const String &  line )

Add a line after a given iterator. Lines starting with "[" cannot be added (to prevent problems with section headers). If the line contains a key and the section already contains this key the method aborts and returns false, use setValue() instead. Parameters: line_it  the iterator to insert after line  the line to be added Returns: true, if line could be added

bool INIFile::insertValue (  const String &  section, const String &  key, const String &  value )

Insert a new value in a given section If the key exists already or the sections doesnt exist, nothing happens. Parameters: section  the section to insert the key key  the key to insert value  the new value Returns: bool true if the value was inserted false if key or section do not exist

bool INIFile::isValid (  const LineIterator &  it  )  const

Test if the given LineIterator is valid for this instance.

bool INIFile::isValid (   )  const

Returns the current state of the instance of INIFile. An instance is valid if it is read or writen succesfully.

bool INIFile::operator== (  const INIFile &  inifile  )  const

Equality operator. Two instances are equal if they have the same sections with the same lines.

bool INIFile::read (   )

Open a file and read its contents. This method destroys all existing data in memory and then tries to open the file specified by setFilename. If the file could not be opened, the method returns false, leaving the INIFile instance in invalid state (as returned by isValid ). If the file could be opened, the whole file is read into an internal buffer and the different sections are interpreted. Then, internal datastructures for fast access to the stored data are build (Hashtable containing the sections). Lines starting with '!', ';', or '#' are treated as comment lines and stored, but not interpreted. Key-names and values are trimmed. If a line starts with "[", but no closing bracket occurs, false is returned. Returns: bool true if the file could be opened and read false otherwise

void INIFile::setFilename (  const String &  filename  )

Sets a new filename. The state of valid_ is set to false.

bool INIFile::setLine (  LineIterator  line_it, const String &  line )

Change the contents of a line. Replaces the line given by line_it by the text in line. Section lines cannot be changed with this method. If the line contains a key, the old key is deleted and the new (if any) is set. If the line starts with "[" the method aborts. Parameters: line_it  iterator to the line to change line  new content of the line

bool INIFile::setValue (  const String &  section, const String &  key, const String &  value )

Change the value corresponding to a given key. Replaces the value of an existing key in an existing section. If the key or the new value is a empty string nothing is changed. Parameters: section  the section to look in for the key key  the key to look for value  the new value Returns: bool true if the value was changed false if key or section do not exist

bool INIFile::write (   )

Writes the buffer contents to a file. If the file could not be written, valid_ is set to false, ow true. Returns: bool true if the file could be succesfully written false otherwise