avoiding binary incompatibility issues by modifying the public API

Author: Jolanrensen

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

@@ -24,6 +24,7 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
 import org.jetbrains.kotlinx.dataframe.columns.toColumnSet
 import org.jetbrains.kotlinx.dataframe.dataTypes.IFRAME
 import org.jetbrains.kotlinx.dataframe.dataTypes.IMG
+import org.jetbrains.kotlinx.dataframe.documentation.ExcludeFromSources
 import org.jetbrains.kotlinx.dataframe.exceptions.CellConversionException
 import org.jetbrains.kotlinx.dataframe.exceptions.TypeConversionException
 import org.jetbrains.kotlinx.dataframe.impl.api.Parsers
@@ -189,27 +190,38 @@ public fun <T : Any> DataColumn<T?>.convertToDouble(): DataColumn<Double?> = con
  * If [locale] parameter is defined, it's number format is used for parsing.
  * If [locale] parameter is null, the current system locale is used.
  * If the column cannot be parsed, then the POSIX format is used.
- *
+ */
+@ExcludeFromSources
+private interface DataColumnStringConvertToDoubleDoc
+
+/** @include [DataColumnStringConvertToDoubleDoc] */
+@JvmName("convertToDoubleFromString")
+public fun DataColumn<String>.convertToDouble(locale: Locale? = null): DataColumn<Double> =
+    convertToDouble(locale = locale, useFastDoubleParser = false)
+
+/**
+ * @include [DataColumnStringConvertToDoubleDoc]
  * @param useFastDoubleParser whether to use the new _experimental_ FastDoubleParser, defaults to `false` for now.
  */
 @JvmName("convertToDoubleFromString")
 public fun DataColumn<String>.convertToDouble(
     locale: Locale? = null,
-    useFastDoubleParser: Boolean = false,
+    useFastDoubleParser: Boolean,
 ): DataColumn<Double> = this.castToNullable().convertToDouble(locale, useFastDoubleParser).castToNotNullable()
 
+/** @include [DataColumnStringConvertToDoubleDoc] */
+@JvmName("convertToDoubleFromStringNullable")
+public fun DataColumn<String?>.convertToDouble(locale: Locale? = null): DataColumn<Double?> =
+    convertToDouble(locale = locale, useFastDoubleParser = false)
+
 /**
- * Parses a String column to Double considering locale (number format).
- * If [locale] parameter is defined, it's number format is used for parsing.
- * If [locale] parameter is null, the current system locale is used.
- * If the column cannot be parsed, then the POSIX format is used.
- *
+ * @include [DataColumnStringConvertToDoubleDoc]
  * @param useFastDoubleParser whether to use the new _experimental_ FastDoubleParser, defaults to `false` for now.
  */
 @JvmName("convertToDoubleFromStringNullable")
 public fun DataColumn<String?>.convertToDouble(
     locale: Locale? = null,
-    useFastDoubleParser: Boolean = false,
+    useFastDoubleParser: Boolean,
 ): DataColumn<Double?> {
     fun applyParser(parser: (String) -> Double?): DataColumn<Double?> {
         var currentRow = 0

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

@@ -11,6 +11,8 @@ import org.jetbrains.kotlinx.dataframe.impl.api.StringParser
 import org.jetbrains.kotlinx.dataframe.impl.api.parseImpl
 import org.jetbrains.kotlinx.dataframe.impl.api.tryParseImpl
 import org.jetbrains.kotlinx.dataframe.typeClass
+import org.jetbrains.kotlinx.dataframe.util.PARSER_OPTIONS
+import org.jetbrains.kotlinx.dataframe.util.PARSER_OPTIONS_COPY
 import java.time.format.DateTimeFormatter
 import java.util.Locale
 import kotlin.reflect.KProperty
@@ -64,6 +66,44 @@ public data class ParserOptions(
     val nullStrings: Set<String>? = null,
     val useFastDoubleParser: Boolean = false,
 ) {
+
+    /** For binary compatibility. */
+    @Deprecated(
+        message = PARSER_OPTIONS,
+        level = DeprecationLevel.HIDDEN,
+    )
+    public constructor(
+        locale: Locale? = null,
+        dateTimeFormatter: DateTimeFormatter? = null,
+        dateTimePattern: String? = null,
+        nullStrings: Set<String>? = null,
+    ) : this(
+        locale = locale,
+        dateTimeFormatter = dateTimeFormatter,
+        dateTimePattern = dateTimePattern,
+        nullStrings = nullStrings,
+        useFastDoubleParser = false,
+    )
+
+    /** For binary compatibility. */
+    @Deprecated(
+        message = PARSER_OPTIONS_COPY,
+        level = DeprecationLevel.HIDDEN,
+    )
+    public fun copy(
+        locale: Locale? = this.locale,
+        dateTimeFormatter: DateTimeFormatter? = this.dateTimeFormatter,
+        dateTimePattern: String? = this.dateTimePattern,
+        nullStrings: Set<String>? = this.nullStrings,
+    ): ParserOptions =
+        ParserOptions(
+            locale = locale,
+            dateTimeFormatter = dateTimeFormatter,
+            dateTimePattern = dateTimePattern,
+            nullStrings = nullStrings,
+            useFastDoubleParser = useFastDoubleParser,
+        )
+
     internal fun getDateTimeFormatter(): DateTimeFormatter? =
         when {
             dateTimeFormatter != null -> dateTimeFormatter

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt

@@ -15,6 +15,10 @@ internal const val DF_READ_NO_CSV = "This function is deprecated and should be r
 internal const val DF_READ_NO_CSV_REPLACE =
     "this.readCSV(fileOrUrl, delimiter, header, colTypes, skipLines, readLines, duplicate, charset)"
 
+internal const val PARSER_OPTIONS = "This constructor is only here for binary compatibility. $MESSAGE_0_16"
+
+internal const val PARSER_OPTIONS_COPY = "This function is only here for binary compatibility. $MESSAGE_0_16"
+
 // endregion
 
 // region WARNING in 0.16, ERROR in 0.17