kitepdf-core/io.github.yuroyami.kitepdf.core

Package-level declarations

Types

class ByteArrayBuilder(initialCapacity: Int = 64)

Grow-on-demand byte buffer. Pure Kotlin (no platform OutputStream classes), so it works in commonMain across all targets, and it's faster than mutableListOf<Byte>() because it stores into a contiguous primitive array.

ByteReader

class ByteReader(val bytes: ByteArray)

Random-access byte cursor over an in-memory PDF.

KiteDocument

interface KiteDocument

A parsed document from any handler: the fz_document equivalent. Lets a viewer treat a io.github.yuroyami.kitepdf.PdfDocument and an io.github.yuroyami.kitepdf.epub.EpubDocument uniformly.

KiteFormatException

open class KiteFormatException(message: String, cause: Throwable? = null) : RuntimeException

Common supertype for "these bytes are not a well-formed document of the format this handler reads" failures. Format handlers throw a subtype (PdfFormatException, EpubFormatException, ...) with a precise message; callers that prefer null-on-failure use the handler's openOrNull.

KiteLock

actual class KiteLock

A minimal reentrant mutual-exclusion lock (T-16). JVM/Android wrap ReentrantLock, native targets a reentrant atomic spinlock, JS/Wasm are single-threaded no-ops. Use through withLock.

expect class KiteLock

A minimal reentrant mutual-exclusion lock (T-16). JVM/Android wrap ReentrantLock, native targets a reentrant atomic spinlock, JS/Wasm are single-threaded no-ops. Use through withLock.

actual class KiteLock

Single-threaded target: locking is a no-op.

actual class KiteLock

A minimal reentrant mutual-exclusion lock (T-16). JVM/Android wrap ReentrantLock, native targets a reentrant atomic spinlock, JS/Wasm are single-threaded no-ops. Use through withLock.

actual class KiteLock

Reentrant spinlock over a single atomic owner word. POSIX mutex structs differ per native family (structs on Apple/Linux, integer typedefs on MinGW), so a portable pure-atomics lock beats four platform actuals here. Spinning is acceptable because every critical section under this lock is a few map operations; the parse work itself runs outside it (T-16). After a short spin budget the waiter yields: an empty spin on Darwin's QoS scheduler can starve a lower-priority holder scheduled on the same core (the failure mode that got OSSpinLock deprecated).

actual class KiteLock

Single-threaded target: locking is a no-op.

actual class KiteLock

Single-threaded target: locking is a no-op.

KiteMetadata

data class KiteMetadata(val title: String? = null, val authors: List<String> = emptyList(), val language: String? = null, val rightToLeft: Boolean = false)

Format-neutral document metadata, for a viewer's title bar / info panel. PDF fills it from /Info and XMP; EPUB from the OPF dc: elements.

KiteOutlineItem

class KiteOutlineItem(val title: String, val pageIndex: Int?, val children: List<KiteOutlineItem> = emptyList())

One node of a format-neutral outline (PDF bookmarks / EPUB table of contents), for a viewer's navigation panel.

KitePage

interface KitePage

A renderable page from any document handler: the format-neutral fz_page equivalent. Both io.github.yuroyami.kitepdf.PdfPage and io.github.yuroyami.kitepdf.epub.EpubPage implement it, so one viewer / rasterizer path serves every format.

KiteRawApi

@RequiresOptIn(message = "Raw PDF object-model API: stable file format, unstable Kotlin surface. May change between minor releases.", level = RequiresOptIn.Level.WARNING)

@Target(allowedTargets = [AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.CONSTRUCTOR])

annotation class KiteRawApi

Marks the raw object-model surface: direct access to xref tables, trailer dictionaries, indirect-object resolution, and the low-level editor primitives. The FILE FORMAT these expose is stable; the Kotlin surface is not, and may change between minor releases without a deprecation cycle. High-level API (pages, outlines, form fields, rendering, search) never requires this opt-in.

KiteSearchHit

class KiteSearchHit(val pageIndex: Int, val quads: List<Rectangle>, val text: String)

One search match: display-space quads (one per line touched) on page pageIndex.

KiteStructuredText

class KiteStructuredText(val blocks: List<KiteTextBlock>)

Format-neutral structured text for a KitePage: the minimal blocks → lines → text model a viewer needs for extraction, search highlights and selection, without committing to a handler's internals.

KiteTextBlock

class KiteTextBlock(val lines: List<KiteTextLine>)

A paragraph-ish group of consecutive lines from one layout block.

KiteTextLine

class KiteTextLine(val text: String, val bounds: Rectangle, val charEdges: DoubleArray)

One laid-out line. charEdges has text.length + 1 display-space x boundaries: charEdges[i] is the left edge of char i, the final entry the line's right edge. That is enough to build sub-line highlight quads.

KiteWarnings

object KiteWarnings

The fz_warn equivalent: a process-global, nullable warning sink for the places where the engine silently salvages (cached-null resolves, repair fallbacks, skipped page-tree kids, failed filters, placeholder images).

KiteWarningSink

fun interface KiteWarningSink

Receives one-line diagnostics from lenient salvage paths.

PdfFormatException

class PdfFormatException(message: String, cause: Throwable? = null) : KiteFormatException

Raised for any structural PDF error: bad header, truncated stream, malformed xref, etc.

Rectangle

data class Rectangle(val left: Double, val bottom: Double, val right: Double, val top: Double)

PDF rectangle: left, bottom, right, top in user-space units.

WrongPasswordException

class WrongPasswordException(message: String, cause: Throwable? = null) : RuntimeException

Raised when a PDF is encrypted and the supplied password did not authenticate.

Functions

currentThreadId

actual fun currentThreadId(): Long

A stable identifier for the calling thread (0 on single-threaded targets). Lets cycle guards distinguish same-thread reentrancy (a real cycle) from another thread legitimately resolving the same object concurrently.

expect fun currentThreadId(): Long

actual fun currentThreadId(): Long

kiteWarn

fun kiteWarn(message: () -> String)

Emit through KiteWarnings.sink. Message construction is lazy (free when no sink is installed) and a throwing sink can never break the caller.

withLock

inline fun <T> KiteLock.withLock(block: () -> T): T