기술 문서

콤마 소수 Delphi 앱을 위한 로캘 중립 PDF 숫자

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 숫자를 망가뜨리나?

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가 지수 형태를 지원하지 않는다고 말합니다. 렌더링 결과에서 어느 쪽 문제든 거슬러 올라가는 일은 비참합니다. 어긋난 행렬은 여러분 코드의 레이아웃 버그와 완벽히 똑같이 보이고 페이지의 어떤 것도 지역 설정을 가리키지 않으니까요

Delphi용 losLab PDF Developer Library인 PDFlibPas는 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;
콤마 소수 데스크톱의 PDFlibPas AddPageMatrix는 수정 전에 0,5 0 0 0,25 1E-5 12,75 cm을 썼고, PDF 파서는 이를 숫자 0과 모르는 토큰들로 읽어 cm에 엉뚱한 피연산자를 남기고 페이지가 조용히 변형되지만, PLDoubleToStrConst는 유효한 점 소수를 기록합니다
콤마는 PDF 문법에서 숫자 문자가 아니므로 손상은 잘못된 의미의 유효한 토큰으로 읽힙니다. 그리고 1E-5 같은 ffGeneral 지수는 콤마 로캘만이 아니라 모든 로캘에서 무효입니다

프로세스 안에서 FormatSettings.DecimalSeparator를 바꾸는 것은 지름길입니다. OS에서 자체 TFormatSettings를 만드는 코드는 이 검사를 거치지 않으므로, 여러분 애플리케이션이 그렇게 한다면 실제 독일 지역 설정을 지닌 CI 에이전트가 더 정직한 테스트입니다

두 종류의 숫자, 두 계열의 헬퍼

PDFlibPas는 숫자 헬퍼를 청중별로 갈라 놓았습니다. 사람에게 보이는 텍스트는 로캘을 따라도 되고, 기계를 위해 쓰이는 것은 절대 따르지 않습니다. PDFlibExtra.pas의 PLFloatToStr와 PLStrToFloat는 FloatToStr와 StrToFloat 위의 얇은 래퍼이며, 선언의 주석이 사람이 읽는 텍스트 전용이라고 말해 줍니다. 기계 출력(PDF, FDF, XFDF, JSON, XML, CSV)은 대신 불변 계열을 지납니다. 쓰기의 PLDoubleToStrConst, 읽기의 PLTryStrToFloatInvariant, 그리고 자체 TryStrToFloat 호출에 점 소수를 깐 TFormatSettings 레코드가 필요할 때의 PLInvariantFormatSettings입니다

정밀도는 전역이 아니라 일별로 정해집니다. 행렬은 소수 여섯 자리, 좌표와 TJ 조정은 넷, 색과 FDF 사각형은 셋입니다. 기계 쪽은 API 표면이 암시하는 것보다 넓은 곳을 커버합니다:

  • 기존 페이지 콘텐츠 앞에 cm을 붙이는 AddPageMatrix, ScalePage, DeskewPage
  • 페이지 요소가 생성될 때 쓰이는 Tm 리셋, TJ 어드밴스, cm 변환
  • 텍스트가 패스로 변환될 때 나오는 글리프 배치 행렬과 아웃라인 점
  • RedactRegion이 앞에 붙이는 검정 채움 상자, FDF 내보내기의 /Rect 값, 재색칠이 쓰는 색 피연산자

PLDoubleToStrConst는 손으로 짠 포매터이며, 고정 TFormatSettings로 FloatToStrF를 감싸는 것보다 옳은 선택이었다고 생각합니다. ffFixed는 정수부가 정밀도를 넘어서면 여전히 과학적 표기로 떨어지고, 0.5가 더 짧고 동일한데도 0.500000을 남깁니다. 자체 루틴은 언제나 마침표를 쓰고, 뒤따르는 0을 떼어내고, 유한 입력에는 지수를 절대 쓰지 않습니다. 요청 정밀도보다 작은 0이 아닌 값의 유효 숫자도 유지합니다. PLDoubleToStrConst(1E-9, 6)은 0.000000001을 돌려주고, 약 5E-16 아래만 0이 됩니다. 작은 스케일 팩터를 0으로 반올림하면 유효한 행렬이 특이 행렬이 되는데, 이는 십진수 자리 하나 어긋난 것보다 나쁜 실패입니다

PDFlibPas는 숫자 포맷팅을 둘로 나눕니다: PLFloatToStr와 PLStrToFloat는 유저 대면 텍스트를 위해 로캘 종속으로 남고, PLDoubleToStrConst와 PLTryStrToFloatInvariant는 PDF 문법이 되는 모든 것을 점 구분자, 지수 없음, 여섯 또는 넷 또는 셋의 일별 고정 정밀도로 포맷합니다
불변 포매터는 의도적으로 손으로 짜여졌습니다. 뒤따르는 0을 떼어내고, 지수를 절대 쓰지 않고, 작은 값의 유효 숫자를 유지합니다. 스케일 팩터를 0으로 반올림하면 유효한 행렬이 특이 행렬이 되기 때문입니다

