Technischer Artikel

PDF-Zahlen vs. JSON: NaN, Infinity und null in Delphi

"value":-.25 ist das, was ein JSON-Writer produziert, wenn er ein völlig legales PDF-Zahl-Token unverändert kopiert, und ein strenger RFC-8259-Parser gibt direkt hinter dem Minuszeichen auf. Seine Nachbarn +1.5 und 007.5 aus demselben PDF-Array scheitern genauso. PDF-Zahlen in JSON zu verwandeln heißt, jedes Token ziffernweise umzubuchstabieren, für NaN und Infinity null zu schreiben und das regionale Dezimalkomma aus der Ausgabe fernzuhalten

Vier Schreibweisen, die PDF akzeptiert und JSON ablehnt

Die beiden Grammatiken gehen in vier kleinen Details auseinander. ISO 32000-1 §7.3.3 lässt eine Zahl mit Pluszeichen beginnen, den Ganzzahlteil weglassen (.5), auf einem nackten Punkt enden (4.) und führende Nullen tragen (007.5). RFC 8259 §6 erlaubt nichts davon. Eine JSON-Zahl hat ein optionales Minus, einen Ganzzahlteil, der 0 ist oder mit einer Ziffer von 1 bis 9 beginnt, und mindestens eine Ziffer nach einem Dezimalpunkt. Die Producer haben Anspruch auf die PDF-Formen, und Generatoren, die Zahlen mit eigenem Formatierungscode drucken, samt Dateien, die jemand von Hand in einem Texteditor geflickt hat, benutzen sie

Die Kollision wird schärfer in einer Bibliothek, die den Quelltext respektiert. PDF Library for Delphi (PDFlibPas) behält für jede reale Zahl die exakten Zeichen, die sie geparst hat, ein kalibrierter Farbwert wird also unverändert zurückgespeichert statt auf die Default-vier-Dezimalstellen gerundet; die Begründung steht im Artikel zum Bewahren geparster PDF-Dezimalpräzision. Der Tokenizer bügelt .5 bereits beim Lesen in 0.5 und 4. in 4.0, und Integer werden aus ihrem Wert neu gebaut, +3 kommt also als 3 zurück. Drei Schreibweisen erreichen den Writer trotzdem wortwörtlich: ein Vorzeichen vor führendem Punkt (-.25), ein explizites Plus an einer reellen Zahl (+1.5) und führende Nullen (007.5)

Ein Writer, der diese gespeicherten Zeichen direkt in JSON klebt, produziert eine Datei, die im Editor völlig in Ordnung aussieht. Der Ärger beginnt auf dem Rückweg. SetObjectJSON gibt 0 zurück, und LastErrorCode meldet PDFLIB_ERROR_OBJECT_JSON_INVALID, also 105

PDFlibPas GetObjectJSON schreibt die von RFC 8259 abgelehnten PDF-Zahl-Tokens ziffernweise um: -.25 wird -0.25, +1.5 verliert das Plus, 007.5 wirft seine führenden Nullen ab, und Nachkommastellen wie 1.250000 überleben, weil eine Formatierung aus dem gespeicherten Double binäres Rauschen hinzufügen würde
Den exakt geparsten Text anzuhängen ließe den Export gelingen, während ein strenger Reader mit Invalid JSON number und Fehler 105 stoppt — der Writer buchstabiert jedes Token daher selbst um

Der Round Trip unten ist der schnellste Weg zu sehen, was GetObjectJSON tatsächlich ausgibt. Jede Zahl kommt eingewickelt als {"type":"number","value":...}, und die drei heiklen Tokens kommen als -0.25, 1.5 und 7.5 heraus

uses
  System.SysUtils, PDFlibrary;

var
  Lib: TPDFlib;
  JSON: AnsiString;
begin
  Lib := TPDFlib.Create;
  try
    if Lib.LoadFromFile('legacy-drawing.pdf', '') = 0 then
      raise Exception.Create('load failed');

    // Objekt 12 ist ein Array, geschrieben als [-.25 +1.5 007.5]
    JSON := Lib.GetObjectJSON(12, 0);
    if JSON = '' then
      raise Exception.CreateFmt('export failed, error %d',
        [Lib.LastErrorCode]);
    // Jedes Element liest sich als {"type":"number","value":-0.25} und so weiter

    // SetObjectJSON gibt bei Erfolg 1 zurück; für Options 0 übergeben
    if Lib.SetObjectJSON(12, JSON, 0) = 0 then
      raise Exception.CreateFmt('round trip rejected, error %d',
        [Lib.LastErrorCode]);

    Lib.SaveToFile('legacy-drawing-roundtrip.pdf');
  finally
    Lib.Free;
  end;
