Utility a pomocné třídy

Utility a pomocné třídy

Tento průvodce ukazuje, jak používat malé, zaměřené pomocné třídy, které Aspose.PDF FOSS pro .NET poskytuje pro běžné nízkoúrovňové úkoly: celočíselná matematika používaná bezpečnostními primitivy, konfigurace regexového vyhledávání, vyhodnocování funkcí PostScript, objevování externích fontů, extrakce podcest vektoru, fyzické měření textu, úpravy bufferovaných obsahových proudů, velké paměťové proudy a hlášení verze knihovny. Tyto třídy nejsou samostatnými vstupními body, ale podporují vyšší úrovně operací s dokumenty, textem a vykreslováním v celém API.

Pomocné třídy pro celočíselnou matematiku

MathExtensions je malý statický pomocník používaný interně bezpečnostními primitivy knihovny, ale je k dispozici pro obecné použití kdykoli potřebujete operaci modulo, která vždy vrací nezáporný výsledek.

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

Konfigurace regexového vyhledávání

RegexManager je statická třída, která konfiguruje engine regulárních výrazů používaný operacemi textového vyhledávání, jako je TextFragmentAbsorber. Nastavte MatchTimeout, aby omezil, jak dlouho může vzor běžet, a povolte NonBacktracking k použití engine regulárních výrazů bez backtrackingu pro výkonnostně citlivá vyhledávání.

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);

Vyhodnocování funkcí PostScript

PostScriptEvaluator je statická třída, která vyhodnocuje funkce PDF typu 4 (PDF32000 §7.10.5) — PostScript kalkulačkové programy vložené v PDF, například ty použité v některých definicích barevných prostorů a stínování.

double[] inputs = { 0.5 };

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

Cesty pro vyhledávání externích fontů

ExternalFontCache spravuje složky, které se prohledávají pro externí (nevestavěné) TrueType/OpenType fonty během vykreslování a konverze. Použijte Instance k získání singletonu, GetDefaultFontsFolders k prohlédnutí vestavěných míst vyhledávání a SetFontsFolders k jejich přidání nebo nahrazení.

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);

Extrahování vektorových podcest

GraphicsAbsorber navštíví stránku a extrahuje její namalované vektorové podcesty jako prvky SubPath, z nichž každá nese vlastní ohraničující Rectangle v prostoru stránky. To je užitečné pro kontrolu nebo měření vektorové grafiky bez ručního parsování obsahového proudu.

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}]");
    }
}

Měření fyzického textového segmentu

PhysicalTextSegment je projekce v prostoru stránky absorbovaného TextSegment. Získejte ji přes TextSegment.PhysicalSegment pro měření sekvence znaků nebo přečtení jejího rozřešeného 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;
    }
}

Bufferování úprav obsahového proudu

ContentsAppender, dosažený přes Page.ContentsAppender, bufferuje operátory, aby je předřadil nebo připojil ke streamu obsahu stránky, a provede je v jednom kroku pomocí 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();

Velké proudy v paměti

OptimizedMemoryStream je rozšiřitelný paměťový stream, který může překročit 2GB limit jediné pole MemoryStream tím, že ukládá data do bloků pevné velikosti. Dědí z Stream, takže podporuje běžné operace čtení, zápisu a posunu.

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();

Informace o verzi knihovny

BuildVersionInfo je statická třída, která v době běhu poskytuje název produktu knihovny a čísla verzí — užitečné pro diagnostiku a požadavky na podporu.

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

Tipy a osvědčené postupy

• Nastavte RegexManager.MatchTimeout před prováděním vyhledávání na nedůvěryhodných nebo uživatelem dodaných vzorcích, aby se předešlo katastrofickému zpětnému sledování.
• Zavolejte ExternalFontCache.SetFontsFolders s reset: true, když chcete kompletně nahradit výchozí cesty pro hledání místo jejich připojení.
• Upřednostněte OptimizedMemoryStream před MemoryStream, když bufferujete velmi velké dokumenty nebo obrazová data, která mohou přesáhnout 2GB.
• Vždy ukončete dávku úprav ContentsAppender pomocí UpdateData() — buffered operátory nejsou do proudu obsahu zapsány až do té doby.
• GraphicsAbsorber.Elements může obsahovat instance GraphicElement kromě SubPath; před přetypováním zkontrolujte typ.

Běžné problémy

FAQ

Proč se MathExtensions.Mod liší od operátoru % C#?

MathExtensions.Mod vždy vrací nezáporný zbytek, zatímco vestavěný operátor % může vrátit zápornou hodnotu, pokud je dividend záporný.

Jak zabránit, aby regex-založené textové vyhledávání běželo příliš dlouho?

Nastavte RegexManager.MatchTimeout na TimeSpan před vytvořením nebo spuštěním TextFragmentAbsorber, který používá regexový vzor.

Nahrazuje SetFontsFolders nebo přidává k existujícím vyhledávacím cestám?

Závisí to na argumentu reset: předáte true pro nahrazení aktuálního seznamu složek, nebo false pro připojení nových složek k němu.

Co GraphicsAbsorber ve skutečnosti extrahuje?

Extrahuje natřené vektorové podcesty stránky jako prvky SubPath, z nichž každý má ohraničující Rectangle v prostoru stránky, pomocí GraphicsAbsorber.Visit.

Kdy bych měl použít OptimizedMemoryStream místo MemoryStream?

Když může bufferovaná data přiblížit se nebo překročit 2GB, protože MemoryStream je založeno na jediném poli s tímto pevně daným limitem.

API Reference Shrnutí

Viz také:

• Metadata a nástroje
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation