Merge pull request #189 from Kotlin/update-csv-read-docs

update csv read docs with ways to read locale specific numbers

Author: koperagen

docs/StardustDocs/topics/KPropertiesApi.md

@@ -15,7 +15,7 @@ data class Passenger(
     val lastName: String
 )
 
-val passengers = DataFrame.read("titanic.csv", delimiter = ';')
+val passengers = DataFrame.read("titanic.csv")
     .add(Passenger::lastName) { "name"<String>().split(",").last() }
     .dropNulls(Passenger::age)
     .filter {
@@ -39,7 +39,7 @@ data class Passenger(
     val name: String
 )
 
-val passengers = DataFrame.read("titanic.csv", delimiter = ';')
+val passengers = DataFrame.read("titanic.csv")
     .filter { it.get(Passenger::city).endsWith("NY") }
     .toListOf<Passenger>()
 ```

docs/StardustDocs/topics/apiLevels.md

@@ -34,7 +34,7 @@ In the most of the code snippets in this documentation there's a tab selector th
 <!---FUN extensionProperties1-->
 
 ```kotlin
-val df = DataFrame.read("titanic.csv", delimiter = ';')
+val df = DataFrame.read("titanic.csv")
 ```
 
 <!---END-->
@@ -55,7 +55,7 @@ df.add("lastName") { name.split(",").last() }
 <!---FUN strings-->
 
 ```kotlin
-DataFrame.read("titanic.csv", delimiter = ';')
+DataFrame.read("titanic.csv")
     .add("lastName") { "name"<String>().split(",").last() }
     .dropNulls("age")
     .filter {
@@ -79,7 +79,7 @@ val age by column<Int?>()
 val name by column<String>()
 val lastName by column<String>()
 
-DataFrame.read("titanic.csv", delimiter = ';')
+DataFrame.read("titanic.csv")
     .add(lastName) { name().split(",").last() }
     .dropNulls { age }
     .filter { survived() && home().endsWith("NY") && age()!! in 10..20 }
@@ -100,7 +100,7 @@ data class Passenger(
     val lastName: String
 )
 
-val passengers = DataFrame.read("titanic.csv", delimiter = ';')
+val passengers = DataFrame.read("titanic.csv")
     .add(Passenger::lastName) { "name"<String>().split(",").last() }
     .dropNulls(Passenger::age)
     .filter {

docs/StardustDocs/topics/columnAccessorsApi.md

@@ -21,7 +21,7 @@ Now columns can be accessed in a type-safe way using `invoke` operator:
 <!---FUN accessors2-->
 
 ```kotlin
-DataFrame.read("titanic.csv", delimiter = ';')
+DataFrame.read("titanic.csv")
     .add(lastName) { name().split(",").last() }
     .dropNulls { age }
     .filter { survived() && home().endsWith("NY") && age()!! in 10..20 }

docs/StardustDocs/topics/extensionPropertiesApi.md

@@ -7,7 +7,7 @@ When `DataFrame` is used within Jupyter Notebooks or Datalore with Kotlin Kernel
 <!---FUN extensionProperties1-->
 
 ```kotlin
-val df = DataFrame.read("titanic.csv", delimiter = ';')
+val df = DataFrame.read("titanic.csv")
 ```
 
 <!---END-->

docs/StardustDocs/topics/read.md

@@ -11,7 +11,7 @@ DataFrame.read("input.csv")
 
 Input string can be a file path or URL.
 
-### Reading CSV
+## Reading CSV
 
 All these calls are valid:
 
@@ -92,7 +92,47 @@ G: *
     D: Int
 ```
 
-### Reading JSON
+### Dealing with locale specific numbers
+
+Sometimes columns in your CSV can be interpreted differently depending on your system locale.
+
+<table>
+<tr><th>numbers</th></tr>
+<tr><td>12,123</td></tr>
+<tr><td>41,111</td></tr>
+</table>
+
+Here comma can be decimal or thousands separator, thus different values.
+You can deal with it in two ways
+
+1) Provide locale as a parser option
+
+<!---FUN readNumbersWithSpecificLocale-->
+
+```kotlin
+val df = DataFrame.readCSV(
+    file,
+    parserOptions = ParserOptions(locale = Locale.UK),
+)
+```
+
+<!---END-->
+
+2) Disable type inference for specific column and convert it yourself
+
+<!---FUN readNumbersWithColType-->
+
+```kotlin
+val df = DataFrame.readCSV(
+    file,
+    colTypes = mapOf("colName" to ColType.String)
+)
+```
+
+<!---END-->
+
+
+## Reading JSON
 
 Basics for reading JSONs are the same: you can read from file or from remote URL.
 
@@ -160,7 +200,7 @@ D: Boolean?
 Column A has `String` type because all values are string literals, no implicit conversion is performed. Column C
 has `Number` type because it's the least common type for `Int` and `Double`.
 
-#### JSON Reading Options: Type Clash Tactic
+### JSON Reading Options: Type Clash Tactic
 
 By default, if a type clash occurs when reading JSON, a new column group is created consisting of: "value", "array", and
 any number of object properties:
@@ -211,7 +251,7 @@ For this case, you can set `typeClashTactic = JSON.TypeClashTactic.ANY_COLUMNS`
 
 This option is also possible to set in the Gradle- and KSP plugin by providing `jsonOptions`.
 
-#### JSON Reading Options: Key/Value Paths
+### JSON Reading Options: Key/Value Paths
 
 If you have some JSON looking like
 
@@ -302,7 +342,7 @@ Only the bracket notation of json path is supported, as well as just double quot
 
 For more examples, see the "examples/json" module.
 
-### Reading Excel
+## Reading Excel
 
 Add dependency:
 
@@ -347,7 +387,7 @@ df1["IDS"].type() shouldBe typeOf<String>()
 
 <!---END-->
 
-### Reading Apache Arrow formats
+## Reading Apache Arrow formats
 
 Add dependency:
 

docs/StardustDocs/topics/stringApi.md

@@ -7,7 +7,7 @@ String column names are the easiest way to access data in DataFrame:
 <!---FUN strings-->
 
 ```kotlin
-DataFrame.read("titanic.csv", delimiter = ';')
+DataFrame.read("titanic.csv")
     .add("lastName") { "name"<String>().split(",").last() }
     .dropNulls("age")
     .filter {

tests/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Read.kt

@@ -10,13 +10,15 @@ import org.jetbrains.kotlinx.dataframe.api.columnTypes
 import org.jetbrains.kotlinx.dataframe.api.convert
 import org.jetbrains.kotlinx.dataframe.api.dataFrameOf
 import org.jetbrains.kotlinx.dataframe.api.with
+import org.jetbrains.kotlinx.dataframe.io.ColType
 import org.jetbrains.kotlinx.dataframe.io.readArrowFeather
 import org.jetbrains.kotlinx.dataframe.io.readCSV
 import org.jetbrains.kotlinx.dataframe.io.readJson
 import org.jetbrains.kotlinx.dataframe.testArrowFeather
 import org.jetbrains.kotlinx.dataframe.testCsv
 import org.jetbrains.kotlinx.dataframe.testJson
 import org.junit.Test
+import java.util.*
 import kotlin.reflect.typeOf
 
 class Read {
@@ -84,4 +86,26 @@ class Read {
         df.rowsCount() shouldBe 1
         df.columnsCount() shouldBe 4
     }
+
+    @Test
+    fun readNumbersWithSpecificLocale() {
+        val file = testCsv("numbers.csv")
+        // SampleStart
+        val df = DataFrame.readCSV(
+            file,
+            parserOptions = ParserOptions(locale = Locale.UK),
+        )
+        // SampleEnd
+    }
+
+    @Test
+    fun readNumbersWithColType() {
+        val file = testCsv("numbers.csv")
+        // SampleStart
+        val df = DataFrame.readCSV(
+            file,
+            colTypes = mapOf("colName" to ColType.String)
+        )
+        // SampleEnd
+    }
 }