"struct" --- Interpret bytes as packed binary data
**************************************************

**Πηγαίος κώδικας:** Lib/struct.py

======================================================================

This module performs conversions between Python values and C structs
represented as Python "bytes" objects.  This can be used in handling
binary data stored in files or from network connections, among other
sources.  It uses Συμβολοσειρές μορφοποίησης as compact descriptions
of the layout of the C structs and the intended conversion to/from
Python values.

Σημείωση:

  By default, the result of packing a given C struct includes pad
  bytes in order to maintain proper alignment for the C types
  involved; similarly, alignment is taken into account when unpacking.
  This behavior is chosen so that the bytes of a packed struct
  correspond exactly to the layout in memory of the corresponding C
  struct.  To handle platform-independent data formats or omit
  implicit pad bytes, use "standard" size and alignment instead of
  "native" size and alignment: see Διάταξη Byte, Μέγεθος και Στοίχιση
  for details.

Αρκετές συναρτήσεις του "struct" (και μέθοδοι της κλάσης "Struct")
δέχονται μια παράμετρο *buffer*. Αυτή αναφέρεται σε αντικείμενα που
υλοποιούν τα Buffer Protocol και παρέχουν είτε ένα αναγνώσιμο είτε
έναν αναγνώσιμο-εγγράψιμο buffer. Οι πιο συνηθισμένοι τύποι που
χρησιμοποιούνται για αυτόν τον σκοπό είναι οι "bytes" και "bytearray",
αλλά πολλοί άλλοι τύποι που μπορούν να θεωρηθούν ως πίνακες bytes
υλοποιούν το πρωτόκολλο buffer, επιτρέποντας την ανάγνωση/τροφοδότηση
χωρίς επιπλέον αντιγραφή από ένα αντικείμενο "bytes".


Συναρτήσεις και εξαιρέσεις
==========================

Το module ορίζει την ακόλουθη εξαίρεση και συναρτήσεις:

exception struct.error

   Εξαίρεση που γίνεται raise σε διάφορες περιπτώσεις· το όρισμα είναι
   μια συμβολοσειρά που περιγράφει το σφάλμα.

struct.pack(format, v1, v2, ...)

   Επιστρέφει ένα αντικείμενο τύπου bytes που περιέχει τις τιμές *v1*,
   *v2*, ... πακεταρισμένες σύμφωνα με τη συμβολοσειρά μορφοποίησης
   *format*. Τα ορίσματα πρέπει να ταιριάζουν ακριβώς με τις
   απαιτούμενες τιμές της μορφοποίησης.

struct.pack_into(format, buffer, offset, v1, v2, ...)

   Πακετάρει τις τιμές *v1*, *v2*, ... σύμφωνα με τη συμβολοσειρά
   μορφοποίησης *format* και γράφει τα πακεταρισμένα bytes στον
   εγγράψιμο buffer *buffer* ξεκινώντας από τη θέση *offset*.
   Σημειώστε ότι το *offset* είναι υποχρεωτικό όρισμα.

struct.unpack(format, buffer)

   Αποσυμπιέζει από τον buffer *buffer* (ο οποίος υποτίθεται έχει
   πακεταριστεί με τη μέθοδο "pack(format, ...)") σύμφωνα με την
   συμβολοσειρά μορφοποίησης *format*. Το αποτέλεσμα είναι μια
   πλειάδα, ακόμα κι αν περιέχει μόνο ένα στοιχείο. Το μέγεθος του
   buffer σε bytes πρέπει να ταιριάζει με το απαιτούμενο μέγεθος
   σύμφωνα με τη μορφή, όπως καθορίζεται από τη συνάρτηση
   "calcsize()".

struct.unpack_from(format, /, buffer, offset=0)

   Αποσυμπιέζει από τον *buffer* ξεκινώντας από τη θέση *offset*,
   σύμφωνα με τη συμβολοσειρά μορφοποίησης *format*.  Το αποτέλεσμα
   είναι μια πλειάδα, ακόμα κι αν περιέχει μόνο ένα στοιχείο. Το
   μέγεθος του buffer σε bytes, ξεκινώντας από τη θέση *offset*,
   πρέπει να είναι τουλάχιστον το μέγεθος που απαιτείται από τη μορφή,
   όπως καθορίζεται από τη συνάρτηση "calcsize()".

