add generated sources

Kotlin · Jan 22, 2025 · ade2d4e · ade2d4e
1 parent fda8adf
commit ade2d4e
Show file tree

Hide file tree

Showing 4 changed files with 149 additions and 0 deletions.
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt
@@ -6,38 +6,168 @@ import org.jetbrains.kotlinx.dataframe.DataFrame
 import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload
 import org.jetbrains.kotlinx.dataframe.annotations.Interpretable
 import org.jetbrains.kotlinx.dataframe.annotations.Refine
+import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
 import org.jetbrains.kotlinx.dataframe.columns.toColumnSet
+import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls.Select
 import org.jetbrains.kotlinx.dataframe.impl.api.removeImpl
+import org.jetbrains.kotlinx.dataframe.util.MINUS
+import org.jetbrains.kotlinx.dataframe.util.MINUS_REPLACE
 import kotlin.reflect.KProperty
 
 // region DataFrame
 
 // region remove
 
+/**
+ * ## The Remove Operation
+ *
+ * Removes the specified [columns] from the original [DataFrame] and returns a new [DataFrame] without them.
+ *
+ * This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
+ *
+ * See [Selecting Columns][Select.SelectSelectingOptions].
+ *
+ * For more information: [See `remove` on the documentation website.](https://kotlin.github.io/dataframe/remove.html)
+ */
+internal interface Remove
+
+/**
+ * ## The Remove Operation
+ *
+ * Removes the specified [columns][org.jetbrains.kotlinx.dataframe.columns] from the original [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] and returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] without them.
+ *
+ * This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
+ *
+ * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
+ *
+ * For more information: [See `remove` on the documentation website.](https://kotlin.github.io/dataframe/remove.html)
+ * ### This Remove Overload
+ * Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl].
+ * (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]).
+ *
+ * This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda,
+ * which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and
+ * expects you to return a [SingleColumn][org.jetbrains.kotlinx.dataframe.columns.SingleColumn] or [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] (so, a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]).
+ * This is an entity formed by calling any (combination) of the functions
+ * in the DSL that is or can be resolved into one or more columns.
+ *
+ * #### NOTE:
+ * While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]
+ * in this DSL directly with any function, they are NOT valid return types for the
+ * [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] first, for instance
+ * with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col].
+ *
+ * ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar]
+ *
+ * &nbsp;&nbsp;&nbsp;&nbsp;
+ *
+ * [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html)
+ *
+ * #### For example:
+ *
+ * `df.`<code>`operation`</code>` { length `[and][org.jetbrains.kotlinx.dataframe.api.AndColumnsSelectionDsl.and]` age }`
+ *
+ * `df.`<code>`operation`</code>`  {  `[cols][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.cols]`(1..5) }`
+ *
+ * `df.`<code>`operation`</code>`  {  `[colsOf][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.colsOf]`<`[Double][Double]`>() }`
+ *
+ *
+ * @param [columns] The [Columns Selector][ColumnsSelector] used to remove the columns of this [DataFrame].
+ */
 @Refine
 @Interpretable("Remove0")
 public fun <T> DataFrame<T>.remove(columns: ColumnsSelector<T, *>): DataFrame<T> =
     removeImpl(allowMissingColumns = true, columns = columns).df
 
+/**
+ * ## The Remove Operation
+ *
+ * Removes the specified [columns][org.jetbrains.kotlinx.dataframe.columns] from the original [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] and returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] without them.
+ *
+ * This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
+ *
+ * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
+ *
+ * For more information: [See `remove` on the documentation website.](https://kotlin.github.io/dataframe/remove.html)
+ * ### This Remove Overload
+ * Select columns using their [column names][String]
+ * ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]).
+ *
+ * #### For example:
+ *
+ * `df.`<code>`operation`</code>`("length", "age")`
+ *
+ * @param [columns] The [Column Names][String] used to remove the columns of this [DataFrame].
+ */
 public fun <T> DataFrame<T>.remove(vararg columns: String): DataFrame<T> = remove { columns.toColumnSet() }
 
+/**
+ * ## The Remove Operation
+ *
+ * Removes the specified [columns][org.jetbrains.kotlinx.dataframe.columns] from the original [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] and returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] without them.
+ *
+ * This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
+ *
+ * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
+ *
+ * For more information: [See `remove` on the documentation website.](https://kotlin.github.io/dataframe/remove.html)
+ * ### This Remove Overload
+ * Select columns using [column accessors][org.jetbrains.kotlinx.dataframe.columns.ColumnReference]
+ * ([Column Accessors API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ColumnAccessorsApi]).
+ *
+ * #### For example:
+ *
+ * `val length by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()`
+ *
+ * `val age by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()`
+ *
+ * `df.`<code>`operation`</code>`(length, age)`
+ *
+ * @param [columns] The [Column Accessors][ColumnReference] used to remove the columns of this [DataFrame].
+ */
 @AccessApiOverload
 public fun <T> DataFrame<T>.remove(vararg columns: AnyColumnReference): DataFrame<T> = remove { columns.toColumnSet() }
 
