kpermute

com.eignex.kpermute/IntPermutation

IntPermutation

interface IntPermutation : Iterable<Int> (source)

Reversible permutation over a 32-bit integer domain.

An IntPermutation defines a bijection on either:

a finite domain [0, size) when size >= 0, or
the full signed 32-bit space when size == -1.

Implementations are deterministic: the same instance always maps the same input to the same output, and decode is the exact inverse of encode. They are designed for tasks such as data shuffling, masking, and index remapping without storing full lookup tables.

Security note: These permutations are not cryptographic. They are not PRPs and are not intended to resist adversarial inversion or analysis.

Contract:

For finite domains (size >= 0), valid inputs to encode and decode are in [0, size). Out-of-range values trigger IllegalArgumentException.
encodeUnchecked and decodeUnchecked skip range checks and must only be called with valid domain values when size >= 0.
iterator yields encode(i) for all valid i in index order.

Use intPermutation to construct concrete implementations.

Inheritors

ArrayIntPermutation

FullIntPermutation

HalfIntPermutation

UIntPermutation

Properties

size

abstract val size: Int(source)

Domain size of the permutation.

size >= 0: finite domain [0, size).
size == -1: full signed 32-bit domain.

Functions

decode

open fun decode(encoded: Int): Int(source)

Decodes a previously encoded integer back to its original value.

For finite domains (size >= 0), encoded must be in [0, size).

decodeUnchecked

abstract fun decodeUnchecked(encoded: Int): Int(source)

Decodes a previously encoded value without range checks.

encode

open fun encode(value: Int): Int(source)

Encodes an integer in the permutation domain into its permuted value.

For finite domains (size >= 0), value must be in [0, size).

encodeUnchecked

abstract fun encodeUnchecked(value: Int): Int(source)

Encodes a value without range checks.

iterator

open operator override fun iterator(): IntIterator(source)

Returns an iterator over encode(i) for all i in [0, size) for finite domains, or over the full 32-bit space when size == -1.

abstract fun iterator(offset: Int): IntIterator(source)

Returns an iterator over encode(i) for indices in [offset, size).

For finite domains, offset is an index in 0..size. For full-domain implementations, semantics are defined by the implementation.

fun IntPermutation.range(range: IntRange): IntPermutation

Returns a view of this permutation that operates on range instead of [0, size). Only valid for finite domains where range.count() == size.