ppl7::AssocArray Klassenreferenz

Komplexes mehrdimensionales Array mit Strings als Schlüssel. Mehr ...

Klassen
class	ArrayKey
	Datentyp für Schlüssel. Mehr ...
class	Iterator
class	ValueNode

Öffentliche Methoden
	PPL7EXCEPTION (InvalidKeyException, Exception)
	PPL7EXCEPTION (ExportBufferToSmallException, Exception)
	PPL7EXCEPTION (ImportFailedException, Exception)
Konstruktoren und Destruktoren
	AssocArray ()
	Konstruktor des Assoziativen Arrays. Mehr ...
	AssocArray (const AssocArray &other)
	Copy-Konstruktor des Assoziativen Arrays. Mehr ...
	~AssocArray ()
	Destruktor der Klasse. Mehr ...
Informationen ausgeben/auslesen
size_t	count (bool recursive=false) const
	Anzahl Schlüssel zählen. Mehr ...
size_t	count (const String &key, bool recursive=false) const
	Anzahl Schlüssel für ein bestimmtes Element zählen. Mehr ...
size_t	size () const
	Anzahl Elemente. Mehr ...
void	list (const String &prefix="") const
	Inhalt des Arrays ausgeben. Mehr ...
void	reserve (size_t num)
	Speicher reservieren. Mehr ...
size_t	capacity () const
	Aktuelle Kapazität des AssocArrays. Mehr ...
Werte setzen
void	add (const AssocArray &other)
	AssocArray kopieren Mehr ...
void	set (const String &key, const String &value)
	String hinzufügen Mehr ...
void	set (const String &key, const String &value, size_t size)
	String mit bestimmter Länge hinzufügen Mehr ...
void	set (const String &key, const Array &value)
	Array hinzufügen Mehr ...
void	set (const String &key, const DateTime &value)
	DateTime hinzufügen Mehr ...
void	set (const String &key, const ByteArray &value)
	ByteArray hinzufügen Mehr ...
void	set (const String &key, const ByteArrayPtr &value)
	ByteArrayPtr hinzufügen Mehr ...
void	set (const String &key, const AssocArray &value)
	AssocArray hinzufügen Mehr ...
void	set (const String &key, const Pointer &value)
	Pointer hinzufügen Mehr ...
void	set (const String &key, const Variant &value)
	Variant hinzufügen Mehr ...
void	setf (const String &key, const char *fmt,...)
	Formatierten String hinzufügen. Mehr ...
Werte erweitern (nur Strings)
void	append (const String &key, const String &value, const String &concat="")
	String verlängern Mehr ...
void	appendf (const String &key, const String &concat, const char *fmt,...)
	String mit Formatiertem String verlängern Mehr ...
Werte löschen
void	clear ()
	Inhalt des Arrays löschen. Mehr ...
void	erase (const String &key)
	Einzelnen Schlüssel löschen. Mehr ...
void	remove (const String &key)
	Einzelnen Schlüssel löschen. Mehr ...
Import und Export von Daten
size_t	fromTemplate (const String &templ, const String &linedelimiter="\n", const String &splitchar="=", const String &concat="\n", bool dotrim=false)
	Wandelt ein Key-Value Template in ein Assoziatives Array um. Mehr ...
size_t	fromConfig (const String &content, const String &linedelimiter="\n", const String &splitchar="=", const String &concat="\n", bool dotrim=false)
	Wandelt eine Konfigurationsdatei in ein Assoziatives Array um. Mehr ...
void	toTemplate (String &s, const String &prefix="", const String &linedelimiter="\n", const String &splitchar="=") const
	Inhalt des Assoziativen Arrays in ein Template exportieren. Mehr ...
size_t	binarySize () const
	Liefert Anzahl Bytes, die für exportBinary erforderlich sind. Mehr ...
void	exportBinary (void *buffer, size_t buffersize, size_t *realsize) const
	Inhalt des Arrays in einem plattform-unabhängigen Binären-Format exportieren. Mehr ...
void	exportBinary (ByteArray &buffer) const
	Inhalt des Arrays in einem plattform-unabhängigen Binären-Format exportieren. Mehr ...
size_t	importBinary (const void *buffer, size_t buffersize)
	Daten aus einem vorherigen Export wieder importieren. Mehr ...
void	importBinary (const ByteArrayPtr &buffer)
	Daten aus einem vorherigen Export wieder importieren. Mehr ...
Werte direkt auslesen
String &	getString (const String &key) const
	String auslesen. Mehr ...
AssocArray &	getArray (const String &key) const
	AssocArray auslesen. Mehr ...
Variant &	get (const String &key) const
	Schlüssel auslesen. Mehr ...
bool	exists (const String &key) const
	Schlüssel vorhanden. Mehr ...
Array durchwandern
void	reset (Iterator &it) const
	Zeiger für das Durchwandern des Arrays zurücksetzen. Mehr ...
bool	getFirst (Iterator &it, Variant::DataType type=Variant::TYPE_UNKNOWN) const
	Erstes Element zurückgeben. Mehr ...
bool	getNext (Iterator &it, Variant::DataType type=Variant::TYPE_UNKNOWN) const
	Nächstes Element zurückgeben. Mehr ...
bool	getLast (Iterator &it, Variant::DataType type=Variant::TYPE_UNKNOWN) const
	Letztes Element zurückgeben. Mehr ...
bool	getPrevious (Iterator &it, Variant::DataType type=Variant::TYPE_UNKNOWN) const
	Vorhergehendes Element zurückgeben. Mehr ...