end;

Das Token umbuchstabieren statt neu berechnen

GetObjectJSON editiert die gespeicherten Zeichen, statt das geparste Double zu formatieren. Es liest ein optionales Vorzeichen, sammelt die Ziffern beidseits eines einzelnen Dezimalpunkts und macht dann nur die Eingriffe, auf denen JSON besteht: Das Plus fällt, führende Nullen werden auf eine gestrippt, ein leerer Ganzzahlteil wird zu 0, ein nackter Endpunkt fällt, und das Minus wird wieder vorangestellt. Ein Token, das irgendein anderes Zeichen enthält oder gar keine Ziffern, wird stattdessen aus seinem geparsten Wert mit zehn Dezimalstellen formatiert, und dieser Weg schreibt null, wenn der Wert nicht endlich ist

PDFlibPas GetObjectJSON liest das Vorzeichen, sammelt die Ziffern um einen einzelnen Dezimalpunkt und wendet nur die von JSON verlangten Eingriffe an, während jedes andere Zeichen oder eine leere Ziffernfolge auf PLJSONNumber zurückfällt, das für NaN und Infinity null statt einer Zahl schreibt
Umbuchstabieren schlägt Neuberechnen: Der Tokenizer hat .5 und 4. bereits unterwegs gebügelt, der Writer behält also jede überlebende Ziffer, und der Roundtrip rekonstruiert exakt denselben Wert
  • -.25 wird -0.25, und +.5 wird 0.5
  • +1.5 wird 1.5
  • 007.5 wird 7.5, während 0.75 bleibt, wie es ist
  • 4. wird 4, falls so ein Token den Writer überhaupt erreicht
  • 2.22221 und 1.250000 behalten jede Nachkommastelle, Nachlaufnullen eingeschlossen

Aus dem Double zu formatieren wäre ein Einzeiler gewesen, und er wäre auf zwei Arten falsch gewesen. Die Default-Ausgabegenauigkeit des Dokuments liegt bei vier Dezimalstellen, 2.22221 verlöre also eine Ziffer. Die Genauigkeit anzuheben rettet es auch nicht: 0.1 hat keine exakte Binärform, und eine 17-signifikante-Stellen-Konvertierung druckt 0.10000000000000001. Die Originalziffern zu behalten bedeutet, dass SetObjectJSON und ImportObjectJSON, die jede JSON-Zahl an den PDF-Tokenizer zurückreichen, exakt den Wert neu aufbauen, den die Datei deklariert hat

Dieses Versprechen deckt den Wert. Die Bytes sind eine andere Sache. Nach einem Re-Import wird -.25 als -0.25 gespeichert und gesichert; beide Schreibweisen sind unter §7.3.3 gleich, ein Byte-Level-Diff flaggt die Änderung trotzdem. Bei einem Dokument, dessen Byte-Bereiche von einer Signatur gedeckt sind, würden wir Objekte gar nicht erst durch einen Export-und-Import-Zyklus schicken, außer der Plan ist, danach neu zu signieren

Was bedeutet null in der GetDocumentJSON-Ausgabe?

GetDocumentJSON schreibt null für jede Zahl, die NaN oder unendlich ist, denn RFC 8259 §6 hat für beides keine Syntax. Infinity ist leichter zu erzeugen, als es klingt. Der PDF-Tokenizer akkumuliert Ziffern durch wiederholte Multiplikation in ein Double, das bei etwa 1,8 × 10308 ausläuft, ein Integerliteral von etwas über 300 Stellen wird beim Parsen also zu +Inf. Gewöhnliche Producer schreiben nie so ein Literal; gefuzzte und feindliche Dateien tun es, weshalb ein 400-stelliger Integer in dasselbe Testkorpus gehört wie die Fälle aus dem Artikel zum Härten eines Pascal-PDF-Parsers gegen bösartige Dateien

Die Endlichkeitsprüfung muss zuerst kommen. GetDocumentJSON druckt ganzzahlige Werte unter MaxInt als Integer und alles andere mit Pascals Str(D:0:6), was für 1,25 fein ist und für +Inf tödlich, denn Str schreibt dann den Text +Inf, und kein JSON-Consumer parst das. Die Sechs-Dezimalstellen-Formatierung markiert zudem, wofür das Dokument-JSON gedacht ist: ein Überblick über die ganze Datei. Wenn Sie die exakten Ziffern eines Objekts brauchen, fragen Sie GetObjectJSON für dieses Objekt

