Справочник Swift API

PDF Oxide предоставляет идиоматичные привязки для Swift поверх нативного C ABI. Системный модуль CPdfOxide открывает доступ к заголовку cbindgen через module map, а PdfOxide — это обёртка на Swift. Дескрипторы принадлежат классам (освобождаются в deinit), возвращаемые C-строки и буферы копируются в Swift String/[UInt8], а коды ошибок, отличные от успешного, выбрасываются как PdfOxideError.

// Package.swift
dependencies: [
    .package(url: "https://github.com/yfedoseev/pdf_oxide", from: "0.3.69"),
],
targets: [
    .target(name: "YourTarget", dependencies: [
        .product(name: "PdfOxide", package: "pdf_oxide"),
    ]),
]

import PdfOxide

Про Rust API см. Справочник Rust API. Про Python API см. Справочник Python API. Подробности о типах см. в разделе Типы и перечисления.

Все индексы страниц начинаются с нуля. Большинство методов помечены throws и выбрасывают PdfOxideError при коде ошибки C ABI, отличном от успешного.

---

Document

Основной класс для открытия, извлечения, рендеринга и анализа PDF-файлов. Экземпляры создаются через статические фабричные методы open*.

Открытие

static func open(_ path: String) throws -> Document

Открыть PDF по пути к файлу.

static func openFromBytes(_ bytes: [UInt8]) throws -> Document

Открыть PDF из байтов в памяти (например, загруженных из S3 или полученных по HTTP).

static func openWithPassword(_ path: String, password: String) throws -> Document

Открыть зашифрованный PDF с паролем пользователя или владельца.

static func openFromDocxBytes(_ bytes: [UInt8]) throws -> Document
static func openFromPptxBytes(_ bytes: [UInt8]) throws -> Document
static func openFromXlsxBytes(_ bytes: [UInt8]) throws -> Document

Преобразовать офисный документ (DOCX, PPTX, XLSX) из байтов в памяти в Document.

func authenticate(_ password: String) throws -> Bool

Аутентифицировать уже открытый зашифрованный документ. Возвращает true при успехе.

func close()

Освободить нативный дескриптор немедленно (идемпотентно; также выполняется в deinit).

Сведения о документе

func pageCount() throws -> Int
func version() throws -> PdfVersion
func isEncrypted() throws -> Bool
func hasStructureTree() throws -> Bool
func hasXfa() throws -> Bool
func page(_ index: Int) -> Page

Методы доступа к общим метаданным документа. page(_:) возвращает лёгкий дескриптор Page для указанного индекса.

Извлечение текста

func extractText(_ page: Int) throws -> String

Извлечь обычный текст с одной страницы.

func extractChars(_ pageIndex: Int) throws -> [Char]

Извлечь позиционирование и метаданные шрифта для каждого символа.

func extractWords(_ pageIndex: Int) throws -> [Word]

Извлечь слова с ограничивающими прямоугольниками, именем/размером шрифта и флагом полужирного начертания.

func extractTextLines(_ pageIndex: Int) throws -> [TextLine]

Извлечь текст, сгруппированный по строкам, с числом слов и ограничивающими прямоугольниками.

func extractTables(_ pageIndex: Int) throws -> [Table]

Обнаружить и извлечь таблицы со строками, столбцами, заголовками и текстом ячеек.

func extractStructuredJson(_ page: Int) throws -> String

Извлечь структурированное JSON-представление содержимого страницы.

Автоизвлечение и классификация

func extractTextAuto(_ pageIndex: Int) throws -> String

Автоматически выбрать оптимальный способ извлечения и вернуть текст страницы.

func extractAllText() throws -> String

Извлечь текст со всех страниц документа.

func extractPageAuto(_ pageIndex: Int, optionsJson: String = "{}") throws -> String

Автоматически извлечь страницу с параметрами, заданными через JSON.

func classifyPage(_ pageIndex: Int) throws -> String
func classifyDocument() throws -> String

Классифицировать одну страницу или весь документ (например, отсканированный или цифровой).

Извлечение из области

func extractTextInRect(_ pageIndex: Int, x: Float, y: Float, w: Float, h: Float) throws -> String
func extractWordsInRect(_ pageIndex: Int, x: Float, y: Float, w: Float, h: Float) throws -> [Word]
func extractLinesInRect(_ pageIndex: Int, x: Float, y: Float, w: Float, h: Float) throws -> [TextLine]
func extractTablesInRect(_ pageIndex: Int, x: Float, y: Float, w: Float, h: Float) throws -> [Table]
func extractImagesInRect(_ pageIndex: Int, x: Float, y: Float, w: Float, h: Float) throws -> [Image]

Извлечь содержимое, ограниченное прямоугольником (x, y, w, h) (точки пользовательского пространства PDF, начало координат — нижний левый угол).

Конвертация

func toPlainText(_ page: Int) throws -> String
func toMarkdown(_ page: Int) throws -> String
func toHtml(_ page: Int) throws -> String

Конвертировать одну страницу в обычный текст, Markdown или HTML.

func toPlainTextAll() throws -> String
func toMarkdownAll() throws -> String
func toHtmlAll() throws -> String

Конвертировать все страницы в обычный текст, Markdown или HTML.

Экспорт в офисные форматы

func toDocx() throws -> [UInt8]
func toPptx() throws -> [UInt8]
func toXlsx() throws -> [UInt8]