struct.iter_unpack(format, buffer)

   Iteratively unpack from the buffer *buffer* according to the format
   string *format*.  This function returns an iterator which will read
   equally-sized chunks from the buffer until all its contents have
   been consumed.  The buffer's size in bytes must be a multiple of
   the size required by the format, as reflected by "calcsize()".

   Κάθε επανάληψη επιστρέφει μια πλειάδα σύμφωνα με τη συμβολοσειρά
   μορφοποίησης.

   Νέο στην έκδοση 3.4.

struct.calcsize(format)

   Επιστρέφει το μέγεθος της δομής (και κατά συνέπεια του αντικειμένου
   bytes που παράγεται από το "pack(format, ...)") που αντιστοιχεί στη
   συμβολοσειρά μορφοποίησης *format*.


Συμβολοσειρές μορφοποίησης
==========================

Format strings are the mechanism used to specify the expected layout
when packing and unpacking data.  They are built up from Χαρακτήρες
μορφής, which specify the type of data being packed/unpacked.  In
addition, there are special characters for controlling the Διάταξη
Byte, Μέγεθος και Στοίχιση.


Διάταξη Byte, Μέγεθος και Στοίχιση
----------------------------------

By default, C types are represented in the machine's native format and
byte order, and properly aligned by skipping pad bytes if necessary
(according to the rules used by the C compiler).

Εναλλακτικά, ο πρώτος χαρακτήρας της συμβολοσειράς μορφοποίησης μπορεί
να χρησιμοποιηθεί για να υποδείξει τη σειρά byte, το μέγεθος και την
ευθυγράμμιση των συσκευασμένων δεδομένων, σύμφωνα με το παρακάτω
πίνακα:

+-------------+--------------------------+------------+-------------+
| Χαρακτήρας  | Σειρά bytes              | Μέγεθος    | Στοίχιση    |
|=============|==========================|============|=============|
| "@"         | native                   | native     | native      |
+-------------+--------------------------+------------+-------------+
| "="         | native                   | τυπικό     | κανένα      |
+-------------+--------------------------+------------+-------------+
| "<"         | little-endian            | τυπικό     | κανένα      |
+-------------+--------------------------+------------+-------------+
| ">"         | big-endian               | τυπικό     | κανένα      |
+-------------+--------------------------+------------+-------------+
| "!"         | δίκτυο (= big-endian)    | τυπικό     | κανένα      |
+-------------+--------------------------+------------+-------------+

Αν ο πρώτος χαρακτήρας δεν είναι ένας από αυτούς, υποτίθεται "'@'".

Native byte order is big-endian or little-endian, depending on the
host system. For example, Intel x86 and AMD64 (x86-64) are little-
endian; Motorola 68000 and PowerPC G5 are big-endian; ARM and Intel
Itanium feature switchable endianness (bi-endian). Use "sys.byteorder"
to check the endianness of your system.

Το native μέγεθος και η στοίχιση καθορίζονται χρησιμοποιώντας την
έκφραση "sizeof" του μεταγλωττιστή C. Αυτό συνδυάζεται πάντα με την
native σειρά byte.

Το τυπικό μέγεθος εξαρτάται μόνο από τον χαρακτήρα μορφοποίησης· δείτε
τον πίνακα στην ενότητα Χαρακτήρες μορφής.

Σημειώστε τη διαφορά μεταξύ του "'@'" και "'='": και τα δύο
χρησιμοποιούν τη native σειρά byte,  αλλά το μέγεθος και η στοίχιση
του τελευταίου είναι τυποποιημένα.

Η μορφή "'!'" αντιπροσωπεύει τη σειρά byte του δικτύου, η οποία είναι
πάντα big-endian όπως ορίζεται στο IETF RFC 1700.

Δεν υπάρχει τρόπος να δηλωθεί non-native σειρά byte (να επιβληθεί
εναλλαγή byte). Χρησιμοποιήστε την κατάλληλη επιλογή "'<'" ή "'>'".

Σημειώσεις:

1. Το συμπλήρωμα (padding) προστίθεται αυτόματα μόνο μεταξύ διαδοχικών
   μελών της δομής. Δεν προστίθεται συμπλήρωμα στην αρχή ή στο τέλος
   της κωδικοποιημένης δομής.

2. Δεν προστίθεται συμπλήρωμα όταν χρησιμοποιείται non-native μέγεθος
   και στοίχιση, π.χ. με '<','>', '=', και '!'.

3. Για να ευθυγραμμίσετε το τέλος μιας δομής με την απαίτηση στοίχισης
   ενός συγκεκριμένου τύπου, τελειώστε τη μορφή με τον κωδικό για αυτό
   τον τύπο με πλήθος επαναλήψεων μηδέν. Δείτε Παραδείγματα.


Χαρακτήρες μορφής
-----------------

Οι χαρακτήρες μορφής έχουν την ακόλουθη σημασία· η μετατροπή μεταξύ
τιμών C και Python είναι προφανής, δεδομένων των τύπων τους. Η στήλη
'Τυπικό μέγεθος' αναφέρεται στο μέγεθος της συμπιεσμένης τιμής σε byte
όταν χρησιμοποιείται τυπικό μέγεθος· δηλαδή, όταν η συμβολοσειρά
μορφής ξεκινά με ένα από τα "'<'", "'>'", "'!'" or "'='". Όταν
χρησιμοποιείται το native μέγεθος, το μέγεθος της συμπιεσμένης τιμής
εξαρτάται από την πλατφόρμα.

+----------+----------------------------+----------------------+------------------+--------------+
| Μορφή    | Τύπος C                    | Τύπος Python         | Τυπικό μέγεθος   | Σημειώσεις   |
|==========|============================|======================|==================|==============|
| "x"      | συμπληρωματικό byte        | καμία τιμή           |                  |              |
+----------+----------------------------+----------------------+------------------+--------------+
| "c"      | "char"                     | bytes μήκους 1       | 1                |              |
+----------+----------------------------+----------------------+------------------+--------------+
| "b"      | "signed char"              | integer              | 1                | (1), (2)     |
+----------+----------------------------+----------------------+------------------+--------------+
| "B"      | "unsigned char"            | integer              | 1                | (2)          |
+----------+----------------------------+----------------------+------------------+--------------+
| "?"      | "_Bool"                    | bool                 | 1                | (1)          |
+----------+----------------------------+----------------------+------------------+--------------+
| "h"      | "short"                    | integer              | 2                | (2)          |
+----------+----------------------------+----------------------+------------------+--------------+
| "H"      | "unsigned short"           | integer              | 2                | (2)          |
+----------+----------------------------+----------------------+------------------+--------------+
| "i"      | "int"                      | integer              | 4                | (2)          |
+----------+----------------------------+----------------------+------------------+--------------+
| "I"      | "unsigned int"             | integer              | 4                | (2)          |
+----------+----------------------------+----------------------+------------------+--------------+
| "l"      | "long"                     | integer              | 4                | (2)          |
+----------+----------------------------+----------------------+------------------+--------------+
| "L"      | "unsigned long"            | integer              | 4                | (2)          |
+----------+----------------------------+----------------------+------------------+--------------+
| "q"      | "long long"                | integer              | 8                | (2)          |
+----------+----------------------------+----------------------+------------------+--------------+
| "Q"      | "unsigned long long"       | integer              | 8                | (2)          |
+----------+----------------------------+----------------------+------------------+--------------+
| "n"      | "ssize_t"                  | integer              |                  | (3)          |
+----------+----------------------------+----------------------+------------------+--------------+
| "N"      | "size_t"                   | integer              |                  | (3)          |
+----------+----------------------------+----------------------+------------------+--------------+
| "e"      | (6)                        | float                | 2                | (4)          |
+----------+----------------------------+----------------------+------------------+--------------+
| "f"      | "float"                    | float                | 4                | (4)          |
+----------+----------------------------+----------------------+------------------+--------------+
| "d"      | "double"                   | float                | 8                | (4)          |
+----------+----------------------------+----------------------+------------------+--------------+
| "s"      | "char[]"                   | bytes                |                  |              |
+----------+----------------------------+----------------------+------------------+--------------+
| "p"      | "char[]"                   | bytes                |                  |              |
+----------+----------------------------+----------------------+------------------+--------------+
| "P"      | "void *"                   | integer              |                  | (5)          |
+----------+----------------------------+----------------------+------------------+--------------+

