CXI-Basis-Programmierreferenz / Version 2 / Datenspeicherung / CxiNode / Zeichenketten /

GetItem - Zeichenkette direkt abfragen

const char * CxiNode :: GetItem (CxiName pname, int index = -1, const char *pdef = 0, CxiLong options = 0) const
const char * cxiGetItem (CxiHandle self, CxiName pname, int index, const char *pdef, CxiLong options)

Fragt eine String-Variable oder ein Element einer Stringliste direkt ab

pname:
Name der Variablen

index:
Index innerhalb der Stringliste (siehe Text)

pdef:
Rückgabewert für den Fehlerfall (Vorgabe NULL)

options:
Steuerparameter (s.u.)

return:
bei Erfolg Adresse des Wertes der Variablen im CxiNode-Datenpuffer, im Fehlerfall pdef

Mit dem Parameter options kann die Arbeitsweise beeinflusst werden, der Wert ist eine ODER-Verknüpfung verschiedener Angaben:

cxiOptGetItemNoNull angegeben:
Im Fehlerfall wird niemals ein NULL-Zeiger zurückgegeben.

cxiOptGetItemStr angegeben:
Im Fehlerfall wird ein Leerstring ("") zurückgegeben.

Keine Option angegeben (Vorgabe):
Im Fehlerfall wird pdef zurückgegeben.

Die Elemente einer Variable vom Typ cxiTypeLst werden beginnend mit 0 durchnummeriert. Der Parameter index gibt entweder direkt die Nummer des gewünschten Elements an (Werte größer oder gleich 0), oder er ist eine relative Position vom Ende der Liste ausgehend (negativer Wert). Der Wert 0 kennzeichnet also das erste, -1 das letzte Element der Liste. Variablen vom Typ cxiTypeStr werden als einelementige Listen aufgefasst, bei diesen muss also der Index 0 oder -1 angegeben werden; alle anderen Angaben für den Index werden als Fehler zurückgewiesen.

Die Funktionen GetItemStr und GetItemTest stellen häufig benötigte Spezialfälle dieser Funktion dar.

ACHTUNG: Es wird direkt ein Zeiger auf den Datenbereich des CXI-Objekts zurückgegeben. Dieser Zeiger ist bis zur nächsten Änderung des Blocks (oder einem Wechsel des Sichtfensters im CXI-Baum) gültig. Der Bereich, auf den der Zeiger zeigt, darf unter keinen Umständen direkt verändert werden.

Nur Strings und String-Listen können mit dieser Funktion abgefragt werden.

Resource-Referenzen werden aufgelöst. Ist dies nicht möglich, wird ein Fehler zurückgegeben. Achtung! Wird eine Resource-Referenz erfolgreich aufgelöst, so zeigt der zurückgelieferte Zeiger in den Resource-Block!

Der zurückgegebene Zeiger darf NICHT direkt als Parameter in einem Funktionsaufruf verwendet werden, der den Inhalt des Blocks oder eines seiner Resource-Blöcke verändert. Geschieht dies doch, ist das Verhalten des Programms undefiniert. In einigen Fällen erkennt CXI einen Missbrauch eines solchen Zeigers und liefert den Fehler cxiErrorIllegalItemPointer.

Portabilität:
Diese Funktion ist in allen unterstützten Systemen verfügbar.

Siehe auch:
GetItemStr
GetItemTest
QueryItemCount
FindInList
IsInList
IsEqual...
GetStr
GetAsStr
GetAsNum
GetLst
SetStr (mit Beispiel)
SetLst
InsertItem
AppendItem
DeleteItem