bool	getFirst (Iterator &it, String &key, String &value) const
	Ersten String im Array finden und Key und Value in Strings speichern. Mehr ...
bool	getNext (Iterator &it, String &key, String &value) const
	Nächsten String im Array finden und Key und Value in Strings speichern. Mehr ...
bool	getLast (Iterator &it, String &key, String &value) const
	Letzten String im Array finden und Key und Value in Strings speichern. Mehr ...
bool	getPrevious (Iterator &it, String &key, String &value) const
	Vorhergehenden String im Array finden und Key und Value in Strings speichern. Mehr ...
Operatoren
Variant &	operator[] (const String &key) const
	Schlüssel auslesen. Mehr ...
AssocArray &	operator= (const AssocArray &other)
	Assoziatives Array kopieren. Mehr ...
AssocArray &	operator+= (const AssocArray &other)
	Assoziatives Array hinzufügen. Mehr ...

Private Methoden
ValueNode *	createTree (const ArrayKey &key, Variant *var)
	Interne Funktion, die ein Element im Baum sucht oder anlegt. Mehr ...
ValueNode *	findInternal (const ArrayKey &key) const
	Interne Funktion zum Suchen eines Elements. Mehr ...

Private Attribute
ppluint64	maxint
size_t	num
ppl7::AVLTree< ArrayKey, ValueNode >	Tree

Ausführliche Beschreibung

Beschreibung:

Die Klasse AssocArray dient als Container für beliebige Key-Value-Paare. Ein Schlüssel (Key) besteht aus einem String, der aus beliebigen Zeichen bestehen kann. Ein Value kann veschiedene Datentypen enthalten. Gegenwärtig werden folgende Datentypen unterstützt:

• String
• Array
• ByteArray
• ByteArrayPtr
• AssocArray
• DateTime

Die Schlüssel werden sortiert in einem AVL-Baum verwaltet (siehe AVLTree), so dass auch bei sehr großen Arrays eine schnelle Verarbeitung gewährleistet ist. Gross-/Kleinschreibung wird ignoriert, der Schlüssel "TEST" wäre also identisch mit "test" oder "Test".

Mehrdimensionale Arrays sind möglich, indem einem Schlüssel als Wert einfach ein anderes Array zugeordnet wird. In einem solchen Array kann jedes Element direkt angesprochen werden, indem man die einzelnen Schlüssel durch Slash (/) getrennt zu einem einzigen Schlüssel zusammenfasst.

Mehrdimensionale Arrays werden automatisch generiert. Gibt man bei einem leeren Array dem Schlüssel "ebene1/ebene2/key" einen Wert, werden automatisch folgende Aktionen ausgeführt:

• Es wird ein neues AssocArray generiert und mit dem Schlüssel "ebene1" in das Array eingefügt
• In das Array "ebene1" wird ein weiteres neues Array mit dem Schlüssel "ebene2" eingefügt
• In das Array "ebene2" wird der eigentliche Wert unter dem Schlüssel "key" eingefügt

Beispiel:

Einen Wert setzen und wieder auslesen:

ppl7::AssocArray a;
// Wert setzen
a.set("ebene1/ebene2/key","Ein Wert");
// Wert auslesen
a.get("ebene1/ebene2/key").toString().printnl();

Durch ein AssocArray durchiterieren:

void IterateArray(const ppl7::AssocArray &a)
{
    ppl7::AssocArray::Iterator it;
    a.reset(it);
    while (a.getNext(it)) {
        const ppl7::String &key=it.key();
        const ppl7::Variant &var=*it.value().value;
        if (var.isString()) {
            cout << "Key: " << key << ", Value: " << var.toString() << endl;
        }
    }
}

Wenn von vorneherein bekannt ist, dass im Array nur Strings vorhanden sind, kann man auch noch auf diese Weise durchiterieren:

void IterateArray(const ppl7::AssocArray &a)
{
    ppl7::AssocArray::Iterator it;
    ppl7::String Key, Value;
    a.reset(it);
    while (a.GetNext(it,Key,Value)) {
        cout << "Key: " << Key << ", Value: " << Value << endl;
    }
}

Beschreibung der Konstruktoren und Destruktoren

ppl7::AssocArray::AssocArray

(

)

Beschreibung:

Initialisiert die Instanz mit 0 und initialisiert den AVL-Baum.

ppl7::AssocArray::AssocArray

(

const AssocArray &

other

)

Beschreibung:

Macht eine Kopie des Assoziativen Arrays other.

Parameter

[in]

other

Referenz auf zu kopierendes Assoziatives Array

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel

ppl7::AssocArray::~AssocArray

(

)

Beschreibung:

Der Destruktor ruft die Funktion AssocArray::clear auf, um alle vorhandenen Elemente zu löschen.

Dokumentation der Elementfunktionen

void ppl7::AssocArray::add

(

const AssocArray &

other

)

Beschreibung:

Mit dieser Funktion wird der komplette Inhalt des Assoziativen Arrays other in dieses hineinkopiert. Das Array wird vorher nicht gelöscht, so dass vorhandene Schlüssel erhalten bleiben. Gibt es in other jedoch gleichnamige Schlüssel, werden die bisherigen Werte überschrieben.

Parameter

[in]

a

Das zu kopierende AssocArray

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel

void ppl7::AssocArray::append	(	const String &	key,
		const String &	value,
		const String &	concat = ""
	)

Beschreibung:

Diese Funktion fügt den Inhalt des Strings value an den bereits vorhandenen Wert des Schlüssels key an. Falls der optionale Parameter concat einen Wert enthält, wird dieser als Trennung zwischen bestehendem und neuem String verwendet. War der Schlüssel bisher nicht vorhanden, wird ein neuer angelegt.

