Changeset 2742

Show
Ignore:
Timestamp:
03/16/08 10:55:24 (10 months ago)
Author:
hans
Message:

Translate documentation to english.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/bknr/datastore/src/data/encoding.lisp

    r2626 r2742  
    1 ;;;; Schreiben und Lesen von Lisp-Objekten in einem Binaerformat. 
     1;;;; Reading and writing Lisp objects in a binary format. 
    22 
    33;;; Design: 
    44;;; 
    5 ;;;   - relativ kompakter Output 
    6 ;;; 
    7 ;;;   - keine willkuerlichen Beschraenkungen 
    8 ;;;     Integers duerfen z.B. beliebig gross sein. 
    9 ;;; 
    10 ;;;   - Aber generell Performance vor Features 
    11 ;;;     Insbesondere wird nicht auf Zyklen geprueft! 
    12  
    13 ;;; Fuer jeden unterstuetzten Datentyp ist ein Buchstabe als Tag definiert, 
    14 ;;; am dem beim Lesen den Typ wieder erkannt werden kann. 
    15 ;;; 
    16 ;;; Mittels der Funktionen ENCODE und DECODE kann ein beliebiges Objekt 
    17 ;;; geschrieben bzw. gelesen werden.  Sie werten automatisch den Datentype 
    18 ;;; (beim Schreiben) bzw. das Tag (beim Lesen) aus. 
    19 ;;; 
    20 ;;; Ist der Datentyp ohnehin bekannt, koennen die entsprechenden Funktionen 
    21 ;;; auch direkt aufgerufen werden.  Z.B. schreibt ENCODE-INTEGER ein Integer. 
    22 ;;; 
    23 ;;; Ist an der entsprechenden Stelle im File ueberhaupt nur ein Integer 
    24 ;;; sinnvoll, kann zusaetzlich auch noch das Tag entfallen.  Dazu gibt es 
    25 ;;; im Allgemeinen eine low-level Funktion, z.B. %ENCODE-INTEGER, die nur 
    26 ;;; die eigentlichen Daten ohne Tag schreibt, und eine zugehoerige Funktion 
    27 ;;; DECODE-INTEGER, die solche Daten liest. 
     5;;;   - compact storage requirements 
     6;;;   - no arbitary limits (e.g. integers may be arbitarily large) 
     7;;;   - high read and write performance, thus no checking for cyclic data 
     8 
     9;;; For every supported data type, a character is defined as tag denoting 
     10;;; the type when reading. 
     11;;; 
     12;;; The functions ENCODE and DECODE encode and decode an arbitary object. 
     13;;; Upon write, ENCODE determines the data type from the lisp data type. 
     14;;; Upon read, DECODE determines the data type of the object by looking at 
     15;;; the tag character. 
     16;;; 
     17;;; If the data type is known upfron, the respective coder function can be 
     18;;; called directly.  ENCODE-INTEGER encodes an integer, for example. 
     19;;; 
     20;;; At certain file positions, only one datatype makes sense (i.e. when 
     21;;; writing a structure with a fixed layout).  In this case, the tag need 
     22;;; not be written.  For this purpose, a low-level function, i.e. 
     23;;; %ENCODE-INTEGER, exists to write the object without writing a tag, 
     24;;; and a matching decode function DECODE-INTEGER to read such untagged 
     25;;; data. 
    2826 
    2927;;; Format: 
    3028 
    31 ;;;    Feld    Format     Kommentar 
     29;;;    Field    Format     Comment 
    3230;;; ---------------------------------------------------------------- 
    3331;;; Integer 
    3432;;;     tag     #\i 
    35 ;;;     n       byte       Laenge der folgenden Bytesequenz 
    36 ;;;     data    byte[n]    Die eigentlich Zahl, Big Endian 
    37 ;;; ---------------------------------------------------------------- 
    38 ;;; Referenz auf Store-Object 
     33;;;     n       byte       Number of bytes that follow 
     34;;;     data    byte[n]    The actual data, a big endian number 
     35;;; ---------------------------------------------------------------- 
     36;;; Reference to a STORE-OBJECT 
    3937;;;     tag     #\o 
    40 ;;;     ID      %integer   Die ID des bezeichneten Objektes 
    41 ;;; 
    42 ;;; ---------------------------------------------------------------- 
    43 ;;; Liste 
     38;;;     ID      %integer   ID of the referenced object 
     39;;; 
     40;;; ---------------------------------------------------------------- 
     41;;; List 
    4442;;;     tag     #\l 
    45 ;;;     n       %integer   Anzahl der folgenden Objekte 
    46 ;;;     data    object[n]  Objekte mit Tag 
    47 ;;;     tail    object     Falls n != 0: CDR des letzten Conses 
     43;;;     n       %integer   Number of bytes that follow 
     44;;;     data    object[n]  Objects including tag 
     45;;;     tail    object     If n != 0: CDR of the last cons 
    4846;;; 
    4947;;; ---------------------------------------------------------------- 
    5048;;; Char 
    5149;;;     tag     #\c 
    52 ;;;     data    char       Zeichen, mit WRITE-CHAR geschrieben 
     50;;;     data    char       Character, written with WRITE-CHAR 
    5351;;; ---------------------------------------------------------------- 
    5452;;; String 
    5553;;;     tag     #\s 
    56 ;;;     n       %integer   Anzahl der folgenden Zeichen 
    57 ;;;     data    char[n]    Zeichen wie von WRITE-CHAR geschrieben (!) 
    58 ;;; (Das exakte Format haengte also vom External-Format des Streams ab. 
    59 ;;; Es kann sich um Latin-1, UTF-8, UTF-16 oder was-auch-immer handeln.) 
     54;;;     n       %integer   Number of bytes that follow 
     55;;;     data    char[n]    Characters, written with WRITE-CHAR 
     56;;; Note that the layout of strings will change to not use WRITE-CHAR 
    6057;;; 
    6158;;; ---------------------------------------------------------------- 
    6259;;; Symbol 
    6360;;;     tag     #\y 
    64 ;;;     package %string    Name des Home-Pakets des Symbols 
    65 ;;;     name    %string    Name des Symbols 
     61;;;     package %string    Name of the home package of the symbol 
     62;;;     name    %string    Name of the symbol 
    6663;;; 
    6764;;; ---------------------------------------------------------------- 
    …… 
    7067;;;     test    %symbol    hash-table-test-function 
    7168;;;     r.-size %double    hash-table-rehash-size 
    72 ;;;     n       %integer   Anzahl der folgenden Wertepaare 
    73 ;;;     data    pair[n]    Wertepaare im folgenden Format: 
     69;;;     n       %integer   Number of value pairs that follow 
     70;;;     data    pair[n]    Value pairs in the following format 
    7471;;; 
    7572;;;   pair: 
    76 ;;;     key     object     Objekt mit Tag 
    77 ;;;     value   object     Objekt mit Tag 
     73;;;     key     object     Objekt with tag 
     74;;;     value   object     Objekt with tag 
    7875;;; 
    7976;;; ---------------------------------------------------------------- 
    …… 
    9895;;; 
    9996;;;   if (flags has bit 0 set) { 
    100 ;;;     length  %integer          Laenge des Vektors 
     97;;;     length  %integer          Length of fector 
    10198;;;   } else { 
    102 ;;;     n       %integer          Anzahl der folgenden Dimensionen 
     99;;;     n       %integer          Number of dimensions following 
    103100;;;     dims    %integer[n]       ARRAY-DIMENSIONS 
    104101;;;   }  
    …… 
    108105;;;   } 
    109106;;; 
    110 ;;;     data    object[\Pi dims]  Daten in row-major-order 
     107;;;     data    object[\Pi dims]  Data in row-major-order 
    111108;;; 
    112109;;; ----------------------------------------------------------------