Техническая статья

Грамматика чисел PDF против JSON: NaN, Infinity и null

"value":-.25 — то, что производит JSON-писатель, копирующий совершенно легальный токен числа PDF как есть, и строгий парсер RFC 8259 сдаётся прямо после знака минус. Его соседи +1.5 и 007.5 из того же PDF-массива проваливаются так же. Превратить числа PDF в JSON — значит переписать каждый токен цифра за цифрой, написать null для NaN и Infinity и не пустить региональную десятичную запятую в вывод

Четыре написания, которые PDF принимает, а JSON отвергает

Две грамматики расходятся в четырёх мелочах. ISO 32000-1 §7.3.3 позволяет числу начинаться с плюса, опускать целую часть (.5), кончаться голой точкой (4.) и нести ведущие нули (007.5). RFC 8259 §6 не разрешает ничего из этого: опциональный минус, целая часть — либо 0, либо начинающаяся с цифры от 1 до 9, — и хотя бы одна цифра после любой десятичной точки. Производители вольны писать PDF-формы, и генераторы, печатающие числа собственным кодом форматирования, равно как файлы, поправленные кем-то руками в текстовом редакторе, этим пользуются

Столкновение обостряется в библиотеке, уважающей исходный текст. PDF Library for Delphi (PDFlibPas) хранит точные символы, которые она разобрала, для каждого вещественного числа, поэтому калиброванное цветовое значение сохраняется назад неизменным вместо округления к умолчанию в четыре знака; рассуждение — в статье сохранение распарсенной десятичной точности PDF. Токенизатор уже латает .5 в 0.5 и 4. в 4.0 при чтении, а целые строятся заново из значения, поэтому +3 возвращается как 3. Три написания всё ещё доходят до писателя дословно: знак перед ведущей точкой (-.25), явный плюс у вещественного (+1.5) и ведущие нули (007.5)

Писатель, вклеивающий те сохранённые символы прямо в JSON, производит файл, прекрасно выглядящий в редакторе. Беда начинается на обратном пути. SetObjectJSON возвращает 0, а LastErrorCode сообщает PDFLIB_ERROR_OBJECT_JSON_INVALID, то есть 105

GetObjectJSON в PDFlibPas переписывает отвергаемые RFC 8259 токены чисел PDF цифра в цифру: -.25 становится -0.25, +1.5 теряет плюс, 007.5 сбрасывает ведущие нули, а дробные цифры вроде 1.250000 выживают, потому что форматирование из сохранённого Double добавило бы бинарный шум
Старый писатель приклеивал точный разобранный текст, собственный читатель библиотеки спотыкался с Invalid JSON number, и ошибка 105 ломала round trip, который экспортная сторона называла успехом

Round trip ниже — самый быстрый способ увидеть, что GetObjectJSON реально издаёт. Каждое число приходит обёрнутым как {"type":"number","value":...}, и три неудобных токена выходят как -0.25, 1.5 и 7.5

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'); // Объект 12 — массив, записанный как [-.25 +1.5 007.5] JSON := Lib.GetObjectJSON(12, 0); if JSON = '' then raise Exception.CreateFmt('export failed, error %d', [Lib.LastErrorCode]); // Каждый элемент читается как {"type":"number","value":-0.25} и так далее // SetObjectJSON возвращает 1 при успехе; передавайте 0 в Options 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;

Переписывание токена вместо пересчёта

GetObjectJSON правит сохранённые символы, а не форматирует разобранный Double. Он читает опциональный знак, собирает цифры по обе стороны единственной десятичной точки и затем делает только правки, которых требует JSON: плюс уходит, ведущие нули срезаются до одного, пустая целая часть становится 0, голая хвостовая точка отбрасывается, а минус ставится обратно впереди. Токен, содержащий любой другой символ или вовсе без цифр, форматируется из разобранного значения с десятью знаками, и тот путь пишет null, когда значение нефинитно

PDFNumberTextToJSON в PDFlibPas читает знак, собирает цифры вокруг единственной десятичной точки и применяет только правки, которых требует JSON, тогда как любой другой символ или пустой набор цифр откатывается к PLJSONNumber, пишущей null для NaN и Infinity вместо числа
Переписывание бьёт пересчёт: токенизатор уже залатал .5 и 4. на входе, поэтому писатель хранит каждую уцелевшую цифру, и round trip воссоздаёт ровно то же значение
  • -.25 становится -0.25, а +.5 — 0.5
  • +1.5 становится 1.5
  • 007.5 становится 7.5, тогда как 0.75 остаётся как есть
  • 4. становится 4, если такой токен вообще дойдёт до писателя
  • 2.22221 и 1.250000 хранят каждую дробную цифру, включая хвостовые нули

