Skip to content

Commit 97204c3

Browse files
koperagenkoperagen
committed
Deprecate predicate argument in single, colsInGroups, colsAtAnyDepth
1 parent b1ecefe commit 97204c3

File tree

7 files changed

+166
-30
lines changed

7 files changed

+166
-30
lines changed

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

+58-8
Original file line numberDiff line numberDiff line change
@@ -65,24 +65,23 @@ public interface ColsAtAnyDepthColumnsSelectionDsl {
6565
/**
6666
* ## Cols At Any Depth
6767
*
68-
* Returns all columns in [this\] at any depth (so also inside [Column Groups][ColumnGroup]) if they satisfy the
69-
* optional given predicate.
68+
* Returns all columns in [this\] at any depth (so also inside [Column Groups][ColumnGroup])
7069
*
7170
* This function can also be followed by another [ColumnSet] filter function like
7271
* [colsOf][ColumnsSelectionDsl.colsOf], [single][ColumnsSelectionDsl.single], or [valueCols][ColumnsSelectionDsl.valueCols].
7372
* ### Check out: [Grammar]
7473
* #### For example:
7574
* `// Depth-first search to a column containing the value "Alice"`
7675
*
77-
* `df.`[select][DataFrame.select]` { `[colsAtAnyDepth][ColumnsSelectionDsl.colsAtAnyDepth]`().`[first][ColumnsSelectionDsl.firstCol]` { "Alice" `[in][Iterable.contains]` it.`[values][DataColumn.values]`() } }`
76+
* `df.`[select][DataFrame.select]` { `[colsAtAnyDepth][ColumnsSelectionDsl.colsAtAnyDepth]`().`[filter][FilterColumnsSelectionDsl.filter]` { "Alice" `[in][Iterable.contains]` it.`[values][DataColumn.values]`() }.`[first][ColumnsSelectionDsl.firstCol]`() }`
7877
* {@include [LineBreak]}
7978
* `// The columns at any depth excluding the top-level`
8079
*
8180
* `df.`[select][DataFrame.select]` { `[colGroups][ColumnsSelectionDsl.colGroups]`().`[colsAtAnyDepth][ColumnSet.colsAtAnyDepth]`() }`
8281
* {@include [LineBreak]}
8382
* `// All value- and frame columns at any depth`
8483
*
85-
* `df.`[select][DataFrame.select]` { `[colsAtAnyDepth][ColumnsSelectionDsl.colsAtAnyDepth]` { !it.`[isColumnGroup][DataColumn.isColumnGroup]` } }`
84+
* `df.`[select][DataFrame.select]` { `[colsAtAnyDepth][ColumnsSelectionDsl.colsAtAnyDepth]`().`[filter][FilterColumnsSelectionDsl.filter]` { !it.`[isColumnGroup][DataColumn.isColumnGroup]` } }`
8685
* {@include [LineBreak]}
8786
* `// All value columns at any depth nested under a column group named "myColGroup"`
8887
*
@@ -94,13 +93,13 @@ public interface ColsAtAnyDepthColumnsSelectionDsl {
9493
*
9594
* #### Converting from deprecated syntax:
9695
*
97-
* `dfs { condition } -> `[colsAtAnyDepth][colsAtAnyDepth]` { condition }`
96+
* `dfs { condition } -> `[colsAtAnyDepth][colsAtAnyDepth]`().`[filter][FilterColumnsSelectionDsl.filter]` { condition }`
9897
*
99-
* `allDfs(includeGroups = false) -> `[colsAtAnyDepth][colsAtAnyDepth]` { includeGroups || !it.`[isColumnGroup][DataColumn.isColumnGroup]`() }`
98+
* `allDfs(includeGroups = false) -> `[colsAtAnyDepth][colsAtAnyDepth]`().`[filter][FilterColumnsSelectionDsl.filter]` { includeGroups || !it.`[isColumnGroup][DataColumn.isColumnGroup]`() }`
10099
*
101100
* `dfsOf<Type> { condition } -> `[colsAtAnyDepth][colsAtAnyDepth]`().`[colsOf][ColumnsSelectionDsl.colsOf]`<Type> { condition }`
102101
*
103-
* [cols][ColumnsSelectionDsl.cols]` { condition }.`[recursively][recursively]`() -> `[colsAtAnyDepth][colsAtAnyDepth]` { condition }`
102+
* [cols][ColumnsSelectionDsl.cols]` { condition }.`[recursively][recursively]`() -> `[colsAtAnyDepth][colsAtAnyDepth]`().`[filter][FilterColumnsSelectionDsl.filter]` { condition }`
104103
*
105104
* [first][ColumnsSelectionDsl.first]` { condition }.`[rec][rec]`() -> `[colsAtAnyDepth][colsAtAnyDepth]` { condition }.`[first][ColumnsSelectionDsl.first]`()`
106105
*
@@ -122,40 +121,82 @@ public interface ColsAtAnyDepthColumnsSelectionDsl {
122121
* `df.`[select][DataFrame.select]` { `[colGroups][ColumnsSelectionDsl.colGroups]`().`[colsAtAnyDepth][ColumnsSelectionDsl.colsAtAnyDepth]` { "Alice" `[in][Iterable.contains]` it.`[values][DataColumn.values]`() } }`
123122
*/
124123
@Interpretable("ColsAtAnyDepth0")
124+
@Deprecated("", replaceWith = ReplaceWith("colsAtAnyDepth().filter(predicate)"))
125125
public fun ColumnSet<*>.colsAtAnyDepth(predicate: ColumnFilter<*> = { true }): ColumnSet<*> =
126126
colsAtAnyDepthInternal(predicate)
127127

128128
/**
129129
* @include [CommonAtAnyDepthDocs]
130130
* @set [CommonAtAnyDepthDocs.Examples]
131131
*
132-
* `df.`[select][DataFrame.select]` { `[colsAtAnyDepth][ColumnsSelectionDsl.colsAtAnyDepth]` { "Alice" `[in][Iterable.contains]` it.`[values][DataColumn.values]`() }.`[first][ColumnsSelectionDsl.first]`() }`
132+
* `df.`[select][DataFrame.select]` { `[colGroups][ColumnsSelectionDsl.colGroups]`().`[colsAtAnyDepth][ColumnsSelectionDsl.colsAtAnyDepth]`().filter { "Alice" `[in][Iterable.contains]` it.`[values][DataColumn.values]`() } }`
133+
*/
134+
@Interpretable("ColsAtAnyDepth0")
135+
public fun ColumnSet<*>.colsAtAnyDepth(): ColumnSet<*> = colsAtAnyDepthInternal { true }
136+
137+
/**
138+
* @include [CommonAtAnyDepthDocs]
139+
* @set [CommonAtAnyDepthDocs.Examples]
140+
*
141+
* `df.`[select][DataFrame.select]` { `[colsAtAnyDepth][ColumnsSelectionDsl.colsAtAnyDepth]` { "Alice" `[in][Iterable.contains]` it.`[values][DataColumn.values]`() }.`[first][ColumnsSelectionDsl.first]`() }`
133142
*
134143
* `df.`[select][DataFrame.select]` { `[colsAtAnyDepth][ColumnsSelectionDsl.colsAtAnyDepth]` { !it.`[isColumnGroup][DataColumn.isColumnGroup]` } }`
135144
*/
136145
@Interpretable("ColsAtAnyDepth1")
146+
@Deprecated("", replaceWith = ReplaceWith("colsAtAnyDepth().filter(predicate)"))
137147
public fun ColumnsSelectionDsl<*>.colsAtAnyDepth(predicate: ColumnFilter<*> = { true }): ColumnSet<*> =
138148
asSingleColumn().colsAtAnyDepthInternal(predicate)
139149

150+
/**
151+
* @include [CommonAtAnyDepthDocs]
152+
* @set [CommonAtAnyDepthDocs.Examples]
153+
*
154+
* `df.`[select][DataFrame.select]` { `[colsAtAnyDepth][ColumnsSelectionDsl.colsAtAnyDepth]`().filter { "Alice" `[in][Iterable.contains]` it.`[values][DataColumn.values]`() }.`[first][ColumnsSelectionDsl.first]`() }`
155+
*
156+
* `df.`[select][DataFrame.select]` { `[colsAtAnyDepth][ColumnsSelectionDsl.colsAtAnyDepth]`().filter { !it.`[isColumnGroup][DataColumn.isColumnGroup]` } }`
157+
*/
158+
@Interpretable("ColsAtAnyDepth1")
159+
public fun ColumnsSelectionDsl<*>.colsAtAnyDepth(): ColumnSet<*> = asSingleColumn().colsAtAnyDepthInternal { true }
160+
140161
/**
141162
* @include [CommonAtAnyDepthDocs]
142163
* @set [CommonAtAnyDepthDocs.Examples]
143164
*
144165
* `df.`[select][DataFrame.select]` { myColGroup.`[colsAtAnyDepth][SingleColumn.colsAtAnyDepth]` { "Alice" `[in][Iterable.contains]` it.`[values][DataColumn.values]`() } }`
145166
*/
146167
@Interpretable("ColsAtAnyDepth2")
168+
@Deprecated("", replaceWith = ReplaceWith("colsAtAnyDepth().filter(predicate)"))
147169
public fun SingleColumn<DataRow<*>>.colsAtAnyDepth(predicate: ColumnFilter<*> = { true }): ColumnSet<*> =
148170
ensureIsColumnGroup().colsAtAnyDepthInternal(predicate)
149171

172+
/**
173+
* @include [CommonAtAnyDepthDocs]
174+
* @set [CommonAtAnyDepthDocs.Examples]
175+
*
176+
* `df.`[select][DataFrame.select]` { myColGroup.`[colsAtAnyDepth][SingleColumn.colsAtAnyDepth]`().filter { "Alice" `[in][Iterable.contains]` it.`[values][DataColumn.values]`() } }`
177+
*/
178+
@Interpretable("ColsAtAnyDepth2")
179+
public fun SingleColumn<DataRow<*>>.colsAtAnyDepth(): ColumnSet<*> =
180+
ensureIsColumnGroup().colsAtAnyDepthInternal { true }
181+
150182
/**
151183
* @include [CommonAtAnyDepthDocs]
152184
* @set [CommonAtAnyDepthDocs.Examples]
153185
*
154186
* `df.`[select][DataFrame.select]` { "myColumnGroup".`[colsAtAnyDepth][String.colsAtAnyDepth]` { "Alice" `[in][Iterable.contains]` it.`[values][DataColumn.values]`() } }`
155187
*/
188+
@Deprecated("", replaceWith = ReplaceWith("colsAtAnyDepth().filter(predicate)"))
156189
public fun String.colsAtAnyDepth(predicate: ColumnFilter<*> = { true }): ColumnSet<*> =
157190
columnGroup(this).colsAtAnyDepth(predicate)
158191

192+
/**
193+
* @include [CommonAtAnyDepthDocs]
194+
* @set [CommonAtAnyDepthDocs.Examples]
195+
*
196+
* `df.`[select][DataFrame.select]` { "myColumnGroup".`[colsAtAnyDepth][String.colsAtAnyDepth]`().filter { "Alice" `[in][Iterable.contains]` it.`[values][DataColumn.values]`() } }`
197+
*/
198+
public fun String.colsAtAnyDepth(): ColumnSet<*> = columnGroup(this).colsAtAnyDepth { true }
199+
159200
/**
160201
* @include [CommonAtAnyDepthDocs]
161202
* @set [CommonAtAnyDepthDocs.Examples]
@@ -175,9 +216,18 @@ public interface ColsAtAnyDepthColumnsSelectionDsl {
175216
*
176217
* `df.`[select][DataFrame.select]` { "pathTo"["myGroupCol"].`[colsAtAnyDepth][ColumnsSelectionDsl.colsAtAnyDepth]` { "Alice" `[in][Iterable.contains]` it.`[values][DataColumn.values]`() } }`
177218
*/
219+
@Deprecated("", replaceWith = ReplaceWith("colsAtAnyDepth().filter(predicate)"))
178220
public fun ColumnPath.colsAtAnyDepth(predicate: ColumnFilter<*> = { true }): ColumnSet<*> =
179221
columnGroup(this).colsAtAnyDepth(predicate)
180222

223+
/**
224+
* @include [CommonAtAnyDepthDocs]
225+
* @set [CommonAtAnyDepthDocs.Examples]
226+
*
227+
* `df.`[select][DataFrame.select]` { "pathTo"["myGroupCol"].`[colsAtAnyDepth][ColumnsSelectionDsl.colsAtAnyDepth]`().filter { "Alice" `[in][Iterable.contains]` it.`[values][DataColumn.values]`() } }`
228+
*/
229+
public fun ColumnPath.colsAtAnyDepth(): ColumnSet<*> = columnGroup(this).colsAtAnyDepth { true }
230+
181231
// endregion
182232
}
183233

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

