Skip to content

Commit 25e1b56

Browse files
JolanrensenJolanrensen
committed
kdocs created for DataFrame.select.
kdocs updated across other column-functions
1 parent 18c5db4 commit 25e1b56

File tree

10 files changed

+1032
-213
lines changed

10 files changed

+1032
-213
lines changed

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

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver
1010
import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
1111

1212
/**
13+
* ## Predicate
14+
*
1315
* [Predicate] is used to reach a [Boolean] result using the given instance of `T` as `it`.
1416
*
1517
* Shorthand for:
@@ -20,6 +22,8 @@ import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
2022
public typealias Predicate<T> = (it: T) -> Boolean
2123

2224
/**
25+
* ## Selector
26+
*
2327
* [Selector] is used to express or select any instance of `R` using the given instance of `T` as `this` and `it`.
2428
*
2529
* Shorthand for:
@@ -32,6 +36,8 @@ public typealias Selector<T, R> = T.(it: T) -> R
3236
// region selectors
3337

3438
/**
39+
* ## DataFrame Expression
40+
*
3541
* [DataFrameExpression] is used to express or select any instance of `R` using the given instance of [DataFrame]`<T>`
3642
* as `this` and `it`.
3743
*
@@ -43,6 +49,8 @@ public typealias Selector<T, R> = T.(it: T) -> R
4349
public typealias DataFrameExpression<T, R> = Selector<DataFrame<T>, R>
4450

4551
/**
52+
* ## Row Expression
53+
*
4654
* [RowExpression] is used to express or select any instance of `R` using the given instance of [DataRow]`<T>` as
4755
* `this` and `it`.
4856
*
@@ -54,6 +62,8 @@ public typealias DataFrameExpression<T, R> = Selector<DataFrame<T>, R>
5462
public typealias RowExpression<T, R> = Selector<DataRow<T>, R>
5563

5664
/**
65+
* ## Row Value Expression
66+
*
5767
* [RowValueExpression] is used to express or select any instance of `R` using the given value `it: C` and the given
5868
* instance of [DataRow]`<T>` as `this`.
5969
*
@@ -65,6 +75,8 @@ public typealias RowExpression<T, R> = Selector<DataRow<T>, R>
6575
public typealias RowValueExpression<T, C, R> = DataRow<T>.(it: C) -> R
6676

6777
/**
78+
* ## Row Column Expression
79+
*
6880
* [RowColumnExpression] is used to express or select any instance of `R` using the given instances of
6981
* [DataRow]`<T>` as `row` and [DataColumn]`<C>` as `col`.
7082
*
@@ -76,6 +88,8 @@ public typealias RowValueExpression<T, C, R> = DataRow<T>.(it: C) -> R
7688
public typealias RowColumnExpression<T, C, R> = (row: DataRow<T>, col: DataColumn<C>) -> R
7789

7890
/**
91+
* ## Column Expression
92+
*
7993
* [ColumnExpression] is used to express or select any instance of `R` using the given instance of [DataColumn]`<C>` as
8094
* `this` and `it`.
8195
*
@@ -87,6 +101,8 @@ public typealias RowColumnExpression<T, C, R> = (row: DataRow<T>, col: DataColum
87101
public typealias ColumnExpression<C, R> = Selector<DataColumn<C>, R>
88102

89103
/**
104+
* ## Column Selector
105+
*
90106
* A [ColumnSelector] is used to express or select a single column, represented by [SingleColumn]`<C>`, using the
91107
* context of [ColumnsSelectionDsl]`<T>` as `this` and `it`.
92108
*
@@ -98,10 +114,12 @@ public typealias ColumnExpression<C, R> = Selector<DataColumn<C>, R>
98114
public typealias ColumnSelector<T, C> = Selector<ColumnsSelectionDsl<T>, SingleColumn<C>>
99115

100116
/**
117+
* ## Columns Selector
118+
*
101119
* A [ColumnsSelector] is used to express or select one or multiple columns, represented by [ColumnsResolver]`<C>`,
102120
* using the context of [ColumnsSelectionDsl]`<T>` as `this` and `it`.
103121
*
104-
* See [ColumnsSelectionDsl] for more information.
122+
* See [Columns Selection DSL][ColumnsSelectionDsl] for more information.
105123
*
106124
* Shorthand for:
107125
* ```kotlin
@@ -115,6 +133,8 @@ public typealias ColumnsSelector<T, C> = Selector<ColumnsSelectionDsl<T>, Column
115133
// region filters
116134

117135
/**
136+
* ## Row Filter
137+
*
118138
* [RowFilter] is used to filter or find rows using the given instance of [DataRow]`<T>` as `this` and `it`.
119139
* Return `true` if the row should be included in the result.
120140
*
@@ -126,6 +146,8 @@ public typealias ColumnsSelector<T, C> = Selector<ColumnsSelectionDsl<T>, Column
126146
public typealias RowFilter<T> = RowExpression<T, Boolean>
127147

128148
/**
149+
* ## Column Filter
150+
*
129151
* [ColumnFilter] is used to filter or find columns using the given instance of [ColumnWithPath]`<T>` as `it`.
130152
* Return `true` if the column should be included in the result.
131153
*
@@ -137,6 +159,8 @@ public typealias RowFilter<T> = RowExpression<T, Boolean>
137159
public typealias ColumnFilter<T> = Predicate<ColumnWithPath<T>>
138160

139161
/**
162+
* ## Row Value Filter
163+
*
140164
* [RowValueFilter] is used to filter or find rows using the given value of `it: C` and the given instance of
141165
* [DataRow]`<T>` as `this`.
142166
* Return `true` if the row should be included in the result.

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

Lines changed: 474 additions & 68 deletions
Large diffs are not rendered by default.

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

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,11 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
1111
import org.jetbrains.kotlinx.dataframe.columns.ColumnSet
1212
import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
1313
import org.jetbrains.kotlinx.dataframe.columns.toColumnSet
14+
import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls
1415
import org.jetbrains.kotlinx.dataframe.documentation.Indent
1516
import org.jetbrains.kotlinx.dataframe.documentation.LineBreak
17+
import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns
18+
import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumnsLink
1619
import org.jetbrains.kotlinx.dataframe.documentation.UsageTemplateColumnsSelectionDsl.UsageTemplate
1720
import org.jetbrains.kotlinx.dataframe.impl.columns.changePath
1821
import org.jetbrains.kotlinx.dataframe.impl.columns.createColumnSet
@@ -23,13 +26,195 @@ import kotlin.reflect.KProperty
2326

2427
// region DataFrame
2528

29+
/**
30+
* ## The Select Operation
31+
*
32+
* Returns a new [DataFrame] with only the columns selected by [columns].
33+
*
34+
* See [Selecting Columns][SelectSelectingOptions].
35+
*
36+
* For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
37+
*/
38+
internal interface Select {
39+
40+
/**
41+
*
42+
* ## Selecting Columns
43+
* Selecting columns for various operations (including but not limited to
44+
* [DataFrame.select][org.jetbrains.kotlinx.dataframe.DataFrame.select], [DataFrame.update][org.jetbrains.kotlinx.dataframe.DataFrame.update], [DataFrame.gather][org.jetbrains.kotlinx.dataframe.DataFrame.gather], and [DataFrame.fillNulls][org.jetbrains.kotlinx.dataframe.DataFrame.fillNulls])
45+
* can be done in the following ways:
46+
* ### 1. [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.Dsl.WithExample]
47+
* Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl].
48+
* (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]).
49+
*
50+
* This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda,
51+
* which operates on the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and
52+
* expects you to return a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]; an entity formed by calling any (combination) of the functions
53+
* in the DSL that is or can be resolved into one or more columns.
54+
* ### Check out: [Columns Selection DSL Usage][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.Usage]
55+
*
56+
* &nbsp;&nbsp;&nbsp;&nbsp;
57+
*
58+
* [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html)
59+
*
60+
* #### For example:
61+
*
62+
* `df.`[select][org.jetbrains.kotlinx.dataframe.api.select]` { length `[and][org.jetbrains.kotlinx.dataframe.api.AndColumnsSelectionDsl.and]` age }`
63+
*
64+
* `df.`[select][org.jetbrains.kotlinx.dataframe.api.select]` { `[cols][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.cols]`(1..5) }`
65+
*
66+
* `df.`[select][org.jetbrains.kotlinx.dataframe.api.select]` { `[colsOf][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.colsOf]`<`[Double][Double]`>() }`
67+
*
68+
*
69+
* #### NOTE: There's also a 'single column' variant used sometimes: [Column Selection DSL][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.DslSingle.WithExample].
70+
* ### 2. [Column names][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.ColumnNames.WithExample]
71+
* Select columns using their [column names][String]
72+
* ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]).
73+
*
74+
* #### For example:
75+
*
76+
* `df.`[select][org.jetbrains.kotlinx.dataframe.api.select]`("length", "age")`
77+
*
78+
* ### 3. [Column references][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.ColumnAccessors.WithExample]
79+
* Select columns using [column accessors][org.jetbrains.kotlinx.dataframe.columns.ColumnReference]
80+
* ([Column Accessors API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ColumnAccessorsApi]).
81+
*
82+
* #### For example:
83+
*
84+
* `val length by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()`
85+
*
86+
* `val age by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()`
87+
*
88+
* `df.`[select][org.jetbrains.kotlinx.dataframe.api.select]`(length, age)`
89+
*
90+
* ### 4. [KProperties][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.KProperties.WithExample]
91+
* Select columns using [KProperties][KProperty] ([KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]).
92+
*
93+
* #### For example:
94+
* ```kotlin
95+
* data class Person(val length: Double, val age: Double)
96+
* ```
97+
*
98+
* `df.`[select][org.jetbrains.kotlinx.dataframe.api.select]`(Person::length, Person::age)`
99+
*
100+
*/
101+
public interface SelectSelectingOptions
102+
}
103+
104+
private interface SetSelectOperationArg
105+
106+
/**
107+
* ## The Select Operation
108+
*
109+
* Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns][org.jetbrains.kotlinx.dataframe.columns].
110+
*
111+
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
112+
*
113+
* For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
114+
* ### This Select Overload
115+
*/
116+
private interface CommonSelectDocs
117+
118+
/**
119+
* ## The Select Operation
120+
*
121+
* Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns][org.jetbrains.kotlinx.dataframe.columns].
122+
*
123+
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
124+
*
125+
* For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
126+
* ### This Select Overload
127+
* Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl].
128+
* (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]).
129+
*
130+
* This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda,
131+
* which operates on the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and
132+
* expects you to return a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]; an entity formed by calling any (combination) of the functions
133+
* in the DSL that is or can be resolved into one or more columns.
134+
* ### Check out: [Columns Selection DSL Usage][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.Usage]
135+
*
136+
* &nbsp;&nbsp;&nbsp;&nbsp;
137+
*
138+
* [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html)
139+
*
140+
* #### For example:
141+
*
142+
* `df.`[select][org.jetbrains.kotlinx.dataframe.api.select]` { length `[and][org.jetbrains.kotlinx.dataframe.api.AndColumnsSelectionDsl.and]` age }`
143+
*
144+
* `df.`[select][org.jetbrains.kotlinx.dataframe.api.select]` { `[cols][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.cols]`(1..5) }`
145+
*
146+
* `df.`[select][org.jetbrains.kotlinx.dataframe.api.select]` { `[colsOf][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.colsOf]`<`[Double][Double]`>() }`
147+
*
148+
*
149+
* @param [columns] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame].
150+
*/
26151
public fun <T> DataFrame<T>.select(columns: ColumnsSelector<T, *>): DataFrame<T> =
27152
get(columns).toDataFrame().cast()
28153