Форматирование из Double вышло бы однострочником — и оказалось бы неверным дважды. Точность вывода документа по умолчанию — четыре знака, поэтому 2.22221 потерял бы цифру. Поднятие точности тоже не спасает: у 0.1 нет точной двоичной формы, и конверсия в 17 значащих цифр печатает 0.10000000000000001. Сохранение исходных цифр означает, что SetObjectJSON и ImportObjectJSON, отдающие каждое JSON-число обратно PDF-токенизатору, перестраивают ровно то значение, которое объявила файл

То обещание покрывает значение. Байты — другая материя. После реимпорта -.25 хранится и сохраняется как -0.25; оба написания равны по §7.3.3, но побайтовый diff пометит изменение. На документе, чьи диапазоны байтов накрыты подписью, мы бы вообще не гоняли объекты через цикл экспорта-импорта, разве что план состоит в повторном подписании потом

Что означает null в выводе GetDocumentJSON?

GetDocumentJSON пишет null для любого числа, которое NaN или бесконечно, потому что у RFC 8259 §6 нет синтаксиса ни для того ни для другого. Infinity проще получить, чем кажется. PDF-токенизатор копит цифры повторным умножением в Double, который упирается в потолок около 1.8 × 10308, поэтому целочисленный литерал чуть длиннее 300 цифр превращается в +Inf ещё при разборе. Обычные производители такой литерал не пишут; фаззнутые и враждебные файлы пишут, поэтому 400-значное целое принадлежит тому же тестовому корпусу, что и случаи из статьи укрепление Pascal-парсера PDF против злонамеренных файлов

Проверка финитности должна идти первой. GetDocumentJSON печатает целые значения ниже MaxInt как целые, а всё остальное — паскалевским Str(D:0:6), что хорошо для 1.25 и фатально для +Inf: Str тогда пишет текст +Inf, который не разберёт ни один JSON-потребитель. Шестизнаковое форматирование заодно помечает, для чего документный JSON: это обзор всего файла. Когда нужны точные цифры одного объекта, спрашивайте GetObjectJSON по тому объекту

null намеренно теряет данные, и делит написание с чем-то ещё. PDF-объект null тоже выходит как null в документном JSON, поэтому потребитель не отличит "файл сказал null" от "файл сказал число, слишком большое для Double", глядя на одно значение. GetObjectJSON разводит их: PDF-объект null пишется как {"type":"null"}, а число хранит обёртку "type":"number". Код, читающий документный JSON, должен принимать null везде, где может стоять число, журналировать номер объекта и считать файл подозрительным вместо подстановки 0

Почему один NaN может оборвать экспорт SVG или JSON?

Форматтер чисел, масштабирующий ввод и зовущий Round, упирается в Round(NaN), а на Win32, где Delphi не маскирует x87-исключение невалидной операции, это поднимает EInvalidOp. Исключение стреляет после того, как писатель уже издал часть вывода. Одно вырожденное измерение — 0/0 внутри метрики или NaN, переданный вызывающим, — оставляет на диске обрезанный файл

PLDoubleToStr из PDFlibExtra, инвариантный форматтер, которым библиотека пользуется для потоков содержимого, SVG, XML, CSV и большей части своего JSON, возвращает 0 для NaN. Его целочисленная ветка клампит масштабированное значение к ±9.2 × 1018, как и дробная ветка, поэтому Infinity тоже выходит конечным литералом. В потоке содержимого это правильное решение: слот операнда обязан держать число, а вьювер, встретивший +Inf посреди пути, не имеет ничего осмысленного для рисования

В отчёте ноль — неправильное решение, и тут мы чувствуем себя твёрдо: 0 — совершенно правдоподобный угол дескеу или пиксельная ошибка, так что записывать его в значении "ответа нет" — портить данные незаметно. Писатели отчётов используют вместо этого PLJSONNumber(Value, Decimals) из того же юнита, которая пишет null для NaN или Infinity и инвариантные цифры иначе. GetSimilarImageDeduplicationReportJSON, GetAnnotationHitsJSON и отчёты barcode, deskew, structured text и PDF/VCR идут через неё, поэтому нефинитный угол дескеу доходит до потребителя как null

