Skip to content

Commit bb50c0d

Browse files
AndreiKingsleyAndreiKingsley
authored
Merge pull request #1631 from Kotlin/migration_guide
Migration guide
2 parents 177b6f7 + 7beb6f6 commit bb50c0d

File tree

2 files changed

+189
-1
lines changed

2 files changed

+189
-1
lines changed

‎docs/StardustDocs/d.tree‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -225,5 +225,7 @@
225225
<toc-element topic="_shadow_resources.md" hidden="true"/>
226226
<toc-element topic="Support.md"/>
227227
<toc-element topic="FAQ.md"/>
228-
<toc-element topic="Migration-From-Plugins.md"/>
228+
<toc-element topic="MigrationTo_1_0.md">
229+
<toc-element topic="Migration-From-Plugins.md"/>
230+
</toc-element>
229231
</instance-profile>

‎docs/StardustDocs/topics/MigrationTo_1_0.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Migration to 1.0
2+
3+
## Deprecations and removals
4+
5+
As we move toward version 1.0, many functions have been changed, deprecated, or removed.
6+
This section provides a complete overview of all API changes to help you migrate to 1.0.
7+
8+
### Renamed functions and classes to the correct CamelCase spelling { id="camelCase" }
9+
10+
All functions and classes in Kotlin DataFrame
11+
have been renamed to
12+
[the correct CamelCase spelling](https://developer.android.com/kotlin/style-guide#camel_case).
13+
14+
See below for a complete list of the renamed functions and classes.
15+
16+
### Migration to Deephaven CSV
17+
18+
All CSV (as well as TSV) IO was migrated to a new, fast, and efficient
19+
[Deephaven CSV](https://github.com/deephaven/deephaven-csv) implementation.
20+
It significantly improves CSV IO performance and brings many new parametrization options.
21+
22+
All related methods are now located in the separate [`dataframe-csv`](Modules.md#dataframe-csv) module
23+
(which is included by default in the general [`dataframe`](Modules.md#dataframe-general) artifact
24+
and in `%use dataframe` in [Kotlin Notebook](SetupKotlinNotebook.md)).
25+
26+
Functions were also renamed to [the correct CamelCase spelling](#camelCase).
27+
28+
All new functions keep the same arguments as before and additionally introduce new ones.
29+
Also, [there are new arguments that expose Deephaven CSV features](read.md#unlocking-deephaven-csv-features).
30+
31+
32+
See [](read.md#read-from-csv).
33+
34+
> All outdated CSV IO functions raise `WARNING` in 1.0 and will raise `ERROR` in 1.1.
35+
36+
| 0.15 | 1.0 |
37+
|-------------------------------------------------|-------------------------------------------------|
38+
| `CSV`/`TSV` | `CsvDeephaven`/`TsvDeephaven` |
39+
| `DataFrame.readCSV(..)`/`DataFrame.readTSV(..)` | `DataFrame.readCsv(..)`/`DataFrame.readTsv(..)` |
40+
| `DataFrame.read(delimeter=.., ..)` | `DataFrame.readCsv(delimeter=.., ..)` |
41+
| `df.writeCSV(..)`/`df.writeTSV(..)` | `df.writeCsv(..)`/`df.writeTsv(..)` |
42+
| `df.toCSV(..)` | `df.toCsvStr(..)` |
43+
44+
### Migration to Standard Library `Instant`
45+
46+
Since Kotlin 2.1.20,
47+
[`Instant` is now part of the standard library](https://kotlinlang.org/docs/whatsnew2120.html#new-time-tracking-functionality)
48+
(as `kotlin.time.Instant`).
49+
You can still use the old (deprecated) `kotlinx.datetime.Instant` type, but its support will be removed in Kotlin DataFrame 1.1.
50+
51+
> New `Instant` in the Kotlin Standard Library becomes stable in 2.3.0.
52+
> In earlier versions, all related operations should be marked with the `@OptIn(ExperimentalTime::class)` annotation.
53+
{style="note"}
54+
55+
For now, each `Instant`-related operation has been split into two new ones —
56+
one for the new stdlib `kotlin.time.Instant` and one for the old deprecated `kotlinx.datetime.Instant`.
57+
The behavior of old operations remains unchanged: they work with `kotlinx.datetime.Instant` and raise `ERROR` in 1.0.
58+
In version 1.1, they will be returned and will operate on the new stdlib `kotlin.time.Instant`.
59+
60+
<table>
61+
<tr>
62+
<th>0.15</th>
63+
<th>1.0</th>
64+
<th>Note</th>
65+
</tr>
66+
<tr>
67+
<td rowspan="2"><code>col.convertToInstant()</code></td>
68+
<td><code>col.convertToDeprecatedInstant()</code></td>
69+
<td><code>WARNING</code> in 1.0, <code>ERROR</code> in 1.1</td>
70+
</tr>
71+
<tr>
72+
<td><code>col.convertToStdlibInstant()</code></td>
73+
<td>Will be renamed back into <code>convertToInstant() in 1.1</code></td>
74+
</tr>
75+
<tr>
76+
<td rowspan="2"><code>df.convert { columns }.toInstant()</code></td>
77+
<td><code>df.convert { columns }.convertToDeprecatedInstant()</code></td>
78+
<td><code>WARNING</code> in 1.0, <code>ERROR</code> in 1.1</td>
79+
</tr>
80+
<tr>
81+
<td><code>df.convert { columns }.convertToStdlibInstant()</code></td>
82+
<td>Will be renamed back into <code>convertToInstant() in 1.1</code></td>
83+
</tr>
84+
<tr>
85+
<td rowspan="2"><code>ColType.Instant</code></td>
86+
<td><code>ColType.DeprecatedInstant</code></td>
87+
<td><code>WARNING</code> in 1.0, <code>ERROR</code> in 1.1</td>
88+
</tr>
89+
<tr>
90+
<td><code>ColType.StdlibInstant</code></td>
91+
<td>Will be renamed back into <code>Instant</code> in 1.1</td>
92+
</tr>
93+
</table>
94+
95+
96+
In version 1.0, all parsing operations still convert `Instant`
97+
values into the deprecated `kotlinx.datetime.Instant`.
98+
To enable parsing into the new standard library `kotlin.time.Instant`,
99+
set the corresponding parsing option **`ParserOptions.parseExperimentalInstant`**
100+
(that will be default in 1.1).
101+
For example:
102+
103+
```kotlin
104+
DataFrame.readCsv(
105+
...,
106+
parserOptions = ParserOptions(parseExperimentalInstant = true)
107+
)
108+
```
109+
110+
### Deprecation of `cols()` and other methods in Columns Selection DSL
111+
112+
`cols()` overloads without arguments, which select all columns of a DataFrame or
113+
all subcolumns inside a column group in the [Columns Selection DSL](ColumnSelectors.md),
114+
are deprecated in favor of `all()` and `allCols()` respectively.
115+
These replacements allow the [Compiler Plugin](Compiler-Plugin.md) to fully support such selections.
116+
117+
`colsAtAnyDepth()`, `colsInGroups()`, and `single()` overloads with a `predicate` argument
118+
that filters columns are also deprecated for better Compiler Plugin support.
119+
Use `.filter(predicate)` for filtering instead.
120+
121+
| 0.15 | 1.0 |
122+
|--------------------------------------------------|------------------------------------------------------------------|
123+
| `df.select { cols() }` | `df.select { all() }` |
124+
| `df.select { colGroup.cols() }` | `df.select { colGroup.allCols() }` |
125+
| `df.select { colsAtAnyDepth { predicate } }` | `df.select { colsAtAnyDepth().filter { predicate } }` |
126+
| `df.select { colsInGroups { predicate } }` | `df.select { colsInGroups().filter { predicate } }` |
127+
| `df.select { single { predicate } }` | `df.select { cols().filter { predicate }.single() }` |
128+
| `df.select { colGroup.singleCol { predicate } }` | `df.select { colGroup.allCols().filter { predicate }.single() }` |
129+
| `df.select { colSet.single { predicate } }` | `df.select { colSet.filter { predicate }.single() }` |
130+
131+
132+
133+
### Removed functions and classes
134+
135+
The next functions and classes raise `ERROR` in 1.0 and will be removed in 1.1.
136+
137+
| 0.15 | 1.0 | Reason |
138+
|----------------------------------------------------------------|------------------------------------------------------------------------------|----------------------------------------|
139+
| `DataColumn.createFrameColumn(name, df, startIndices)` | `df.chunked(name, startIndices)` | Replaced with another function. |
140+
| `DataColumn.createWithTypeInference(name, values, nullable)` | `DataColumn.createByInference(name, values, TypeSuggestion.Infer, nullable)` | Replaced with another function. |
141+
| `DataColumn.create(name, values, infer)` | `DataColumn.createByType(name, values, infer)` | Replaced with another function. |
142+
| `col.isComparable()` | `col.valuesAreComparable()` | Renamed to better reflect its purpose. |
143+
| `df.minus { columns }` | `df.remove { columns }` | Replaced with another function. |
144+
| `df.move { columns }.toLeft()`/`df.moveToLeft{ columns }` | `df.move { columns }.toStart()`/`df.moveToStart { columns }` | Renamed to better reflect its purpose. |
145+
| `df.move { columns }.toRight()`/`df.moveToRight{ columns }` | `df.move { columns }.toEnd()`/`df.moveToEnd{ columns }` | Renamed to better reflect its purpose. |
146+
| `row.rowMin()`/`row.rowMinOrNull()` | `row.rowMinOf()`/`row.rowMinOfOrNull()` | Renamed to better reflect its purpose. |
147+
| `row.rowMax()`/`row.rowMaxOrNull()` | `row.rowMaxOf()`/`AnyRow.rowMaxOfOrNull()` | Renamed to better reflect its purpose. |
148+
| `row.rowPercentile()`/`row.rowPercentileOrNull()` | `row.rowPercentileOf()`/`row.rowPercentileOfOrNull()` | Renamed to better reflect its purpose. |
149+
| `row.rowMedian()`/`row.rowMedianOrNull()` | `row.rowMedianOf()`/`row.rowMedianOfOrNull()` | Renamed to better reflect its purpose. |
150+
| `df.convert { columns }.to { converter }` | `df.convert { columns }.asColumn { converter }` | Renamed to better reflect its purpose. |
151+
| `df.toHTML(..)`/`df.toStandaloneHTML()` | `df.toHtml(..)`/`df.toStandaloneHtml()` | Renamed to the correct CamelCase. |
152+
| `df.writeHTML()` | `df.writeHtml()` | Renamed to the correct CamelCase. |
153+
| `asURL(fileOrUrl)`/`isURL(path)` | `asUrl(fileOrUrl)`/`isUrl(path)` | Renamed to the correct CamelCase. |
154+
| `df.convert { columns }.toURL()`/`df.convertToURL { columns }` | `df.convert { columns }.toUrl()`/`df.convertToUrl { columns }` | Renamed to the correct CamelCase. |
155+
| `df.filterBy(column)` | `df.filter { column }` | Replaced with another function. |
156+
| `FormattingDSL` | `FormattingDsl` | Renamed to the correct CamelCase. |
157+
| `RGBColor` | `RgbColor` | Renamed to the correct CamelCase. |
158+
| `df.insert(column).after(columnPath)` | `df.insert(column).after { columnPath }` | Replaced with another function. |
159+
| `CompareResult.Equals` / `CompareResult.isEqual()` | `CompareResult.Matches` / `CompareResult.matches()` | Renamed to better reflect its purpose. |
160+
| `CompareResult.isSuperOrEqual()` | `CompareResult.isSuperOrMatches()` | Renamed to better reflect its purpose. |
161+
162+
The next functions and classes raise `WARNING` in 1.0 and `ERROR` in 1.1.
163+
164+
| 0.15 | 1.0 | Reason |
165+
|----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
166+
| `df.split { columns }.default(..)` / `df.split { columns }.into(..)` / `df.split { columns }.inward(..)` | `df.split { columns }.by(..).default(..)` / `df.split { columns }.by(..).into(..)` / `df.split { columns }.by(..).inward(..)` | Removed a shortcut to clarify the behaviour; Only for `String` columns. |
167+
| `dataFrameOf(header, values)` | `dataFrameOf(header).withValues(values)` | Replaced with another function. |
168+
| `df.generateCode(..)` | `df.generateInterfaces(..)` | Replaced with another function. |
169+
| `df.select { mapToColumn(name, infer) { body } }` | `df.select { expr(name, infer) { body } }` | Removed duplicated functionality. |
170+
| `stringCol.length()` | `stringCol.map { it?.length ?: 0 }` | Removed a shortcut to clarify the behaviour; Only for `String` columns. |
171+
| `stringCol.lowercase()` / `stringCol.uppercase()` | `stringCol.map { it?.lowercase() }` / `stringCol.map { it?.uppercase() }` | Removed a shortcut to clarify the behaviour; Only for `String` columns. |
172+
| `df.add(columns)` / `df.add(dataframes)` | `df.addAll(columns)` / `df.addAll(dataframes)` | Renamed to to improve completion. |
173+
| `row.isEmpty()` / `row.isNotEmpty()` | `row.values().all { it == null }` / `row.values().all { it == null }` | Removed a shortcut to clarify the behaviour; |
174+
| `row.getRow(index)` / `row.getRowOrNull(index)` / `row.getRows(indices)` | `row.df().getRow(index)` / `row.df().getRowOrNull(index)` / `row.df().getRows(indices)` | Removed a shortcut to clarify the behaviour; |
175+
| `df.copy()` | `df.columns().toDataFrame().cast()` | Removed a shortcut to clarify the behaviour; |
176+
| `KeyValueProperty<T>` | `NameValueProperty<T>` | Removed duplicated functionality. |
177+
178+
<!--TODO (https://github.com/Kotlin/dataframe/issues/1630)
179+
180+
## Modules
181+
182+
## Compiler Plugin
183+
184+
## Changes in working with JDBC
185+
186+
-->

0 commit comments

Comments
 (0)