Экспортировать документ в байты DOCX, PPTX или XLSX.

Изображения, шрифты и контуры

func embeddedImages(_ pageIndex: Int) throws -> [Image]

Извлечь встроенные растровые изображения (с сырыми байтами) со страницы.

func embeddedFonts(_ pageIndex: Int) throws -> [Font]

Перечислить встроенные шрифты на странице с указанием типа, кодировки и флага подмножества.

func extractPaths(_ pageIndex: Int) throws -> [Path]

Извлечь векторные контуры (линии, кривые, фигуры) со страницы.

func fontsToJson(_ pageIndex: Int) throws -> String
func fontSize(_ pageIndex: Int, fontIndex: Int) throws -> Float

Сериализовать шрифты страницы в JSON или прочитать размер одного шрифта.

Аннотации

func pageAnnotations(_ pageIndex: Int) throws -> [Annotation]

Извлечь аннотации (тип, подтип, содержимое, автор, прямоугольник) со страницы.

func annotationsToJson(_ pageIndex: Int) throws -> String

Сериализовать аннотации страницы в JSON.

func annotationExtras(_ pageIndex: Int, index: Int) throws -> AnnotationExtras

Прочитать расширенные атрибуты аннотации (цвет, даты, флаги, URI, значок, опорные точки).

Поиск

func search(_ pageIndex: Int, _ term: String, _ caseSensitive: Bool) throws -> [SearchResult]

Найти текст на одной странице.

func searchAll(_ term: String, _ caseSensitive: Bool) throws -> [SearchResult]

Найти текст по всему документу.

func searchResultsToJson(_ pageIndex: Int, _ term: String, caseSensitive: Bool) throws -> String

Выполнить поиск по странице и сериализовать совпадения в JSON.

Геометрия страницы

func pageWidth(_ pageIndex: Int) throws -> Float
func pageHeight(_ pageIndex: Int) throws -> Float
func pageRotation(_ pageIndex: Int) throws -> Int
func pageElements(_ pageIndex: Int) throws -> ElementList

Прочитать размеры страницы, поворот и универсальный список элементов страницы.

Рендеринг

func renderPage(_ pageIndex: Int, format: Int32 = 0) throws -> RenderedImage

Отрендерить страницу в RenderedImage (PNG при format равном 0, JPEG при 1).

func renderPageZoom(_ pageIndex: Int, zoom: Float, format: Int32 = 0) throws -> RenderedImage

Отрендерить страницу с заданным коэффициентом масштабирования.

func renderPageThumbnail(_ pageIndex: Int, size: Int, format: Int32 = 0) throws -> RenderedImage

Отрендерить миниатюру, вписывающуюся в size пикселей.

func renderPageWithOptions(
    _ pageIndex: Int, dpi: Int32 = 150, format: Int32 = 0,
    bgR: Float = 1, bgG: Float = 1, bgB: Float = 1, bgA: Float = 1,
    transparentBackground: Bool = false, renderAnnotations: Bool = true, jpegQuality: Int32 = 90
) throws -> RenderedImage

Отрендерить с полным набором параметров рендеринга (DPI, цвет/прозрачность фона, аннотации, качество JPEG).

func renderPageWithOptionsEx(
    _ pageIndex: Int, dpi: Int32 = 150, format: Int32 = 0,
    bgR: Float = 1, bgG: Float = 1, bgB: Float = 1, bgA: Float = 1,
    transparentBackground: Bool = false, renderAnnotations: Bool = true,
    jpegQuality: Int32 = 90, excludedLayers: [String] = []
) throws -> RenderedImage

Отрендерить с полным набором параметров плюс список имён OCG-слоёв, которые нужно скрыть.

func renderPageRegion(
    _ pageIndex: Int, cropX: Float, cropY: Float, cropWidth: Float, cropHeight: Float,
    format: Int32 = 0
) throws -> RenderedImage

Отрендерить прямоугольную область страницы.

func renderPageFit(_ pageIndex: Int, width: Int32, height: Int32, format: Int32 = 0) throws -> RenderedImage

Отрендерить страницу так, чтобы она вписывалась в width×height пикселей с сохранением соотношения сторон.

func renderPageRaw(_ pageIndex: Int, dpi: Int32 = 150) throws -> (image: RenderedImage, width: Int, height: Int)

Отрендерить в сырой буфер RGBA8888 с предварительно умноженной альфой плюс размеры в пикселях.

func estimateRenderTime(_ pageIndex: Int) throws -> Int32

Оценить стоимость рендеринга страницы (единицы измерения зависят от реализации).

OCR

func ocrPageNeedsOcr(_ pageIndex: Int) throws -> Bool

Эвристически определить, нужен ли странице OCR (например, для отсканированной страницы).

func ocrExtractText(_ pageIndex: Int, engine: OcrEngine? = nil) throws -> String

Извлечь текст с помощью OCR. Передайте собственный OcrEngine или nil для движка по умолчанию.

Формы

func formFields() throws -> [FormField]

Перечислить все поля формы с именем, значением, типом и флагами «только для чтения»/«обязательное».

func exportFormData(formatType: Int32) throws -> [UInt8]

Экспортировать данные формы в виде байтов FDF/XFDF.

func importFormData(_ dataPath: String) throws -> Int32
func importFormFromFile(_ filename: String) throws -> Bool

Импортировать данные формы из пути к файлу.

Структура документа

func outline() throws -> String
func pageLabels() throws -> String
func xmpMetadata() throws -> String
func sourceBytes() throws -> [UInt8]
func planSplitByBookmarks(optionsJson: String = "{}") throws -> String

Прочитать оглавление документа, метки страниц, метаданные XMP, сырые исходные байты или JSON-план разделения на основе закладок.

Очистка содержимого

func eraseHeader(_ pageIndex: Int) throws -> Int32
func eraseFooter(_ pageIndex: Int) throws -> Int32
func eraseArtifacts(_ pageIndex: Int) throws -> Int32
func removeHeaders(threshold: Float) throws -> Int32
func removeFooters(threshold: Float) throws -> Int32
func removeArtifacts(threshold: Float) throws -> Int32

Удалить колонтитулы/артефакты на одной странице или по всему документу с использованием порога частоты.

Валидация

func validatePdfA(_ level: Int32) throws -> PdfAResults
func validatePdfUa(_ level: Int32) throws -> UaResults
func validatePdfX(_ level: Int32) throws -> PdfXResults

Проверить документ на соответствие уровням PDF/A, PDF/UA или PDF/X.

func convertToPdfA(_ level: Int32) throws -> Bool

Преобразовать документ в PDF/A на месте. Возвращает true при успехе.

Подписи

func sign(_ certificate: Certificate, reason: String, location: String) throws -> Int32

Подписать документ сертификатом, встроив причину и местоположение.

func signatureCount() throws -> Int
func signature(_ index: Int) throws -> SignatureInfo?
func verifyAllSignatures() throws -> Int32
func hasTimestamp() throws -> Bool
func dss() throws -> Dss?

Проанализировать существующие подписи, проверить все подписи (1=действительна, 0=недействительна, -1=неизвестно), проверить наличие метки времени документа и получить доступ к Document Security Store.

Штрихкоды

func addBarcodeToPage(_ page: Int, _ barcode: BarcodeImage, x: Float, y: Float, width: Float, height: Float) throws

Нарисовать сгенерированный BarcodeImage на странице в заданной позиции и заданного размера.

---

Page

Лёгкий постраничный дескриптор, возвращаемый методом Document.page(_:). Все методы доступа делегируют родительскому документу.

let index: Int

Индекс страницы (с нуля).

func text() throws -> String
func markdown() throws -> String
func html() throws -> String
func plainText() throws -> String

Извлечь страницу как обычный текст, Markdown или HTML.

---

Pdf

Класс для создания PDF из исходных форматов и их сохранения.

Фабричные методы

static func fromMarkdown(_ md: String) throws -> Pdf
static func fromHtml(_ html: String) throws -> Pdf
static func fromText(_ text: String) throws -> Pdf

Создать PDF из Markdown, HTML или обычного текста.

static func fromImage(_ path: String) throws -> Pdf
static func fromImageBytes(_ bytes: [UInt8]) throws -> Pdf

Создать одностраничный PDF из файла изображения или байтов изображения.

static func fromHtmlCss(html: String, css: String, fontBytes: [UInt8] = []) throws -> Pdf

Создать PDF из HTML + CSS с необязательным встроенным шрифтом.

static func fromHtmlCssWithFonts(html: String, css: String, fonts: [(String, [UInt8])]) throws -> Pdf

Создать PDF из HTML + CSS с несколькими именованными шрифтами.

Методы

func save(_ path: String) throws
func toBytes() throws -> [UInt8]
func pageCount() throws -> Int
func close()

Сохранить в файл, получить байты PDF, подсчитать страницы или освободить дескриптор.

---

DocumentEditor

Изменяемый редактор для модификации существующих PDF: страницы, поворот, геометрия, редактирование (redaction), уплощение, формы, слияние и сохранение.

Открытие и жизненный цикл

static func openEditor(_ path: String) throws -> DocumentEditor
static func open(_ path: String) throws -> DocumentEditor
static func openFromBytes(_ bytes: [UInt8]) throws -> DocumentEditor
func close()
func free()

Открыть редактор из пути или байтов и освободить дескриптор по завершении.

Сведения и метаданные

func pageCount() throws -> Int
func version() throws -> PdfVersion
func isModified() throws -> Bool
func getSourcePath() throws -> String
func getProducer() throws -> String
func setProducer(_ value: String) throws
func getCreationDate() throws -> String
func setCreationDate(_ date: String) throws

Прочитать сведения о документе, а также получить/задать производителя (producer) и дату создания.

Операции со страницами

func deletePage(_ page: Int) throws
func movePage(_ from: Int, _ to: Int) throws
func rotatePageBy(_ page: Int, _ degrees: Int) throws
func rotateAllPages(_ degrees: Int) throws
func setPageRotation(_ page: Int, _ degrees: Int) throws
func getPageRotation(_ page: Int) throws -> Int

Удалять, перемещать и поворачивать страницы.

Геометрия страницы

func cropMargins(left: Float, right: Float, top: Float, bottom: Float) throws
func getPageCropBox(_ page: Int) throws -> Bbox
func setPageCropBox(_ page: Int, x: Double, y: Double, width: Double, height: Double) throws
func getPageMediaBox(_ page: Int) throws -> Bbox
func setPageMediaBox(_ page: Int, x: Double, y: Double, width: Double, height: Double) throws