PDFlibPas останавливает NaN и Infinity тремя путями: AddPageMatrix, ScalePage и RedactRegion отвергают нефинитные аргументы на входе, PLDoubleToStr пишет 0 в слоты потоков содержимого, а PLJSONNumber пишет null в отчётах, где ноль читался бы как правдоподобное измерение, — после того как Round(NaN) поднимал EInvalidOp посреди экспорта
Ноль — правильный ответ для потока содержимого и неправильный для отчёта, поэтому писатели отчётов отдают каждый Double в PLJSONNumber и позволяют null сказать: значение было, но непредставимо

Та же функция публична, поэтому ваш собственный JSON рядом с библиотечным может следовать тому же правилу. Набросок ниже строит маленькую запись о перекосе; форма записи — наша, вызов форматирования — библиотечный

uses

SysUtils, PDFlibTypes, PDFlibExtra; // Ваш собственный писатель отчётов, использующий правило чисел библиотеки function SkewReportJSON(Page: Integer; Angle, Confidence: Double): string; var B: PLStringBuilder; begin B := PLStringBuilder.Create(128); try // Сперва форматируйте каждый Double в текст; PLJSONNumber пишет null // для NaN или Infinity и всегда использует десятичную точку B.Append('{"page":').Append(Page) .Append(',"angle":').Append(string(PLJSONNumber(Angle, 4))) .Append(',"confidence":').Append(string(PLJSONNumber(Confidence, 4))) .Append('}'); // Никогда B.Append(Angle): на Delphi тот оверлоад следует пользовательской локали Result := B.ToString; finally B.Free; end; end;

Куда пользовательская локаль просачивается в JSON

Любой форматтер, заглядывающий в региональные настройки, может положить запятую там, где JSON требует точку. PLFloatToStr из PDFlibExtra — тонкая обёртка над FloatToStr, и делает ровно это. Напишите поле вроде maxAcceptedMeanError с её помощью на немецком или французском десктопе — и получите "maxAcceptedMeanError":1,5. Парсер JSON читает это как значение 1 и бродячий токен. То поле отчитывает худшую принятую пиксельную ошибку из перцептуальной дедупликации изображений, а GetSimilarImageDeduplicationReportJSON пишет его через PLJSONNumber(Stats.MaxAcceptedMeanError, 6), поэтому разделитель остаётся точкой, что бы ни было настроено на машине

Второй путь тише. На Delphi PLStringBuilder — голый алиас System.SysUtils.TStringBuilder, чей оверлоад Append(Double) форматирует через пользовательскую локаль. Сборки Free Pascal вместо этого используют маленький класс сборщика Unicode из PDFlibTypes, потому что собственный TStringBuilder рантайма FPC — только ANSI. Скомпилируйте один и тот же исходник обоими — и сборка Delphi может разойтись со сборкой FPC. Тест, который гоняется только на Free Pascal или только на машине en-US, запятую не увидит

Тест ниже воспроизводит comma-десктоп внутри процесса и скармливает отчёт строгому парсеру. Берите вход, реально содержащий почти-дубликаты изображений: без совпадений средняя ошибка равна 0, а значение без дробной части прячет проблему разделителя

uses

System.SysUtils, System.JSON, PDFlibrary; var Lib: TPDFlib; Report: WideString; Parsed: TJSONValue; begin // Заставьте этот процесс вести себя как немецкий или французский десктоп FormatSettings.DecimalSeparator := ','; Lib := TPDFlib.Create; try if Lib.LoadFromFile('scanned-batch.pdf', '') = 0 then raise Exception.Create('load failed'); // Сухой прогон с порогами 2, 2, 4: документ не модифицируется Lib.GetSimilarImageDeduplicationReportJSON(2, 2, 4, Report); Parsed := TJSONObject.ParseJSONValue(Report); // Эту nil-проверку добавляете вы, она не часть библиотеки if Parsed = nil then raise Exception.Create('report is not valid JSON on a comma locale'); Parsed.Free; finally Lib.Free; end; end;

Три входа, которые стоит держать в тестовом наборе

Обработку чисел в JSON легко сломать и легко охранять. Одна страница с -.25, +1.5 и 007.5 покрывает зазор грамматики; проверьте, что вывод GetObjectJSON разбирается и что SetObjectJSON возвращает 1. Один объект с 400-значным целым покрывает переполнение; документный JSON должен показать null на той позиции. Один отчёт, произведённый с DecimalSeparator в запятую, покрывает локаль. Прогоняйте каждое через строгий парсер, а не читайте вывод на глаз, потому что 1,5 и 1.5 легко пропустить в длинной строке JSON

Object JSON, document JSON и аналитические отчёты делят те правила чисел через сборки Delphi, C++Builder и Free Pascal. На странице продукта PDF Library for Delphi перечислены редакции и остальной объектный и отчётный API