Άλλαξε στην έκδοση 3.3: Προστέθηκε υποστήριξη για τις μορφές "'n'" και
"'N'".

Άλλαξε στην έκδοση 3.6: Προστέθηκε υποστήριξη για τη μορφή "'e'".

Σημειώσεις:

1. The "'?'" conversion code corresponds to the "_Bool" type defined
   by C99. If this type is not available, it is simulated using a
   "char". In standard mode, it is always represented by one byte.

2. When attempting to pack a non-integer using any of the integer
   conversion codes, if the non-integer has a "__index__()" method
   then that method is called to convert the argument to an integer
   before packing.

   Άλλαξε στην έκδοση 3.2: Added use of the "__index__()" method for
   non-integers.

3. Οι κωδικοί μετατροπής "'n'" και "'N'" είναι διαθέσιμοι μόνο για το
   native μέγεθος (επιλεγμένο ως προεπιλογή ή με τον χαρακτήρα
   διάταξης byte "'@'"). Για το τυπικό μέγεθος, μπορείτε να
   χρησιμοποιήσετε οποιαδήποτε από τις άλλες μορφές ακέραιων που
   ταιριάζουν στην εφαρμογή σας.

4. Για τους κωδικούς μετατροπής "'f'", "'d'" και "'e'", η συσκευασμένη
   αναπαράσταση χρησιμοποιεί τη μορφή IEEE 754 binary32, binary64 ή
   binary16 (αντίστοιχα για "'f'", "'d'" ή "'e'"), ανεξάρτητα από τη
   μορφή κινητής υποδιαστολής που χρησιμοποιεί η πλατφόρμα.

5. Ο χαρακτήρας μορφοποίησης "'P'" είναι διαθέσιμος μόνο για τη φυσική
   σειρά byte (επιλεγμένη ως προεπιλογή ή με τον χαρακτήρα σειράς byte
   "'@'"). Ο χαρακτήρας σειράς byte "'='" επιλέγει τη χρήση little- ή
   big-endian σειράς με βάση το σύστημα. Το module struct δεν
   ερμηνεύει αυτό ως native σειρά, επομένως η μορφή "'P'" δεν είναι
   διαθέσιμη.

6. Ο τύπος IEEE 754 binary16 "half precision" εισήχθη στην αναθεώρηση
   του 2008 του προτύπου IEEE 754 standard. Διαθέτει ένα bit προσήμου,
   έναν εκθέτη 5-bit και ακρίβεια 11-bit (με 10 bit αποθηκευμένα ρητά)
   και μπορεί να αναπαραστήσει αριθμούς μεταξύ περίπου "6.1e-05" και
   "6.5e+04" με πλήρη ακρίβεια. Αυτός ο τύπος δεν υποστηρίζεται ευρέως
   από τους μεταγλωττιστές της C: σε μια τυπική μηχανή, ένας μη
   προσημασμένος short μπορεί να χρησιμοποιηθεί για αποθήκευση, αλλά
   όχι για αριθμητικές πράξεις. Δείτε τη σελίδα της Wikipedia για τη
   half-precision floating-point format για περισσότερες πληροφορίες.

