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

Числа PDF без локали для Delphi с запятой-десятичной

Переключите Windows-тестовую машину на немецкие региональные настройки, выполните рутину, дописывающую матрицу масштабирования и сдвига перед содержимым страницы, и выгрузите поток содержимого. Вместо 0.5 0 0 0.25 0.00001 12.75 cm вы получите 0,5 0 0 0,25 1E-5 12,75 cm. Парсер содержимого читает это как число 0, затем нераспознанный токен ,5, затем числа, которые больше не сходятся с шестью операндами, которых ждёт cm, — и страница рисуется с трансформацией, о которой вы не просили. Числа, которые будет парсить машина, требуют фиксированной точки, без экспоненты и без какой-либо зависимости от FormatSettings — и на пишущей стороне, и на читающей

Почему локаль с запятой-десятичной ломает числа PDF?

Локаль с запятой-десятичной ломает числа PDF потому, что форматирование чисел с плавающей точкой в Delphi по умолчанию следует за рабочим столом, тогда как синтаксис чисел PDF фиксирован. FloatToStr использует FormatSettings.DecimalSeparator, поэтому на машине de-DE, fr-FR или pt-BR каждая дробь выходит с запятой. ISO 32000-1 §7.3.3 разрешает в числе цифры, одну точку и ведущий знак. Больше ничего. Запятая, таким образом, раскалывает одно число на валидное целое плюс мусор, и результат — страница, которая рендерится, просто неправильно

За первой ловушкой прячется вторая, и она кусается и на американских машинах. FloatToStr использует формат ffGeneral, переключающийся на экспоненциальную запись, как только порядок падает ниже 1E-4, поэтому крошечное смещение пишется как 1E-5. Тот же §7.3.3 говорит, что PDF экспоненциальную форму не поддерживает. Выслеживать любую из проблем от рендеренного вывода мучительно, потому что сползшая матрица выглядит в точности как баг компоновки в вашем собственном коде, и ничто на странице не указывает на региональные настройки

PDFlibPas — losLab PDF Developer Library for Delphi — пишет операнды AddPageMatrix через PLDoubleToStrConst с шестью десятичными знаками, и места вызовов, генерирующие содержимое страниц от вашего имени, следуют тому же правилу. Самый дешёвый регрессионный тест, который мы знаем, переворачивает разделитель в запятую внутри процесса, вызывает API и сканирует результат на запятые и экспоненты:

uses
  System.SysUtils, PDFlibrary;

// Ваша собственная проверка, не часть библиотеки. Она нарочито грубая:
// текстовые строки вроде (Hello, world) Tj тоже содержат запятые, поэтому гоняйте её
// на тестовой странице, рисующей только фигуры
function HasLocaleDamage(const Content: AnsiString): Boolean;
var
  I: Integer;
begin
  Result := False;
  for I := 1 to Length(Content) do
  begin
    if Content[I] = ',' then
      Exit(True);
    if (Content[I] in ['E', 'e']) and (I > 1) and (I < Length(Content)) and
       (Content[I - 1] in ['0'..'9']) and (Content[I + 1] in ['0'..'9', '-', '+']) then
      Exit(True);
  end;
end;

var
  Lib: TPDFlib;
  OldSeparator: Char;
  Content: AnsiString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetPageDimensions(300, 200);
    Lib.DrawBox(10, 10, 20, 20, 1);
    OldSeparator := FormatSettings.DecimalSeparator;
    try
      FormatSettings.DecimalSeparator := ',';   // ведите себя как de-DE-десктоп
      Lib.AddPageMatrix(0.5, 0.25, 1E-5, 12.75);
      Content := Lib.GetPageContentToString;
      // Ожидание: 0.5 0 0 0.25 0.00001 12.75 cm
      // FloatToStr выдал бы: 0,5 0 0 0,25 1E-5 12,75 cm
      Writeln(Content);
      if HasLocaleDamage(Content) then
        Writeln('Locale leaked into the content stream');
    finally
      FormatSettings.DecimalSeparator := OldSeparator;
    end;
  finally
    Lib.Free;
  end;
