init research
This commit is contained in:
@@ -0,0 +1,187 @@
|
||||
# Migration to 1.0
|
||||
|
||||
## Deprecations and removals
|
||||
|
||||
As we move toward version 1.0, many functions have been changed, deprecated, or removed.
|
||||
This section provides a complete overview of all API changes to help you migrate to 1.0.
|
||||
|
||||
### Renamed functions and classes to the correct CamelCase spelling { id="camelCase" }
|
||||
|
||||
All functions and classes in Kotlin DataFrame
|
||||
have been renamed to
|
||||
[the correct CamelCase spelling](https://developer.android.com/kotlin/style-guide#camel_case).
|
||||
|
||||
See below for a complete list of the renamed functions and classes.
|
||||
|
||||
### Migration to Deephaven CSV
|
||||
|
||||
All CSV (as well as TSV) IO was migrated to a new, fast, and efficient
|
||||
[Deephaven CSV](https://github.com/deephaven/deephaven-csv) implementation.
|
||||
It significantly improves CSV IO performance and brings many new parametrization options.
|
||||
|
||||
All related methods are now located in the separate [`dataframe-csv`](Modules.md#dataframe-csv) module
|
||||
(which is included by default in the general [`dataframe`](Modules.md#dataframe-general) artifact
|
||||
and in `%use dataframe` in [Kotlin Notebook](SetupKotlinNotebook.md)).
|
||||
|
||||
Functions were also renamed to [the correct CamelCase spelling](#camelCase).
|
||||
|
||||
All new functions keep the same arguments as before and additionally introduce new ones.
|
||||
Also, [there are new arguments that expose Deephaven CSV features](read.md#unlocking-deephaven-csv-features).
|
||||
|
||||
|
||||
See [](read.md#read-from-csv).
|
||||
|
||||
> All outdated CSV IO functions raise `WARNING` in 1.0 and will raise `ERROR` in 1.1.
|
||||
|
||||
| 0.15 | 1.0 |
|
||||
|-------------------------------------------------|-------------------------------------------------|
|
||||
| `CSV`/`TSV` | `CsvDeephaven`/`TsvDeephaven` |
|
||||
| `DataFrame.readCSV(..)`/`DataFrame.readTSV(..)` | `DataFrame.readCsv(..)`/`DataFrame.readTsv(..)` |
|
||||
| `DataFrame.read(delimeter=.., ..)` | `DataFrame.readCsv(delimeter=.., ..)` |
|
||||
| `df.writeCSV(..)`/`df.writeTSV(..)` | `df.writeCsv(..)`/`df.writeTsv(..)` |
|
||||
| `df.toCSV(..)` | `df.toCsvStr(..)` |
|
||||
|
||||
### Migration to Standard Library `Instant`
|
||||
|
||||
Since Kotlin 2.1.20,
|
||||
[`Instant` is now part of the standard library](https://kotlinlang.org/docs/whatsnew2120.html#new-time-tracking-functionality)
|
||||
(as `kotlin.time.Instant`).
|
||||
You can still use the old (deprecated) `kotlinx.datetime.Instant` type, but its support will be removed in Kotlin DataFrame 1.1.
|
||||
|
||||
> New `Instant` in the Kotlin Standard Library becomes stable in 2.3.0.
|
||||
> In earlier versions, all related operations should be marked with the `@OptIn(ExperimentalTime::class)` annotation.
|
||||
{style="note"}
|
||||
|
||||
For now, each `Instant`-related operation has been split into two new ones —
|
||||
one for the new stdlib `kotlin.time.Instant` and one for the old deprecated `kotlinx.datetime.Instant`.
|
||||
The behavior of old operations remains unchanged: they work with `kotlinx.datetime.Instant` and raise `ERROR` in 1.0.
|
||||
In version 1.1, they will be returned and will operate on the new stdlib `kotlin.time.Instant`.
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>0.15</th>
|
||||
<th>1.0</th>
|
||||
<th>Note</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2"><code>col.convertToInstant()</code></td>
|
||||
<td><code>col.convertToDeprecatedInstant()</code></td>
|
||||
<td><code>WARNING</code> in 1.0, <code>ERROR</code> in 1.1</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>col.convertToStdlibInstant()</code></td>
|
||||
<td>Will be renamed back into <code>convertToInstant() in 1.1</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2"><code>df.convert { columns }.toInstant()</code></td>
|
||||
<td><code>df.convert { columns }.convertToDeprecatedInstant()</code></td>
|
||||
<td><code>WARNING</code> in 1.0, <code>ERROR</code> in 1.1</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>df.convert { columns }.convertToStdlibInstant()</code></td>
|
||||
<td>Will be renamed back into <code>convertToInstant() in 1.1</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td rowspan="2"><code>ColType.Instant</code></td>
|
||||
<td><code>ColType.DeprecatedInstant</code></td>
|
||||
<td><code>WARNING</code> in 1.0, <code>ERROR</code> in 1.1</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>ColType.StdlibInstant</code></td>
|
||||
<td>Will be renamed back into <code>Instant</code> in 1.1</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
|
||||
In version 1.0-Beta5 and later, all parsing operations convert `Instant`
|
||||
values into the new standard library `kotlin.time.Instant` type by default.
|
||||
To enable parsing into the deprecated `kotlinx.datetime.Instant`,
|
||||
set the corresponding parsing option **`ParserOptions.parseExperimentalInstant = false`**
|
||||
(before 1.0-Beta5, this option was `false`, from 1.0-Beta5 onwards it is `true` by default).
|
||||
|
||||
For example:
|
||||
|
||||
```kotlin
|
||||
DataFrame.readCsv(
|
||||
...,
|
||||
parserOptions = ParserOptions(parseExperimentalInstant = false)
|
||||
)
|
||||
```
|
||||
|
||||
### Deprecation of `cols()` and other methods in Columns Selection DSL
|
||||
|
||||
`cols()` overloads without arguments, which select all columns of a DataFrame or
|
||||
all subcolumns inside a column group in the [Columns Selection DSL](ColumnSelectors.md),
|
||||
are deprecated in favor of `all()` and `allCols()` respectively.
|
||||
These replacements allow the [Compiler Plugin](Compiler-Plugin.md) to fully support such selections.
|
||||
|
||||
`colsAtAnyDepth()`, `colsInGroups()`, and `single()` overloads with a `predicate` argument
|
||||
that filters columns are also deprecated for better Compiler Plugin support.
|
||||
Use `.filter(predicate)` for filtering instead.
|
||||
|
||||
| 0.15 | 1.0 |
|
||||
|--------------------------------------------------|------------------------------------------------------------------|
|
||||
| `df.select { cols() }` | `df.select { all() }` |
|
||||
| `df.select { colGroup.cols() }` | `df.select { colGroup.allCols() }` |
|
||||
| `df.select { colsAtAnyDepth { predicate } }` | `df.select { colsAtAnyDepth().filter { predicate } }` |
|
||||
| `df.select { colsInGroups { predicate } }` | `df.select { colsInGroups().filter { predicate } }` |
|
||||
| `df.select { single { predicate } }` | `df.select { cols().filter { predicate }.single() }` |
|
||||
| `df.select { colGroup.singleCol { predicate } }` | `df.select { colGroup.allCols().filter { predicate }.single() }` |
|
||||
| `df.select { colSet.single { predicate } }` | `df.select { colSet.filter { predicate }.single() }` |
|
||||
|
||||
|
||||
|
||||
### Removed functions and classes
|
||||
|
||||
The next functions and classes raise `ERROR` in 1.0 and will be removed in 1.1.
|
||||
|
||||
| 0.15 | 1.0 | Reason |
|
||||
|----------------------------------------------------------------|------------------------------------------------------------------------------|----------------------------------------|
|
||||
| `DataColumn.createFrameColumn(name, df, startIndices)` | `df.chunked(name, startIndices)` | Replaced with another function. |
|
||||
| `DataColumn.createWithTypeInference(name, values, nullable)` | `DataColumn.createByInference(name, values, TypeSuggestion.Infer, nullable)` | Replaced with another function. |
|
||||
| `DataColumn.create(name, values, infer)` | `DataColumn.createByType(name, values, infer)` | Replaced with another function. |
|
||||
| `col.isComparable()` | `col.valuesAreComparable()` | Renamed to better reflect its purpose. |
|
||||
| `df.minus { columns }` | `df.remove { columns }` | Replaced with another function. |
|
||||
| `df.move { columns }.toLeft()`/`df.moveToLeft{ columns }` | `df.move { columns }.toStart()`/`df.moveToStart { columns }` | Renamed to better reflect its purpose. |
|
||||
| `df.move { columns }.toRight()`/`df.moveToRight{ columns }` | `df.move { columns }.toEnd()`/`df.moveToEnd{ columns }` | Renamed to better reflect its purpose. |
|
||||
| `row.rowMin()`/`row.rowMinOrNull()` | `row.rowMinOf()`/`row.rowMinOfOrNull()` | Renamed to better reflect its purpose. |
|
||||
| `row.rowMax()`/`row.rowMaxOrNull()` | `row.rowMaxOf()`/`AnyRow.rowMaxOfOrNull()` | Renamed to better reflect its purpose. |
|
||||
| `row.rowPercentile()`/`row.rowPercentileOrNull()` | `row.rowPercentileOf()`/`row.rowPercentileOfOrNull()` | Renamed to better reflect its purpose. |
|
||||
| `row.rowMedian()`/`row.rowMedianOrNull()` | `row.rowMedianOf()`/`row.rowMedianOfOrNull()` | Renamed to better reflect its purpose. |
|
||||
| `df.convert { columns }.to { converter }` | `df.convert { columns }.asColumn { converter }` | Renamed to better reflect its purpose. |
|
||||
| `df.toHTML(..)`/`df.toStandaloneHTML()` | `df.toHtml(..)`/`df.toStandaloneHtml()` | Renamed to the correct CamelCase. |
|
||||
| `df.writeHTML()` | `df.writeHtml()` | Renamed to the correct CamelCase. |
|
||||
| `asURL(fileOrUrl)`/`isURL(path)` | `asUrl(fileOrUrl)`/`isUrl(path)` | Renamed to the correct CamelCase. |
|
||||
| `df.convert { columns }.toURL()`/`df.convertToURL { columns }` | `df.convert { columns }.toUrl()`/`df.convertToUrl { columns }` | Renamed to the correct CamelCase. |
|
||||
| `df.filterBy(column)` | `df.filter { column }` | Replaced with another function. |
|
||||
| `FormattingDSL` | `FormattingDsl` | Renamed to the correct CamelCase. |
|
||||
| `RGBColor` | `RgbColor` | Renamed to the correct CamelCase. |
|
||||
| `df.insert(column).after(columnPath)` | `df.insert(column).after { columnPath }` | Replaced with another function. |
|
||||
| `CompareResult.Equals` / `CompareResult.isEqual()` | `CompareResult.Matches` / `CompareResult.matches()` | Renamed to better reflect its purpose. |
|
||||
| `CompareResult.isSuperOrEqual()` | `CompareResult.isSuperOrMatches()` | Renamed to better reflect its purpose. |
|
||||
|
||||
The next functions and classes raise `WARNING` in 1.0 and `ERROR` in 1.1.
|
||||
|
||||
| 0.15 | 1.0 | Reason |
|
||||
|----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
|
||||
| `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. |
|
||||
| `dataFrameOf(header, values)` | `dataFrameOf(header).withValues(values)` | Replaced with another function. |
|
||||
| `df.generateCode(..)` | `df.generateInterfaces(..)` | Replaced with another function. |
|
||||
| `df.select { mapToColumn(name, infer) { body } }` | `df.select { expr(name, infer) { body } }` | Removed duplicated functionality. |
|
||||
| `stringCol.length()` | `stringCol.map { it?.length ?: 0 }` | Removed a shortcut to clarify the behaviour; Only for `String` columns. |
|
||||
| `stringCol.lowercase()` / `stringCol.uppercase()` | `stringCol.map { it?.lowercase() }` / `stringCol.map { it?.uppercase() }` | Removed a shortcut to clarify the behaviour; Only for `String` columns. |
|
||||
| `df.add(columns)` / `df.add(dataframes)` | `df.addAll(columns)` / `df.addAll(dataframes)` | Renamed to to improve completion. |
|
||||
| `row.isEmpty()` / `row.isNotEmpty()` | `row.values().all { it == null }` / `row.values().all { it == null }` | Removed a shortcut to clarify the behaviour; |
|
||||
| `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; |
|
||||
| `df.copy()` | `df.columns().toDataFrame().cast()` | Removed a shortcut to clarify the behaviour; |
|
||||
| `KeyValueProperty<T>` | `NameValueProperty<T>` | Removed duplicated functionality. |
|
||||
|
||||
<!--TODO (https://github.com/Kotlin/dataframe/issues/1630)
|
||||
|
||||
## Modules
|
||||
|
||||
## Compiler Plugin
|
||||
|
||||
## Changes in working with JDBC
|
||||
|
||||
-->
|
||||
Reference in New Issue
Block a user