Das null ist bewusst verlustbehaftet, und es teilt seine Schreibweise mit etwas anderem. Ein PDF-null-Objekt kommt im Dokument-JSON ebenfalls als null heraus, ein Consumer kann also an dem einen Wert nicht unterscheiden, ob "die Datei null sagte" oder "die Datei sagte eine Zahl, zu groß für ein Double". GetObjectJSON hält beide auseinander: Das PDF-null-Objekt wird als {"type":"null"} geschrieben, und eine Zahl behält ihren "type":"number"-Wrapper. Code, der Dokument-JSON liest, sollte null überall akzeptieren, wo eine Zahl auftreten kann, die Objektnummer loggen und die Datei als verdächtig behandeln, statt 0 einzusetzen

Warum kann ein einzelnes NaN einen SVG- oder JSON-Export abbrechen?

Ein Zahlenformatter, der seine Eingabe skaliert und Round aufruft, trifft Round(NaN), und auf Win32, wo Delphi die x87-Invalid-Operation-Exception unmaskiert lässt, wirft das EInvalidOp. Die Exception feuert, nachdem der Writer bereits einen Teil seiner Ausgabe emittiert hat. Eine einzige entartete Messung, ein 0/0 in einer Metrik oder ein von einem Aufrufer hereingereichtes NaN, hinterlässt eine abgeschnittene Datei auf der Platte

PLDoubleToStr in PDFlibExtra, der invariante Formatter, den die Bibliothek für Content-Streams, SVG, XML, CSV und den größten Teil ihres JSON nutzt, gibt für NaN 0 zurück. Sein Integer-Zweig klemmt den skalierten Wert ebenso an ±9,2 × 1018 wie der Bruchteil-Zweig, Infinity kommt also ebenfalls als finites Literal heraus. In einem Content-Stream ist das die richtige Antwort. Ein Operandenslot muss eine Zahl halten, und ein Viewer, der mitten in einem Pfad +Inf trifft, hat nichts Sinnvolles zu zeichnen

In einem Report ist null nicht die falsche, sondern die richtige Antwort — aber null, nicht 0, und da sind wir empfindlich: 0 ist eine völlig plausible Angabe für einen Entzerrungswinkel oder Pixel-Fehler, es für "keine Antwort" zu schreiben korrumpiert die Daten also, ohne dass es jemand bemerkt. Report-Writer benutzen stattdessen PLJSONNumber(Value, Decimals) aus derselben Unit, das für NaN oder Infinity null schreibt und sonst invariante Ziffern. GetSimilarImageDeduplicationReportJSON, GetAnnotationHitsJSON und die Barcode-, Deskew-, Structured-Text- und PDF/VCR-Reports laufen alle hindurch, ein nicht endlicher Entzerrungswinkel erreicht den Consumer also als null

PDFlibPas stoppt NaN und Infinity auf drei Wegen: AddPageMatrix, ScalePage und RedactRegion weisen nicht endliche Argumente vorne ab, PLDoubleToStr schreibt 0 für Content-Stream-Slots, und PLJSONNumber schreibt in Reports null, wo 0 als plausible Messung gelesen würde, sodass Round(NaN) nie die Gelegenheit bekommt, mitten im Export ein EInvalidOp auszulösen
Null ist die richtige Antwort für einen Content-Stream und die falsche für einen Report, deshalb reichen die Report-Writer jedes Double an PLJSONNumber durch und lassen null sagen: Der Wert war da, ließ sich aber nicht darstellen

Dieselbe Funktion ist öffentlich, Ihr eigenes JSON kann der Regel der Bibliothek also folgen. Die Skizze unten baut einen kleinen Skew-Record; die Form des Records ist unsere, der Formatierungsaufruf ist der der Bibliothek

uses
  SysUtils, PDFlibTypes, PDFlibExtra;

// Ihr eigener Report-Writer, mit der Zahlenregel der Bibliothek
function SkewReportJSON(Page: Integer; Angle, Confidence: Double): string;
var
  B: PLStringBuilder;