end;
AddPageMatrix в PDFlibPas на comma-десктопе до починки писала 0,5 0 0 0,25 1E-5 12,75 cm, что парсер PDF читает как число 0 плюс неизвестные токены, cm остаётся с неверными операндами, а страница молча трансформируется, тогда как PLDoubleToStrConst пишет валидные десятичные с точкой
Запятая — не числовой символ в синтаксисе PDF, поэтому повреждение читается как валидные токены с неверным смыслом — а экспоненты ffGeneral вроде 1E-5 были невалидны на любой локали, не только запятой

Смена FormatSettings.DecimalSeparator внутри процесса — укороченный путь. Она не прогоняет код, строящий собственный TFormatSettings из ОС, поэтому если ваше приложение так делает, более честный тест — CI-агент с настоящими немецкими региональными настройками

Два сорта чисел, два семейства хелперов

PDFlibPas делит свои числовые хелперы по аудитории: текст для людей может следовать локали, а всё написанное для машины — никогда. PLFloatToStr и PLStrToFloat в PDFlibExtra.pas — тонкие обёртки над FloatToStr и StrToFloat, и комментарий при их объявлении говорит, что они только для человекочитаемого текста. Машинный вывод (PDF, FDF, XFDF, JSON, XML, CSV) идёт через инвариантное семейство: PLDoubleToStrConst на запись, PLTryStrToFloatInvariant на чтение и PLInvariantFormatSettings, когда вам нужна запись TFormatSettings с точкой-десятичной для собственных вызовов TryStrToFloat

Точность выбирается под задачу, а не глобально. Матрицы получают шесть десятичных, координаты и корректировки TJ — четыре, цвета и FDF-прямоугольники — три. Машинная сторона покрывает больше мест, чем подсказывает поверхность API:

  • AddPageMatrix, ScalePage и DeskewPage, которые дописывают cm перед существующим содержимым страницы
  • Сбросы Tm, продвижения TJ и трансформации cm, записываемые при генерации элементов страницы
  • Матрицы размещения глифов и точки контуров, производимые при конверсии текста в path
  • Чёрный заливочный прямоугольник, дописываемый RedactRegion, значения /Rect в FDF-экспорте и цветовые операнды, которые пишет перекраска

PLDoubleToStrConst — форматтер, написанный руками, и мы считаем, что это был правильный выбор по сравнению с обёртыванием FloatToStrF фиксированным TFormatSettings. ffFixed всё равно откатывается к научной записи, когда целая часть перерастает точность, и он оставил бы 0.500000 там, где 0.5 короче и идентичен. Самописная рутина всегда пишет точку, срезает хвостовые нули и никогда не пишет экспоненту для конечного входа. Она ещё и хранит значащие цифры ненулевого значения, которое меньше запрошенной точности: PLDoubleToStrConst(1E-9, 6) возвращает 0.000000001, и лишь значения ниже примерно 5E-16 становятся 0. Округление крошечного масштабного коэффициента в ноль превратило бы валидную матрицу в сингулярную — провал хуже любой съехавшей десятичной

PDFlibPas делит форматирование чисел надвое: PLFloatToStr и PLStrToFloat остаются привязаны к локали для пользовательского текста, а PLDoubleToStrConst и PLTryStrToFloatInvariant форматируют всё, что становится синтаксисом PDF, с точкой, без экспоненты и с фиксированной точностью под задачу — шесть, четыре или три знака
Инвариантный форматтер написан руками намеренно: он срезает хвостовые нули, никогда не пишет экспоненту и хранит значащие цифры крошечных значений, ведь округление масштабного коэффициента в ноль сделало бы валидную матрицу сингулярной

Если пишете юнит-тесты против форматтера, выбирайте образцовые значения с оглядкой на двоичную плавающую точку. Очевидный выбор для «четырёх значащих цифр» — 0.000012345, но умноженный на 1E8 тот double — 1234.4999…, поэтому результат 0.00001234, и проверка проваливается по причине, никак не связанной с локалями. Значение, сидящее заведомо в стороне от середины, вроде 0.000012346, снимает весь спор:

uses
  PDFlibExtra;

// Вызовы Assert — проверки, которые вы добавляете в своём тестовом проекте
procedure CheckNumberHelpers;
var
  V: Double;
begin
  // Машинный вывод: точка-десятичная, без экспоненты, хвостовые нули срезаны
  Assert(PLDoubleToStrConst(1E-5, 6) = '0.00001');
  Assert(PLDoubleToStrConst(-0.5, 6) = '-0.5');
  Assert(PLDoubleToStrConst(0.000012346, 4) = '0.00001235');  // 4 значащие цифры сохранены
  Assert(PLDoubleToStrConst(12345.25, 4) = '12345.25');

  // Машинный вход: False вместо EConvertError
  Assert(PLTryStrToFloatInvariant('0.5', V) and (V = 0.5));
  Assert(PLTryStrToFloatInvariant('  12.75 ', V) and (V = 12.75)); // вход обрезается
  Assert(not PLTryStrToFloatInvariant('0,5', V));   // числа содержимого никогда не используют запятую
end;

Почему парсящая сторона опаснее пишущей?

Парсящая сторона опаснее, потому что парсер, привязанный к локали, не выдаёт слегка неверное число — он бросает исключение. StrToFloat кидает EConvertError всякий раз, когда текст не совпадает с системным разделителем. Проход перекраски, построенный на нём, падал бы в момент, когда встречает обычный оператор 0.5 g на машине с запятой-десятичной, — то есть проваливается практически на каждой реальной странице. Строка клипа вроде "10.5,20.5,50.5,40.5" отвергалась бы целиком, а SVG-длины, SVG-цвета, списки вершин аннотаций и значения output intent либо отклонялись бы, либо тихо заменялись умолчаниями. Это код, который проходит все тесты на машине разработчика и падает у первого клиента в Мюнхене — то же семейство проблем, что и случаи из статьи о Delphi-коде, работающем случайно

Каждый вызов в стиле StrToFloat в библиотеке отсортирован по источнику входа. Операнды потоков содержимого, SVG-атрибуты, цветовые строки painter и разделённые запятыми списки клипов и вершин имеют фиксированный синтаксис с точкой, поэтому идут через PLTryStrToFloatInvariant. Тот хелпер обрезает текст, парсит его с PLInvariantFormatSettings и возвращает False (со значением 0) для пустого, malformed, NaN или бесконечного входа. Разделённые запятыми списки вообще не требовали дебатов: запятая не может быть одновременно разделителем списка и десятичной меткой, поэтому legacy-формы, с которой надо сохранять совместимость, не существует

Для конвейера перекраски, описанного в руководстве по конверсии PDF в одно цветовое пространство, результат таков: RecolorPage и RecolorDocument парсят содержимое страниц одинаково на любой локали. Значения правил, которые вызывающий вбивает в CheckDocumentPolicy, — единственный парсящий случай, идущий снисходительным маршрутом, потому что ту строку набрал человек и вполне мог использовать локальную десятичную метку

Число, передаваемое через строку, требует согласия обоих концов

Когда одна часть кода пишет число в строку, а другая парсит его обратно, писатель и читатель обязаны следовать одному соглашению, и смена только одного из них ломает round trip. Атрибуты структуры tagged PDF работают ровно так. SetStructElemBBox форматирует четыре значения в одну строку и сохраняет её через AddTagAttribute. Когда словарь атрибутов /A записывается, та строка разбирается заново, чтобы решить, чем она станет — числом, массивом или именем

Если бы оба конца следовали системной локали, поездка была бы самосогласованной на немецкой машине. Беда начинается с вызывающим, который следует документации и передаёт "0.5" в AddTagAttribute: читатель, привязанный к локали, не может его разобрать и выдаёт PDF-имя /0.5. Placeholder'ы PDF/VCR бьют зеркально: их GTS_BBox генерируется с точкой, и привязанный к локали шаг валидации перед сохранением отверг бы его. А смена одного лишь писателя на точку ухудшает дело, потому что каждое значение SetStructElem* на системах с запятой-десятичной тогда превращалось бы в имя

