Skip to content

Commit 34bc798

Browse files
JolanrensenJolanrensen
authored
Merge pull request #1022 from Kotlin/remove_docs
`remove` docs and deprecating `df - cols`
2 parents 33b5855 + e2c0cf7 commit 34bc798

File tree

12 files changed

+231
-53
lines changed

12 files changed

+231
-53
lines changed

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

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,38 +6,168 @@ import org.jetbrains.kotlinx.dataframe.DataFrame
66
import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload
77
import org.jetbrains.kotlinx.dataframe.annotations.Interpretable
88
import org.jetbrains.kotlinx.dataframe.annotations.Refine
9+
import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
910
import org.jetbrains.kotlinx.dataframe.columns.toColumnSet
11+
import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls.Select
1012
import org.jetbrains.kotlinx.dataframe.impl.api.removeImpl
13+
import org.jetbrains.kotlinx.dataframe.util.MINUS
14+
import org.jetbrains.kotlinx.dataframe.util.MINUS_REPLACE
1115
import kotlin.reflect.KProperty
1216

1317
// region DataFrame
1418

1519
// region remove
1620

21+
/**
22+
* ## The Remove Operation
23+
*
24+
* Removes the specified [columns] from the original [DataFrame] and returns a new [DataFrame] without them.
25+
*
26+
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
27+
*
28+
* See [Selecting Columns][Select.SelectSelectingOptions].
29+
*
30+
* For more information: [See `remove` on the documentation website.](https://kotlin.github.io/dataframe/remove.html)
31+
*/
32+
internal interface Remove
33+
34+
/**
35+
* ## The Remove Operation
36+
*
37+
* 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.
38+
*
39+
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
40+
*
41+
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
42+
*
43+
* For more information: [See `remove` on the documentation website.](https://kotlin.github.io/dataframe/remove.html)
44+
* ### This Remove Overload
45+
* Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl].
46+
* (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]).
47+
*
48+
* This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda,
49+
* which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and
50+
* 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]).
51+
* This is an entity formed by calling any (combination) of the functions
52+
* in the DSL that is or can be resolved into one or more columns.
53+
*
54+
* #### NOTE:
55+
* While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]
56+
* in this DSL directly with any function, they are NOT valid return types for the
57+
* [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
58+
* with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col].
59+
*
60+
* ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar]
61+
*
62+
*     
63+
*
64+
* [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html)
65+
*
66+
* #### For example:
67+
*
68+
* `df.`[remove][org.jetbrains.kotlinx.dataframe.api.remove]` { length `[and][org.jetbrains.kotlinx.dataframe.api.AndColumnsSelectionDsl.and]` age }`
69+
*
70+
* `df.`[remove][org.jetbrains.kotlinx.dataframe.api.remove]` { `[cols][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.cols]`(1..5) }`
71+
*
72+
* `df.`[remove][org.jetbrains.kotlinx.dataframe.api.remove]` { `[colsOf][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.colsOf]`<`[Double][Double]`>() }`
73+
*
74+
*
75+
* @param [columns] The [Columns Selector][ColumnsSelector] used to remove the columns of this [DataFrame].
76+
*/
1777
@Refine
1878
@Interpretable("Remove0")
1979
public fun <T> DataFrame<T>.remove(columns: ColumnsSelector<T, *>): DataFrame<T> =
2080
removeImpl(allowMissingColumns = true, columns = columns).df
2181

82+
/**
83+
* ## The Remove Operation
84+
*
85+
* 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.
86+
*
87+
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
88+
*
89+
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
90+
*
91+
* For more information: [See `remove` on the documentation website.](https://kotlin.github.io/dataframe/remove.html)
92+
* ### This Remove Overload
93+
* Select columns using their [column names][String]
94+
* ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]).
95+
*
96+
* #### For example:
97+
*
98+
* `df.`[remove][org.jetbrains.kotlinx.dataframe.api.remove]`("length", "age")`
99+
*
100+
* @param [columns] The [Column Names][String] used to remove the columns of this [DataFrame].
101+
*/
22102
public fun <T> DataFrame<T>.remove(vararg columns: String): DataFrame<T> = remove { columns.toColumnSet() }
23103

104+
/**
105+
* ## The Remove Operation
106+
*
107+
* 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.
108+
*
109+
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
110+
*
111+
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
112+
*
113+
* For more information: [See `remove` on the documentation website.](https://kotlin.github.io/dataframe/remove.html)
114+
* ### This Remove Overload
115+
* Select columns using [column accessors][org.jetbrains.kotlinx.dataframe.columns.ColumnReference]
116+
* ([Column Accessors API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ColumnAccessorsApi]).
117+
*
118+
* #### For example:
119+
*
120+
* `val length by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()`
121+
*
122+
* `val age by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()`
123+
*
124+
* `df.`[remove][org.jetbrains.kotlinx.dataframe.api.remove]`(length, age)`
125+
*
126+
* @param [columns] The [Column Accessors][ColumnReference] used to remove the columns of this [DataFrame].
127+
*/
24128
@AccessApiOverload
25129
public fun <T> DataFrame<T>.remove(vararg columns: AnyColumnReference): DataFrame<T> = remove { columns.toColumnSet() }
26130

131+
/**
132+
* ## The Remove Operation
133+
*
134+
* 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.
135+
*
136+
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
137+
*
138+
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
139+
*
140+
* For more information: [See `remove` on the documentation website.](https://kotlin.github.io/dataframe/remove.html)
141+
* ### This Remove Overload
142+
* Select columns using [KProperties][KProperty] ([KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]).
143+
*
144+
* #### For example:
145+
* ```kotlin
146+
* data class Person(val length: Double, val age: Double)
147+
* ```
148+
*
149+
* `df.`[remove][org.jetbrains.kotlinx.dataframe.api.remove]`(Person::length, Person::age)`
150+
*
151+
* @param [columns] The [KProperties][KProperty] used to remove the columns of this [DataFrame].
152+
*/
27153
@AccessApiOverload
28154
public fun <T> DataFrame<T>.remove(vararg columns: KProperty<*>): DataFrame<T> = remove { columns.toColumnSet() }
29155

30156
// endregion
31157

32158
// region minus
33159

160+
@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
34161
public infix operator fun <T> DataFrame<T>.minus(columns: ColumnsSelector<T, *>): DataFrame<T> = remove(columns)
35162

163+
@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
36164
public infix operator fun <T> DataFrame<T>.minus(column: String): DataFrame<T> = remove(column)
37165

166+
@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
38167
@AccessApiOverload
39168
public infix operator fun <T> DataFrame<T>.minus(column: AnyColumnReference): DataFrame<T> = remove(column)
40169

170+
@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
41171
@AccessApiOverload
42172
public infix operator fun <T> DataFrame<T>.minus(columns: KProperty<*>): DataFrame<T> = remove(columns)
43173

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ import kotlin.reflect.KProperty
2525
*
2626
* Returns a new [DataFrame] with only the columns selected by [columns].
2727
*
28+
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
29+
*
2830
* See [Selecting Columns][SelectSelectingOptions].
2931
*
3032
* For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
@@ -108,6 +110,8 @@ internal interface Select {
108110
*
109111
* Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns].
110112
*
113+
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
114+
*
111115
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
112116
*
113117
* 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>
153157
*
154158
* Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns].
155159
*
160+
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
161+
*
156162
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
157163
*
158164
* 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> =
176182
*
177183
* Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns].
178184
*
185+
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
186+
*
179187
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
180188
*
181189
* 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
196204
*
197205
* Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns].
198206
*
207+
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
208+
*
199209
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
200210
*
201211
* For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)

‎core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingColumns.kt‎

Lines changed: 0 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,6 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver
1616
import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
1717
import kotlin.reflect.KProperty
1818

