array — Platzsparende Arrays numerischer Werte

Dieses Modul definiert einen Objekttyp, der ein Array einfacher Werte platzsparend darstellen kann: Zeichen, ganze Zahlen, Gleitkommazahlen und komplexe Zahlen. Arrays sind veränderliche Sequenz-Typen und verhalten sich weitgehend wie Listen, nur dass der Typ der darin gespeicherten Objekte festgelegt ist. Dieser Typ wird beim Erzeugen des Objekts über einen Typcode angegeben. Die folgenden Typcodes sind definiert:

Typcode

C-Typ

Python-Typ

Mindestgröße in Bytes

Hinweise

'b'

signed char

int

1

'B'

unsigned char

int

1

'u'

wchar_t

Unicode-Zeichen

2

(1)

'w'

Py_UCS4

Unicode-Zeichen

4

(2)

'h'

signed short

int

2

'H'

unsigned short

int

2

'i'

signed int

int

2

'I'

unsigned int

int

2

'l'

signed long

int

4

'L'

unsigned long

int

4

'q'

signed long long

int

8

'Q'

unsigned long long

int

8

'e'

_Float16

float

2

(3)

'f'

float

float

4

'd'

double

float

8

'Zf'

float complex

complex

8

(4)

'Zd'

double complex

complex

16

(4)

Hinweise:

  1. Je nach Plattform können es 16 oder 32 Bit sein.

    Geändert in Version 3.9: array('u') verwendet jetzt wchar_t als C-Typ anstelle des veralteten Py_UNICODE. Diese Änderung wirkt sich nicht auf das Verhalten aus, weil Py_UNICODE seit Python 3.3 ein Alias für wchar_t ist.

    Veraltet seit Version 3.3, wird in Version 3.16 entfernt: Bitte wechsle zum Typcode 'w'.

  2. Added in version 3.13.

  3. Der Typ IEEE 754 binary16 mit „halber Genauigkeit“ wurde mit der Fassung von 2008 des IEEE-754-Standards eingeführt. C-Compiler unterstützen diesen Typ nicht durchgängig. Er steht als Typ _Float16 zur Verfügung, wenn der Compiler Anhang H des C23-Standards unterstützt.

    Added in version 3.15.

  4. Die komplexen Typen (Zf und Zd) stehen immer zur Verfügung, unabhängig davon, ob der C-Compiler komplexe Typen unterstützt (Anhang G des C11-Standards). Wie im C11-Standard festgelegt, wird jeder komplexe Typ durch ein C-Array aus zwei Elementen dargestellt, die den Real- und den Imaginärteil enthalten.

    Added in version 3.15.

Siehe auch

Die Module ctypes und struct sowie Module von Drittanbietern wie numpy verwenden ähnliche – aber leicht abweichende – Typcodes.

Die tatsächliche Darstellung der Werte hängt von der Maschinenarchitektur ab, genau genommen von der C-Implementierung. Die tatsächliche Größe lässt sich über das Attribut array.itemsize abfragen.

Das Modul definiert das folgende Element:

array.typecodes

Ein Tupel mit allen verfügbaren Typcodes.

Geändert in Version 3.15: Der Typ wurde von str auf tuple geändert.

Das Modul definiert den folgenden Typ:

class array.array(typecode[, initializer])

Ein neues Array, dessen Elemente durch typecode eingeschränkt sind und das aus dem optionalen Wert initializer heraus initialisiert wird. Dieser muss ein bytes- oder bytearray-Objekt, eine Unicode-Zeichenkette oder ein Iterable über Elemente des passenden Typs sein.

Wird ein bytes- oder bytearray-Objekt übergeben, geht der Initialisierer an die Methode frombytes() des neuen Arrays. Bei einer Unicode-Zeichenkette geht er an die Methode fromunicode(). Andernfalls wird der Iterator des Initialisierers an die Methode extend() übergeben, um die ersten Elemente in das Array einzufügen.

Array-Objekte unterstützen die gewöhnlichen Operationen einer veränderlichen Sequenz: Indizierung, Slicing, Verkettung und Multiplikation. Bei einer Zuweisung an ein Slice muss der zugewiesene Wert ein Array-Objekt mit demselben Typcode sein, in allen anderen Fällen wird TypeError ausgelöst. Array-Objekte setzen außerdem die Puffer-Schnittstelle um und lassen sich überall dort verwenden, wo byte-ähnliche Objekte unterstützt werden.

Arrays sind generisch über den Typ ihres Inhalts.

Löst ein Auditing-Ereignis array.__new__ mit den Argumenten typecode, initializer aus.

typecode

Das Typcode-Zeichen, mit dem das Array erzeugt wurde.

itemsize

Die Länge eines Array-Elements in Bytes in der internen Darstellung.

append(value, /)

Hängt ein neues Element mit dem angegebenen Wert an das Ende des Arrays an.

buffer_info()

Gibt ein Tupel (address, length) zurück, das die aktuelle Speicheradresse und die Länge in Elementen des Puffers nennt, in dem der Inhalt des Arrays liegt. Die Größe des Speicherpuffers in Bytes lässt sich als array.buffer_info()[1] * array.itemsize berechnen. Das ist gelegentlich nützlich, wenn du mit E/A-Schnittstellen auf niedriger Ebene arbeitest, die Speicheradressen benötigen und damit von Natur aus unsicher sind, etwa mit bestimmten ioctl()-Operationen. Die zurückgegebenen Zahlen sind gültig, solange das Array besteht und keine Operation darauf angewandt wird, die seine Länge ändert.