Обрезать поля и получать/задавать геометрию CropBox и MediaBox.

Стирание и редактирование (redaction)

func eraseRegion(_ page: Int, x: Float, y: Float, width: Float, height: Float) throws
func eraseRegions(_ page: Int, _ rects: [(Double, Double, Double, Double)]) throws
func clearEraseRegions(_ page: Int) throws

Поставить в очередь и очистить прямоугольные области стирания.

func applyAllRedactions() throws
func applyPageRedactions(_ page: Int) throws
func isPageMarkedForRedaction(_ page: Int) throws -> Bool
func unmarkPageForRedaction(_ page: Int) throws

Применить отложенные редактирования и управлять постраничными метками редактирования.

func redactionAdd(_ page: Int, x1: Double, y1: Double, x2: Double, y2: Double, r: Double, g: Double, b: Double) throws
func redactionCount(_ page: Int) throws -> Int
func redactionApply(scrubMetadata: Bool, r: Double, g: Double, b: Double) throws -> Int
func redactionScrubMetadata() throws -> Int

Поставить области редактирования в очередь, подсчитать их, безвозвратно применить (возвращает количество удалённых глифов) или вычистить только метаданные/JavaScript/встроенные файлы.

Уплощение

func flattenForms() throws
func flattenFormsOnPage(_ page: Int) throws
func flattenAnnotations(_ page: Int) throws
func flattenAllAnnotations() throws
func flattenWarningsCount() throws -> Int
func flattenWarning(_ index: Int) throws -> String
func isPageMarkedForFlatten(_ page: Int) throws -> Bool
func unmarkPageForFlatten(_ page: Int) throws

Уплощать формы и аннотации, читать предупреждения об уплощении и управлять постраничными метками уплощения.

Формы

func setFormFieldValue(_ name: String, _ value: String) throws
func importFdfBytes(_ data: [UInt8]) throws -> Int32
func importXfdfBytes(_ data: [UInt8]) throws -> Int32

Задать значение поля формы или импортировать данные FDF/XFDF из байтов.

Штрихкоды

func addBarcodeToPage(_ page: Int, _ barcode: BarcodeImage, x: Float, y: Float, width: Float, height: Float) throws

Нарисовать сгенерированный штрихкод на странице.

Операции с документом

func mergeFrom(_ sourcePath: String) throws
func mergeFromBytes(_ bytes: [UInt8]) throws
func convertToPdfA(_ level: Int) throws
func embedFile(_ name: String, _ data: [UInt8]) throws
func extractPagesToBytes(_ pages: [Int]) throws -> [UInt8]

Объединить другой PDF, преобразовать в PDF/A, прикрепить файл или извлечь подмножество страниц в байты.

Сохранение

func save(_ path: String) throws
func saveToBytes() throws -> [UInt8]
func saveToBytesWithOptions(compress: Bool, garbageCollect: Bool, linearize: Bool) throws -> [UInt8]
func saveEncrypted(_ path: String, userPassword: String, ownerPassword: String) throws
func saveEncryptedToBytes(userPassword: String, ownerPassword: String) throws -> [UInt8]

Сохранить в файл или байты с необязательным сжатием/сборкой мусора/линеаризацией или шифрованием паролем AES.

---

DocumentBuilder

Текучий (fluent) строитель для создания тегированных многостраничных PDF с нуля. Большинство методов возвращают self для построения цепочек.

static func create() throws -> DocumentBuilder

Создать новый строитель документа.

Метаданные и структура

func setTitle(_ title: String) throws -> DocumentBuilder
func setAuthor(_ author: String) throws -> DocumentBuilder
func setSubject(_ subject: String) throws -> DocumentBuilder
func setKeywords(_ keywords: String) throws -> DocumentBuilder
func setCreator(_ creator: String) throws -> DocumentBuilder
func onOpen(_ script: String) throws -> DocumentBuilder
func taggedPdfUa1() throws -> DocumentBuilder
func language(_ lang: String) throws -> DocumentBuilder
func roleMap(custom: String, standard: String) throws -> DocumentBuilder
func registerEmbeddedFont(_ name: String, _ font: EmbeddedFont) throws -> DocumentBuilder

Задать метаданные документа, скрипт действия при открытии, тегирование PDF/UA, язык, карту ролей и зарегистрировать встроенные шрифты.

Страницы

func a4Page() throws -> PageBuilder
func letterPage() throws -> PageBuilder
func page(_ width: Float, _ height: Float) throws -> PageBuilder

Начать страницу A4, Letter или произвольного размера, возвращая PageBuilder.

Вывод

func build() throws -> [UInt8]
func save(_ path: String) throws
func saveEncrypted(_ path: String, userPassword: String, ownerPassword: String) throws
func toBytesEncrypted(userPassword: String, ownerPassword: String) throws -> [UInt8]
func close()

Собрать в байты, сохранить в файл или сохранить с шифрованием AES.

---

PageBuilder

Текучий (fluent) строитель содержимого одной страницы, возвращаемый методами DocumentBuilder.a4Page() / .letterPage() / .page(_:_:). Большинство методов возвращают self.

Текст и компоновка

func font(_ name: String, _ size: Float) throws -> PageBuilder
func at(_ x: Float, _ y: Float) throws -> PageBuilder
func text(_ text: String) throws -> PageBuilder
func heading(_ level: Int, _ text: String) throws -> PageBuilder
func paragraph(_ text: String) throws -> PageBuilder
func space(_ points: Float) throws -> PageBuilder
func horizontalRule() throws -> PageBuilder
func columns(_ columnCount: UInt32, _ gapPt: Float, _ text: String) throws -> PageBuilder
func footnote(_ refMark: String, _ noteText: String) throws -> PageBuilder
func newPageSameSize() throws -> PageBuilder

Задать активный шрифт и позицию, затем написать текст, заголовки, абзацы, отступы, разделители, многоколоночный поток, сноски или начать страницу того же размера.

Встроенные текстовые фрагменты

func inline(_ text: String) throws -> PageBuilder
func inlineBold(_ text: String) throws -> PageBuilder
func inlineItalic(_ text: String) throws -> PageBuilder
func inlineColor(_ r: Float, _ g: Float, _ b: Float, _ text: String) throws -> PageBuilder
func newline() throws -> PageBuilder

Добавить стилизованные встроенные текстовые фрагменты и переносы строк.

Ссылки и скрипты

func linkUrl(_ url: String) throws -> PageBuilder
func linkPage(_ page: Int) throws -> PageBuilder
func linkNamed(_ destination: String) throws -> PageBuilder
func linkJavascript(_ script: String) throws -> PageBuilder
func onOpen(_ script: String) throws -> PageBuilder
func onClose(_ script: String) throws -> PageBuilder
func fieldKeystroke(_ script: String) throws -> PageBuilder
func fieldFormat(_ script: String) throws -> PageBuilder
func fieldValidate(_ script: String) throws -> PageBuilder
func fieldCalculate(_ script: String) throws -> PageBuilder

Добавить аннотации-ссылки URL/страница/именованная/JavaScript и прикрепить скрипты уровня страницы или поля.

Аннотации-разметки

func highlight(_ r: Float, _ g: Float, _ b: Float) throws -> PageBuilder
func underline(_ r: Float, _ g: Float, _ b: Float) throws -> PageBuilder
func strikeout(_ r: Float, _ g: Float, _ b: Float) throws -> PageBuilder
func squiggly(_ r: Float, _ g: Float, _ b: Float) throws -> PageBuilder
func stickyNote(_ text: String) throws -> PageBuilder
func stickyNoteAt(_ x: Float, _ y: Float, _ text: String) throws -> PageBuilder
func watermark(_ text: String) throws -> PageBuilder
func watermarkConfidential() throws -> PageBuilder
func watermarkDraft() throws -> PageBuilder
func stamp(_ typeName: String) throws -> PageBuilder
func freetext(_ x: Float, _ y: Float, _ w: Float, _ h: Float, _ text: String) throws -> PageBuilder

Добавить разметку выделения/подчёркивания/зачёркивания/волнистого подчёркивания, заметки-стикеры, водяные знаки, штампы и свободный текст (free-text).

Поля форм

func textField(_ name: String, _ x: Float, _ y: Float, _ w: Float, _ h: Float, defaultValue: String? = nil) throws -> PageBuilder
func checkbox(_ name: String, _ x: Float, _ y: Float, _ w: Float, _ h: Float, checked: Bool) throws -> PageBuilder
func pushButton(_ name: String, _ x: Float, _ y: Float, _ w: Float, _ h: Float, _ caption: String) throws -> PageBuilder
func signatureField(_ name: String, _ x: Float, _ y: Float, _ w: Float, _ h: Float) throws -> PageBuilder
func comboBox(_ name: String, _ x: Float, _ y: Float, _ w: Float, _ h: Float, options: [String], selected: String? = nil) throws -> PageBuilder
func radioGroup(_ name: String, values: [String], xs: [Float], ys: [Float], ws: [Float], hs: [Float], selected: String? = nil) throws -> PageBuilder

Добавить текстовые поля AcroForm, флажки, кнопки, поля подписи, выпадающие списки и группы переключателей.

Штрихкоды и изображения

func barcode1d(_ barcodeType: Int32, _ data: String, _ x: Float, _ y: Float, _ w: Float, _ h: Float) throws -> PageBuilder
func barcodeQr(_ data: String, _ x: Float, _ y: Float, _ size: Float) throws -> PageBuilder
func image(_ bytes: [UInt8], _ x: Float, _ y: Float, _ w: Float, _ h: Float) throws -> PageBuilder
func imageWithAlt(_ bytes: [UInt8], _ x: Float, _ y: Float, _ w: Float, _ h: Float, altText: String) throws -> PageBuilder
func imageArtifact(_ bytes: [UInt8], _ x: Float, _ y: Float, _ w: Float, _ h: Float) throws -> PageBuilder

Нарисовать одномерные штрихкоды, QR-коды и изображения (с необязательным альтернативным текстом или тегированием как артефакт).

Векторная графика

func rect(_ x: Float, _ y: Float, _ w: Float, _ h: Float) throws -> PageBuilder
func filledRect(_ x: Float, _ y: Float, _ w: Float, _ h: Float, _ r: Float, _ g: Float, _ b: Float) throws -> PageBuilder
func line(_ x1: Float, _ y1: Float, _ x2: Float, _ y2: Float) throws -> PageBuilder
func strokeRect(_ x: Float, _ y: Float, _ w: Float, _ h: Float, width: Float, _ r: Float, _ g: Float, _ b: Float) throws -> PageBuilder
func strokeLine(_ x1: Float, _ y1: Float, _ x2: Float, _ y2: Float, width: Float, _ r: Float, _ g: Float, _ b: Float) throws -> PageBuilder
func strokeRectDashed(_ x: Float, _ y: Float, _ w: Float, _ h: Float, width: Float, _ r: Float, _ g: Float, _ b: Float, dashArray: [Float], phase: Float) throws -> PageBuilder
func strokeLineDashed(_ x1: Float, _ y1: Float, _ x2: Float, _ y2: Float, width: Float, _ r: Float, _ g: Float, _ b: Float, dashArray: [Float], phase: Float) throws -> PageBuilder
func textInRect(_ x: Float, _ y: Float, _ w: Float, _ h: Float, _ text: String, align: Int32) throws -> PageBuilder

Нарисовать прямоугольники, линии, обведённые/пунктирные фигуры и текст, ограниченный прямоугольником.

Таблицы

func table(nColumns: Int, widths: [Float], aligns: [Int32], nRows: Int, cellStrings: [String], hasHeader: Bool) throws -> PageBuilder

Буферизовать статическую таблицу; cellStrings — это построчный порядок (row * nColumns + col).

func streamingTableBegin(nColumns: Int, headers: [String], widths: [Float], aligns: [Int32], repeatHeader: Bool) throws -> PageBuilder
func streamingTableBeginV2(nColumns: Int, headers: [String], widths: [Float], aligns: [Int32], repeatHeader: Bool, mode: Int32, sampleRows: Int, minColWidthPt: Float, maxColWidthPt: Float, maxRowspan: Int) throws -> PageBuilder
func streamingTableSetBatchSize(_ batchSize: Int) throws -> PageBuilder
func streamingTablePendingRowCount() throws -> Int
func streamingTableBatchCount() throws -> Int
func streamingTableFlush() throws -> PageBuilder
func streamingTablePushRow(_ cells: [String]) throws -> PageBuilder
func streamingTablePushRowV2(_ cells: [String], rowspans: [Int]?) throws -> PageBuilder
func streamingTableFinish() throws -> PageBuilder

Строить большие таблицы инкрементально с потоковыми строками, необязательным объединением строк (rowspan), пакетной обработкой и режимами автоподбора.

Завершение

func done() throws
func close()

Завершить страницу и вернуть управление родительскому строителю.

---

EmbeddedFont

Шрифт, зарегистрированный в DocumentBuilder.

static func fromFile(_ path: String) throws -> EmbeddedFont
static func fromBytes(_ bytes: [UInt8], name: String? = nil) throws -> EmbeddedFont
func close()

Загрузить шрифт TrueType/OpenType из файла или байтов.

---

BarcodeImage

Генерация и анализ одномерных/двумерных штрихкодов.

static func generateQrCode(_ data: String, errorCorrection: Int32 = 1, sizePx: Int32 = 256) throws -> BarcodeImage
static func generateBarcode(_ data: String, format: Int32, sizePx: Int32 = 256) throws -> BarcodeImage

Сгенерировать QR-код или штрихкод заданного формата.

func data() throws -> String
func format() throws -> Int32
func confidence() throws -> Float
func imagePng(sizePx: Int32 = 256) throws -> [UInt8]
func svg(sizePx: Int32 = 256) throws -> String
func close()

Прочитать декодированную полезную нагрузку, формат и уверенность распознавания или отрендерить штрихкод в байты PNG либо строку SVG.

---

RenderedImage

Отрендеренное изображение страницы, возвращаемое методами Document.renderPage*.

let width: Int
let height: Int
let data: [UInt8]
func save(_ path: String) throws
func close()

Размеры в пикселях, закодированные байты изображения и вспомогательный метод для сохранения изображения в файл.

---

Renderer

Отдельный дескриптор конфигурации рендерера.

static func create(dpi: Int32 = 150, format: Int32 = 0, quality: Int32 = 90, antiAlias: Bool = true) throws -> Renderer
func close()

Создать переиспользуемый рендерер с настройками DPI, формата (0=PNG, 1=JPEG), качества JPEG и сглаживания.

---

OcrEngine

OCR-движок, использующий модели обнаружения/распознавания.

static func create(detModelPath: String, recModelPath: String, dictPath: String) throws -> OcrEngine
func close()

Создать движок из путей к модели обнаружения, модели распознавания и словарю. Передайте его в Document.ocrExtractText(_:engine:).

---

Certificate

Сертификат подписи и ключ.

static func loadFromBytes(_ bytes: [UInt8], password: String) throws -> Certificate
static func loadFromPem(certPem: String, keyPem: String) throws -> Certificate

Загрузить сертификат из байтов PKCS#12 (с паролем) или из строк PEM.

func subject() throws -> String
func issuer() throws -> String
func serial() throws -> String
func validity() throws -> CertificateValidity
func isValid() throws -> Bool
func close()

Прочитать субъект, издателя, серийный номер, окно действия и текущую действительность.

---

SignatureInfo

Сведения о существующей подписи, возвращаемые методом Document.signature(_:).

func signerName() throws -> String
func signingReason() throws -> String
func signingLocation() throws -> String
func signingTime() throws -> Int64
func certificate() throws -> Certificate?
func padesLevel() throws -> Int32
func hasTimestamp() throws -> Bool
func timestamp() throws -> Timestamp?
func addTimestamp(_ ts: Timestamp) throws -> Bool
func verify() throws -> Int32
func verifyDetached(_ pdf: [UInt8]) throws -> Int32
func close()

Прочитать метаданные подписавшего, сертификат, уровень PAdES и метку времени; проверить подпись (с необязательной проверкой отделённого дайджеста сообщения).

---

Timestamp

Токен метки времени RFC 3161.

static func parse(_ bytes: [UInt8]) throws -> Timestamp
func token() throws -> [UInt8]
func messageImprint() throws -> [UInt8]
func time() throws -> Int64
func serial() throws -> String
func tsaName() throws -> String
func policyOid() throws -> String
func hashAlgorithm() throws -> Int32
func verify() throws -> Bool
func close()

Разобрать токен метки времени и прочитать его поля или проверить его.

---

TsaClient

Клиент центра меток времени (Time-Stamping Authority) (за фичей tsa-client).

static func create(url: String, username: String? = nil, password: String? = nil,
                   timeout: Int32 = 30, hashAlgo: Int32 = 0, useNonce: Bool = true, certReq: Bool = true) throws -> TsaClient
func requestTimestamp(_ data: [UInt8]) throws -> Timestamp
func requestTimestampHash(_ hash: [UInt8], hashAlgo: Int32) throws -> Timestamp
func close()

Настроить конечную точку TSA и запросить метки времени по данным или по предварительно вычисленному хешу.

---

Dss

Document Security Store, возвращаемое методом Document.dss().

func certCount() throws -> Int
func crlCount() throws -> Int
func ocspCount() throws -> Int
func vriCount() throws -> Int
func cert(_ index: Int) throws -> [UInt8]
func crl(_ index: Int) throws -> [UInt8]
func ocsp(_ index: Int) throws -> [UInt8]
func close()

Подсчитать и прочитать сертификаты, CRL и ответы OCSP, сохранённые для долгосрочной проверки (long-term validation).

---

PdfAResults / UaResults / PdfXResults

Дескрипторы результатов валидации, возвращаемые методами Document.validatePdfA/Ua/X(_:).

// PdfAResults
func isCompliant() throws -> Bool
func errors() throws -> [String]
func warningCount() throws -> Int
func close()

// UaResults
func isAccessible() throws -> Bool
func errors() throws -> [String]
func warnings() throws -> [String]
func stats() throws -> UaStats
func close()

// PdfXResults
func isCompliant() throws -> Bool
func errors() throws -> [String]
func close()

Проверить соответствие/доступность, списки ошибок и предупреждений, а также статистику PDF/UA.

---

ElementList

Универсальный постраничный список элементов, возвращаемый методом Document.pageElements(_:).

func count() throws -> Int
func element(_ index: Int) throws -> Element
func all() throws -> [Element]
func toJson() throws -> String
func close()

Перебрать элементы страницы (тип, текст, прямоугольник) или сериализовать их в JSON.

---

Функции верхнего уровня

Свободные функции, работающие с сырыми байтами или глобальным состоянием.

func signBytes(_ pdf: [UInt8], certificate: Certificate, reason: String? = nil, location: String? = nil) throws -> [UInt8]

Подписать сырые байты PDF и вернуть подписанный PDF.

func signBytesPades(_ pdf: [UInt8], certificate: Certificate, level: Int32,
                    tsaUrl: String? = nil, reason: String? = nil, location: String? = nil,
                    certs: [[UInt8]] = [], crls: [[UInt8]] = [], ocsps: [[UInt8]] = []) throws -> [UInt8]

Подписать на базовом уровне PAdES (0=B-B, 1=B-T, 2=B-LT) с необязательным URL TSA и материалом отзыва.

func signBytesPadesOpts(_ pdf: [UInt8], certificate: Certificate, level: Int32,
                        tsaUrl: String? = nil, reason: String? = nil, location: String? = nil,
                        certs: [[UInt8]] = [], crls: [[UInt8]] = [], ocsps: [[UInt8]] = []) throws -> [UInt8]

Вариант signBytesPades с параметрами в виде структуры.

func merge(_ paths: [String]) throws -> [UInt8]

Объединить PDF по путям paths (по порядку) в один PDF в памяти.

func addTimestamp(_ pdfData: [UInt8], sigIndex: Int32, tsaUrl: String) throws -> [UInt8]

Добавить метку времени RFC 3161 к подписи и вернуть пересохранённые байты PDF.

func setLogLevel(_ level: Int32)
func getLogLevel() -> Int32

Задать или прочитать глобальный уровень логирования библиотеки (0=Off … 5=Trace).

---

PdfOxide (Глобальная конфигурация)

Перечисление PdfOxide группирует криптографическую политику уровня процесса, предзагрузку моделей и конфигурацию парсера.

static func cryptoActiveProvider() -> String
static func cryptoCbom() -> String
static func cryptoFipsAvailable() -> Int32
static func cryptoInventory() -> String
static func cryptoPolicy() -> String
static func cryptoSetPolicy(_ spec: String) -> Int32
static func cryptoUseFips() -> Int32

Проанализировать и настроить криптографического провайдера, CBOM/инвентаризацию, политику и режим FIPS.

static func modelManifest() -> String
static func prefetchAvailable() -> Int32
static func prefetchModels(languagesCsv: String) throws -> String

