Merge branch 'master' into functions_inline

# Conflicts:
#	core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/max.kt
#	core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/min.kt
#	core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/Utils.kt

Author: AndreiKingsley

KDOC_PREPROCESSING.md

@@ -356,7 +356,7 @@ Since [v0.3.9](https://github.com/Jolanrensen/KoDEx/releases/tag/v0.3.9) it's al
 exclude a whole file from the `sources.jar` by adding the annotation to the top of the file,
 like `@file:ExcludeFromSources`.
 
-## KoDEX Conventions in DataFrame
+## KoDEx Conventions in DataFrame
 
 ### Common Concepts and Definitions
 

README.md

@@ -219,21 +219,21 @@ Check it out on [**Datalore**](https://datalore.jetbrains.com/view/notebook/vq5j
 
 Explore [**more examples here**](examples).
 
-## Kotlin, Kotlin Jupyter, OpenAPI, Arrow and JDK versions
+## Kotlin, Kotlin Jupyter, Arrow, and JDK versions
 
 This table shows the mapping between main library component versions and minimum supported Java versions.
 
-| Kotlin DataFrame Version | Minimum Java Version | Kotlin Version | Kotlin Jupyter Version | OpenAPI version | Apache Arrow version |
-|--------------------------|----------------------|----------------|------------------------|-----------------|----------------------|
-| 0.10.0                   | 8                    | 1.8.20         | 0.11.0-358             | 3.0.0           | 11.0.0               |
-| 0.10.1                   | 8                    | 1.8.20         | 0.11.0-358             | 3.0.0           | 11.0.0               |
-| 0.11.0                   | 8                    | 1.8.20         | 0.11.0-358             | 3.0.0           | 11.0.0               |
-| 0.11.1                   | 8                    | 1.8.20         | 0.11.0-358             | 3.0.0           | 11.0.0               |
-| 0.12.0                   | 8                    | 1.9.0          | 0.11.0-358             | 3.0.0           | 11.0.0               |
-| 0.12.1                   | 8                    | 1.9.0          | 0.11.0-358             | 3.0.0           | 11.0.0               |
-| 0.13.1                   | 8                    | 1.9.22         | 0.12.0-139             | 3.0.0           | 15.0.0               |
-| 0.14.1                   | 8                    | 2.0.20         | 0.12.0-139             | 3.0.0           | 17.0.0               |
-| 0.15.0                   | 8                    | 2.0.20         | 0.12.0-139             | 3.0.0           | 18.1.0               |
+| Kotlin DataFrame Version | Minimum Java Version | Kotlin Version | Kotlin Jupyter Version | Apache Arrow version |
+|--------------------------|----------------------|----------------|------------------------|----------------------|
+| 0.10.0                   | 8                    | 1.8.20         | 0.11.0-358             | 11.0.0               |
+| 0.10.1                   | 8                    | 1.8.20         | 0.11.0-358             | 11.0.0               |
+| 0.11.0                   | 8                    | 1.8.20         | 0.11.0-358             | 11.0.0               |
+| 0.11.1                   | 8                    | 1.8.20         | 0.11.0-358             | 11.0.0               |
+| 0.12.0                   | 8                    | 1.9.0          | 0.11.0-358             | 11.0.0               |
+| 0.12.1                   | 8                    | 1.9.0          | 0.11.0-358             | 11.0.0               |
+| 0.13.1                   | 8                    | 1.9.22         | 0.12.0-139             | 15.0.0               |
+| 0.14.1                   | 8                    | 2.0.20         | 0.12.0-139             | 17.0.0               |
+| 0.15.0                   | 8                    | 2.0.20         | 0.12.0-139             | 18.1.0               |
 
 ## Code of Conduct
 

build.gradle.kts

@@ -52,10 +52,12 @@ dependencies {
     api(projects.core)
     api(projects.dataframeArrow)
     api(projects.dataframeExcel)
-    api(projects.dataframeOpenapi)
     api(projects.dataframeJdbc)
     api(projects.dataframeCsv)
 
+    // experimental, so not included by default:
+    // api(projects.dataframeOpenapi)
+
     kover(projects.core)
     kover(projects.dataframeArrow)
     kover(projects.dataframeExcel)

core/api/core.api

@@ -27,6 +27,7 @@ import org.jetbrains.kotlinx.dataframe.io.JSON
  * @param csvOptions options to parse CSV data. Not used when data is not Csv
  * @param jsonOptions options to parse JSON data. Not used when data is not Json
  * @param jdbcOptions options to parse data from a database via JDBC. Not used when data is not stored in the database
+ * @param enableExperimentalOpenApi Can be set to `true` to enable experimental OpenAPI 3.0.0 types support
  */
 @Retention(AnnotationRetention.SOURCE)
 @Target(AnnotationTarget.FILE)
@@ -40,6 +41,7 @@ public annotation class ImportDataSchema(
     val csvOptions: CsvOptions = CsvOptions(','),
     val jsonOptions: JsonOptions = JsonOptions(),
     val jdbcOptions: JdbcOptions = JdbcOptions(),
+    val enableExperimentalOpenApi: Boolean = false,
 )
 
 public enum class DataSchemaVisibility {

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/annotations/ImportDataSchema.kt

@@ -4,6 +4,7 @@ import org.jetbrains.kotlinx.dataframe.ColumnsContainer
 import org.jetbrains.kotlinx.dataframe.DataColumn
 import org.jetbrains.kotlinx.dataframe.DataFrame
 import org.jetbrains.kotlinx.dataframe.DataRow
+import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload
 import org.jetbrains.kotlinx.dataframe.columns.ColumnAccessor
 import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup
 import org.jetbrains.kotlinx.dataframe.columns.ColumnPath
@@ -85,6 +86,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      * @throws [IllegalArgumentException] if the column is not found.
      * @return The [DataColumn] this [KProperty Accessor][KProperty] points to.
      */
+    @AccessApiOverload
     public operator fun <T> KProperty<T>.invoke(): DataColumn<T> = this@ColumnSelectionDsl[this]
 
     /**
@@ -94,6 +96,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      * @throws [IllegalArgumentException] if the column is not found.
      * @return The [ColumnGroup] this [KProperty Accessor][KProperty] points to.
      */
+    @AccessApiOverload
     public operator fun <T> KProperty<DataRow<T>>.invoke(): ColumnGroup<T> = this@ColumnSelectionDsl[this]
 
     /**
@@ -103,6 +106,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      * @throws [IllegalArgumentException] if the column is not found.
      * @return The [FrameColumn] this [KProperty Accessor][KProperty] points to.
      */
+    @AccessApiOverload
     public operator fun <T> KProperty<DataFrame<T>>.invoke(): FrameColumn<T> = this@ColumnSelectionDsl[this]
 
     /**
@@ -136,6 +140,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      */
     @Suppress("INAPPLICABLE_JVM_NAME")
     @JvmName("KPropertyDataRowGet")
+    @AccessApiOverload
     public operator fun <T, R> KProperty<DataRow<T>>.get(column: KProperty<R>): DataColumn<R> = invoke()[column]
 
     /**
@@ -154,6 +159,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      */
     @Suppress("INAPPLICABLE_JVM_NAME")
     @JvmName("KPropertyDataRowGet")
+    @AccessApiOverload
     public operator fun <T, R> KProperty<DataRow<T>>.get(column: KProperty<DataRow<R>>): ColumnGroup<R> =
         invoke()[column]
 
@@ -173,6 +179,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      */
     @Suppress("INAPPLICABLE_JVM_NAME")
     @JvmName("KPropertyDataRowGet")
+    @AccessApiOverload
     public operator fun <T, R> KProperty<DataRow<T>>.get(column: KProperty<DataFrame<R>>): FrameColumn<R> =
         invoke()[column]
 
@@ -190,6 +197,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      * @throws [IllegalArgumentException] if the column is not found.
      * @return The [DataColumn] these [KProperty Accessors][KProperty] point to.
      */
+    @AccessApiOverload
     public operator fun <T, R> KProperty<T>.get(column: KProperty<R>): DataColumn<R> = invoke().asColumnGroup()[column]
 
     /**
@@ -206,6 +214,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      * @throws [IllegalArgumentException] if the column is not found.
      * @return The [ColumnGroup] these [KProperty Accessors][KProperty] point to.
      */
+    @AccessApiOverload
     public operator fun <T, R> KProperty<T>.get(column: KProperty<DataRow<R>>): ColumnGroup<R> =
         invoke().asColumnGroup()[column]
 
@@ -223,6 +232,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      * @throws [IllegalArgumentException] if the column is not found.
      * @return The [FrameColumn] these [KProperty Accessors][KProperty] point to.
      */
+    @AccessApiOverload
     public operator fun <T, R> KProperty<T>.get(column: KProperty<DataFrame<R>>): FrameColumn<R> =
         invoke().asColumnGroup()[column]
 

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnSelectionDsl.kt

@@ -3,6 +3,7 @@ package org.jetbrains.kotlinx.dataframe.api
 import org.jetbrains.kotlinx.dataframe.ColumnsSelector
 import org.jetbrains.kotlinx.dataframe.DataFrame
 import org.jetbrains.kotlinx.dataframe.DataRow
+import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload
 import org.jetbrains.kotlinx.dataframe.columns.ColumnPath
 import org.jetbrains.kotlinx.dataframe.columns.ColumnSet
 import org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver
@@ -491,6 +492,7 @@ public interface ColumnsSelectionDsl<out T> : // SingleColumn<DataRow<T>>
      * @return A [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] containing the columns selected by [selector].
      * @see [SingleColumn.except]
      */
+    @AccessApiOverload
     public operator fun <C, R> KProperty<C>.invoke(selector: ColumnsSelector<C, R>): ColumnSet<R> =
         columnGroup(this).select(selector)
 

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt

@@ -7,6 +7,7 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup
 import org.jetbrains.kotlinx.dataframe.columns.ColumnKind
 import org.jetbrains.kotlinx.dataframe.columns.FrameColumn
 import org.jetbrains.kotlinx.dataframe.columns.ValueColumn
+import org.jetbrains.kotlinx.dataframe.impl.isIntraComparable
 import org.jetbrains.kotlinx.dataframe.impl.isMixedNumber
 import org.jetbrains.kotlinx.dataframe.impl.isPrimitiveNumber
 import org.jetbrains.kotlinx.dataframe.impl.isPrimitiveOrMixedNumber
@@ -18,11 +19,7 @@ import org.jetbrains.kotlinx.dataframe.util.IS_INTER_COMPARABLE_IMPORT
 import kotlin.contracts.ExperimentalContracts
 import kotlin.contracts.contract
 import kotlin.reflect.KType
-import kotlin.reflect.KTypeProjection
-import kotlin.reflect.KVariance
-import kotlin.reflect.full.createType
 import kotlin.reflect.full.isSubtypeOf
-import kotlin.reflect.full.withNullability
 import kotlin.reflect.typeOf
 
 public fun AnyCol.isColumnGroup(): Boolean {
@@ -93,13 +90,4 @@ public fun AnyCol.isComparable(): Boolean = valuesAreComparable()
  *
  * Technically, this means the values' common type `T(?)` is a subtype of [Comparable]`<in T>(?)`
  */
-public fun AnyCol.valuesAreComparable(): Boolean =
-    isValueColumn() &&
-        isSubtypeOf(
-            Comparable::class.createType(
-                arguments = listOf(
-                    KTypeProjection(KVariance.IN, type().withNullability(false)),
-                ),
-                nullable = hasNulls(),
-            ),
-        )
+public fun AnyCol.valuesAreComparable(): Boolean = isValueColumn() && type().isIntraComparable()

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/DataColumnType.kt

@@ -1,7 +1,7 @@
 package org.jetbrains.kotlinx.dataframe.api
 
 @PublishedApi
-internal val skipNA_default: Boolean = false
+internal val skipNaN_default: Boolean = false
 
 @PublishedApi
 internal val ddof_default: Int = 1

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/Defaults.kt

@@ -18,6 +18,8 @@ import org.jetbrains.kotlinx.dataframe.documentation.NaN
 import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns
 import org.jetbrains.kotlinx.dataframe.get
 import org.jetbrains.kotlinx.dataframe.typeClass
+import kotlin.contracts.ExperimentalContracts
+import kotlin.contracts.contract
 import kotlin.reflect.KProperty
 
 // region fillNulls
@@ -298,8 +300,30 @@ public fun <T, C> DataFrame<T>.fillNulls(vararg columns: ColumnReference<C>): Up
 
 // endregion
 
+/** Is only `true` if [this] is [Double.NaN] or [Float.NaN]. */
 internal inline val Any?.isNaN: Boolean get() = (this is Double && isNaN()) || (this is Float && isNaN())
 
+/**
+ * Returns `true` if [this] is considered NA.
+ * "NA", in DataFrame, roughly means `null` or `NaN`.
+ *
+ * Overload of `isNA` with contract support.
+ *
+ * @see NA
+ */
+@JvmName("isNaWithContract")
+@Suppress("NOTHING_TO_INLINE")
+@OptIn(ExperimentalContracts::class)
+internal inline fun <T : Any?> T.isNA(): Boolean {
+    contract { returns(false) implies (this@isNA != null) }
+    return isNA
+}
+
+/**
+ * Is `true` if [this] is considered NA.
+ * "NA", in DataFrame, roughly means `null` or `NaN`.
+ * @see NA
+ */
 internal inline val Any?.isNA: Boolean
     get() = when (this) {
         null -> true
@@ -312,10 +336,22 @@ internal inline val Any?.isNA: Boolean
 
 internal inline val AnyCol.canHaveNaN: Boolean get() = typeClass.let { it == Double::class || it == Float::class }
 
+/**
+ * Is `true` when [this] column can have [NA] values.
+ * @see NA
+ */
 internal inline val AnyCol.canHaveNA: Boolean get() = hasNulls() || canHaveNaN || kind() != ColumnKind.Value
 
+/**
+ * Is `true` when [this] is `null` or [Double.NaN].
+ * @see NA
+ */
 internal inline val Double?.isNA: Boolean get() = this == null || this.isNaN()
 
+/**
+ * Is `true` when [this] is `null` or [Float.NaN].
+ * @see NA
+ */
 internal inline val Float?.isNA: Boolean get() = this == null || this.isNaN()
 
 // region fillNaNs