BALL::INIFile Class Reference
[General Purpose File Formats]

#include <INIFile.h>


Classes
class	IteratorTraits_
	Interface for the LineIterator. More...
class	Section
	A section within an INI file. More...
Public Types
enum	{ MAX_LINE_LENGTH = 1048576 }
	Enum for constants. More...
typedef List< Section >::Iterator	SectionIterator
typedef IteratorTraits_	LineIterator
	An iterator for the lines in an INIFile.
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
bool	setContent (const List< String > &lines)
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)
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
static const String	UNDEFINED
	Return type for undefined keys "[UNDEFINED!]".
static 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_ BALL::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.

Enumerator:

MAX_LINE_LENGTH

Maximum line length for each entry (1048576).

Constructor & Destructor Documentation

BALL::INIFile::INIFile ( )

Default constructor.

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

Member Function Documentation

bool BALL::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 BALL::INIFile::appendSection ( const String & section )

Append a section.

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

void BALL::INIFile::clear ( )

Clear the internal datastructures.

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

bool BALL::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 BALL::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.

LineIterator BALL::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 BALL::INIFile::getNumberOfSections ( ) const

Count all sections.

The HEADER is not counted!

SectionIterator BALL::INIFile::getSection ( Position pos )

Return an iterator to a section at a given position.

Returns:

SectionIterator

iterator to the section

SectionIterator BALL::INIFile::getSection ( const String & section_name )

Return an iterator to a section with a given name.

Returns:

SectionIterator

iterator to the section

LineIterator BALL::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 BALL::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 BALL::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 BALL::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 BALL::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 BALL::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 BALL::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 BALL::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 BALL::INIFile::isValid ( ) const

Returns the current state of the instance of INIFile.

An instance is valid if it is read or writen succesfully.

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

Equality operator.

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

bool BALL::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 BALL::INIFile::setFilename ( const String & filename )

Sets a new filename.

The state of valid_ is set to false.

bool BALL::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 BALL::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 BALL::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

BALL::INIFile Class Reference [General Purpose File Formats]

Classes

Public Types

Public Member Functions

Static Public Attributes

Protected Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

BALL::INIFile Class Reference
[General Purpose File Formats]