Bemerkung

Verwendest du Array-Objekte aus C- oder C++-Code heraus, ist die Puffer-Schnittstelle der Array-Objekte die bessere Wahl – nur von dort lassen sich diese Angaben überhaupt sinnvoll nutzen. Diese Methode wird nur aus Gründen der Rückwärtskompatibilität beibehalten und sollte in neuem Code vermieden werden. Die Puffer-Schnittstelle ist unter Buffer-Protokoll beschrieben.

byteswap()

Vertauscht die Bytes („byteswap“) aller Elemente des Arrays. Das wird nur für Werte mit einer Größe von 1, 2, 4, 8 oder 16 Bytes unterstützt, bei anderen Werttypen wird RuntimeError ausgelöst. Nützlich ist das beim Einlesen von Daten aus einer Datei, die auf einer Maschine mit anderer Byte-Reihenfolge geschrieben wurde. Beachte, dass bei komplexen Typen die Reihenfolge der Bestandteile erhalten bleibt: zuerst der Realteil, dann der Imaginärteil.

count(value, /)

Gibt zurück, wie oft value im Array vorkommt.

extend(iterable, /)

Hängt die Elemente aus iterable an das Ende des Arrays an. Ist iterable ein anderes Array, muss es genau denselben Typcode haben, sonst wird TypeError ausgelöst. Ist iterable kein Array, muss es iterierbar sein und seine Elemente müssen vom richtigen Typ sein, um an das Array angehängt werden zu können.

frombytes(buffer, /)

Hängt die Elemente aus dem byte-ähnlichen Objekt an und deutet dessen Inhalt als Array von Maschinenwerten, so als wäre er mit der Methode fromfile() aus einer Datei gelesen worden.

Added in version 3.2: fromstring() wurde zur Klarheit in frombytes() umbenannt.

fromfile(f, n, /)

Liest n Elemente als Maschinenwerte aus dem Dateiobjekt f und hängt sie an das Ende des Arrays an. Stehen weniger als n Elemente zur Verfügung, wird EOFError ausgelöst, die verfügbaren Elemente werden aber dennoch in das Array eingefügt.

fromlist(list, /)

Hängt die Elemente aus der Liste an. Das entspricht for x in list: a.append(x), nur dass das Array bei einem Typfehler unverändert bleibt.

fromunicode(ustr, /)

Erweitert dieses Array um die Daten aus der angegebenen Unicode-Zeichenkette. Das Array muss den Typcode 'u' oder 'w' haben, sonst wird ValueError ausgelöst. Verwende array.frombytes(unicodestring.encode(enc)), um Unicode-Daten an ein Array eines anderen Typs anzuhängen.

index(value[, start[, stop]])

Gibt das kleinste i zurück, sodass i der Index des ersten Vorkommens von value im Array ist. Mit den optionalen Argumenten start und stop lässt sich die Suche nach value auf einen Abschnitt des Arrays beschränken. Löst ValueError aus, wenn value nicht gefunden wird.

Geändert in Version 3.10: Die optionalen Parameter start und stop wurden hinzugefügt.

insert(index, value, /)

Fügt ein neues Element value vor der Position index in das Array ein. Negative Werte werden relativ zum Ende des Arrays gezählt.

pop(index=-1, /)

Entfernt das Element mit dem Index i aus dem Array und gibt es zurück. Das optionale Argument ist mit -1 vorbelegt, sodass voreingestellt das letzte Element entfernt und zurückgegeben wird.

remove(value, /)

Entfernt das erste Vorkommen von value aus dem Array.

clear()

Entfernt alle Elemente aus dem Array.

Added in version 3.13.

reverse()

Kehrt die Reihenfolge der Elemente im Array um.

tobytes()

Wandelt das Array in ein Array von Maschinenwerten um und gibt die Bytes-Darstellung zurück, also dieselbe Folge von Bytes, die die Methode tofile() in eine Datei schreiben würde.

Added in version 3.2: tostring() wurde zur Klarheit in tobytes() umbenannt.

tofile(f, /)

Schreibt alle Elemente als Maschinenwerte in das Dateiobjekt f.

tolist()

Wandelt das Array in eine gewöhnliche Liste mit denselben Elementen um.

tounicode()

Wandelt das Array in eine Unicode-Zeichenkette um. Das Array muss den Typ 'u' oder 'w' haben, sonst wird ValueError ausgelöst. Verwende array.tobytes().decode(enc), um aus einem Array eines anderen Typs eine Unicode-Zeichenkette zu erhalten.

Die Zeichenkettendarstellung von Array-Objekten hat die Form array(typecode, initializer). initializer fehlt, wenn das Array leer ist. Andernfalls ist es eine Unicode-Zeichenkette, falls typecode 'u' oder 'w' ist, sonst eine Liste von Zahlen. Die Zeichenkettendarstellung lässt sich zugesichert mit eval() wieder in ein Array desselben Typs und Werts zurückverwandeln, solange die Klasse array mit from array import array importiert wurde. Enthält sie entsprechende Gleitkommawerte, müssen außerdem die Variablen inf und nan definiert sein. Beispiele:

array('l')
array('w', 'hello \u2641')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14, -inf, nan])

Siehe auch

Modul struct

Packen und Entpacken uneinheitlicher Binärdaten.

NumPy

Das Paket NumPy definiert einen weiteren Array-Typ.