begin
  B := PLStringBuilder.Create(128);
  try
    // Erst jedes Double zu Text formatieren; PLJSONNumber schreibt null
    // für NaN oder Infinity und benutzt immer einen Dezimalpunkt
    B.Append('{"page":').Append(Page)
     .Append(',"angle":').Append(string(PLJSONNumber(Angle, 4)))
     .Append(',"confidence":').Append(string(PLJSONNumber(Confidence, 4)))
     .Append('}');
    // Niemals B.Append(Angle): unter Delphi folgt diese Überladung dem User-Locale
    Result := B.ToString;
  finally
    B.Free;
  end;
end;

Wo das User-Locale ins JSON einschleicht

Jeder Formatter, der regionale Einstellungen befragt, kann ein Komma setzen, wo JSON einen Punkt braucht. PLFloatToStr in PDFlibExtra ist ein dünner Wrapper um FloatToStr, und genau das tut es. Ein Feld wie maxAcceptedMeanError damit auf einem deutschen oder französischen Desktop zu schreiben ergibt "maxAcceptedMeanError":1,5. Ein JSON-Parser liest das als den Wert 1 gefolgt von einem herrenlosen Token. Das Feld meldet den schlechtesten akzeptierten Pixel-Fehler aus der perzeptuellen Bild-Deduplizierung, und GetSimilarImageDeduplicationReportJSON schreibt es durch PLJSONNumber(Stats.MaxAcceptedMeanError, 6), das Trennzeichen bleibt also ein Punkt, ganz gleich, wie die Maschine eingestellt ist

Der zweite Weg ist leiser. Unter Delphi ist PLStringBuilder ein schlichter Alias von System.SysUtils.TStringBuilder, dessen Append(Double)-Überladung durch das User-Locale formatiert. Free-Pascal-Builds nutzen stattdessen eine kleine Unicode-Builder-Klasse aus PDFlibTypes, denn das eigene TStringBuilder der FPC-Runtime ist ANSI-only. Dieselbe Quelle mit beiden zu kompilieren lässt den Delphi-Build mit dem FPC-Build uneinig werden. Ein Test, der nur unter Free Pascal läuft, oder nur auf einer en-US-Maschine, sieht das Komma nicht

Der Test unten lässt innerhalb des Prozesses einen Komma-Desktop entstehen und füttert den Report einem strengen Parser. Nehmen Sie eine Eingabe, die wirklich beinahe duplizierte Bilder enthält; ohne Treffer ist der mittlere Fehler 0, und ein Wert ohne Nachkommanteil versteckt das Trennzeichen-Problem

uses
  System.SysUtils, System.JSON, PDFlibrary;

var
  Lib: TPDFlib;
  Report: WideString;
  Parsed: TJSONValue;
begin
  // Diesen Prozess sich wie einen deutschen/französischen Desktop verhalten lassen
  FormatSettings.DecimalSeparator := ',';
  Lib := TPDFlib.Create;
  try
    if Lib.LoadFromFile('scanned-batch.pdf', '') = 0 then
      raise Exception.Create('load failed');
    // Trockenlauf mit Schwellwerten 2, 2, 4: das Dokument wird nicht verändert
    Lib.GetSimilarImageDeduplicationReportJSON(2, 2, 4, Report);
    Parsed := TJSONObject.ParseJSONValue(Report);
    // Diese nil-Prüfung ergänzen Sie selbst, sie ist nicht Teil der Bibliothek
    if Parsed = nil then
      raise Exception.Create('report is not valid JSON on a comma locale');
    Parsed.Free;
  finally
    Lib.Free;
  end;
end;

Drei Eingaben, die in die Testsuite gehören

Zahlen-Handling in JSON ist billig zu brechen und billig zu sichern. Eine Seite mit -.25, +1.5 und 007.5 deckt die Grammatiklücke; prüfen, dass die GetObjectJSON-Ausgabe parst und dass SetObjectJSON 1 zurückgibt. Ein Objekt mit einem 400-stelligen Integer deckt den Überlauf; das Dokument-JSON sollte an dieser Position null zeigen. Ein Report, erzeugt mit DecimalSeparator auf Komma, deckt das Locale. Jedes durch einen strengen Parser schicken, statt die Ausgabe mit dem Auge zu lesen, denn 1,5 und 1.5 gehen in einer langen JSON-Zeile leicht unter

Objekt-JSON, Dokument-JSON und die Analyse-Reports teilen sich diese Zahlenregeln über Delphi-, C++Builder- und Free-Pascal-Builds hinweg. Die PDF Library for Delphi Produktseite listet die Editionen und den Rest der Objekt- und Reporting-API