포매터에 단위 테스트를 쓴다면 샘플 값을 이진 부동소수점을 염두에 두고 고르십시오. "유효 숫자 넷"의 자명한 후보는 0.000012345이지만 그 double에 1E8을 곱하면 1234.4999…이므로 결과는 0.00001234이고 단언은 로캘과 무관한 이유로 실패합니다. 중간점에서 확실하게 떨어진 값, 예컨대 0.000012346은 논쟁 자체를 피합니다:

uses
  PDFlibExtra;

// Assert 호출은 여러분 테스트 프로젝트에서 추가하는 검사다
procedure CheckNumberHelpers;
var
  V: Double;
begin
  // 기계 출력: 점 소수, 지수 없음, 뒤따르는 0 제거
  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');

  // 기계 입력: EConvertError 대신 False
  Assert(PLTryStrToFloatInvariant('0.5', V) and (V = 0.5));
  Assert(PLTryStrToFloatInvariant('  12.75 ', V) and (V = 12.75)); // 입력은 trim된다
  Assert(not PLTryStrToFloatInvariant('0,5', V));   // 콘텐츠 숫자는 콤마를 쓰지 않는다
end;

파싱 쪽이 왜 쓰는 쪽보다 더 위험한가?

로캘 종속 파서는 살짝 틀린 숫자를 만들지 않고 예외를 던지기 때문에 파싱 쪽이 더 위험합니다. 텍스트가 시스템 구분자와 맞지 않을 때마다 StrToFloat은 EConvertError를 throw합니다. 그 위에 지은 재색칠 패스는 콤마 소수 기계에서 평범한 0.5 g 연산자에 닿는 순간 중단되는데, 이는 사실상 모든 실제 페이지에서 실패한다는 뜻입니다. "10.5,20.5,50.5,40.5" 같은 클립 문자열은 그 자리에서 거부되고, SVG 길이, SVG 색, 어노테이션 꼭짓점 목록, output intent 값은 거부되거나 조용히 기본값으로 대체됩니다. 개발자 기계의 모든 테스트를 통과하고 뮌헨의 첫 고객에게 실패하는 코드입니다. 우연히만 동작하는 Delphi 코드 문서의 사례들과 같은 계열의 문제입니다

라이브러리의 모든 StrToFloat형 호출은 입력이 어디서 오는지로 분류됩니다. 콘텐츠 스트림 피연산자, SVG 어트리뷰트, 페인터 색 문자열, 콤마 구분 클립 및 꼭짓점 목록은 고정 점 문법을 갖으므로 PLTryStrToFloatInvariant를 지납니다. 그 헬퍼는 텍스트를 trim하고 PLInvariantFormatSettings로 파싱하며, 빈 값, 형태가 틀린 값, NaN, 무한대 입력에 대해 False를 돌려주고(값은 0으로 설정) 그칩니다. 콤마 구분 목록은 논쟁의 여지가 아예 없었습니다. 콤마는 목록 구분자이자 소수점일 수 없으므로 호환을 유지할 레거시 형태 자체가 없습니다

PDF를 하나의 색 공간으로 변환하기 안내의 재색칠 파이프라인의 결과는 RecolorPage와 RecolorDocument가 모든 로캘에서 페이지 콘텐츠를 동일하게 파싱한다는 것입니다. 호출자가 CheckDocumentPolicy에 입력하는 규칙 값만이 관대한 경로를 택하는 파싱 사례인데, 사람이 그 문자열을 타이핑했고 지역 소수점 기호를 썼을 가능성이 충분하기 때문입니다

문자열로 중계되는 숫자는 양쪽 끝이 합의해야 한다

한 부분이 숫자를 문자열에 쓰고 다른 부분이 그것을 되파싱할 때 기록자와 읽는 자는 같은 규약을 따라야 하며, 하나만 바꾸면 왕복이 깨집니다. 태그 PDF 구조 어트리뷰트는 정확히 이 방식으로 동작합니다. SetStructElemBBox는 네 값을 하나의 문자열로 포맷해 AddTagAttribute로 저장합니다. /A 어트리뷰트 딕셔너리가 쓰일 때 그 문자열은 숫자, 배열, 이름 중 무엇이 되는지 정하려고 다시 파싱됩니다

양쪽 끝이 모두 시스템 로캘을 따른다면 왕복은 독일 기계 위에서 자기 일관적입니다. 문제는 문서를 따라 "0.5"를 AddTagAttribute에 넘기는 호출자에서 시작합니다. 로캘 종속 읽기는 그것을 파싱하지 못해 PDF 이름 /0.5을 내놓습니다. PDF/VCR 자리표시자는 거울상에 걸립니다. 그들의 GTS_BBox는 점으로 생성되는데 저장 전의 로캘 종속 검증 단계가 그것을 거부할 수 있습니다. 그리고 기록자만 점으로 바꾸면 상황은 더 나빠집니다. 모든 SetStructElem* 값이 콤마 소수 시스템에서 이름으로 변하니까요