+/**
+ * ## The Remove Operation
+ *
+ * Removes the specified [columns][org.jetbrains.kotlinx.dataframe.columns] from the original [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] and returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] without them.
+ *
+ * This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
+ *
+ * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
+ *
+ * For more information: [See `remove` on the documentation website.](https://kotlin.github.io/dataframe/remove.html)
+ * ### This Remove Overload
+ * Select columns using [KProperties][KProperty] ([KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]).
+ *
+ * #### For example:
+ * ```kotlin
+ * data class Person(val length: Double, val age: Double)
+ * ```
+ *
+ * `df.`<code>`operation`</code>`(Person::length, Person::age)`
+ *
+ * @param [columns] The [KProperties][KProperty] used to remove the columns of this [DataFrame].
+ */
 @AccessApiOverload
 public fun <T> DataFrame<T>.remove(vararg columns: KProperty<*>): DataFrame<T> = remove { columns.toColumnSet() }
 
 // endregion
 
 // region minus
 
+@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.WARNING)
 public infix operator fun <T> DataFrame<T>.minus(columns: ColumnsSelector<T, *>): DataFrame<T> = remove(columns)
 
+@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.WARNING)
 public infix operator fun <T> DataFrame<T>.minus(column: String): DataFrame<T> = remove(column)
 
+@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.WARNING)
 @AccessApiOverload
 public infix operator fun <T> DataFrame<T>.minus(column: AnyColumnReference): DataFrame<T> = remove(column)
 
+@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.WARNING)
 @AccessApiOverload
 public infix operator fun <T> DataFrame<T>.minus(columns: KProperty<*>): DataFrame<T> = remove(columns)
 

diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/select.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/select.kt
@@ -25,6 +25,8 @@ import kotlin.reflect.KProperty
  *
  * Returns a new [DataFrame] with only the columns selected by [columns].
  *
+ * This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
+ *
  * See [Selecting Columns][SelectSelectingOptions].
  *
  * For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
@@ -108,6 +110,8 @@ internal interface Select {
  *
  * Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns].
  *
+ * This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
+ *
  * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
  *
  * For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
@@ -153,6 +157,8 @@ public fun <T> DataFrame<T>.select(columns: ColumnsSelector<T, *>): DataFrame<T>
  *
  * Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns].
  *
+ * This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
+ *
  * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
  *
  * For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
@@ -176,6 +182,8 @@ public fun <T> DataFrame<T>.select(vararg columns: KProperty<*>): DataFrame<T> =
  *
  * Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns].
  *
+ * This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
+ *
  * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
  *
  * For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
@@ -196,6 +204,8 @@ public fun <T> DataFrame<T>.select(vararg columns: String): DataFrame<T> = selec
  *
  * Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns].
  *
+ * This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
+ *
  * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
  *
  * For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)

diff --git a/...sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingColumns.kt b/...sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingColumns.kt
@@ -10,6 +10,7 @@ import org.jetbrains.kotlinx.dataframe.api.fillNulls
 import org.jetbrains.kotlinx.dataframe.api.gather
 import org.jetbrains.kotlinx.dataframe.api.select
 import org.jetbrains.kotlinx.dataframe.api.update
+import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup
 import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
 import org.jetbrains.kotlinx.dataframe.columns.ColumnSet
 import org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver
@@ -89,6 +90,11 @@ internal interface SelectingColumnsLink
  */
 internal interface SelectingColumns {
 
+    /**
+     * This operation can also be used on [ColumnGroup] and nested columns.
+     */
+    interface ColumnGroupsAndNestedColumnsMention
+
     /*
      * The key for a @set that will define the operation name for the examples below.
      * Make sure to [alias][your examples].

diff --git a/...rated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt b/...rated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt
@@ -79,6 +79,9 @@ internal const val IS_URL_IMPORT = "org.jetbrains.kotlinx.dataframe.io.isUrl"
 
 private const val MESSAGE_0_17 = "Will be ERROR in 0.17."
 
+internal const val MINUS = "This minus overload will be removed in favor of `remove`. $MESSAGE_0_17"
+internal const val MINUS_REPLACE = "this.remove(columns)"
+
 // endregion
 
 // region keep across releases