+50-5
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ public interface ColsInGroupsColumnsSelectionDsl {
6565
/**
6666
* ## Cols in Groups
6767
*
68-
* [colsInGroups][colsInGroups] is a function that returns all (optionally filtered) columns at the top-levels of
68+
* [colsInGroups][colsInGroups] is a function that returns all columns at the top-levels of
6969
* all [column groups][ColumnGroup] in [this\]. This is useful if you want to select all columns that are
7070
* "one level deeper".
7171
*
@@ -87,11 +87,11 @@ public interface ColsInGroupsColumnsSelectionDsl {
8787
*
8888
* and
8989
*
90-
* `df.`[select][DataFrame.select]` { `[colsInGroups][ColumnsSelectionDsl.colsInGroups]` { "user" `[in][String.contains]` it.`[name][DataColumn.name]` } }`
90+
* `df.`[select][DataFrame.select]` { `[colsInGroups][ColumnsSelectionDsl.colsInGroups]`().`[nameContains][ColumnsSelectionDsl.nameContains]`("user") }`
9191
* {@include [LineBreak]}
9292
* Similarly, you can take the columns inside all [column groups][ColumnGroup] in a [ColumnSet]:
9393
* {@include [LineBreak]}
94-
* `df.`[select][DataFrame.select]` { `[colGroups][ColumnsSelectionDsl.colGroups]` { "my" `[in][String.contains]` it.`[name][DataColumn.name]` }.`[colsInGroups][ColumnSet.colsInGroups]`() }`
94+
* `df.`[select][DataFrame.select]` { `[colGroups][ColumnsSelectionDsl.colGroups]`().`[nameContains][ColumnsSelectionDsl.nameContains]`("my").`[colsInGroups][ColumnSet.colsInGroups]`() }`
9595
* {@include [LineBreak]}
9696
*
9797
* #### Examples of this overload:
@@ -100,8 +100,7 @@ public interface ColsInGroupsColumnsSelectionDsl {
100100
*
101101
* @see [ColumnsSelectionDsl.cols\]
102102
* @see [ColumnsSelectionDsl.colGroups\]
103-
* @param [predicate\] An optional predicate to filter the cols by.
104-
* @return A [TransformableColumnSet] containing the (filtered) cols.
103+
* @return A [TransformableColumnSet] containing the cols.
105104
*/
106105
private interface ColsInGroupsDocs {
107106

@@ -117,9 +116,18 @@ public interface ColsInGroupsColumnsSelectionDsl {
117116
*
118117
* `df.`[select][DataFrame.select]` { `[colsOf][ColumnsSelectionDsl.colsOf]`<`[DataRow][DataRow]`<MyGroupType>>().`[colsInGroups][ColumnSet.colsInGroups]`() }`
119118
*/
119+
@Deprecated("", ReplaceWith("this.colsInGroups().filter(predicate)"))
120120
public fun ColumnSet<*>.colsInGroups(predicate: ColumnFilter<*> = { true }): TransformableColumnSet<*> =
121121
transform { it.flatMap { it.cols().filter { predicate(it) } } }
122122

123+
/**
124+
* @include [ColsInGroupsDocs]
125+
* @set [ColsInGroupsDocs.EXAMPLE]
126+
*
127+
* `df.`[select][DataFrame.select]` { `[colsOf][ColumnsSelectionDsl.colsOf]`<`[DataRow][DataRow]`<MyGroupType>>().`[colsInGroups][ColumnSet.colsInGroups]`() }`
128+
*/
129+
public fun ColumnSet<*>.colsInGroups(): TransformableColumnSet<*> = transform { it.flatMap { it.cols() } }
130+
123131
/**
124132
* @include [ColsInGroupsDocs]
125133
* @set [ColsInGroupsDocs.EXAMPLE]
@@ -128,9 +136,18 @@ public interface ColsInGroupsColumnsSelectionDsl {
128136
*
129137
* `df.`[select][DataFrame.select]` { `[colsInGroups][ColumnSet.colsInGroups]`() }`
130138
*/
139+
@Deprecated("", ReplaceWith("colsInGroups().filter(predicate)"))
131140
public fun ColumnsSelectionDsl<*>.colsInGroups(predicate: ColumnFilter<*> = { true }): TransformableColumnSet<*> =
132141
asSingleColumn().colsInGroups(predicate)
133142

143+
/**
144+
* @include [ColsInGroupsDocs]
145+
* @set [ColsInGroupsDocs.EXAMPLE]
146+
*
147+
* `df.`[select][DataFrame.select]` { `[colsInGroups][ColumnSet.colsInGroups]`() }`
148+
*/
149+
public fun ColumnsSelectionDsl<*>.colsInGroups(): TransformableColumnSet<*> = asSingleColumn().colsInGroups()
150+
134151
/**
135152
* @include [ColsInGroupsDocs]
136153
* @set [ColsInGroupsDocs.EXAMPLE]
@@ -139,18 +156,37 @@ public interface ColsInGroupsColumnsSelectionDsl {
139156
*
140157
* `df.`[select][DataFrame.select]` { myColumnGroup.`[colsInGroups][SingleColumn.colsInGroups]` { it.`[any][ColumnWithPath.any]` { it == "Alice" } } }`
141158
*/
159+
@Deprecated("", ReplaceWith("this.colsInGroups().filter(predicate)"))
142160
public fun SingleColumn<DataRow<*>>.colsInGroups(predicate: ColumnFilter<*> = { true }): TransformableColumnSet<*> =
143161
ensureIsColumnGroup().allColumnsInternal().colsInGroups(predicate)
144162

163+
/**
164+
* @include [ColsInGroupsDocs]
165+
* @set [ColsInGroupsDocs.EXAMPLE]
166+
*
167+
* `df.`[select][DataFrame.select]` { myColumnGroup.`[colsInGroups][SingleColumn.colsInGroups]` { it.`[any][ColumnWithPath.any]` { it == "Alice" } } }`
168+
*/
169+
public fun SingleColumn<DataRow<*>>.colsInGroups(): TransformableColumnSet<*> =
170+
ensureIsColumnGroup().allColumnsInternal().colsInGroups()
171+
145172
/**
146173
* @include [ColsInGroupsDocs]
147174
* @set [ColsInGroupsDocs.EXAMPLE]
148175
*
149176
* `df.`[select][DataFrame.select]` { "myColumnGroup".`[colsInGroups][String.colsInGroups]`() }`
150177
*/
178+
@Deprecated("", ReplaceWith("colsInGroups().filter(predicate)"))
151179
public fun String.colsInGroups(predicate: ColumnFilter<*> = { true }): TransformableColumnSet<*> =
152180
columnGroup(this).colsInGroups(predicate)
153181

182+
/**
183+
* @include [ColsInGroupsDocs]
184+
* @set [ColsInGroupsDocs.EXAMPLE]
185+
*
186+
* `df.`[select][DataFrame.select]` { "myColumnGroup".`[colsInGroups][String.colsInGroups]`() }`
187+
*/
188+
public fun String.colsInGroups(): TransformableColumnSet<*> = columnGroup(this).colsInGroups()
189+
154190
/**
155191
* @include [ColsInGroupsDocs]
156192
* @set [ColsInGroupsDocs.EXAMPLE]
@@ -172,8 +208,17 @@ public interface ColsInGroupsColumnsSelectionDsl {
172208
*
173209
* `df.`[select][DataFrame.select]` { "pathTo"["myColumnGroup"].`[colsInGroups][ColumnPath.colsInGroups]`() }`
174210
*/
211+
@Deprecated("", ReplaceWith("colsInGroups().filter(predicate)"))
175212
public fun ColumnPath.colsInGroups(predicate: ColumnFilter<*> = { true }): TransformableColumnSet<*> =
176213
columnGroup(this).colsInGroups(predicate)
214+
215+
/**
216+
* @include [ColsInGroupsDocs]
217+
* @set [ColsInGroupsDocs.EXAMPLE]
218+
*
219+
* `df.`[select][DataFrame.select]` { "pathTo"["myColumnGroup"].`[colsInGroups][ColumnPath.colsInGroups]`() }`
220+
*/
221+
public fun ColumnPath.colsInGroups(): TransformableColumnSet<*> = columnGroup(this).colsInGroups()
177222
}
178223

179224
// endregion

0 commit comments

Comments
 (0)