renamed DataColumn.create to DataColumn.crateUnsafe and added clarifying KDocs for that suite of functions to explain what they're for

Author: Jolanrensen

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/DataColumn.kt

@@ -25,6 +25,9 @@ import org.jetbrains.kotlinx.dataframe.impl.columns.toColumnKind
 import org.jetbrains.kotlinx.dataframe.impl.getValuesType
 import org.jetbrains.kotlinx.dataframe.impl.splitByIndices
 import org.jetbrains.kotlinx.dataframe.schema.DataFrameSchema
+import org.jetbrains.kotlinx.dataframe.util.CREATE_FRAME_COLUMN
+import org.jetbrains.kotlinx.dataframe.util.CREATE_FRAME_COLUMN_IMPORT
+import org.jetbrains.kotlinx.dataframe.util.CREATE_FRAME_COLUMN_REPLACE
 import kotlin.reflect.KClass
 import kotlin.reflect.KProperty
 import kotlin.reflect.KType
@@ -45,6 +48,9 @@ public interface DataColumn<out T> : BaseColumn<T> {
         /**
          * Creates [ValueColumn] using given [name], [values] and [type].
          *
+         * Be careful; values are NOT checked to adhere to [type] for efficiency,
+         * unless you specify [infer].
+         *
          * @param name name of the column
          * @param values list of column values
          * @param type type of the column
@@ -56,11 +62,20 @@ public interface DataColumn<out T> : BaseColumn<T> {
             type: KType,
             infer: Infer = Infer.None,
             defaultValue: T? = null,
-        ): ValueColumn<T> = ValueColumnImpl(values, name, getValuesType(values, type, infer), defaultValue)
+        ): ValueColumn<T> =
+            ValueColumnImpl(
+                values = values,
+                name = name,
+                type = getValuesType(values, type, infer),
+                defaultValue = defaultValue,
+            )
 
         /**
          * Creates [ValueColumn] using given [name], [values] and reified column [type].
          *
+         * Be careful; values are NOT checked to adhere to [type] for efficiency,
+         * unless you specify [infer].
+         *
          * Note, that column [type] will be defined at compile-time using [T] argument
          *
          * @param T type of the column
@@ -74,26 +89,56 @@ public interface DataColumn<out T> : BaseColumn<T> {
             infer: Infer = Infer.None,
         ): ValueColumn<T> =
             createValueColumn(
-                name,
-                values,
-                getValuesType(
-                    values,
-                    typeOf<T>(),
-                    infer,
-                ),
+                name = name,
+                values = values,
+                type = typeOf<T>(),
+                infer = infer,
             )
 
+        /**
+         * Creates [ColumnGroup] using the given [name] and [df] representing the group of columns.
+         *
+         * @param name name of the column group
+         * @param df the collection of columns representing the column group
+         */
         public fun <T> createColumnGroup(name: String, df: DataFrame<T>): ColumnGroup<T> = ColumnGroupImpl(name, df)
 
+        // TODO this shouldn't be here
         public fun <T> createFrameColumn(name: String, df: DataFrame<T>, startIndices: Iterable<Int>): FrameColumn<T> =
             FrameColumnImpl(name, df.splitByIndices(startIndices.asSequence()).toList(), lazy { df.schema() })
 
+        /**
+         * Creates [FrameColumn] using the given [name] and list of dataframes [groups].
+         *
+         * Be careful; [groups] must be a non-null list of [DataFrames][DataFrame].
+         * This is NOT checked at runtime for efficiency, nor is the validity of given [schema].
+         *
+         * @param name name of the frame column
+         * @param groups the dataframes to be put in the column
+         * @param schema an optional (lazily calculated) [DataFrameSchema] representing
+         *   the intersecting schema of [groups]
+         */
         public fun <T> createFrameColumn(
             name: String,
             groups: List<DataFrame<T>>,
             schema: Lazy<DataFrameSchema>? = null,
         ): FrameColumn<T> = FrameColumnImpl(name, groups, schema)
 
+        /**
+         * Creates either a [FrameColumn], [ColumnGroup], or [ValueColumn] by analyzing each value in
+         * [values].
+         * This is safer but less efficient than the other functions.
+         *
+         * Some conversions are done automatically to attempt to unify the values, like:
+         * - `null` -> [DataFrame.empty][DataFrame.empty]`()` and [DataRow] -> single-row [DataFrame] when there are other
+         *   [DataFrames][DataFrame] present in [values]
+         * - [List][List]`<`[DataRow][DataRow]`<*>>` -> [DataFrame]
+         * etc.
+         *
+         * @param name name of the column
+         * @param values the values to represent each row in the column
+         * @param nullable optionally you can specify whether [values] contains nulls, if `null` it is inferred.
+         */
         public fun <T> createWithTypeInference(
             name: String,
             values: List<T>,
@@ -102,9 +147,21 @@ public interface DataColumn<out T> : BaseColumn<T> {
 
         /**
          * Calls [createColumnGroup], [createFrameColumn], or [createValueColumn] based on
-         * [type] without checking the actual values in [values].
+         * [type].
+         *
+         * Be careful; Values in [values] are NOT checked to adhere to the given [type], nor
+         * do we check whether there are nulls among the values when the given type is [DataFrame]
+         * (a [FrameColumn] cannot contain `null`, this causes runtime exceptions).
+         * When [type] is `DataFrame<*>?`, a [ValueColumn] is created to avoid this issue.
+         *
+         * This may be unsafe but is more efficient than [createWithTypeInference].
+         *
+         * @param name the name of the column
+         * @param values the values to represent each row in the column
+         * @param type the (unchecked) common type of [values]
+         * @param infer in case a [ValueColumn] is created, this controls how/whether types need to be inferred
          */
-        public fun <T> create(
+        public fun <T> createUnsafe(
             name: String,
             values: List<T>,
             type: KType,
@@ -118,11 +175,27 @@ public interface DataColumn<out T> : BaseColumn<T> {
 
         /**
          * Calls [createColumnGroup], [createFrameColumn], or [createValueColumn] based on
-         * type [T] without checking the actual values in [values].
+         * type [T].
+         *
+         * Be careful; Values in [values] are NOT checked to adhere to the given [type], nor
+         * do we check whether there are nulls among the values when the given type is [DataFrame]
+         * (a [FrameColumn] cannot contain `null`, this causes runtime exceptions).
+         * When [type] is `DataFrame<*>?`, a [ValueColumn] is created to avoid this issue.
+         *
+         * This may be unsafe but is more efficient than [createWithTypeInference].
+         *
+         * @param T the (unchecked) common type of [values]
+         * @param name the name of the column
+         * @param values the values to represent each row in the column
+         * @param infer in case a [ValueColumn] is created, this controls how/whether types need to be inferred
          */
-        public inline fun <reified T> create(name: String, values: List<T>, infer: Infer = Infer.None): DataColumn<T> =
-            create(name, values, typeOf<T>(), infer)
+        public inline fun <reified T> createUnsafe(
+            name: String,
+            values: List<T>,
+            infer: Infer = Infer.None,
+        ): DataColumn<T> = createUnsafe(name, values, typeOf<T>(), infer)
 
+        /** Creates an empty [DataColumn] with given [name]. */
         public fun empty(name: String = ""): AnyCol = createValueColumn(name, emptyList<Unit>(), typeOf<Unit>())
     }
 

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/TypeConversions.kt

@@ -234,16 +234,22 @@ public enum class Infer {
 
     /**
      * Use reified type argument of an inline [DataFrame] operation as [DataColumn.type].
+     *
+     * This is the most efficient but least safe option.
      */
     None,
 
     /**
-     * Use reified type argument of an inline [DataFrame] operation as [DataColumn.type], but compute [DataColumn.hasNulls] by checking column [DataColumn.values] for an actual presence of *null* values.
+     * Use reified type argument of an inline [DataFrame] operation as [DataColumn.type],
+     * but compute [DataColumn.hasNulls] by checking column [DataColumn.values] for an actual presence of `null` values.
      */
     Nulls,
 
     /**
-     * Infer [DataColumn.type] and [DataColumn.hasNulls] from actual [DataColumn.values] using optionally provided base type as an upper bound.
+     * Infer [DataColumn.type] and [DataColumn.hasNulls] from actual [DataColumn.values] using an optionally provided
+     * base type as an upper bound.
+     *
+     * This is the least efficient but safest option.
      */
     Type,
 
@@ -306,17 +312,17 @@ public inline fun <reified T> Iterable<T>.toColumn(name: String = "", infer: Inf
     if (infer == Infer.Type) {
         DataColumn.createWithTypeInference(name, asList())
     } else {
-        DataColumn.create(name, asList(), typeOf<T>(), infer)
+        DataColumn.createUnsafe(name, asList(), typeOf<T>(), infer)
     }.forceResolve()
 
 public inline fun <reified T> Iterable<*>.toColumnOf(name: String = ""): DataColumn<T> =
-    DataColumn.create(name, asList() as List<T>, typeOf<T>()).forceResolve()
+    DataColumn.createUnsafe(name, asList() as List<T>, typeOf<T>()).forceResolve()
 
 public inline fun <reified T> Iterable<T>.toColumn(ref: ColumnReference<T>): DataColumn<T> =
-    DataColumn.create(ref.name(), asList()).forceResolve()
+    DataColumn.createUnsafe(ref.name(), asList()).forceResolve()
 
 public inline fun <reified T> Iterable<T>.toColumn(property: KProperty<T>): DataColumn<T> =
-    DataColumn.create(property.columnName, asList()).forceResolve()
+    DataColumn.createUnsafe(property.columnName, asList()).forceResolve()
 
 public fun Iterable<String>.toPath(): ColumnPath = ColumnPath(asList())
 

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/constructors.kt

@@ -290,7 +290,7 @@ public fun dataFrameOf(header: Iterable<String>, values: Iterable<Any?>): DataFr
 public inline fun <T, reified C> dataFrameOf(header: Iterable<T>, fill: (T) -> Iterable<C>): DataFrame<*> =
     header.map { value ->
         fill(value).asList().let {
-            DataColumn.create(value.toString(), it)
+            DataColumn.createUnsafe(value.toString(), it)
         }
     }.toDataFrame()
 
@@ -325,7 +325,7 @@ public class DataFrameBuilder(private val header: List<String>) {
     public inline operator fun <reified T> invoke(crossinline valuesBuilder: (String) -> Iterable<T>): DataFrame<*> =
         withColumns { name ->
             valuesBuilder(name).let {
-                DataColumn.create(
+                DataColumn.createUnsafe(
                     name = name,
                     values = it.asList(),
                 )
@@ -345,15 +345,15 @@ public class DataFrameBuilder(private val header: List<String>) {
 
     public inline fun <reified C> fillIndexed(nrow: Int, crossinline init: (Int, String) -> C): DataFrame<*> =
         withColumns { name ->
-            DataColumn.create(
+            DataColumn.createUnsafe(
                 name,
                 List(nrow) { init(it, name) },
             )
         }
 
     public inline fun <reified C> fill(nrow: Int, crossinline init: (Int) -> C): DataFrame<*> =
         withColumns { name ->
-            DataColumn.create(
+            DataColumn.createUnsafe(
                 name = name,
                 values = List(nrow, init),
             )

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/map.kt

@@ -34,20 +34,20 @@ public inline fun <T, reified R> DataColumn<T>.map(
     crossinline transform: (T) -> R,
 ): DataColumn<R> {
     val newValues = Array(size()) { transform(get(it)) }.asList()
-    return DataColumn.create(name(), newValues, typeOf<R>(), infer)
+    return DataColumn.createUnsafe(name(), newValues, typeOf<R>(), infer)
 }
 
 public fun <T, R> DataColumn<T>.map(type: KType, infer: Infer = Infer.Nulls, transform: (T) -> R): DataColumn<R> {
     val values = Array<Any?>(size()) { transform(get(it)) }.asList()
-    return DataColumn.create(name(), values, type, infer).cast()
+    return DataColumn.createUnsafe(name(), values, type, infer).cast()
 }
 
 public inline fun <T, reified R> DataColumn<T>.mapIndexed(
     infer: Infer = Infer.Nulls,
     crossinline transform: (Int, T) -> R,
 ): DataColumn<R> {
     val newValues = Array(size()) { transform(it, get(it)) }.asList()
-    return DataColumn.create(name(), newValues, typeOf<R>(), infer)
+    return DataColumn.createUnsafe(name(), newValues, typeOf<R>(), infer)
 }
 
 public fun <T, R> DataColumn<T>.mapIndexed(
@@ -56,7 +56,7 @@ public fun <T, R> DataColumn<T>.mapIndexed(
     transform: (Int, T) -> R,
 ): DataColumn<R> {
     val values = Array<Any?>(size()) { transform(it, get(it)) }.asList()
-    return DataColumn.create(name(), values, type, infer).cast()
+    return DataColumn.createUnsafe(name(), values, type, infer).cast()
 }
 
 // endregion

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/sort.kt

@@ -94,7 +94,7 @@ private interface CommonDataColumnSortWithDocs
 
 /** @include [CommonDataColumnSortWithDocs] */
 public fun <T, C : DataColumn<T>> C.sortWith(comparator: Comparator<T>): C =
-    DataColumn.create(name, values().sortedWith(comparator), type) as C
+    DataColumn.createUnsafe(name, values().sortedWith(comparator), type) as C
 
 /** @include [CommonDataColumnSortWithDocs] */
 public fun <T, C : DataColumn<T>> C.sortWith(comparator: (T, T) -> Int): C = sortWith(Comparator(comparator))

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/valueCounts.kt

@@ -40,9 +40,9 @@ public fun <T> DataColumn<T>.valueCounts(
     }
     if (dropNA) grouped = grouped.filter { !it.first.isNA }
     val nulls = if (dropNA) false else hasNulls()
-    val values = DataColumn.create(name(), grouped.map { it.first }, type().withNullability(nulls))
+    val values = DataColumn.createUnsafe(name(), grouped.map { it.first }, type().withNullability(nulls))
     val countName = if (resultColumn == name()) resultColumn + "1" else resultColumn
-    val counts = DataColumn.create(countName, grouped.map { it.second }, typeOf<Int>())
+    val counts = DataColumn.createUnsafe(countName, grouped.map { it.second }, typeOf<Int>())
     return dataFrameOf(values, counts).cast()
 }
 

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/api/parse.kt

@@ -525,7 +525,7 @@ internal fun DataColumn<String?>.tryParseImpl(options: ParserOptions?): DataColu
     if (type.jvmErasure == String::class && !nullStringParsed) {
         return this // nothing parsed
     }
-    return DataColumn.create(name(), parsedValues, type)
+    return DataColumn.createUnsafe(name(), parsedValues, type)
 }
 
 internal fun <T> DataColumn<String?>.parse(parser: StringParser<T>, options: ParserOptions?): DataColumn<T?> {

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/FrameColumnImpl.kt

@@ -33,6 +33,17 @@ internal open class FrameColumnImpl<T> constructor(
         // This only runs with `kotlin.dataframe.debug=true` in gradle.properties.
         if (BuildConfig.DEBUG) {
             require(!values.anyNull()) { "FrameColumn cannot null values." }
+
+//            val schema = columnSchema?.value
+//                ?: values.mapNotNull { it.takeIf { it.nrow > 0 }?.schema() }.intersectSchemas()
+//
+//            for (df in values) {
+//                val dfSchema = df.schema()
+//                if (dfSchema.columns.isEmpty()) continue
+//                require(dfSchema.compare(schema).isDerivedOrEqual()) {
+//                    "DataFrames in FrameColumn don't adhere to the given schema:\nGiven:\n$schema\n\nActual:\n$dfSchema"
+//                }
+//            }
         }
     }
 

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/constructors.kt

@@ -59,7 +59,7 @@ internal fun <T, R> ColumnsContainer<T>.newColumn(
     val df = this as? DataFrame<T> ?: dataFrameOf(columns()).cast()
     val (nullable, values) = computeValues(df, expression)
     return when (infer) {
-        Infer.Nulls -> DataColumn.create(
+        Infer.Nulls -> DataColumn.createUnsafe(
             name = name,
             values = values,
             type = type.withNullability(nullable).replaceGenericTypeParametersWithUpperbound(),
@@ -72,7 +72,7 @@ internal fun <T, R> ColumnsContainer<T>.newColumn(
             nullable = nullable,
         )
 
-        Infer.None -> DataColumn.create(
+        Infer.None -> DataColumn.createUnsafe(
             name = name,
             values = values,
             type = type.replaceGenericTypeParametersWithUpperbound(),

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/columns/DataColumns.kt

@@ -44,7 +44,7 @@ class DataColumns {
         }
 
         shouldThrow<IllegalArgumentException> {
-            DataColumn.create(
+            DataColumn.createUnsafe(
                 "",
                 listOf(dataFrameOf("a")(1), null),
             )