std.buffer — Byte-Puffer

→ Zurück zur Unit-Übersicht

Operationen auf rohen Speicherbereichen: kopieren, füllen, umkehren, vergleichen, suchen, in Hex umwandeln und zurück. Die Unit allokiert nichts — jeder Puffer kommt vom Aufrufer, jede Funktion bekommt die Länge mitgeteilt.

Genau daraus folgt ihre wichtigste Eigenschaft: sie ist binärsicher. Nullbytes mitten in den Daten beenden nichts, Werte über 127 werden unverändert durchgereicht.

Einsatzbereiche: Protokollrahmen, Binärformate, Zwischenschicht für Netzwerk- und Krypto-Units.

Autor: Andreas Röne
Copyright: 2024–2025 Andreas Röne
Quelle: std/buffer.lyx

<WRAP info> Diese Unit ist vollständig geprüft und arbeitet fehlerfrei — einschließlich des Hex-Rundlaufs über alle Bytewerte von 0 bis 255 und der Suche in Daten mit eingebetteten Nullbytes. Zu beachten sind lediglich die Aufrufkonventionen unter Worauf zu achten ist. </WRAP>

import std.buffer;

Die ersten beiden sind reine Empfehlungen — keine Funktion der Unit verwendet sie.

BufferFind liefert auch dann -1, wenn die Nadel leer ist (nlen == 0) oder länger als der Heuhaufen — nicht 0, wie es manche Textsuchen tun.

BufferCopy setzt voraus, dass sich Quelle und Ziel nicht überlappen — es wird von vorn nach hinten kopiert.

HexToBuffer akzeptiert Groß- und Kleinschreibung und meldet -1 bei ungerader Länge oder Zeichen außerhalb von 0–9/A–F/a–f. Ein leerer String ergibt 0.

Die beiden Base64-Rechner geben nur Größen zurück; die Kodierung selbst liegt in std.base64, das mit EncodedLen eine namensgleiche Funktion mitbringt. Beide liefern dieselben Werte — geprüft für Eingabelängen 1 bis 8 gegen die tatsächliche Ausgabe von EncodeBytes.

import std.buffer;
import std.alloc;

fn main(): int64 {
    // Binaerdaten mit Nullbytes und Werten ueber 127
    var bin: int64 := alloc(8);
    poke8(bin, 0);     poke8(bin+1, 15);  poke8(bin+2, 16);  poke8(bin+3, 127);
    poke8(bin+4, 128); poke8(bin+5, 200); poke8(bin+6, 254); poke8(bin+7, 255);

    // Als Hex ausgeben
    var hex: int64 := alloc(32);
    var n: int64 := BufferToHex(bin as pchar, 8, hex as pchar);
    PrintLn("BufferToHex: ", IntToStr(n), " Zeichen -> ", hex as pchar);

    // und wieder zurueck
    var zurueck: int64 := alloc(16);
    var m: int64 := HexToBuffer(hex as pchar, zurueck as pchar);
    PrintLn("HexToBuffer: ", IntToStr(m), " Bytes, identisch? ",
            IntToStr(BufferEquals(bin as pchar, 8, zurueck as pchar, 8) as int64));

    // Suchen und Vergleichen arbeiten laengenbasiert, Nullbytes stoeren nicht
    var muster: int64 := alloc(4);
    poke8(muster, 128); poke8(muster+1, 200);
    PrintLn("Find(Muster 128 200) = ", IntToStr(BufferFind(bin as pchar, 8, muster as pchar, 2)));

    // Textpuffer zusammensetzen
    var buf: int64 := alloc(64);
    var len: int64 := BufferCopy(buf as pchar, "Hallo" as pchar, 5);
    len := BufferAppendString(buf as pchar, len, " Welt" as pchar, 64);
    PrintLn("nach Append: ", IntToStr(len), " Bytes");
    var text: int64 := alloc(64);
    BufferToString(buf as pchar, len, text as pchar);
    PrintLn("als String:  '", text as pchar, "'");

    // Wachstum planen
    PrintLn("CalculateCapacity(256, 300)  = ", IntToStr(BufferCalculateCapacity(256, 300)));
    PrintLn("CalculateCapacity(256, 5000) = ", IntToStr(BufferCalculateCapacity(256, 5000)));
    return 0;
}

Ausgabe:

BufferToHex: 16 Zeichen -> 000F107F80C8FEFF
HexToBuffer: 8 Bytes, identisch? 1
Find(Muster 128 200) = 4
nach Append: 10 Bytes
als String:  'Hallo Welt'
CalculateCapacity(256, 300)  = 512
CalculateCapacity(256, 5000) = 5000

Der Hex-Rundlauf umfasst hier bewusst das Nullbyte, die Grenzwerte 127/128 und 255 — alle acht Bytes kommen unverändert zurück.

Keine Funktion kennt die Größe der übergebenen Puffer. BufferCopy(dest, src, 1000) schreibt tausend Bytes, gleich wie groß dest ist; BufferToHex braucht 2·len + 1 Bytes im Ziel, BufferToString len + 1. Diese Größen rechnet der Aufrufer aus.

Einzige Ausnahme ist BufferAppendString: dort begrenzt max_out das Ziel.

Die Funktion hängt nur die Zeichen an und gibt die neue Länge zurück. Ein Nullbyte setzt sie nicht — dafür ist BufferToString da:

var len: int64 := BufferCopy(buf as pchar, "Hallo" as pchar, 5);
len := BufferAppendString(buf as pchar, len, " Welt" as pchar, 64);
BufferToString(buf as pchar, len, text as pchar);     // erst hier entsteht ein String

Die Platzprüfung lautet buf_len + str_len >= max_out — ein Byte bleibt also für die spätere Nullterminierung frei. Bei max_out = 13 und einem Ergebnis von genau 13 Bytes kommt deshalb -1 zurück.

Es schreibt genau zwei Zeichen an den Anfang des Puffers. Was dahinter steht, bleibt stehen:

Puffer vorher 'XXX', ByteToHex(255, puffer)  ->  'FFX'

Für einen einzelnen Bytewert als Zeichenkette also selbst terminieren, oder BufferToHex mit len = 1 verwenden.

BufferCopy kopiert vorwärts. Überlappen sich Quelle und Ziel so, dass das Ziel hinter der Quelle liegt, werden bereits kopierte Bytes erneut gelesen. Für Verschiebungen innerhalb eines Puffers zuerst in einen Zwischenpuffer kopieren.

BufferToHex und ByteToHex geben A–F aus. HexToBuffer liest beide Schreibweisen.

• std.base64 — die eigentliche Base64-Kodierung
• std.alloc — Puffer beschaffen und freigeben
• std.pack — Zahlen und Strings strukturiert in Puffer schreiben
• std.string — Funktionen für nullterminierte Zeichenketten