Класи утиліт та допоміжних класів

Утилітні та допоміжні класи

У цьому посібнику показано, як використовувати маленькі, вузькоспеціалізовані допоміжні класи, які Aspose.PDF FOSS для .NET постачає для загальних низькорівневих завдань: цілочисельна математика, що використовується безпековими примітивами, налаштування пошуку за регулярними виразами, оцінка функцій PostScript, виявлення зовнішніх шрифтів, витяг підшляхів векторів, фізичне вимірювання тексту, буферизовані правки потоків вмісту, великі потоки в оперативній пам’яті та повідомлення про версію бібліотеки. Ці класи не є самостійними точками входу, але вони підтримують вищого рівня операції з документами, текстом і рендерингом по всьому API.

Допоміжні функції цілочисельної математики

MathExtensions — це невелика статична допоміжна функція, що використовується всередині безпекових примітивів бібліотеки, проте доступна для загального використання, коли потрібна операція modulo, яка завжди повертає невід’ємний результат.

// Unlike the C# % operator, Mod never returns a negative value.
int wrapped = MathExtensions.Mod(-3, 5); // 2

Налаштування пошуку за регулярними виразами

RegexManager — це статичний клас, який налаштовує движок регулярних виразів, що використовується операціями пошуку тексту, такими як TextFragmentAbsorber. Встановіть MatchTimeout, щоб обмежити час виконання шаблону, і увімкніть NonBacktracking, щоб використовувати неретроспективний движок regex для пошуків, чутливих до продуктивності.

using var doc = Document.Open(pdfBytes);

// Guard against runaway regex patterns.
RegexManager.MatchTimeout = TimeSpan.FromSeconds(5);
RegexManager.NonBacktracking = true;

var absorber = new TextFragmentAbsorber(@"\d{3}-\d{4}", true);
doc.Pages[1].Accept(absorber);

Оцінка функцій PostScript

PostScriptEvaluator — це статичний клас, який обчислює функції PDF типу 4 (PDF32000 §7.10.5) — програми-калькулятори PostScript, вбудовані в PDF, наприклад, ті, що використовуються в деяких визначеннях колірного простору та затінень.

double[] inputs = { 0.5 };

// Evaluate a PostScript calculator program against the input array.
var outputs = PostScriptEvaluator.Evaluate("{ 2 mul }", inputs);

Зовнішні шляхи пошуку шрифтів

ExternalFontCache керує папками, які шукаються для зовнішніх (не вбудованих) TrueType/OpenType гарнітур під час рендерингу та конвертації. Скористайтеся Instance, щоб отримати доступ до сінглтона, GetDefaultFontsFolders — щоб переглянути вбудовані місця пошуку, і SetFontsFolders — щоб додати їх або замінити.

var cache = ExternalFontCache.Instance;
var defaultFolders = cache.GetDefaultFontsFolders();

// reset: false appends to the existing search paths instead of replacing them.
cache.SetFontsFolders(new[] { @"C:\Fonts\Custom" }, reset: false);

Видобування векторних підшляхів

GraphicsAbsorber відвідує сторінку та видобуває її намальовані векторні підшляхи як елементи SubPath, кожен з яких має власну межу у просторі сторінки Rectangle. Це корисно для огляду або вимірювання векторного мистецтва без ручного розбору потоку вмісту.

using var doc = Document.Open(pdfBytes);

var absorber = new GraphicsAbsorber();
absorber.Visit(doc.Pages[1]);

Console.WriteLine($"Elements found: {absorber.Elements.Count}");

foreach (var element in absorber.Elements)
{
    if (element is SubPath subPath)
    {
        Rectangle bounds = subPath.Rectangle;
        Console.WriteLine($"Sub-path bounds: [{bounds.LLX}, {bounds.LLY}, {bounds.URX}, {bounds.URY}]");
    }
}

Фізичне вимірювання текстового сегмента

PhysicalTextSegment — це проекція у просторі сторінки поглинутого TextSegment. Отримайте її через TextSegment.PhysicalSegment, щоб виміряти послідовність символів або прочитати її розв’язане TextState.

