Довідник 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

Перетворити Office-документ (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

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

Витягання за областю

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.

Експорт у Office

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

Прочитати інформацію про документ та отримати/встановити виробника й дату створення.

Операції зі сторінками

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

Встановити активний шрифт і позицію, а потім записати текст, заголовки, абзаци, відступи, лінії, багатоколонковий потік, виноски або розпочати сторінку того самого розміру.

Вбудовані фрагменти (runs)

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

Додати розмітку виділення/підкреслення/закреслення/хвилясту, стікери, водяні знаки, штампи та вільнотекстові анотації.

Поля форм

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, збережені для довготривалої валідації.

---

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.

Наступні кроки

• Типи та переліки — усі спільні типи та переліки
• Довідник API сторінки — узгоджена ітерація по сторінках для всіх прив’язок
• Початок роботи з Swift — посібник