그래서 기록자는 PLDoubleToStrConst(v, 6)를 쓰고 읽는 자는 PLTryStrToFloatLenient를 씁니다. 점 형태를 먼저 시도하고 시스템 로캘로 폴백합니다. "1,25"를 넘기는 콤마 로캘 호출자는 1.25라는 숫자를 받습니다. 비용이 있고 우리는 그것을 알고 받아들였습니다. 독일 시스템에서 "1.500"은 천오백이 아니라 1.5로 읽히는데, 점 형태가 이기기 때문입니다. API는 점을 구분자로 문서화하므로 어트리뷰트 문자열 속의 독일식 천 단위 묶음은 포기하기로 한 입력입니다. 리터럴 NAN과 INF 문자열은 숫자로 취급되지 않습니다

PDFlibPas SetStructElemBBox와 그 형제들은 숫자를 문자열로 AddTagAttribute를 통해 중계하고 /A 기록자가 그 문자열들을 되파싱하므로 양쪽 끝이 함께 움직입니다: PLDoubleToStrConst는 점으로 쓰고 PLTryStrToFloatLenient는 로캘 폴백과 함께 점을 먼저 읽어 콤마 로캘의 1,25도 여전히 1.25로 읽힙니다
기록자만 고쳤다면 모든 구조 요소 어트리뷰트가 PDF 이름으로 타락했을 것입니다. 그래서 왕복은 양쪽 끝을 함께 움직이거나 전혀 움직이지 않습니다
uses
  System.SysUtils, PDFlibrary;

var
  Lib: TPDFlib;
begin
  FormatSettings.DecimalSeparator := ',';   // 콤마 소수 호출자
  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');   // /0.5가 아니라 /SpaceAfter 0.5
    Lib.AddTagAttribute('Layout', 'StartIndent', '1,25'); // 로캘 폴백으로 /StartIndent 1.25
    Lib.DrawText(20, 20, 'figure');
    Lib.EndTag;
    Lib.SaveToFile('tagged.pdf');
  finally
    Lib.Free;
  end;
end;

여러분 자신의 코드에 대한 권고는 AddTagAttribute에는 점 소수 문자열을 넘기고, 오래된 구성 파일에서 읽어 들인 문자열처럼 통제할 수 없는 값에만 콤마 폴백을 남기는 것입니다. 그 어트리뷰트들 주위의 구조 트리가 어떻게 만들어지는지는 태그 PDF 구조 가이드가 다룹니다

NaN과 무한대가 막히는 곳

AddPageMatrix, ScalePage, RedactRegion는 NaN과 무한대 인자를 앞에서 거부하고 0을 돌려줍니다. 어느 쪽도 PDF 숫자로 표현할 수 없기 때문입니다. 검사는 명시적이어야 합니다. NaN은 <= 0 검사를 슬그머니 지나가므로 스케일 팩터만의 범위 검사로는 NaN 스케일이 포매터까지 여행할 수 있고, Win32에서 NaN에 Round를 부르면 x87 유닛이 기본값으로 무효 연산을 마스킹하지 않아 EInvalidOp가 raise됩니다. PLDoubleToStrConst는 마지막 방어선으로 NaN에 0을 쓰지만 행렬 안의 0은 특이 변환이므로 실제로 페이지를 지키는 것은 API 수준의 검사입니다. 여러분 코드에서는 반환값을 검사하십시오. ScalePage가 여러분이 계산한 팩터에 대해 0을 돌려주면 무엇보다 먼저 그 팩터를 출력하십시오. 상류 어딘가의 0/0이 정확히 이 NaN을 만듭니다

두 경계는 의도된 것입니다. 메타파일 상태 문자열은 단일 프로세스 안에서 로캘로 쓰고 읽히며 파일에 닿지 않으므로 로캘 종속으로 남습니다. 그리고 페이지 생성 경로로 작은 값을 테스트한다면 호출 직후에 콘텐츠를 읽으십시오. 나중에 문서 좌표 정밀도로 페이지 콘텐츠를 다시 내보내는 연산은 1E-5를 정당하게 0으로 바꾸는데, 그것은 반올림이지 로캘 누출이 아닙니다

길러야 할 습관은 짧습니다. 애플리케이션의 PDF 생산 경로를 콤마 구분자로 한 번 돌리고, 출력에서 콤마와 지수를 훑고, 파서가 읽을 모든 것에서 FloatToStr를 멀리하십시오. 기존 파일에서 읽은 숫자는 관련 규칙을 따르는데 파싱한 소수 정밀도 보존하기 문서에서, 저장을 거쳐도 정확한 소스 텍스트가 살아남는 이야기를 다룹니다. 평가판 빌드, API 레퍼런스, 라이선스 세부는 PDFlibPas Delphi PDF 라이브러리 제품 페이지에 있습니다