Skip to content

Commit 700a99b

Browse files
JolanrensenJolanrensen
authored
Merge pull request #1830 from Kotlin/parsing-1.0-migration
Added parsing date-time migration docs for 1.0
2 parents b7ca664 + a615401 commit 700a99b

1 file changed

Lines changed: 239 additions & 9 deletions

File tree

‎docs/StardustDocs/topics/MigrationTo_1_0.md‎

Lines changed: 239 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ This section provides a complete overview of all API changes to help you migrate
77

88
### Renamed functions and classes to the correct CamelCase spelling { id="camelCase" }
99

10-
All functions and classes in Kotlin DataFrame
11-
have been renamed to
10+
All functions and classes in Kotlin DataFrame
11+
have been renamed to
1212
[the correct CamelCase spelling](https://developer.android.com/kotlin/style-guide#camel_case).
1313

1414
See below for a complete list of the renamed functions and classes.
@@ -28,7 +28,6 @@ Functions were also renamed to [the correct CamelCase spelling](#camelCase).
2828
All new functions keep the same arguments as before and additionally introduce new ones.
2929
Also, [there are new arguments that expose Deephaven CSV features](read.md#unlocking-deephaven-csv-features).
3030

31-
3231
See [](read.md#read-from-csv).
3332

3433
> All outdated CSV IO functions raise `WARNING` in 1.0 and will raise `ERROR` in 1.1.
@@ -44,13 +43,15 @@ See [](read.md#read-from-csv).
4443
### Migration to Standard Library `Instant`
4544

4645
Since Kotlin 2.1.20,
47-
[`Instant` is now part of the standard library](https://kotlinlang.org/docs/whatsnew2120.html#new-time-tracking-functionality)
46+
[
47+
`Instant` is now part of the standard library](https://kotlinlang.org/docs/whatsnew2120.html#new-time-tracking-functionality)
4848
(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.
49+
You can still use the old (deprecated) `kotlinx.datetime.Instant` type, but its support will be removed in Kotlin
50+
DataFrame 1.1.
5051

5152
> New `Instant` in the Kotlin Standard Library becomes stable in 2.3.0.
5253
> In earlier versions, all related operations should be marked with the `@OptIn(ExperimentalTime::class)` annotation.
53-
{style="note"}
54+
> {style="note"}
5455
5556
For now, each `Instant`-related operation has been split into two new ones —
5657
one for the new stdlib `kotlin.time.Instant` and one for the old deprecated `kotlinx.datetime.Instant`.
@@ -104,7 +105,7 @@ For example:
104105
```kotlin
105106
DataFrame.readCsv(
106107
...,
107-
parserOptions = ParserOptions(parseExperimentalInstant = false)
108+
parserOptions = ParserOptions(parseExperimentalInstant = false)
108109
)
109110
```
110111

@@ -129,8 +130,6 @@ Use `.filter(predicate)` for filtering instead.
129130
| `df.select { colGroup.singleCol { predicate } }` | `df.select { colGroup.allCols().filter { predicate }.single() }` |
130131
| `df.select { colSet.single { predicate } }` | `df.select { colSet.filter { predicate }.single() }` |
131132

132-
133-
134133
### Removed functions and classes
135134

136135
The next functions and classes raise `ERROR` in 1.0 and will be removed in 1.1.
@@ -177,6 +176,237 @@ The next functions and classes raise `WARNING` in 1.0 and `ERROR` in 1.1.
177176
| `df.copy()` | `df.columns().toDataFrame().cast()` | Removed a shortcut to clarify the behaviour; |
178177
| `KeyValueProperty<T>` | `NameValueProperty<T>` | Removed duplicated functionality. |
179178

179+
## Parsing and Converting Date-Time
180+
181+
In 0.15 and up to 1.0-Beta4 we did support the [kotlinx-datetime](https://github.com/Kotlin/kotlinx-datetime)
182+
types; however, they were still treated second-level in DataFrame. [`ParserOptions`](parse.md#parser-options)
183+
were still built around the Java `DataTimeFormatter`-paradigm.
184+
Starting from 1.0-Beta5, [kotlinx-datetime](https://github.com/Kotlin/kotlinx-datetime) types now become first-class
185+
citizens,
186+
while still allowing you to use Java types if you need them.
187+
188+
<table>
189+
<tr>
190+
<th>0.15</th>
191+
<th>1.0</th>
192+
<th>Reason</th>
193+
</tr>
194+
<tr>
195+
<td>
196+
197+
```kotlin
198+
df.parse()
199+
```
200+
</td>
201+
<td>
202+
203+
```kotlin
204+
df.parse()
205+
```
206+
</td>
207+
<td>Default parsing behavior remains largely unchanged.</td>
208+
</tr>
209+
<tr>
210+
<td>
211+
212+
```kotlin
213+
df.parse(
214+
ParserOptions(
215+
skipTypes = setOf(
216+
typeOf<kotlinx.datetime.LocalDate>(),
217+
...,
218+
),
219+
),
220+
)
221+
```
222+
</td>
223+
<td>
224+
225+
```kotlin
226+
df.parse(
227+
ParserOptions(dateTime = DateTimeParserOptions.Java),
228+
)
229+
```
230+
</td>
231+
<td>If you want to force parsing to Java date-time types, you no longer have use skipTypes, you can simply change the `dateTime` argument.</td>
232+
</tr>
233+
<tr>
234+
<td>
235+
236+
```kotlin
237+
DataFrame.parser.addSkipType(
238+
typeOf<kotlinx.datetime.LocalDate>(),
239+
)
240+
```
241+
</td>
242+
<td>
243+
244+
```kotlin
245+
DataFrame.parser.dateTimeLibrary = ParseDateTimeLibrary.JAVA
246+
```
247+
</td>
248+
<td>The same logic applies for the <a href="parse.md#global-parser-options">global parser options</a>.</td>
249+
</tr>
250+
<tr>
251+
<td rowspan="2">
252+
253+
```kotlin
254+
ParserOptions(dateTimeFormatter = myFormatter)
255+
```
256+
</td>
257+
<td>
258+
Kotlin:
259+
260+
```kotlin
261+
ParserOptions(
262+
dateTime = DateTimeParserOptions.Kotlin
263+
.withFormat<_>(myKotlinFormat),
264+
)
265+
```
266+
</td>
267+
<td rowspan="2">You now need to explicitly specify you expect Java or Kotlin date-time types via `DateTimeParserOptions.X`. Then you can specify the relevant options, like a `kotlinx.datetime.format.DateTimeFormat` or `java.time.DateTimeFormatter`. These are typed now too, optionally for Java.</td>
268+
</tr>
269+
<tr>
270+
<td>
271+
Java:
272+
273+
```kotlin
274+
ParserOptions(
275+
dateTime = DateTimeParserOptions.Java
276+
.withFormatter<java.time.LocalDateTime>(myJavaFormatter),
277+
)
278+
```
279+
</td>
280+
</tr>
281+
<tr>
282+
<td>
283+
284+
```kotlin
285+
ParserOptions(
286+
locale = myLocale,
287+
dateTimeFormatter = myFormatter,
288+
)
289+
```
290+
</td>
291+
<td>
292+
293+
```kotlin
294+
ParserOptions(
295+
dateTime = DateTimeParserOptions.Java
296+
.withLocale(myLocale)
297+
.withFormatter<java.time.LocalDateTime>(myFormatter),
298+
)
299+
```
300+
</td>
301+
<td>Locale for date-time only works for Java types. If you need Kotlin types ánd a locale use <a href="convert.md">convert</a> to convert to Kotlin types afterwards.</td>
302+
</tr>
303+
<tr>
304+
<td rowspan="2">
305+
306+
```kotlin
307+
ParserOptions(dateTimePattern = "MM/dd yyyy")
308+
```
309+
</td>
310+
<td>
311+
Kotlin:
312+
313+
```kotlin
314+
@OptIn(FormatStringsInDatetimeFormats::class)
315+
ParserOptions(
316+
dateTime = DateTimeParserOptions.Kotlin
317+
.withPattern<kotlinx.datetime.LocalDate>("MM/dd yyyy"),
318+
)
319+
```
320+
</td>
321+
<td rowspan="2">Again, you now need to specify the target date-time library and the expected type for your pattern (optionally for Java). In Kotlin you also need to opt-in, because using `DateTimeFormat` instead is <a href="https://github.com/Kotlin/kotlinx-datetime#using-unicode-format-strings-like-yyyy-mm-dd">recommended</a>.</td>
322+
</tr>
323+
<tr>
324+
<td>
325+
Java:
326+
327+
```kotlin
328+
ParserOptions(
329+
dateTime = DateTimeParserOptions.Java
330+
.withPattern<java.time.LocalDate>("MM/dd yyyy"),
331+
)
332+
```
333+
</td>
334+
</tr>
335+
<tr>
336+
<td rowspan="2">
337+
338+
```kotlin
339+
DataFrame.parser.addDateTimePattern("MM/dd yyyy")
340+
```
341+
</td>
342+
<td>
343+
Kotlin:
344+
345+
```kotlin
346+
@OptIn(FormatStringsInDatetimeFormats::class)
347+
DataFrame.parser
348+
.addDateTimeUnicodePattern<kotlinx.datetime.LocalDate>("MM/dd yyyy")
349+
```
350+
</td>
351+
<td rowspan="2">Same idea. Though you can now also use `...addDateTimeFormat()` / `...addJavaDateTimeFormatter()`, which we would recommend more.</td>
352+
</tr>
353+
<tr>
354+
<td>
355+
Java:
356+
357+
```kotlin
358+
DataFrame.parser
359+
.addJavaDateTimePattern<java.time.LocalDate>("MM/dd yyyy")
360+
```
361+
</td>
362+
</tr>
363+
<tr>
364+
<td rowspan="2">
365+
366+
```kotlin
367+
convert { stringCols }.toLocalDate(pattern = "MM/dd yyyy")
368+
```
369+
</td>
370+
<td>
371+
Kotlin:
372+
373+
```kotlin
374+
@OptIn(FormatStringsInDatetimeFormats::class)
375+
convert { stringCols }.toLocalDate(pattern = "MM/dd yyyy")
376+
```
377+
</td>
378+
<td rowspan="2">Same logic applies to convert: you need to opt-in to use patterns for Kotlin types and specify "Java" for Java types.</td>
379+
</tr>
380+
<tr>
381+
<td>
382+
Java:
383+
384+
```kotlin
385+
convert { stringCols }.toJavaLocalDate(pattern = "MM/dd yyyy")
386+
```
387+
</td>
388+
</tr>
389+
<tr>
390+
<td>
391+
392+
```kotlin
393+
stringCol.convertToLocalDate(locale = Locale.GERMAN)
394+
```
395+
</td>
396+
<td>
397+
398+
```kotlin
399+
stringCol
400+
.convertToJavaLocalDate(locale = Locale.GERMAN)
401+
.convertToLocalDate()
402+
```
403+
</td>
404+
<td>If you need to supply a locale to be able to parse date-time types, parse to Java types first, then convert to Kotlin ones.</td>
405+
</tr>
406+
</table>
407+
408+
For more information, check out [](parse.md#parsing-date-time-strings).
409+
180410
<!--TODO (https://github.com/Kotlin/dataframe/issues/1630)
181411
182412
## Modules

0 commit comments

Comments
 (0)