Поэтому писатели используют PLDoubleToStrConst(v, 6), а читатель — PLTryStrToFloatLenient, который сначала пробует форму с точкой, а при неудаче откатывается к системной локали. Вызывающий с comma-локалью, передавший "1,25", получает число 1.25. Цена есть, и мы приняли её осознанно: на немецкой системе "1.500" читается как 1.5, а не как тысяча пятьсот, потому что форма с точкой побеждает. API документирует точку как разделитель, поэтому немецкая группировка тысяч в строке атрибута — тот вход, от которого мы сознательно отказались. Литые строки NAN и INF числами не считаются

SetStructElemBBox в PDFlibPas и его братья передают числа строками через AddTagAttribute, а писатель /A парсит эти строки обратно, поэтому оба конца двигаются вместе: PLDoubleToStrConst пишет с точкой, а PLTryStrToFloatLenient сперва читает точку с локальным fallback, так что comma-локальное 1,25 по-прежнему читается как 1.25
Починка одного писателя выродила бы каждый атрибут структурного элемента в PDF-имя, поэтому round trip двигает оба конца сразу или никак
uses
  System.SysUtils, PDFlibrary;

var
  Lib: TPDFlib;
begin
  FormatSettings.DecimalSeparator := ',';   // вызывающий с comma-десятичной
  Lib := TPDFlib.Create;
  try
    Lib.BeginTag('Figure', 'Sales chart', '');
    Lib.SetStructElemBBox(10.5, 20.25, 200.5, 100.75); // /BBox [ 10.5 20.25 200.5 100.75 ]
    Lib.AddTagAttribute('Layout', 'SpaceAfter', '0.5');   // /SpaceAfter 0.5, а не /0.5
    Lib.AddTagAttribute('Layout', 'StartIndent', '1,25'); // /StartIndent 1.25 через локальный fallback
    Lib.DrawText(20, 20, 'figure');
    Lib.EndTag;
    Lib.SaveToFile('tagged.pdf');
  finally
    Lib.Free;
  end;
end;

Наша рекомендация для собственного кода — передавать в AddTagAttribute строки с точкой-десятичной и оставлять запятую-откат для значений, которыми вы не управляете, вроде строк, загруженных из старого конфигурационного файла. Как строится дерево структуры вокруг тех атрибутов, описано в руководстве по tagged PDF структуре

Где останавливаются NaN и бесконечность

AddPageMatrix, ScalePage и RedactRegion отвергают NaN и бесконечные аргументы upfront и возвращают 0, ведь ни одно число PDF не способно представить ни то, ни другое. Проверка обязана быть явной. NaN проскальзывает мимо теста <= 0, поэтому проверка диапазона на одном масштабном коэффициенте позволила бы NaN-масштабу доехать до самого форматтера, а вызов Round на NaN поднимает EInvalidOp на Win32, где x87-блок по умолчанию не маскирует невалидные операции. PLDoubleToStrConst пишет 0 для NaN как последнюю линию обороны, но ноль внутри матрицы — сингулярная трансформация, так что настоящую защиту странице даёт проверка на уровне API. В собственном коде тестируйте возвращаемое значение: когда ScalePage возвращает 0 для посчитанного вами коэффициента, напечатайте коэффициент прежде всего остального, потому что 0/0 где-то выше по потоку производит ровно этот NaN

Две границы проведены намеренно. Строки состояния метафайла пишутся и читаются с локалью внутри одного процесса и никогда не попадают в файл, поэтому остаются привязанными к локали. А если тестируете малые значения через путь генерации страницы, читайте содержимое сразу после вызова: операция, которая позже перевыпускает содержимое страницы с точностью координат документа, законно превратит 1E-5 в 0, и это округление, а не утечка локали

Привычка, которую стоит завести, коротка. Прогоните PDF-производящие пути вашего приложения один раз с разделителем-запятой, отсканируйте вывод на запятые и экспоненты и держите FloatToStr подальше от всего, что прочитает парсер. Числа, читаемые из существующего файла, следуют родственному правилу, разобранному в статье о сохранении спарсенной десятичной точности, где точный исходный текст переживает сохранение. Пробные сборки, справочник API и детали лицензирования — на странице продукта PDFlibPas Delphi PDF library