obj_save¶
obj_save speichert ein Objekt in einer Datei oder in einer Zeichenkette als XML-Datei oder Binärdatei.
- ret = obj_save(obj, ssFilename)
- ret = obj_save(obj, ssFilename, ssFormat)
- ssXMLString = obj_save(obj, "")
Returnwert
Falls ssFilename ein vollständiger Dateiname ist, ist ret ungleich 0, wenn die Funktion erfolgreich war und 0 wenn die Funktion fehlgeschlagen ist. Falls der Dateiname die Extension .uso (für Uni Script Object) hat, wird die Datei in einem binären Format gespeichert.
Falls ssFilename ein leerer String (""
) ist, ist der Returnwert ein String
mit dem XML-Code des Objekts obj oder, falls für ssFormat "binary"
,
"b"
oder "uncompressed-binary"
oder "u"
angegeben wurde, das Objekt
in einem Binärformat.
Parameter
- obj
obj ist ein mit obj_create erzeugtes Objekt.
- ssFilename
ssFilename ist der komplette Dateiname oder ein leerer String (
""
) (siehe ret).
- ssFormat
ssFormat ist entweder ein Format-String der angibt, wie Zahlen gespeichert werden sollen (siehe printf) (der Default-Wert ist
"%.20g"
) oder der String"binary"
oder"b"
bzw."uncompressed-binary"
oder"u"
um die Datei in einem binären Dateiformat zu speichern.
Beispiel
obj = obj_create()
obj[1] = 123
obj.a = "Hello"
obj.c = obj_create()
obj.c.d = 456
obj.save("d:\\test.xml")
erzeugt die folgende xml-Datei:
<?xml version='1.0' encoding='utf-8'?>
<obj id='1'>
<number ikey='1'>123</number>
<string key='a'>Hello</string>
<obj id='2' key='c'>
<number key='d'>456</number>
</obj>
</obj>
Ein leerer String speichert den XML-Text in einem String:
s = obj.save("")
Die Angabe "binary"
erzeugt ein binäres Format:
s = obj.save("", "binary")
mem_dump(s)
Kommentar
Anmerkungen
Das Speichern von Objekten als Binärdatei ist wesentlich schneller als das Speichern als XML-Datei, insbesondere wenn die Datei viele große Vektoren oder Matrizen enthält, Faktor 50 oder mehr.
Das Speichern in einem String eignet sich nur für Objekte mit einigen, wenigen MB. Größere Objekte mit mehreren Megabytes an Daten sollten in Dateien gespeichert werden.
XML-Schema
Beschreibung des relax-ng Schemas der XML-Dateien (siehe auch http://relaxng.org/compact-tutorial-20030326.html):
obj = element obj { obj_attlist, (obj_inner | simple)* }
obj_attlist = attribute id { xsd:positiveInteger }?
simple =
number
| \string
| complex
| number-matrix
| string-matrix
| complex-matrix
| variant-matrix
obj_inner = element obj { obj_inner_attlist, simple* }
obj_inner_attlist =
key_or_ikey,
attribute id { xsd:positiveInteger }?,
attribute ref { xsd:positiveInteger }?
#
number = element number { key_or_ikey, xsd:double }
\string = element string { string_attlist, text }
string_attlist =
key_or_ikey,
attribute encoding { xsd:string "base64" }?
complex = element complex { key_or_ikey, cpx }
#
mat_number = element number { xsd:double }
mat_string = element string { mat_string_attlist, text }
mat_string_attlist = attribute encoding { xsd:string "base64" }?
mat_complex = element complex { cpx }
#
number-matrix = element number-matrix { matrix_attlist, mat_number+ }
string-matrix = element string-matrix { matrix_attlist, mat_string+ }
complex-matrix = element complex-matrix { matrix_attlist, mat_complex+ }
variant-matrix =
element variant-matrix {
matrix_attlist, (mat_number | mat_string | mat_complex)+
}
cpx = xsd:string { pattern = "[\-+]?[0-9]*\.?[0-9]+([eE][\-+]?[0-9]+)?[\-+][0-9]*\.?[0-9]+([eE][\-+]?[0-9]+)?i" }
key_or_ikey =
attribute key { text }
| attribute ikey { xsd:double }
row_cols =
attribute rows { xsd:positiveInteger },
attribute cols { xsd:positiveInteger }
matrix_attlist = key_or_ikey, row_cols
Binärformat
header: "USO" version-number
object: 'o' len ikey id-or-ref
object: 'p' len key id-or-ref
endofobj: ')'
double: 'n' ikey data
double: 'm' key data
string: 's' ikey string
string: 't' key string
complex: 'c' ikey cdata
complex: 'd' key cdata
matrix: 'N' len ikey shape data
matrix: 'M' len key shape data
smatrix: 'S' len ikey shape string
smatrix: 'T' len key shape string
cmatrix: 'C' len ikey shape cdata
cmatrix: 'D' len key shape cdata
vmatrix: 'V' len ikey shape vdata
vmatrix: 'W' len key shape vdata
Alle Werte werden in Little-Endian byte order (LEBO) gespeichert.
Dem Header (4 Bytes) folgt ein Objekt ‚o‘ mit der ID=1 und dem ikey=0.0. Dem Objekt folgen beliebig viele Objekte oder andere Datenelemente. Jedes Objekt wird mit einem endofobj: ‚)‘ beendet.
version-number |
byte, diese Version hat die Nummer 1. |
len |
Alle Matrizen und Objekte haben hinter dem Tag die Länge des Elementes als 64-Bit Integer gespeichert. |
ikey |
Zahlenkey (double - 8 Bytes). |
key |
keylen (int32) in Bytes, gefolgt beliebig vielen UTF-16-Zeichen. In keys sind beliebige UNICODE-Zeichen erlaubt, aber keine null-Zeichen. |
id_or_ref |
(int32), ID des Objekts (1, 2, …) oder, falls id_or_ref eine negative Zahl ist, Referenz auf ein anderes Objekt. |
shape |
nrows (int32) ncols (int32). Anzahl an Zeilen und Spalten einer Matrix. Die Elemente der Matrix werden spaltenweise gespeichert: a[1;1], a[2;1], … |
string |
len (int32) in Bytes, gefolgt von UTF-16-Zeichen oder beliebigen Bytes (auch 0-Bytes). |
data |
Matrix mit Zahlen (double - 8 Bytes). Falls nicht das Format
|
cdata |
Matrix mit komplexen Elementen (jeweils zwei double-Werte: real, imag). |
vdata |
Variantmatrix. Elemente können Zahl, komplexe Zahl, String oder Objekt sein. Vor den Daten steht jeweils ein Kennbyte: ‚n‘, ‚c‘, ‚s‘, ‚o‘. |
Zyklische Referenzen
Die Funktion kann auch Objekte speichern, die zyklische Referenzen enthalten, z. B.
obj = obj_create()
obj.val = 123
obj.next = obj_create()
obj.next.val = 456
obj.next.next = obj
obj.save("d:\\test1.xml")
erzeugt folgende Datei (beachte Attribute id
und ref
):
<?xml version='1.0' encoding='utf-8'?>
<obj id='1'>
<obj id='2' key='next'>
<obj key='next' ref='1'/>
<number key='val'>456</number>
</obj>
<number key='val'>123</number>
</obj>
History
Version |
Beschreibung |
---|---|
R2014.3 |
Objekte können nun auch in einem Binärformat gespeichert werden. |
5.10.0 |
Für den Dateinamen kann ein leerer String angegeben werden, um das Objekt in einem String anstatt einer Datei zu speichern. |
5.0.0 |
Unicode-Änderungen. |
4.1.0 |
Neu. |
Siehe auch
id-699932