154+
/**
155+
* ## The Select Operation
156+
*
157+
* Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns][org.jetbrains.kotlinx.dataframe.columns].
158+
*
159+
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
160+
*
161+
* For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
162+
* ### This Select Overload
163+
* Select columns using [KProperties][KProperty] ([KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]).
164+
*
165+
* #### For example:
166+
* ```kotlin
167+
* data class Person(val length: Double, val age: Double)
168+
* ```
169+
*
170+
* `df.`[select][org.jetbrains.kotlinx.dataframe.api.select]`(Person::length, Person::age)`
171+
*
172+
* @param [columns] The [KProperties][KProperty] used to select the columns of this [DataFrame].
173+
*/
29174
public fun <T> DataFrame<T>.select(vararg columns: KProperty<*>): DataFrame<T> = select { columns.toColumnSet() }
30175

176+
/**
177+
* ## The Select Operation
178+
*
179+
* Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns][org.jetbrains.kotlinx.dataframe.columns].
180+
*
181+
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
182+
*
183+
* For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
184+
* ### This Select Overload
185+
* Select columns using their [column names][String]
186+
* ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]).
187+
*
188+
* #### For example:
189+
*
190+
* `df.`[select][org.jetbrains.kotlinx.dataframe.api.select]`("length", "age")`
191+
*
192+
* @param [columns] The [Column Names][String] used to select the columns of this [DataFrame].
193+
*/
31194
public fun <T> DataFrame<T>.select(vararg columns: String): DataFrame<T> = select { columns.toColumnSet() }
32195

196+
/**
197+
* ## The Select Operation
198+
*
199+
* Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns][org.jetbrains.kotlinx.dataframe.columns].
200+
*
201+
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
202+
*
203+
* For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
204+
* ### This Select Overload
205+
* Select columns using [column accessors][org.jetbrains.kotlinx.dataframe.columns.ColumnReference]
206+
* ([Column Accessors API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ColumnAccessorsApi]).
207+
*
208+
* #### For example:
209+
*
210+
* `val length by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()`
211+
*
212+
* `val age by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()`
213+
*
214+
* `df.`[select][org.jetbrains.kotlinx.dataframe.api.select]`(length, age)`
215+
*
216+
* @param [columns] The [Column Accessors][ColumnReference] used to select the columns of this [DataFrame].
217+
*/
33218
public fun <T> DataFrame<T>.select(vararg columns: AnyColumnReference): DataFrame<T> = select { columns.toColumnSet() }
34219

35220
// endregion

0 commit comments

Comments
 (0)