Parameter

[in]	key	Name des Schlüssels
[in]	value	Wert
[in]	concat	Trennzeichen (Optional, Default=keins)

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel
TypeConversionException	Schlüssel ist bereits vorhanden, enthält aber keinen String

void ppl7::AssocArray::appendf	(	const String &	key,
		const String &	concat,
		const char *	fmt,
			...
	)

Beschreibung:

Diese Funktion erstellt zuerst einen neuen String anhand des Formatstrings fmt und der zusätzlichen optionalen Parameter. Dieser wird an den bereits vorhandenen Wert des Schlüssels key angehangen. Falls der optionale Parameter concat einen Wert enthält, wird dieser als Trennung zwischen bestehendem und neuem String verwendet. War der Schlüssel bisher nicht vorhanden, wird ein neuer angelegt.

Parameter

[in]	key	Name des Schlüssels
[in]	concat	Trennzeichen (Optional, Default=keins)
[in]	fmt	Formatstring
[in]	...	Optionale Parameter

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel
TypeConversionException	Schlüssel ist bereits vorhanden, enthält aber keinen String

size_t ppl7::AssocArray::binarySize

(

)

const

Beschreibung:

Diese Funktion liefert die Anzahl Bytes zurück, die für den Buffer der Funktion AssocArray::exportBinary erforderlich sind. Es kann dadurch ein ausreichend großer Puffer vor Aufruf der Funktion exportBinary angelegt werden.

Rückgabe

Anzahl Bytes oder 0 im Fehlerfall

Siehe auch

• AssocArray::exportBinary
• AssocArray::importBinary

size_t ppl7::AssocArray::capacity

(

)

const

Beschreibung:

Gibt zurück, wieviele Elemente diese Ebene des Assoziativen Arrays verwalten kann, ohne dass neuer Speicher allokiert werden muss.

Rückgabe

Anzahl Elemente

void ppl7::AssocArray::clear

(

)

Beschreibung:

Mit dieser Funktion wird der komplette Inhalt des Arrays gelöscht. Dabei der Destruktor für jedes vorhandene Element aufgerufen, der wiederum sicherstellt, dass die darin enthaltenen Daten ordnungsgemäß gelöscht werden.

size_t ppl7::AssocArray::count

(

bool

recursive = false

)

const

Beschreibung:

Diese Funktion liefert die Anzahl Schlüssel auf dieser Ebene des Array zurück.

Parameter

[in]

recursive

Falls recursive auf true gesetzt wird die Funktion rekusriv für jeden Schlüssel aufgerufen, dessen Wert ebenfalls ein Array ist.

Rückgabe

Anzahl Schlüssel

size_t ppl7::AssocArray::count	(	const String &	key,
		bool	recursive = false
	)		const

Beschreibung:

Diese Funktion liefert die Anzahl Schlüssel zurück, die in dem angegebenen Key enthalten sind.

Parameter

[in]	key	Schlüssel-Name eines Assoziativen Arrays innerhalb dieses Arrays
[in]	recursive	Falls recursive auf true gesetzt wird die Funktion rekusriv für jeden Schlüssel aufgerufen, dessen Wert ebenfalls ein Array ist.

Rückgabe

Anzahl Schlüssel

AssocArray::ValueNode * ppl7::AssocArray::createTree ( const ArrayKey &  key, Variant *  var  )

private

Beschreibung:

Diese Funktion durchsucht den Baum nach dem gewünschten Element. Ist es vorhanden, wird dessen Pointer zurückgeliefert, wenn nicht, wird es angelegt, jedoch ohne Daten. Bei verschachtelten Schlüsseln wird die Funktion rekursiv aufgerufen, bis das letzte Element erreicht ist. Die Funktion wird intern von allen Funktionen verwendet, die Daten in das Array speichern.

Parameter

[in]	key	Pointer auf den Namen des Schlüssels
[in]	var	Pointer auf die Daten, die unter diesem Schlüssel abgelegt werden sollen

Rückgabe

Bei Erfolg liefert die Funktion einen Pointer auf das gewünschte Element zurück. Im Fehlerfall wird eine Exception geworfen.

Ausnahmebehandlung

InvalidKeyException	Wird geworfen, wenn der Schlüssel ungültig oder leer ist
std::bad_alloc	Kein Speicher mehr frei

Bemerkungen

Bei der Angabe eines verschachtelten Schlüssels kann es vorkommen, dass bereits vorhandene Elemente überschrieben werden. Beispiel:

Das Element ebene1/schlüssel1 ist im Baum bereits vorhanden und beinhaltet einen String. Nun wird das neue Element ebene1/schlüssel1/unterschlüssel1 angelegt. Da Schlüssel eindeutig sein müssen, wird der String ebene1/schlüssel1 gelöscht und in ein Array umgewandelt.

void ppl7::AssocArray::erase

(

const String &

key

)

Beschreibung:

Mit dieser Funktion wird ein einzelner Schlüssel aus dem Array gelöscht.

Parameter

[in]

key

Pointer auf den Namen des zu löschenden Schlüssels

Rückgabe

Bei Erfolg liefert die die Funktion true (1) zurück, im Fehlerfall false (0).*

bool ppl7::AssocArray::exists

(

const String &

key

)

const

Beschreibung:

Diese Funktion prüft, ob der Schlüssels key im Assoziativen Array enthalten ist.

Parameter

key	Name des Schlüssels

Rückgabe

Liefert true zurück, wenn der Schlüssel vorhanden ist, sonst false

Ausnahmebehandlung