Прочитать манифест OCR-моделей и предзагрузить модели для списка языков, разделённого запятыми.

static func setMaxOpsPerStream(_ limit: Int64) -> Int64
static func setPreserveUnmappedGlyphs(_ preserve: Int32) -> Int32

Настроить лимиты парсера и поведение сопоставления глифов.

---

Типы-значения

Простые структуры, возвращаемые методами извлечения.

PdfOxideError

struct PdfOxideError: Error, CustomStringConvertible {
    let code: Int32
    let op: String
}

Выбрасывается при любом коде ошибки C ABI, отличном от успешного.

PdfVersion

struct PdfVersion { let major: Int; let minor: Int }

Версия PDF (например, 1.7).

Bbox

struct Bbox { let x: Double; let y: Double; let width: Double; let height: Double }

Ограничивающий прямоугольник, выровненный по осям, в единицах пользовательского пространства PDF.

Char

struct Char { let character: UInt32; let bbox: Bbox; let fontName: String; let fontSize: Double }

Один извлечённый символ (скалярное значение Unicode).

Word

struct Word { let text: String; let bbox: Bbox; let fontName: String; let fontSize: Double; let bold: Bool }

Одно извлечённое слово.

TextLine

struct TextLine { let text: String; let bbox: Bbox; let wordCount: Int }

Одна извлечённая строка текста.

Table

struct Table {
    let rowCount: Int
    let colCount: Int
    let hasHeader: Bool
    func cell(_ row: Int, _ col: Int) -> String
}

Одна извлечённая таблица; ячейки читаются по запросу через cell(_:_:).

Font

struct Font { let name: String; let type: String; let encoding: String; let embedded: Bool; let subset: Bool }

Дескриптор встроенного шрифта.

Image

struct Image {
    let width: Int
    let height: Int
    let bitsPerComponent: Int
    let format: String
    let colorspace: String
    let data: [UInt8]
}

Извлечённое растровое изображение с его сырыми байтами.

Annotation

struct Annotation { let type: String; let subtype: String; let content: String; let author: String; let rect: Bbox; let borderWidth: Double }

Основные атрибуты аннотации.

AnnotationExtras

struct AnnotationExtras {
    let color: UInt32
    let creationDate: Int64
    let modificationDate: Int64
    let hidden: Bool
    let markedDeleted: Bool
    let printable: Bool
    let readOnly: Bool
    let uri: String
    let iconName: String
    let quadPoints: [QuadPoint]
}

Расширенные атрибуты аннотации из annotationExtras(_:index:).

Path

struct Path { let bbox: Bbox; let strokeWidth: Double; let hasStroke: Bool; let hasFill: Bool; let operationCount: Int }

Сводка геометрии векторного контура.

SearchResult

struct SearchResult { let text: String; let page: Int; let bbox: Bbox }

Совпадение текстового поиска.

FormField

struct FormField { let name: String; let value: String; let type: String; let readonly: Bool; let required: Bool }

Дескриптор поля формы.

QuadPoint

struct QuadPoint { let x1, y1, x2, y2, x3, y3, x4, y4: Double }

Четырёхугольник аннотации-разметки.

Element

struct Element { let type: String; let text: String; let rect: Bbox }

Универсальный элемент страницы из ElementList.

CertificateValidity

struct CertificateValidity { let notBefore: Int64; let notAfter: Int64 }

Окно действия сертификата (метки времени Unix).

UaStats

struct UaStats { let structElements: Int; let images: Int; let tables: Int; let forms: Int; let annotations: Int; let pages: Int }

Статистика структуры PDF/UA из UaResults.stats().

---

Полный пример

import PdfOxide

// --- Extraction ---
let doc = try Document.open("input.pdf")
print("Pages: \(try doc.pageCount())")

for i in 0..<(try doc.pageCount()) {
    let text = try doc.extractText(i)
    print("Page \(i + 1): \(text.count) characters")
}

// Word-level geometry
let words = try doc.extractWords(0)
for w in words.prefix(5) {
    print("'\(w.text)' at \(w.bbox) font=\(w.fontName) size=\(w.fontSize)")
}

// Render the first page to PNG
let image = try doc.renderPage(0, format: 0)
try image.save("page0.png")

// --- Creation (fluent) ---
let builder = try DocumentBuilder.create()
try builder.setTitle("Report")
let page = try builder.letterPage()
try page.at(72, 720).font("Helvetica", 18).heading(1, "Report")
try page.paragraph("Generated by PDF Oxide.")
try page.done()
try builder.save("report.pdf")

// --- Editing ---
let editor = try DocumentEditor.open("document.pdf")
try editor.rotateAllPages(90)
try editor.setFormFieldValue("name", "John Doe")
try editor.mergeFrom("appendix.pdf")
try editor.save("output.pdf")

// --- Signatures ---
let cert = try Certificate.loadFromBytes(p12Bytes, password: "secret")
let signed = try signBytesPades(pdfBytes, certificate: cert, level: 1,
                                tsaUrl: "https://freetsa.org/tsr")

Other Language Bindings

PDF Oxide предоставляет нативные привязки для всех основных экосистем: Rust, Python, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C, и Elixir.

Дальнейшие шаги

• Типы и перечисления — все общие типы и перечисления
• Справочник Page API — единообразная постраничная итерация для всех привязок
• Начало работы с Swift — учебное руководство