19-
/** [Selecting Columns][SelectingColumns] */
20-
internal interface SelectingColumnsLink
21-
2219
/**
2320
* ## Selecting Columns
2421
* Selecting columns for various operations (including but not limited to
@@ -89,16 +86,8 @@ internal interface SelectingColumnsLink
8986
*/
9087
internal interface SelectingColumns {
9188

92-
/*
93-
* The key for a @set that will define the operation name for the examples below.
94-
* Make sure to [alias][your examples].
95-
*/
96-
interface OPERATION
97-
9889
// Using <code>` notation to not create double `` when including
9990

100-
interface SetDefaultOperationArg
101-
10291
/**
10392
* Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl].
10493
* (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]).
@@ -158,9 +147,6 @@ internal interface SelectingColumns {
158147
interface WithExample
159148
}
160149

161-
/** [Columns Selection DSL][Dsl.WithExample] */
162-
interface DslLink
163-
164150
/**
165151
* Select or express a single column using the Column Selection DSL.
166152
* (Any [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]).
@@ -217,9 +203,6 @@ internal interface SelectingColumns {
217203
interface WithExample
218204
}
219205

220-
/** [Column Selection DSL][DslSingle.WithExample] */
221-
interface DslSingleLink
222-
223206
/**
224207
* Select columns using their [column names][String]
225208
* ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]).
@@ -238,9 +221,6 @@ internal interface SelectingColumns {
238221
interface WithExample
239222
}
240223

241-
/** [Column names][ColumnNames.WithExample] */
242-
interface ColumnNamesLink
243-
244224
/**
245225
* Select columns using [column accessors][ColumnReference]
246226
* ([Column Accessors API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ColumnAccessorsApi]).
@@ -263,9 +243,6 @@ internal interface SelectingColumns {
263243
interface WithExample
264244
}
265245

266-
/** [Column references][ColumnAccessors.WithExample] */
267-
interface ColumnAccessorsLink
268-
269246
/** Select columns using [KProperties][KProperty] ([KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]). */
270247
interface KProperties {
271248

@@ -282,7 +259,4 @@ internal interface SelectingColumns {
282259
*/
283260
interface WithExample
284261
}
285-
286-
/** [KProperties][KProperties.WithExample] */
287-
interface KPropertiesLink
288262
}

‎core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,9 @@ internal const val IS_URL = "This function is replaced by `isUrl()`. $MESSAGE_0_
7373
internal const val IS_URL_REPLACE = "isUrl(path)"
7474
internal const val IS_URL_IMPORT = "org.jetbrains.kotlinx.dataframe.io.isUrl"
7575

76+
internal const val MINUS = "This minus overload will be removed in favor of `remove`. $MESSAGE_0_16"
77+
internal const val MINUS_REPLACE = "this.remove(columns)"
78+
7679
// endregion
7780

7881
// region WARNING in 0.16, ERROR in 0.17

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

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,38 +6,93 @@ import org.jetbrains.kotlinx.dataframe.DataFrame
66
import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload
77
import org.jetbrains.kotlinx.dataframe.annotations.Interpretable
88
import org.jetbrains.kotlinx.dataframe.annotations.Refine
9+
import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
910
import org.jetbrains.kotlinx.dataframe.columns.toColumnSet
11+
import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls
12+
import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls.Select
13+
import org.jetbrains.kotlinx.dataframe.documentation.ExcludeFromSources
14+
import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns
1015
import org.jetbrains.kotlinx.dataframe.impl.api.removeImpl
16+
import org.jetbrains.kotlinx.dataframe.util.MINUS
17+
import org.jetbrains.kotlinx.dataframe.util.MINUS_REPLACE
1118
import kotlin.reflect.KProperty
1219

1320
// region DataFrame
1421

1522
// region remove
1623

24+
/**
25+
* ## The Remove Operation
26+
*
27+
* Removes the specified [columns] from the original [DataFrame] and returns a new [DataFrame] without them.
28+
*
29+
* @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention]
30+
*
31+
* See [Selecting Columns][Select.SelectSelectingOptions].
32+
*
33+
* For more information: {@include [DocumentationUrls.Remove]}
34+
*/
35+
internal interface Remove
36+
37+
/** {@set [SelectingColumns.OPERATION] [remove][remove]} */
38+
@ExcludeFromSources
39+
private interface SetRemoveOperationArg
40+
41+
/**
42+
* {@include [Remove]}
43+
* ### This Remove Overload
44+
*/
45+
@ExcludeFromSources
46+
private interface CommonRemoveDocs
47+
48+
/**
49+
* @include [CommonRemoveDocs]
50+
* @include [SelectingColumns.Dsl.WithExample] {@include [SetRemoveOperationArg]}
51+
* @param [columns] The [Columns Selector][ColumnsSelector] used to remove the columns of this [DataFrame].
52+
*/
1753
@Refine
1854
@Interpretable("Remove0")
1955
public fun <T> DataFrame<T>.remove(columns: ColumnsSelector<T, *>): DataFrame<T> =
2056
removeImpl(allowMissingColumns = true, columns = columns).df
2157

58+
/**
59+
* @include [CommonRemoveDocs]
60+
* @include [SelectingColumns.ColumnNames.WithExample] {@include [SetRemoveOperationArg]}
61+
* @param [columns] The [Column Names][String] used to remove the columns of this [DataFrame].
62+
*/
2263
public fun <T> DataFrame<T>.remove(vararg columns: String): DataFrame<T> = remove { columns.toColumnSet() }
2364

65+
/**
66+
* @include [CommonRemoveDocs]
67+
* @include [SelectingColumns.ColumnAccessors.WithExample] {@include [SetRemoveOperationArg]}
68+
* @param [columns] The [Column Accessors][ColumnReference] used to remove the columns of this [DataFrame].
69+
*/
2470
@AccessApiOverload
2571
public fun <T> DataFrame<T>.remove(vararg columns: AnyColumnReference): DataFrame<T> = remove { columns.toColumnSet() }
2672

73+
/**
74+
* @include [CommonRemoveDocs]
75+
* @include [SelectingColumns.KProperties.WithExample] {@include [SetRemoveOperationArg]}
76+
* @param [columns] The [KProperties][KProperty] used to remove the columns of this [DataFrame].
77+
*/
2778
@AccessApiOverload
2879
public fun <T> DataFrame<T>.remove(vararg columns: KProperty<*>): DataFrame<T> = remove { columns.toColumnSet() }
2980

3081
// endregion
3182

3283
// region minus
3384

85+
@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
3486
public infix operator fun <T> DataFrame<T>.minus(columns: ColumnsSelector<T, *>): DataFrame<T> = remove(columns)
3587

88+
@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
3689
public infix operator fun <T> DataFrame<T>.minus(column: String): DataFrame<T> = remove(column)
3790

91+
@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
3892
@AccessApiOverload
3993
public infix operator fun <T> DataFrame<T>.minus(column: AnyColumnReference): DataFrame<T> = remove(column)
4094

95+
@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
4196
@AccessApiOverload
4297
public infix operator fun <T> DataFrame<T>.minus(columns: KProperty<*>): DataFrame<T> = remove(columns)
4398

0 commit comments

Comments
 (0)