Ένας χαρακτήρας μορφοποίησης μπορεί να προηγείται από έναν ακέραιο
αριθμό επαναλήψεων. Για παράδειγμα, η συμβολοσειρά μορφοποίησης "'4h'"
σημαίνει ακριβώς το ίδιο με "'hhhh'".

Οι χαρακτήρες κενού μεταξύ των μορφοποιήσεων αγνοούνται· ωστόσο, ένας
αριθμός και η μορφή του δεν πρέπει να περιέχουν κενά.

For the "'s'" format character, the count is interpreted as the length
of the bytes, not a repeat count like for the other format characters;
for example, "'10s'" means a single 10-byte string, while "'10c'"
means 10 characters. If a count is not given, it defaults to 1.  For
packing, the string is truncated or padded with null bytes as
appropriate to make it fit. For unpacking, the resulting bytes object
always has exactly the specified number of bytes.  As a special case,
"'0s'" means a single, empty string (while "'0c'" means 0 characters).

Κατά το πακετάρισμα μιας τιμής "x" χρησιμοποιώντας μια από τις μορφές
ακεραίων ("'b'", "'B'", "'h'", "'H'", "'i'", "'I'", "'l'", "'L'",
"'q'", "'Q'"), εάν το "x" είναι εκτός του έγκυρου εύρους για αυτήν τη
μορφή, γίνεται raise μια εξαίρεση "struct.error".

Άλλαξε στην έκδοση 3.1: Προηγουμένως, ορισμένες από τις μορφές
ακεραίων περιτύλιγαν τιμές εκτός εύρους και εμφάνιζαν
"DeprecationWarning" αντί για "struct.error".

Ο χαρακτήρας μορφοποίησης "'p'" κωδικοποιεί ένα "Pascal string",
δηλαδή μια μικρή συμβολοσειρά μεταβλητού μήκους αποθηκευμένη σε
*σταθερό αριθμό byte*, που καθορίζεται από τον μετρητή. Το πρώτο byte
που αποθηκεύεται είναι το μήκος της συμβολοσειράς ή 255, όποιο είναι
μικρότερο. Ακολουθούν τα byte της συμβολοσειράς. Εάν η συμβολοσειρά
που περνά στην "pack()" είναι πολύ μεγάλη (μεγαλύτερη από τον μετρητή
μείον 1), αποθηκεύονται μόνο τα πρώτα "count-1" byte της
συμβολοσειράς. Εάν η συμβολοσειρά είναι μικρότερη από "count-1",
συμπληρώνεται με μηδενικά byte ώστε να χρησιμοποιηθούν ακριβώς τόσα
byte όσα καθορίζει ο μετρητής. Σημειώστε ότι για τη "unpack()", ο
χαρακτήρας μορφοποίησης "'p'" καταναλώνει "count" byte, αλλά η
συμβολοσειρά που επιστρέφεται δεν μπορεί ποτέ να περιέχει περισσότερα
από 255 byte.

Για το χαρακτήρα μορφής "'?'", η τιμή που επιστρέφεται είναι είτε
"True" είτε "False". Κατά την συσκευασία, χρησιμοποιείται η λογική
τιμή του αντικειμένου-ορίσματος. Είτε 0 είτε 1 στη native ή τυπική
αναπαράσταση του bool θα συσκευαστούν, και οποιαδήποτε μη μηδενική
τιμή θα είναι "True" κατά την αποσυσκευασία.


Παραδείγματα
------------

Σημείωση:

  All examples assume a native byte order, size, and alignment with a
  big-endian machine.

A basic example of packing/unpacking three integers:

   >>> from struct import *
   >>> pack('hhl', 1, 2, 3)
   b'\x00\x01\x00\x02\x00\x00\x00\x03'
   >>> unpack('hhl', b'\x00\x01\x00\x02\x00\x00\x00\x03')
   (1, 2, 3)
   >>> calcsize('hhl')
   8