using var doc = Document.Open(pdfBytes);

var absorber = new TextFragmentAbsorber();
doc.Pages[1].Accept(absorber);

foreach (TextFragment fragment in absorber.TextFragments)
{
    foreach (TextSegment segment in fragment.Segments)
    {
        PhysicalTextSegment physical = segment.PhysicalSegment;
        var width = physical.MeasureSegment(segment.StartCharIndex, segment.EndCharIndex, true);
        TextState state = physical.TextState;
    }
}

Буферизація правок потоку вмісту

ContentsAppender, досягнуті через Page.ContentsAppender, буферизує оператори для додавання на початок або кінець потоку вмісту сторінки та здійснює їх коміт в один прохід за допомогою UpdateData.

using var doc = Document.Open(pdfBytes);

Page page = doc.Pages[1];
page.ContentsAppender.AppendToBegin(new GSave());
page.ContentsAppender.AppendToEnd(new GRestore());
page.ContentsAppender.UpdateData();

Великі потоки в пам’яті

OptimizedMemoryStream — це розширюваний поток у пам’яті, який може перевищувати 2 ГБ обмеження одновимірного масиву MemoryStream, зберігаючи дані у фіксованих блоках. Він успадковується від Stream, тому підтримує звичайні операції читання, запису та переміщення.

using var stream = new OptimizedMemoryStream();

byte[] buffer = System.Text.Encoding.UTF8.GetBytes("large payload");
stream.Write(buffer, 0, buffer.Length);

bool canSeek = stream.CanSeek;
byte[] allBytes = stream.ToArray();

Інформація про версію бібліотеки

BuildVersionInfo — це статичний клас, який виводить назву продукту бібліотеки та номери версій під час виконання — корисно для діагностики та запитів підтримки.

Console.WriteLine(BuildVersionInfo.Product);
Console.WriteLine(BuildVersionInfo.AssemblyVersion);
Console.WriteLine(BuildVersionInfo.FileVersion);

Поради та найкращі практики

• Встановіть RegexManager.MatchTimeout перед виконанням пошуку за недовіреними або користувачем наданими шаблонами, щоб уникнути катастрофічного зворотного відстеження.
• Викличте ExternalFontCache.SetFontsFolders з reset: true, коли ви хочете повністю замінити типові шляхи пошуку, а не додавати їх.
• Віддавайте перевагу OptimizedMemoryStream над MemoryStream, коли буферизуєте дуже великі документи або дані зображень, які можуть перевищувати 2 GB.
• Завжди завершуйте пакет редагувань ContentsAppender за допомогою UpdateData() — буферизовані оператори не записуються у потік вмісту до того моменту.
• GraphicsAbsorber.Elements може містити екземпляри GraphicElement, відмінні від SubPath; перевірте тип перед приведенням.

Поширені проблеми

FAQ

Чому MathExtensions.Mod відрізняється від оператора C# %?

MathExtensions.Mod завжди повертає невід’ємний залишок, тоді як вбудований оператор % може повернути від’ємне значення, коли ділене від’ємне.

Як зупинити текстовий пошук на основі regex, який працює занадто довго?

Встановіть RegexManager.MatchTimeout у TimeSpan перед створенням або запуском TextFragmentAbsorber, який використовує шаблон regex.

Чи SetFontsFolders замінює чи додає до існуючих шляхів пошуку?

Залежить від аргументу reset: передайте true, щоб замінити поточний список папок, або false, щоб додати нові папки до нього.

Що саме GraphicsAbsorber витягує?

Він витягує намальовані векторні підшляхи сторінки як елементи SubPath, кожен має межу Rectangle у просторі сторінки, за допомогою GraphicsAbsorber.Visit.

Коли слід використовувати OptimizedMemoryStream замість MemoryStream?

Коли буферизовані дані можуть наблизитися до 2 ГБ або перевищити його, оскільки MemoryStream підтримується одним масивом із цим жорстким обмеженням.

API Reference Підсумок

Дивіться також

• Метадані та утиліти
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation