diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/AlgebraExtensions.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/AlgebraExtensions.kt index a6d508ee4..6712d3baa 100644 --- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/AlgebraExtensions.kt +++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/AlgebraExtensions.kt @@ -1,15 +1,62 @@ package scientifik.kmath.operations +/** + * Returns the sum of all elements in the iterable in this [Space]. + * + * @receiver the algebra that provides addition. + * @param data the collection to sum up. + * @return the sum. + */ fun Space.sum(data: Iterable): T = data.fold(zero) { left, right -> add(left, right) } + +/** + * Returns the sum of all elements in the sequence in this [Space]. + * + * @receiver the algebra that provides addition. + * @param data the collection to sum up. + * @return the sum. + */ fun Space.sum(data: Sequence): T = data.fold(zero) { left, right -> add(left, right) } +/** + * Returns the sum of all elements in the iterable in provided space. + * + * @receiver the collection to sum up. + * @param space the algebra that provides addition. + * @return the sum. + */ fun > Iterable.sumWith(space: S): T = space.sum(this) //TODO optimized power operation -fun RingOperations.power(arg: T, power: Int): T { + +/** + * Raises [arg] to the natural power [power]. + * + * @receiver the algebra to provide multiplication. + * @param arg the base. + * @param power the exponent. + * @return the base raised to the power. + */ +fun Ring.power(arg: T, power: Int): T { + require(power >= 0) { "The power can't be negative." } + require(power != 0 || arg != zero) { "The $zero raised to $power is not defined." } + if (power == 0) return one var res = arg - repeat(power - 1) { - res *= arg - } + repeat(power - 1) { res *= arg } return res } + +/** + * Raises [arg] to the integer power [power]. + * + * @receiver the algebra to provide multiplication and division. + * @param arg the base. + * @param power the exponent. + * @return the base raised to the power. + */ +fun Field.power(arg: T, power: Int): T { + require(power != 0 || arg != zero) { "The $zero raised to $power is not defined." } + if (power == 0) return one + if (power < 0) return one / (this as Ring).power(arg, -power) + return (this as Ring).power(arg, power) +} diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/OptionalOperations.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/OptionalOperations.kt index 75adb1dee..dea45a145 100644 --- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/OptionalOperations.kt +++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/OptionalOperations.kt @@ -143,7 +143,11 @@ interface PowerOperations : Algebra { } /** - * Raises [arg] to the power [pow]. + * Raises this element to the power [pow]. + * + * @receiver the base. + * @param power the exponent. + * @return the base raised to the power. */ infix fun >> T.pow(power: Double): T = context.power(this, power) diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/Buffers.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/Buffers.kt index 723348e3f..294549c31 100644 --- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/Buffers.kt +++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/Buffers.kt @@ -4,13 +4,22 @@ import scientifik.kmath.operations.Complex import scientifik.kmath.operations.complex import kotlin.reflect.KClass - +/** + * Function that produces [Buffer] from its size and function that supplies values. + * + * @param T the type of buffer. + */ typealias BufferFactory = (Int, (Int) -> T) -> Buffer -typealias MutableBufferFactory = (Int, (Int) -> T) -> MutableBuffer - /** - * A generic random access structure for both primitives and objects + * Function that produces [MutableBuffer] from its size and function that supplies values. + * + * @param T the type of buffer. + */ +typealias MutableBufferFactory = (Int, (Int) -> T) -> MutableBuffer + +/** + * A generic random-access structure for both primitives and objects. */ interface Buffer { @@ -69,12 +78,24 @@ interface Buffer { } } +/** + * Creates a sequence that returns all elements from this [Buffer]. + */ fun Buffer.asSequence(): Sequence = Sequence(::iterator) +/** + * Creates an iterable that returns all elements from this [Buffer]. + */ fun Buffer.asIterable(): Iterable = Iterable(::iterator) -val Buffer<*>.indices: IntRange get() = IntRange(0, size - 1) +/** + * Returns an [IntRange] of the valid indices for this [Buffer]. + */ +val Buffer<*>.indices: IntRange get() = 0 until size +/** + * A generic mutable random-access structure for both primitives and objects. + */ interface MutableBuffer : Buffer { operator fun set(index: Int, value: T) diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/IntBuffer.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/IntBuffer.kt index b277374ab..99fd052aa 100644 --- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/IntBuffer.kt +++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/IntBuffer.kt @@ -1,5 +1,10 @@ package scientifik.kmath.structures +/** + * Specialized [MutableBuffer] implementation over [IntArray]. + * + * @property array the underlying array. + */ inline class IntBuffer(val array: IntArray) : MutableBuffer { override val size: Int get() = array.size @@ -16,4 +21,10 @@ inline class IntBuffer(val array: IntArray) : MutableBuffer { } +/** + * Returns [IntBuffer] over this array. + * + * @receiver the array. + * @return the new buffer. + */ fun IntArray.asBuffer(): IntBuffer = IntBuffer(this) diff --git a/kmath-core/src/jvmMain/kotlin/scientifik/kmath/operations/BigNumbers.kt b/kmath-core/src/jvmMain/kotlin/scientifik/kmath/operations/BigNumbers.kt index eb268bb5e..06f2b31ad 100644 --- a/kmath-core/src/jvmMain/kotlin/scientifik/kmath/operations/BigNumbers.kt +++ b/kmath-core/src/jvmMain/kotlin/scientifik/kmath/operations/BigNumbers.kt @@ -5,7 +5,7 @@ import java.math.BigInteger import java.math.MathContext /** - * A field wrapper for Java [BigInteger] + * A field over [BigInteger]. */ object JBigIntegerField : Field { override val zero: BigInteger @@ -24,7 +24,9 @@ object JBigIntegerField : Field { } /** - * A Field wrapper for Java [BigDecimal] + * An abstract field over [BigDecimal]. + * + * @property mathContext the [MathContext] to use. */ abstract class JBigDecimalFieldBase internal constructor(val mathContext: MathContext = MathContext.DECIMAL64) : Field, @@ -50,6 +52,9 @@ abstract class JBigDecimalFieldBase internal constructor(val mathContext: MathCo } +/** + * A field over [BigDecimal]. + */ class JBigDecimalField(mathContext: MathContext = MathContext.DECIMAL64) : JBigDecimalFieldBase(mathContext) { companion object : JBigDecimalFieldBase() }