Τα αποσυσκευασμένα πεδία μπορούν να ονομαστούν είτε αναθέτοντάς τα σε
μεταβλητές είτε περιτυλίγοντάς τα σε μια ονομασμένη πλειάδα:

   >>> record = b'raymond   \x32\x12\x08\x01\x08'
   >>> name, serialnum, school, gradelevel = unpack('<10sHHb', record)

   >>> from collections import namedtuple
   >>> Student = namedtuple('Student', 'name serialnum school gradelevel')
   >>> Student._make(unpack('<10sHHb', record))
   Student(name=b'raymond   ', serialnum=4658, school=264, gradelevel=8)

The ordering of format characters may have an impact on size since the
padding needed to satisfy alignment requirements is different:

   >>> pack('ci', b'*', 0x12131415)
   b'*\x00\x00\x00\x12\x13\x14\x15'
   >>> pack('ic', 0x12131415, b'*')
   b'\x12\x13\x14\x15*'
   >>> calcsize('ci')
   8
   >>> calcsize('ic')
   5

The following format "'llh0l'" specifies two pad bytes at the end,
assuming longs are aligned on 4-byte boundaries:

   >>> pack('llh0l', 1, 2, 3)
   b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'

This only works when native size and alignment are in effect; standard
size and alignment does not enforce any alignment.

Δείτε επίσης:

  Module "array"
     Πακεταρισμένη δυαδική αποθήκευση ομοιογενών δεδομένων.

  Module "xdrlib"
     Packing and unpacking of XDR data.


Κλάσεις
=======

Το module "struct" ορίζει επίσης τον ακόλουθο τύπο:

class struct.Struct(format)

   Return a new Struct object which writes and reads binary data
   according to the format string *format*.  Creating a Struct object
   once and calling its methods is more efficient than calling the
   "struct" functions with the same format since the format string
   only needs to be compiled once.

   Σημείωση:

     The compiled versions of the most recent format strings passed to
     "Struct" and the module-level functions are cached, so programs
     that use only a few format strings needn't worry about reusing a
     single "Struct" instance.

   Τα μεταγλωττισμένα αντικείμενα Struct υποστηρίζουν τις ακόλουθες
   μεθόδους και ιδιότητες:

   pack(v1, v2, ...)

      Ταυτόσημο με τη συνάρτηση "pack()", χρησιμοποιώντας τη
      μεταγλωττισμένη μορφή. ("len(result)" θα είναι ίσο με "size".)

   pack_into(buffer, offset, v1, v2, ...)

      Ταυτόσημο με τη συνάρτηση "pack_into()", χρησιμοποιώντας τη
      μεταγλωττισμένη μορφή.

   unpack(buffer)

      Ταυτόσημο με τη συνάρτηση "unpack()", χρησιμοποιώντας τη
      μεταγλωττισμένη μορφή. Το μέγεθος του buffer σε bytes πρέπει να
      είναι ίσο με "size".

   unpack_from(buffer, offset=0)

      Ταυτόσημο με τη συνάρτηση "unpack_from()", χρησιμοποιώντας τη
      μεταγλωττισμένη μορφή. Το μέγεθος του buffer σε bytes,
      ξεκινώντας από τη θέση *offset*, πρέπει να είναι τουλάχιστον
      "size".

   iter_unpack(buffer)

      Ταυτόσημο με τη συνάρτηση "iter_unpack()", χρησιμοποιώντας τη
      μεταγλωττισμένη μορφή. Το μέγεθος του buffer σε bytes πρέπει να
      είναι πολλαπλάσιο του "size".

      Νέο στην έκδοση 3.4.

   format

      Η συμβολοσειρά μορφής που χρησιμοποιήθηκε για τη δημιουργία
      αυτού του αντικειμένου Struct.

      Άλλαξε στην έκδοση 3.7: Ο τύπος της συμβολοσειράς μορφής είναι
      πλέον "str" αντί για "bytes".

   size

      Το υπολογισμένο μέγεθος της δομής (και κατά συνέπεια του
      αντικειμένου bytes που παράγεται από τη μέθοδο "pack()") που
      αντιστοιχεί στη "format".