InvalidKeyException

Ungültiger Schlüssel

void ppl7::AssocArray::exportBinary	(	void *	buffer,
		size_t	buffersize,
		size_t *	realsize
	)		const

Beschreibung:

Mit dieser Funktion kann der komplette Inhalt des Arrays in einem plattform-unabhängigem binären Format abgelegt werden, das sich zum Speichern in einer Datei oder zum Übertragen über das Internet eignet.

Parameter

[in]	buffer	Pointer auf einen ausreichend großen Puffer. Die Größe des benötigten Puffers kann zuvor mit der Funktion AssocArray::binarySize ermittelt werden. Wird als Buffer NULL übergeben, wird in der Variable realsize ebenfalls die Anzahl Bytes zurückgegeben
[in]	buffersize	Die Größe des Puffers in Bytes
[out]	realsize	In dieser Variable wird gespeichert, wieviele Bytes tatsächlich für den Export verwendet wurden

Ausnahmebehandlung

ExportBufferToSmallException

Wird geworfen, wenn buffersize nicht groß genug ist, um das Assoziative Array vollständig exportieren zu können.

Achtung

Es muss daran gedacht werden, dass nicht alle Datentypen exportiert werden können. Gegenwärtig werden folgende Typen unterstützt:

• String (Wird als UTF-8 exportiert)
• Array
• AssocArray
• ByteArray
• ByteArrayPtr (wird in ein ByteArray umgewandelt!)
• DateTime

Siehe auch

• AssocArray::binarySize
• AssocArray::importBinary

Zu beachten

Das exportierte Binary ist komptibel mit dem Assoziativen Array der PPL-Version 6

void ppl7::AssocArray::exportBinary

(

ByteArray &

buffer

)

const

Beschreibung:

Mit dieser Funktion kann der komplette Inhalt des Arrays in einem plattform-unabhängigem binären Format abgelegt werden, das sich zum Speichern in einer Datei oder zum Übertragen über das Internet eignet.

Parameter

[in,out]

buffer

ByteArray, in dem die exportierten Daten gespeichert werden sollen

Achtung

Es muss daran gedacht werden, dass nicht alle Datentypen exportiert werden können. Gegenwärtig werden folgende Typen unterstützt:

• String (Wird als UTF-8 exportiert)
• Array
• AssocArray
• ByteArray
• ByteArrayPtr (wird in ein ByteArray umgewandelt!)
• DateTime

Siehe auch

• AssocArray::binarySize
• AssocArray::importBinary

Zu beachten

Das exportierte Binary ist komptibel mit dem Assoziativen Array der PPL-Version 6

AssocArray::ValueNode * ppl7::AssocArray::findInternal ( const ArrayKey &  key ) const

private

Beschreibung:

Diese Funktion zerlegt den angegebenen Schlüssel (key) in seine einzelnen Elemente. Als Trennzeichen wird wie bei einer Unix-Pfadangabe der Slash (/) verwendet. Die Funktion sucht zunächst nach dem erste Element des Schlüssels im eigenen Baum. Ist dies vorhanden und handelt es sich bei dessen Datentyp wieder um ein AssocArray, wird deren findInternal-Funktion mit dem restlichen Schlüssel rekursiv aufgerufen. Dies geschieht solange, bis das letzte Element des Keys gefunden wurde.

Parameter

[in]

key

String mit dem gesuchten Schlüssel

Rückgabe

Konnte der Schlüssel gefunden werden, wir der Pointer auf das Element (Variant) zurückgegeben. Wurde der Schlüssel nicht gefunden, wird eine Exception geworfen

Ausnahmebehandlung

InvalidKeyException	Wird geworfen, wenn der Schlüssel ungültig oder leer ist
KeyNotFoundException	Wird geworfen, wenn der Schlüssel nicht vorhanden ist

Zu beachten

Die Funktion wird von allen Get...- und Concat-Funktionen verwendet.

size_t ppl7::AssocArray::fromConfig	(	const String &	content,
		const String &	linedelimiter = "\n",
		const String &	splitchar = "=",
		const String &	concat = "\n",
		bool	dotrim = false
	)

Beschreibung:

Diese Funktion wandelt einen Konfigurations-Text mit mehreren Abschnitten im Key-Value-Format in ein Assoziatives Array um. Ein Abschnitt beginnt immer mit einem Keywort in Eckigen klammern und enthält Key-Value-Paare. Zeilen mit Raute (#) am Anfang werden als Kommentarzeilen interpretiert und ignoriert.

Beispiel einer Konfigurationsdatei

[Abschnitt_1]
# Kommentarzeile, die überlesen wird
key1: value1
key2: value2
[Abschnitt_2]
key1: value1
key2: value2

Parameter

[in]	content	Ein String, dre die zu parsende Konfiguration enthält.
[in]	linedelimiter	Das Zeichen, was als Zeilenende interpretiert werden soll. Default ist Newline
[in]	splitchar	Das Zeichen, was als Trennzeichen zwischen Schlüssel (Key) und Wert (Value) interpretiert werden soll. Der Default ist das Gleichheitszeichen (=)
[in]	concat	Ist concat gesetzt und kommen im Text mehrere identische Schlüssel vor, werden die Werte zu einem String zusammengeführt, wobei als Trennzeichen concat verwendet wird. Ist concat NULL, wird ein vorhandener Schlüssel überschrieben. Der Default ist, dass gleiche Schlüssel mit Newline aneinander gehangen werden.
[in]	dotrim	Ist dotrim=true, werden einzelnen Werte vor dem Einfügen ins Array mit der Funktion Trim getrimmt, also Leerzeilen, Tabs und Zeilenumbrüche am Anfang und Ende gelöscht. Der Default ist false.

Rückgabe

Die Funktion gibt die Anzahl gelesener Key-Value-Paare zurück, oder 0, wenn der Text keine verwertbaren Zeilen enthielt.

Zu beachten

Falls das Array vor dem Aufruf dieser Funktion bereits Datensätze enthielt, werden diese nicht gelöscht. Die Funktion kann also benutzt werden, um Werte aus verschiedenen Templates in ein einziges Array einzulesen. Soll das Array geleert werden, muß vorher die Funktion AssocArray::clear aufgerufen werden.

size_t ppl7::AssocArray::fromTemplate	(	const String &	templ,
		const String &	linedelimiter = "\n",
		const String &	splitchar = "=",
		const String &	concat = "\n",
		bool	dotrim = false
	)

Beschreibung:

Diese Funktion wandelt einen Text mit Key-Value-Paaren in ein Assoziatives Array um. Leere Zeilen oder Zeilen mit Raute (#) am Anfang (Kommentarzeilen) werden ignoriert.

Parameter

[in]	templ	String mit den Key-Value-Paaren
[in]	linedelimiter	Das Zeichen, was als Zeilenende interpretiert werden soll. Default ist Newline
[in]	splitchar	Das Zeichen, was als Trennzeichen zwischen Schlüssel (Key) und Wert (Value) interpretiert werden soll. Der Default ist das Gleichheitszeichen (=)
[in]	concat	Ist concat gesetzt und kommen im Text mehrere identische Schlüssel vor, werden die Werte zu einem String zusammengeführt, wobei als Trennzeichen concat verwendet wird. Ist concat leer, wird ein vorhandener Schlüssel überschrieben. Der Default ist, dass Werte mit gleichem Schlüssel mit Newline aneinander gehangen werden.
[in]	dotrim	Ist dotrim=true, werden einzelnen Werte vor dem Einfügen ins Array mit der Funktion Trim getrimmt, also Leerzeilen, Tabs und Zeilenumbrüche am Anfang und Ende gelöscht. Der Default ist false.

Rückgabe

Die Funktion gibt die Anzahl gelesener Key-Value-Paare zurück, oder 0, wenn der Text keine verwertbaren Zeilen enthielt.

Zu beachten

Falls das Array vor dem Aufruf dieser Funktion bereits Datensätze enthielt, werden diese nicht gelöscht. Die Funktion kann also benutzt werden, um Werte aus verschiedenen Templates in ein einziges Array einzulesen. Soll das Array geleert werden, muß vorher die Funktion AssocArray::clear aufgerufen werden.

Siehe auch

Um Konfigurationsdateien mit verschiedenen Abschnitten (z.B. .ini-Dateien) in ein Assoziatives Array einzulesen, gibt es die Member-Funktion AssocArray::fromConfig

Variant & ppl7::AssocArray::get

(

const String &

key

)

const

Beschreibung:

Diese Funktion liefert den Wert des Schlüssels key als Variant zurück. Dieser kann von der aufrufenden Anwendung in den jeweiligen Datentyp umgewandelt werden.

Parameter

key	Name des Schlüssels

Rückgabe

Referenz auf einen Variant mit dem Wert des Schlüssels

Ausnahmebehandlung

InvalidKeyException	Ungültiger Schlüssel
KeyNotFoundException	Schlüssel wurde nicht gefunden

Beispiel:

Der Variant kann z.B. folgendermaßen in einen String umgewandelt werden:

ppl7::String &str=a.get(L"key1").toString();

AssocArray & ppl7::AssocArray::getArray

(

const String &

key

)

const

Beschreibung:

Parameter

key	Name des Schlüssels

Rückgabe

Referenz auf einen String mit dem Wert des Schlüssels

Ausnahmebehandlung

InvalidKeyException	Ungültiger Schlüssel
KeyNotFoundException	Schlüssel wurde nicht gefunden

bool ppl7::AssocArray::getFirst	(	Iterator &	it,
		Variant::DataType	type = Variant::TYPE_UNKNOWN
	)		const

Beschreibung:

Diese Funktion liefert das erste Element des Arrays zurück. Falls der optionale Parameter type verwendet wird, liefert die Funktion das erste Element dieses Typs zurück.

Parameter

it	Iterator. Dieser muss vom Typ ppl7::AssocArray::Iterator sein.
type	Optional der gewünschte Datentyp (siehe Variant::Type)

Rückgabe

true, wenn ein Element vorhanden war, sonst false

bool ppl7::AssocArray::getFirst	(	Iterator &	it,
		String &	key,
		String &	value
	)		const

Beschreibung:

Diese Funktion sucht den ersten String im Array und speichert dessen Schlüssel im Parameter key und den Wert in value;

Parameter

[in,out]	it	Iterator. Dieser muss vom Typ ppl7::AssocArray::Iterator sein.
[out]	key	String, in dem der Name des Schlüssels gespeichert werden soll
[out]	value	String, in dem der Wert gespeichert werden soll.

Rückgabe

Solange Elemente gefunden werden, liefert die Funktion true zurück, sonst false.

bool ppl7::AssocArray::getLast	(	Iterator &	it,
		Variant::DataType	type = Variant::TYPE_UNKNOWN
	)		const

Beschreibung:

Diese Funktion liefert das letzte Element des Arrays zurück. Falls der optionale Parameter type verwendet wird, liefert die Funktion das letzte Element dieses Typs zurück.

Parameter

it	Iterator. Dieser muss vom Typ ppl7::AssocArray::Iterator sein.
type	Optional der gewünschte Datentyp (siehe Variant::Type)

Rückgabe

true, wenn ein Element vorhanden war, sonst false

bool ppl7::AssocArray::getLast	(	Iterator &	it,
		String &	key,
		String &	value
	)		const

Beschreibung:

Diese Funktion sucht den letzten String im Array und speichert dessen Schlüssel im Parameter key und den Wert in value;

Parameter

[in,out]	it	Iterator. Dieser muss vom Typ ppl7::AssocArray::Iterator sein.
[out]	key	String, in dem der Name des Schlüssels gespeichert werden soll
[out]	value	String, in dem der Wert gespeichert werden soll.

Rückgabe

Solange Elemente gefunden werden, liefert die Funktion true zurück, sonst false.

bool ppl7::AssocArray::getNext	(	Iterator &	it,
		Variant::DataType	type = Variant::TYPE_UNKNOWN
	)		const

Beschreibung:

Diese Funktion liefert das nächste Element des Arrays zurück. Falls der optionale Parameter type verwendet wird, liefert die Funktion das nächste Element dieses Typs zurück.

Parameter

it	Iterator. Dieser muss vom Typ ppl7::AssocArray::Iterator sein.
type	Optional der gewünschte Datentyp (siehe Variant::Type)

Rückgabe

true, wenn ein Element vorhanden war, sonst false

bool ppl7::AssocArray::getNext	(	Iterator &	it,
		String &	key,
		String &	value
	)		const

Beschreibung:

Diese Funktion sucht den nächsten String im Array und speichert dessen Schlüssel im Parameter key und den Wert in value;

Parameter

[in,out]	it	Iterator. Dieser muss vom Typ ppl7::AssocArray::Iterator sein.
[out]	key	String, in dem der Name des Schlüssels gespeichert werden soll
[out]	value	String, in dem der Wert gespeichert werden soll.

Rückgabe

Solange Elemente gefunden werden, liefert die Funktion true zurück, sonst false.

bool ppl7::AssocArray::getPrevious	(	Iterator &	it,
		Variant::DataType	type = Variant::TYPE_UNKNOWN
	)		const

Beschreibung:

Diese Funktion liefert das vorhergehende Element des Arrays zurück. Falls der optionale Parameter type verwendet wird, liefert die Funktion das vorhergehende Element dieses Typs zurück.

Parameter

it	Iterator. Dieser muss vom Typ ppl7::AssocArray::Iterator sein.
type	Optional der gewünschte Datentyp (siehe Variant::Type)

Rückgabe

true, wenn ein Element vorhanden war, sonst false

bool ppl7::AssocArray::getPrevious	(	Iterator &	it,
		String &	key,
		String &	value
	)		const

Beschreibung:

Diese Funktion sucht den vorhergehenden String im Array und speichert dessen Schlüssel im Parameter key und den Wert in value;

Parameter

[in,out]	it	Iterator. Dieser muss vom Typ ppl7::AssocArray::Iterator sein.
[out]	key	String, in dem der Name des Schlüssels gespeichert werden soll
[out]	value	String, in dem der Wert gespeichert werden soll.

Rückgabe

Solange Elemente gefunden werden, liefert die Funktion true zurück, sonst false.

String & ppl7::AssocArray::getString

(

const String &

key

)

const

Beschreibung:

Diese Funktion liefert den Wert des Schlüssels key als String zurück, sofern der Schlüssel auch tatsächlich einen String enthält.

Parameter

key	Name des Schlüssels

Rückgabe

Referenz auf einen String mit dem Wert des Schlüssels

Ausnahmebehandlung

InvalidKeyException	Ungültiger Schlüssel
KeyNotFoundException	Schlüssel wurde nicht gefunden

size_t ppl7::AssocArray::importBinary	(	const void *	buffer,
		size_t	buffersize
	)

Beschreibung:

Mit dieser Funktion kann ein zuvor mit AssocArray::exportBinary exportiertes Assoziatives Array wieder importiert werden. Falls im Array bereits Daten vorhanden sind, werden diese nicht gelöscht, können aber überschrieben werden, wenn es im Export gleichnamige Schlüssel gibt.

Parameter

[in]	buffer	Pointer auf den Puffer, der die zu importierenden Daten enthält
[in]	buffersize	Größe des Puffers

Ausnahmebehandlung

ImportFailedException

Siehe auch

• AssocArray::exportBinary
• AssocArray::binarySize

void ppl7::AssocArray::importBinary

(

const ByteArrayPtr &

bin

)

Beschreibung:

Mit dieser Funktion kann ein zuvor mit AssocArray::exportBinary exportiertes Assoziatives Array wieder importiert werden. Falls im Array bereits Daten vorhanden sind, werden diese nicht gelöscht, können aber überschrieben werden, wenn es im Export gleichnamige Schlüssel gibt.

Parameter

[in]

bin

Referenz auf ByteArray oder ByteArrayPtr mit den zu importierenden Daten

Siehe auch

• CAssocArray::exportBinary
• CAssocArray::binarySize

void ppl7::AssocArray::list

(

const String &

prefix = ""

)

const

Beschreibung:

Diese Funktion dient Debugging-Zwecken. Der Aufruf bewirkt, dass der Inhalt des kompletten Arrays auf STDOUT ausgegeben wird.

Parameter

[in]

prefix

Optionaler Text, der bei der Ausgabe jedem Element vorangestellt wird

Beispiel:

ppl7::AssocArray a;
ppl7::Binary bin;
bin.load("main.cpp");

a.set("key1","value1");
a.set("array1/unterkey1","value2");
a.set("array1/unterkey2","value3");
a.set("array1/noch ein array/unterkey1","value4");
a.set("array1/unterkey2","value5");
a.set("key2","value6");
a.set("dateien/main.cpp",bin);
a.set("array2/unterkey1","value7");
a.set("array2/unterkey2","value8");
a.set("array2/unterkey1","value9");
a.list("prefix");

Ausgabe:

prefix/array1/noch ein array/unterkey1=value4
prefix/array1/unterkey1=value2
prefix/array1/unterkey2=value5
prefix/array2/unterkey1=value9
prefix/array2/unterkey2=value8
prefix/dateien/main.cpp=Binary, 806 Bytes
prefix/key1=value1
prefix/key2=value6

Bemerkungen

Die Funktion gibt nur "lesbare" Element aus. Enthält das Array Pointer oder Binaries, wird das Element zwar ausgegeben, jedoch werden als Wert nur Meta-Informationen ausgegeben (Datentyp, Pointer, Größe).

AssocArray & ppl7::AssocArray::operator+=

(

const AssocArray &

other

)

Beschreibung:

Mit diesem Operator wird der Inhalt das Assoziativen Arrays other dem eigenen Array hinzugefügt. Das Array wird vorher nicht gelöscht, so dass vorhandene Schlüssel erhalten bleiben. Gibt es in other jedoch gleichnamige Schlüssel, werden die bisherigen Werte überschrieben.

Parameter

other

Zu kopierendes assoziatives Array

Rückgabe

Referenz auf dieses Array

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel

AssocArray & ppl7::AssocArray::operator=

(

const AssocArray &

other

)

Beschreibung:

Mit diesem Operator wird der Inhalt das Assoziativen Arrays other übernommen. Der bisherige Inhalt dieses Arrays geht verloren.

Parameter

other

Zu kopierendes assoziatives Array

Rückgabe

Referenz auf dieses Array

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel

Variant & ppl7::AssocArray::operator[]

(

const String &

key

)

const

Beschreibung:

Dieser Operator liefert den Wert des Schlüssels key als Variant zurück. Dieser kann von der aufrufenden Anwendung in den jeweiligen Datentyp umgewandelt werden.

Parameter

key	Name des Schlüssels

Rückgabe

Referenz auf den einen Variant mit dem Wert des Schlüssels

Ausnahmebehandlung

InvalidKeyException	Ungültiger Schlüssel
KeyNotFoundException	Schlüssel wurde nicht gefunden

ppl7::AssocArray::PPL7EXCEPTION	(	InvalidKeyException	,
		Exception
	)

ppl7::AssocArray::PPL7EXCEPTION	(	ExportBufferToSmallException	,
		Exception
	)

ppl7::AssocArray::PPL7EXCEPTION	(	ImportFailedException	,
		Exception
	)

void ppl7::AssocArray::remove

(

const String &

key

)

Beschreibung:

Mit dieser Funktion wird ein einzelner Schlüssel aus dem Array gelöscht.

Parameter

[in]

key

Pointer auf den Namen des zu löschenden Schlüssels

Rückgabe

Bei Erfolg liefert die die Funktion true (1) zurück, im Fehlerfall false (0).*

void ppl7::AssocArray::reserve

(

size_t

num

)

Beschreibung:

Mit dieser Funktion kann vorab Speicher für eine bestimmte Anzahl Elemente reserviert werden. Der Aufruf dieser Funktion ist immer dann sinnvoll, wenn schon vorher bekannt ist, wieviele Elemente benötigt werden, insbesondere, wenn sehr viele Elemente benötigt werden.

Parameter

num	Anzahl Elemente, für die Speicher vorab allokiert werden soll

Zu beachten

Falls schon Speicher allokiert wurde, wird die Anzahl der bereits allokierten Elemente mit num verrechnet und nur die Differenz zusätzlich reserviert.

void ppl7::AssocArray::reset

(

Iterator &

it

)

const

Beschreibung:

Mit dieser Funktion wird der Iterator it, der zum Durchwandern des Arrays mit den Funktion AssocArray::getNext und AssocArray::getPrevious benötigt wird, auf den Anfang zurückgesetzt.

Parameter

[in]

it

Iterator. Dieser muss vom Typ ppl7::AssocArray::Iterator sein.

void ppl7::AssocArray::set	(	const String &	key,
		const String &	value
	)

Beschreibung:

Diese Funktion fügt den Inhalt eines Strings dem Array hinzu.

Parameter

[in]	key	Name des Schlüssels
[in]	value	Wert

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel

void ppl7::AssocArray::set	(	const String &	key,
		const String &	value,
		size_t	size
	)

Beschreibung:

Diese Funktion fügt die ersten size Zeichen des Strings value unter dem Schlüssel key in das Assoziative Array ein.

Parameter

[in]	key	Name des Schlüssels
[in]	value	Wert
[in]	size	Anzahl Zeichen, die aus dem String value übernommen werden sollen

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel

void ppl7::AssocArray::set	(	const String &	key,
		const Array &	value
	)

Beschreibung:

Diese Funktion fügt den Inhalt des Arrays value unter dem Schlüssel key in das Assoziative Array ein.

Parameter

[in]	key	Name des Schlüssels
[in]	value	Daten

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel

void ppl7::AssocArray::set	(	const String &	key,
		const DateTime &	value
	)

Beschreibung:

Diese Funktion fügt den in value angegebenen Zeitstempel unter dem Schlüssel key in das Assoziative Array ein.

Parameter

[in]	key	Name des Schlüssels
[in]	value	Zeitstempel

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel

void ppl7::AssocArray::set	(	const String &	key,
		const ByteArray &	value
	)

Beschreibung:

Diese Funktion fügt den Inhalt des ByteArrays value unter dem Schlüssel key in das Assoziative Array ein.

Parameter

[in]	key	Name des Schlüssels
[in]	value	Daten

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel

void ppl7::AssocArray::set	(	const String &	key,
		const ByteArrayPtr &	value
	)

Beschreibung:

Diese Funktion fügt den Inhalt des ByteArrayPtrs value unter dem Schlüssel key in das Assoziative Array ein.

Parameter

[in]	key	Name des Schlüssels
[in]	value	Daten

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel

void ppl7::AssocArray::set	(	const String &	key,
		const AssocArray &	value
	)

Beschreibung:

Diese Funktion fügt den Inhalt des AssocArrays value unter dem Schlüssel key in das Assoziative Array ein.

Parameter

[in]	key	Name des Schlüssels
[in]	value	Daten

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel

void ppl7::AssocArray::set	(	const String &	key,
		const Pointer &	value
	)

Beschreibung:

Diese Funktion fügt den Inhalt des Pointers value unter dem Schlüssel key in das Assoziative Array ein.

Parameter

[in]	key	Name des Schlüssels
[in]	value	Daten

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel

void ppl7::AssocArray::set	(	const String &	key,
		const Variant &	value
	)

Beschreibung:

Diese Funktion fügt den Inhalt des Variants value unter dem Schlüssel key in das Assoziative Array ein.

Parameter

[in]	key	Name des Schlüssels
[in]	value	Daten

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel
TypeConversionException	Der Datentyp des Variants wurde nicht erkannt oder wird nicht unterstützt.

void ppl7::AssocArray::setf	(	const String &	key,
		const char *	fmt,
			...
	)

Beschreibung:

Diese Funktion fügt den Inhalt eines formatierten Strings dem Array hinzu.

Parameter

[in]	key	Name des Schlüssels
[in]	fmt	Pointer auf den Format-String des Wertes
[in]	...	Beliebig viele Parameter, die vom Formatstring verwendet werden

Ausnahmebehandlung

std::bad_alloc	Kein Speicher mehr frei
OutOfMemoryException	Kein Speicher mehr frei
InvalidKeyException	Ungültiger Schlüssel

size_t ppl7::AssocArray::size

(

)

const

Beschreibung:

Diese Funktion liefert die Anzahl Elemente auf dieser Ebene des Arrays zurück.

Rückgabe

Anzahl Elemente

void ppl7::AssocArray::toTemplate	(	String &	s,
		const String &	prefix = "",
		const String &	linedelimiter = "\n",
		const String &	splitchar = "="
	)		const

Beschreibung:

Mit dieser Funktion wird der textuelle Inhalt des Arrays als Template im Key-Value-Format in einem String abgelegt. Pointer oder Binäre Daten werden ignoriert.

Parameter

[out]	s	String, in dem das Template gespeichert werden soll. Der String wird von der Funktion nicht gelöscht, der Inhalt des Arrays wird angehangen!
[in]	prefix	Optionaler Prefix, der jedem Key vorangestellt werden soll
[in]	linedelimiter	Optionaler Pointer auf einen String, der am Zeilenende ausgegeben werden soll. Der Default ist ein einzelnes Newline.
[in]	splitchar	Optionaler Pointer auf einen String, der als Trennzeichen zwischen Schlüssel und Wert verwendet werden soll. Der Default ist ein Gleichheitszeichen.

Beispiel

#include <stdio.h>
#include <string.h>
#include <ppl7.h>

int main(int argc, char **argv)
{
    ppl7::AssocArray a;
    ppl7::ByteArray bin;
    ppl7::String out;
    bin.load("main.cpp");
    a.set("key1","Dieser Wert geht über\nmehrere Zeilen");
    a.set("array1/unterkey1","value2");
    a.set("array1/unterkey2","value3");
    a.set("array1/noch ein array/unterkey1","value4");
    a.set("array1/unterkey2","value5");
    a.set("key2","value6");
    a.set("dateien/main.cpp",&bin);
    a.set("array2/unterkey1","value7");
    a.set("array2/unterkey2","value8");
    a.set("array2/unterkey1","value9");
    a.toTemplate(&out,"foo");
    out.printnl();
}

Ergebnis:

foo/array1/noch ein array/unterkey1=value4
foo/array1/unterkey1=value2
foo/array1/unterkey2=value5
foo/array2/unterkey1=value9
foo/array2/unterkey2=value8
foo/key1=Dieser Wert geht über
foo/key1=mehrere Zeilen
foo/key2=value6

An diesem Beispiel sieht man, dass Pointer- und ByteArray-Werte nicht exportiert werden und Werte, die Zeilenumbrüche enthalten, werden auf mehrere Key-Value-Paare aufgesplittet. Die Importfunktion (AssocArray::fromTemplate, AssocArray::fromConfig) fügen diese wieder zu einer einzelnen Variable mit Zeilenumbruch zusammen.

Dokumentation der Datenelemente

ppluint64 ppl7::AssocArray::maxint

private

size_t ppl7::AssocArray::num

private

ppl7::AVLTree<ArrayKey, ValueNode> ppl7::AssocArray::Tree

private

---

Die Dokumentation für diese Klasse wurde erzeugt aufgrund der Dateien:

• /jenkins/jobs/clang_ppl7/workspace/include/ppl7-types.h
• /jenkins/jobs/clang_ppl7/workspace/src/types/AssocArray.cpp