diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convert.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convert.kt index 3b7c08f3aa..ffea103f31 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convert.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convert.kt @@ -13,6 +13,7 @@ import org.jetbrains.kotlinx.dataframe.ColumnsContainer import org.jetbrains.kotlinx.dataframe.ColumnsSelector import org.jetbrains.kotlinx.dataframe.DataColumn import org.jetbrains.kotlinx.dataframe.DataFrame +import org.jetbrains.kotlinx.dataframe.DataFrameExpression import org.jetbrains.kotlinx.dataframe.DataRow import org.jetbrains.kotlinx.dataframe.RowColumnExpression import org.jetbrains.kotlinx.dataframe.RowValueExpression @@ -26,7 +27,14 @@ 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.DocumentationUrls +import org.jetbrains.kotlinx.dataframe.documentation.DslGrammarLink import org.jetbrains.kotlinx.dataframe.documentation.ExcludeFromSources +import org.jetbrains.kotlinx.dataframe.documentation.ExpressionsGivenDataFrame +import org.jetbrains.kotlinx.dataframe.documentation.ExpressionsGivenRow +import org.jetbrains.kotlinx.dataframe.documentation.Indent +import org.jetbrains.kotlinx.dataframe.documentation.LineBreak +import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns import org.jetbrains.kotlinx.dataframe.impl.api.Parsers import org.jetbrains.kotlinx.dataframe.impl.api.convertRowColumnImpl import org.jetbrains.kotlinx.dataframe.impl.api.convertToDoubleImpl @@ -48,12 +56,171 @@ import kotlin.reflect.KType import kotlin.reflect.full.isSubtypeOf import kotlin.reflect.typeOf +/** + * Converts the values in the specified [columns\] to a target type + * or using a custom converter, keeping their original names and positions within the [DataFrame]. + * + * This function does not immediately convert the columns but instead selects columns to convert and + * returns a [Convert], + * which serves as an intermediate step. + * The [Convert] object allows you to specify how the selected + * columns will be converted using following methods: + * [to][Convert.to], + * [with][Convert.with], + * [asFrame][Convert.asFrame], + * [perRowCol][Convert.perRowCol], + * [notNull][Convert.notNull], + * [toStr][Convert.toStr], + * [toInt][Convert.toInt], + * [toLong][Convert.toLong], + * [toDouble][Convert.toDouble], + * [toFloat][Convert.toFloat], + * [toBigDecimal][Convert.toBigDecimal], + * [toBigInteger][Convert.toBigInteger], + * [toBoolean][Convert.toBoolean], + * [toLocalDateTime][Convert.toLocalDateTime], + * [toLocalDate][Convert.toLocalDate], + * [toLocalTime][Convert.toLocalTime], + * [toInstant][Convert.toInstant], + * [toURL][Convert.toURL], + * [toIFrame][Convert.toIFrame], + * [toImg][Convert.toImg], and [toDataFrames][Convert.toDataFrames] + * that return a new [DataFrame] with updated columns. + * + * Check out [Grammar]. + * + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * + * See [Selecting Columns][ConvertSelectingOptions]. + * + * For more information: {@include [DocumentationUrls.Convert]} + */ +internal interface ConvertDocs { + + /** + * {@comment Version of [SelectingColumns] with correctly filled in examples} + * @include [SelectingColumns] {@include [SetConvertOperationArg]} + */ + interface ConvertSelectingOptions + + /** + * ## Convert Operation Grammar + * {@include [LineBreak]} + * {@include [DslGrammarLink]} + * {@include [LineBreak]} + * + * **[`convert`][convert]**` { columnsSelector: `[`ColumnsSelector`][ColumnsSelector]` }` + * + * {@include [Indent]} + * __`.`__[**`with`**][Convert.with]`(infer: `[`Infer`][Infer]`, rowExpression: `[`RowValueExpression`][RowValueExpression]`)` + * + * {@include [Indent]} + * `| `__`.`__[**`notNull`**][Convert.notNull]` { rowExpression: `[`RowValueExpression`][RowValueExpression]` }` + * + * {@include [Indent]} + * `| `__`.`__[**`to`**][Convert.to]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`to`**][Convert.to]`(type: `[`KType`][KType]`)` + * + * {@include [Indent]} + * `| `__`.`__[**`to`**][Convert.to]` { columnConverter: `[`DataFrame`](DataFrame)`.(`[`DataColumn`](DataColumn)`) -> `[`AnyBaseColumn`](AnyBaseColumn)` }` + * + * {@include [Indent]} + * `| `__`.`__[**`perRowCol`**][Convert.perRowCol]` { expression: `[`RowColumnExpression`][RowColumnExpression]` }` + * + * {@include [Indent]} + * `| `__`.`__[**`asFrame`**][Convert.asFrame]` { builder: `[`ColumnsContainer`](ColumnsContainer)`.(`[`ColumnConvert`](ColumnConvert)`) -> `[`DataFrame`](DataFrame)` }` + * + * {@include [Indent]} + * `| `__`.`__[**`toStr`**][Convert.toStr]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`toInt`**][Convert.toInt]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`toLong`**][Convert.toLong]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`toDouble`**][Convert.toDouble]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`toFloat`**][Convert.toFloat]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`toBigDecimal`**][Convert.toBigDecimal]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`toBigInteger`**][Convert.toBigInteger]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`toBoolean`**][Convert.toBoolean]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`toLocalDateTime`**][Convert.toLocalDateTime]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`toLocalDate`**][Convert.toLocalDate]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`toLocalTime`**][Convert.toLocalTime]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`toInstant`**][Convert.toInstant]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`toURL`**][Convert.toURL]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`toIFrame`**][Convert.toIFrame]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`toImg`**][Convert.toImg]`()` + * + * {@include [Indent]} + * `| `__`.`__[**`toDataFrames`**][Convert.toDataFrames]`()` + */ + interface Grammar +} + +/** {@set [SelectingColumns.OPERATION] [convert][convert]} */ +@ExcludeFromSources +private interface SetConvertOperationArg + +/** + * {@include [ConvertDocs]} + * ### This Convert Overload + */ +@ExcludeFromSources +private interface CommonConvertDocs + +/** + * @include [CommonConvertDocs] + * @include [SelectingColumns.Dsl] {@include [SetConvertOperationArg]} + * ### Examples: + * ```kotlin + * df.convert { columnA and columnB }.with { it.toString().lowercase() } + * df.convert { colsOf() }.to() + * df.convert { colsAtAnyDepth().colGroups() }.asFrame { it.add("nan") { Double.NaN } } + * ``` + * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to group. + */ @Interpretable("Convert0") public fun DataFrame.convert(columns: ColumnsSelector): Convert = Convert(this, columns) @AccessApiOverload public fun DataFrame.convert(vararg columns: KProperty): Convert = convert { columns.toColumnSet() } +/** + * @include [CommonConvertDocs] + * @include [SelectingColumns.ColumnNames] {@include [SetConvertOperationArg]} + * ### Example: + * ```kotlin + * df.convert("person", "position").toStr() + * df.convert("value").with { (it as Number).toDouble() } + * ``` + * @param [columns\] The [Column Names][String] used to select the columns of this [DataFrame] to group. + */ @Interpretable("Convert2") public fun DataFrame.convert(vararg columns: String): Convert = convert { columns.toColumnSet() } @@ -77,6 +244,24 @@ public inline fun DataFrame.convert( noinline expression: RowValueExpression, ): DataFrame = convert(*headPlusArray(firstCol, cols)).with(infer, expression) +/** + * Converts specified columns + * using row converter [expression] within the [DataFrame]. + * {@include [ExpressionsGivenRow.RowValueExpression]} + * + * ## Note + * @include [ExpressionsGivenRow.AddDataRowNote] + * ## See Also + * - {@include [SeeAlsoConvertPerRowCol]} + * + * ### Example: + * ```kotlin + * // Convert values in selected column to a trimmed `String`. + * df.convert("valueA", "valueB") { it.toString().trim() } + * ``` + * @param [expression] The {@include [ExpressionsGivenRow.RowValueExpressionLink]} to update the rows with. + * @return A new [DataFrame] with the converted values. + */ @Interpretable("Convert6") public inline fun DataFrame.convert( firstCol: String, @@ -96,10 +281,63 @@ public inline fun Convert.notNull( } } +/** + * An intermediate class used in the [convert] operation. + * + * This class itself does not perform any conversion — it is a transitional step + * before specifying how to convert the selected columns. + * It must be followed by one of the conversion methods + * to produce a new [DataFrame] with updated column values and types. + * + * The resulting columns will keep their original names and positions + * in the [DataFrame], but their values will be transformed. + * + * Use the following methods to perform the conversion: + * - [to(type)][to]/[to`()][to] – converts columns to a specific type. + * - [to { columnConverter }][to] - converts columns using column converter expression. + * - [with][Convert.with] – applies a custom row-wise conversion expression. + * - [notNull][Convert.notNull] – like [with], but only for non-null values. + * - [perRowCol][Convert.perRowCol] – applies a conversion that uses both column and row information. + * - [asFrame][Convert.asFrame] – converts [column groups][ColumnGroup] as a [DataFrame] with the given expression. + * - [toStr], [toInt], [toLong], [toDouble], [toFloat], [toBigDecimal], + * [toBigInteger], [toBoolean] – convert to standard types. + * - [toLocalDateTime], [toLocalDate], [toLocalTime], [toInstant] – convert to kotlinx.datetime types. + * - [toURL], [toIFrame], [toImg] – convert to special types. + * - [toDataFrames] – converts a column of lists into separate DataFrames. + * + * See [Grammar][ConvertDocs.Grammar] for more details. + */ @HasSchema(schemaArg = 0) public class Convert(internal val df: DataFrame, internal val columns: ColumnsSelector) { + + /** + * Casts the type parameter of the columns previously selected with [convert][convert] to a new type [R], + * without performing any actual data transformation. + * + * This operation updates the static type of the selected columns for further type-safe conversions. + */ public fun cast(): Convert = Convert(df, columns as ColumnsSelector) + /** + * Converts values in the columns previously selected with [convert] to the specified type [D], + * preserving their original names and positions within the [DataFrame]. + * + * The target type is provided as a reified type argument. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * // Convert selected columns to Int: + * df.convert("year", "count").to() + * + * // Convert all String columns to LocalDate: + * df.convert { colsOf() }.to() + * ``` + * + * @param D The target type, provided as a reified type argument, to convert values to. + * @return A new [DataFrame] with the values converted to type [D]. + */ @Refine @Interpretable("To0") public inline fun to(): DataFrame = to(typeOf()) @@ -107,28 +345,144 @@ public class Convert(internal val df: DataFrame, internal val colum override fun toString(): String = "Convert(df=$df, columns=$columns)" } +/** + * Converts values in the columns previously selected with [convert] to the specified [type], + * preserving their original names and positions within the [DataFrame]. + * + * The target type is provided as a [KType]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * // Convert selected columns to String: + * df.convert("year", "count").to(typeOf()) + * df.convert { year and count }.to(typeOf()) + * // Convert all `Int` columns to `Double` + * df.convert { colsOf() }.to(typeOf()) + * ``` + * + * @param type The target type, provided as a [KType], to convert values to. + * @return A new [DataFrame] with the values converted to [type]. + */ public fun Convert.to(type: KType): DataFrame = to { it.convertTo(type) } +/** + * Converts values in the columns previously selected with [convert] + * using [columnConverter] expression within the [DataFrame]. + * + * The [columnConverter] is a lambda with the current [DataFrame] as receiver and the selected column as argument. + * It returns a new [DataColumn] (or [ColumnGroup]) that will replace the original column. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ## See Also + * - {@include [SeeAlsoConvertWith]} + * + * ### Examples: + * ```kotlin + * // Select `Int` columns ("valueA", "valueB") and multiply them with `Double` column ("coeff"). + * df.convert { valueA and valueB }.to { it * coeff } + * // Convert all columns into column groups, each containing the original column + * df.convert { all() }.to { listOf(it).toColumnGroup(it.name + "Group") } + * ``` + * + * @return A new [DataFrame] with the values converted to [type]. + */ public fun Convert.to(columnConverter: DataFrame.(DataColumn) -> AnyBaseCol): DataFrame = df.replace(columns).with { columnConverter(df, it) } -@Refine -@Interpretable("With0") -public inline fun Convert.with( - infer: Infer = Infer.Nulls, - noinline rowConverter: RowValueExpression, -): DataFrame = withRowCellImpl(typeOf(), infer, rowConverter) +/** [Convert per row col][Convert.perRowCol] to provide a new value for every selected cell giving its column. */ +@ExcludeFromSources +private interface SeeAlsoConvertPerRowCol + +/** [Convert with][Convert.to] to convert using a column converter */ +@ExcludeFromSources +private interface SeeAlsoConvertTo +/** + * Converts values in the columns previously selected with [convert] + * using [row value][RowValueExpression] [expression] within the [DataFrame]. + * + * A [row value expression][RowValueExpression] allows to provide a new value for every selected cell + * given its row (as a receiver) and its previous value (as a lambda argument). + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ## Note + * @include [ExpressionsGivenRow.AddDataRowNote] + * ## See Also + * - {@include [SeeAlsoConvertPerRowCol]} + * - {@include [SeeAlsoConvertTo]} + * + * ### Examples: + * ```kotlin + * // Select columns with json values and convert it to decoded `String`. + * df.convert { valueJson }.with { Json.decode(it) } + * // Convert all `Int` columns to `Duration`, multiplying each value by the corresponding value from the "coeff" `Double` column before conversion + * df.convert { colsOf() }.with { baseValue -> (baseValue * coeff).toDuration(DurationUnit.MICROSECONDS) } + * ``` + * + * @param infer [Infer] strategy that defines how the [type][DataColumn.type] of the resulting column should be determined. + * Defaults to [Infer.Nulls]. + * @param [expression] The [RowValueExpression] to provide a new value for every selected cell giving its row and previous value. + * @return A new [DataFrame] with the converted values. + */ @Refine @Interpretable("With0") public inline fun Convert.with( - noinline rowConverter: RowValueExpression, -): DataFrame = with(Infer.Nulls, rowConverter) + infer: Infer = Infer.Nulls, + noinline expression: RowValueExpression, +): DataFrame = withRowCellImpl(typeOf(), infer, expression) +/** + * Converts [column groups][ColumnGroup] previously selected with [convert] + * as a [DataFrame] using a [dataframe expression][DataFrameExpression]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Example: + * ```kotlin + * // Add a column to selected column group "name". + * df.convert { name }.asFrame { it.add("fullName") { "\$firstName \$lastName" } } + * ``` + * + * @param [expression] The {@include [ExpressionsGivenDataFrame.DataFrameExpressionLink]} to replace the selected column group with. + */ public fun Convert>.asFrame( - body: ColumnsContainer.(ColumnGroup) -> DataFrame, -): DataFrame = to { body(this, it.asColumnGroup()).asColumnGroup(it.name()) } + expression: ColumnsContainer.(ColumnGroup) -> DataFrame, +): DataFrame = to { expression(this, it.asColumnGroup()).asColumnGroup(it.name()) } +/** [Convert with][Convert.with] to provide a new value for every selected cell + * giving its row and its previous value. */ +@ExcludeFromSources +private interface SeeAlsoConvertWith + +/** + * Converts values in the columns previously selected with [convert] + * using [row column][RowColumnExpression] [expression] within the [DataFrame]. + * + * A [row column expression][RowColumnExpression] allows to provide a new value for every selected cell + * given its row and column (as lambda arguments). + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ## See Also + * - {@include [SeeAlsoConvertWith]} + * - {@include [SeeAlsoConvertTo]} + * + * ### Example: + * ```kotlin + * // Convert values in all columns to `String` and add their column name to the end + * df.convert { all() }.perRowCol { row, col -> + * row[col].toString() + col.name() + * } + * ``` + * + * @param infer [Infer] strategy that defines how the [type][DataColumn.type] of the resulting column should be determined. + * Defaults to [Infer.Nulls]. + * @param [expression] The [RowColumnExpression] to provide a new value for every selected cell giving its row and column. + */ @Refine @Interpretable("PerRowCol") public inline fun Convert.perRowCol( @@ -136,8 +490,22 @@ public inline fun Convert.perRowCol( noinline expression: RowColumnExpression, ): DataFrame = convertRowColumnImpl(typeOf(), infer, expression) +/** + * Converts values in this column to the specified type [C]. + * + * The target type is provided as a reified type argument. + * + * @param [C] The target type to convert values to. + * @return A new [DataColumn] with the values converted to type [C]. + */ public inline fun AnyCol.convertTo(): DataColumn = convertTo(typeOf()) as DataColumn +/** + * Converts values in this column to the specified [type]. + * + * @param type The target type, provided as a [KType], to convert values to. + * @return A new [DataColumn] with the values converted to [type]. + */ @Suppress("UNCHECKED_CAST") public fun AnyCol.convertTo(newType: KType): AnyCol = when { @@ -147,9 +515,27 @@ public fun AnyCol.convertTo(newType: KType): AnyCol = else -> convertToTypeImpl(newType, null) } +/** + * Converts values in this `String` column to the specified type [C]. + * + * The target type is provided as a reified type argument. + * + * @param [C] The target type to convert values to. + * @param [parserOptions] Optional [ParserOptions] to customize parsing behavior (e.g., locale, null strings). + * @return A new [DataColumn] with the values converted to type [C]. + */ public inline fun DataColumn.convertTo(parserOptions: ParserOptions? = null): DataColumn = convertTo(typeOf(), parserOptions) as DataColumn +/** + * Converts values in this `String` column to the specified [type][newType]. + * + * The target type is provided as a [KType]. + * + * @param [newType] The target type to convert values to. + * @param [parserOptions] Optional [ParserOptions] to customize parsing behavior (e.g., locale, null strings). + * @return A new [DataColumn] with the values converted to [type]. + */ public fun DataColumn.convertTo(newType: KType, parserOptions: ParserOptions? = null): AnyCol = when { newType.isSubtypeOf(typeOf()) -> @@ -162,59 +548,151 @@ public fun DataColumn.convertTo(newType: KType, parserOptions: ParserOp else -> convertToTypeImpl(newType, parserOptions) } +/** + * Converts values in this column to [LocalDateTime]. + * + * @return A new [DataColumn] with the [LocalDateTime] values. + */ @JvmName("convertToLocalDateTimeFromT") public fun DataColumn.convertToLocalDateTime(): DataColumn = convertTo() +/** + * Converts values in this column to [LocalDateTime]. Preserves null values. + * + * @return A new [DataColumn] with the [LocalDateTime] nullable values. + */ public fun DataColumn.convertToLocalDateTime(): DataColumn = convertTo() +/** + * Converts values in this column to [LocalDate]. + * + * @return A new [DataColumn] with the [LocalDate] values. + */ @JvmName("convertToLocalDateFromT") public fun DataColumn.convertToLocalDate(): DataColumn = convertTo() +/** + * Converts values in this column to [LocalDate]. Preserves null values. + * + * @return A new [DataColumn] with the [LocalDate] nullable values. + */ public fun DataColumn.convertToLocalDate(): DataColumn = convertTo() +/** + * Converts values in this column to [LocalTime]. + * + * @return A new [DataColumn] with the [LocalTime] values. + */ @JvmName("convertToLocalTimeFromT") public fun DataColumn.convertToLocalTime(): DataColumn = convertTo() +/** + * Converts values in this column to [LocalTime]. Preserves null values. + * + * @return A new [DataColumn] with the [LocalTime] nullable values. + */ public fun DataColumn.convertToLocalTime(): DataColumn = convertTo() +/** + * Converts values in this column to [Byte]. + * + * @return A new [DataColumn] with the [Byte] values. + */ @JvmName("convertToByteFromT") public fun DataColumn.convertToByte(): DataColumn = convertTo() +/** + * Converts values in this column to [Byte]. Preserves null values. + * + * @return A new [DataColumn] with the [Byte] nullable values. + */ public fun DataColumn.convertToByte(): DataColumn = convertTo() +/** + * Converts values in this column to [Short]. + * + * @return A new [DataColumn] with the [Short] values. + */ @JvmName("convertToShortFromT") public fun DataColumn.convertToShort(): DataColumn = convertTo() +/** + * Converts values in this column to [Short]. Preserves null values. + * + * @return A new [DataColumn] with the [Short] nullable values. + */ public fun DataColumn.convertToShort(): DataColumn = convertTo() +/** + * Converts values in this column to [Int]. + * + * @return A new [DataColumn] with the [Int] values. + */ @JvmName("convertToIntFromT") public fun DataColumn.convertToInt(): DataColumn = convertTo() +/** + * Converts values in this column to [Int]. Preserves null values. + * + * @return A new [DataColumn] with the [Int] nullable values. + */ public fun DataColumn.convertToInt(): DataColumn = convertTo() +/** + * Converts values in this column to [Long]. + * + * @return A new [DataColumn] with the [Long] values. + */ @JvmName("convertToLongFromT") public fun DataColumn.convertToLong(): DataColumn = convertTo() +/** + * Converts values in this column to [Long]. Preserves null values. + * + * @return A new [DataColumn] with the [Long] nullable values. + */ public fun DataColumn.convertToLong(): DataColumn = convertTo() +/** + * Converts values in this column to [String]. + * + * @return A new [DataColumn] with the [String] values. + */ @JvmName("convertToStringFromT") public fun DataColumn.convertToString(): DataColumn = convertTo() +/** + * Converts values in this column to [String]. Preserves null values. + * + * @return A new [DataColumn] with the [String] nullable values. + */ public fun DataColumn.convertToString(): DataColumn = convertTo() +/** + * Converts values in this column to [Double]. + * + * @return A new [DataColumn] with the [Double] values. + */ @JvmName("convertToDoubleFromT") public fun DataColumn.convertToDouble(): DataColumn = convertTo() +/** + * Converts values in this column to [Double]. Preserves null values. + * + * @return A new [DataColumn] with the [Double] nullable values. + */ public fun DataColumn.convertToDouble(): DataColumn = convertTo() /** - * Parses a String column to Double considering locale (number format). + * Converts values in this [String] column to [Double] considering locale (number format). * * If any of the parameters is `null`, the global default (in [DataFrame.parser][DataFrame.Companion.parser]) is used. * * @param locale If defined, its number format is used for parsing. * The default in [DataFrame.parser][DataFrame.Companion.parser] is the system locale. * If the column cannot be parsed, the POSIX format is used. + * + * @return A new [DataColumn] with the [Double] values. */ @ExcludeFromSources private interface DataColumnStringConvertToDoubleDoc @@ -263,28 +741,85 @@ public fun DataColumn.convertToDouble( useFastDoubleParser = useFastDoubleParser, ) +/** + * Converts values in this column to [Float]. + * + * @return A new [DataColumn] with the [Float] values. + */ @JvmName("convertToFloatFromT") public fun DataColumn.convertToFloat(): DataColumn = convertTo() +/** + * Converts values in this column to [Float]. Preserves null values. + * + * @return A new [DataColumn] with the [Float] nullable values. + */ public fun DataColumn.convertToFloat(): DataColumn = convertTo() +/** + * Converts values in this column to [BigDecimal]. + * + * @return A new [DataColumn] with the [BigDecimal] values. + */ @JvmName("convertToBigDecimalFromT") public fun DataColumn.convertToBigDecimal(): DataColumn = convertTo() +/** + * Converts values in this column to [BigDecimal]. Preserves null values. + * + * @return A new [DataColumn] with the [BigDecimal] nullable values. + */ public fun DataColumn.convertToBigDecimal(): DataColumn = convertTo() +/** + * Converts values in this column to [BigInteger]. + * + * @return A new [DataColumn] with the [BigInteger] values. + */ @JvmName("convertToBigIntegerFromT") public fun DataColumn.convertToBigInteger(): DataColumn = convertTo() +/** + * Converts values in this column to [BigInteger]. Preserves null values. + * + * @return A new [DataColumn] with the [BigInteger] nullable values. + */ public fun DataColumn.convertToBigInteger(): DataColumn = convertTo() +/** + * Converts values in this column to [Boolean]. + * + * @return A new [DataColumn] with the [Boolean] values. + */ @JvmName("convertToBooleanFromT") public fun DataColumn.convertToBoolean(): DataColumn = convertTo() +/** + * Converts values in this column to [Boolean]. Preserves null values. + * + * @return A new [DataColumn] with the [Boolean] nullable values. + */ public fun DataColumn.convertToBoolean(): DataColumn = convertTo() // region convert URL +/** + * Converts values in an [URL] columns previously selected with [convert] to an [IFRAME], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { imgUrl }.toIFrame() + * ``` + * + * @param border Whether the iframe should have a border. Defaults to `false`. + * @param width Optional width of the iframe in pixels. + * @param height Optional height of the iframe in pixels. + * @return A new [DataFrame] with the values converted to an [IFRAME]. + */ @JvmName("toIframeFromUrlNullable") @Refine @Converter(IFRAME::class, nullable = true) @@ -295,6 +830,22 @@ public fun Convert.toIFrame( height: Int? = null, ): DataFrame = to { it.map { url -> url?.let { IFRAME(url.toString(), border, width, height) } } } +/** + * Converts values in an [URL] columns previously selected with [convert] to an [IFRAME], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { imgUrl }.toIFrame() + * ``` + * + * @param border Whether the iframe should have a border. Defaults to `false`. + * @param width Optional width of the iframe in pixels. + * @param height Optional height of the iframe in pixels. + * @return A new [DataFrame] with the values converted to an [IFRAME]. + */ @JvmName("toIframeFromUrl") @Refine @Converter(IFRAME::class, nullable = false) @@ -305,6 +856,22 @@ public fun Convert.toIFrame( height: Int? = null, ): DataFrame = to { it.map { IFRAME(it.toString(), border, width, height) } } +/** + * Converts values in an [URL] columns previously selected with [convert] to an [IMG], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { avatarUrl }.toImg() + * ``` + * + * @param width Optional width of the image in pixels. + * @param height Optional height of the image in pixels. + * @return A new [DataFrame] with the values converted to an [IMG]. + */ @JvmName("toImgFromUrlNullable") @Refine @Converter(IMG::class, nullable = true) @@ -312,6 +879,21 @@ public fun Convert.toIFrame( public fun Convert.toImg(width: Int? = null, height: Int? = null): DataFrame = to { it.map { url -> url?.let { IMG(url.toString(), width, height) } } } +/** + * Converts values in an [URL] columns previously selected with [convert] to an [IMG], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { avatarUrl }.toImg() + * ``` + * + * @param width Optional width of the image in pixels. + * @param height Optional height of the image in pixels. + * @return A new [DataFrame] with the values converted to an [IMG]. + */ @JvmName("toImgFromUrl") @Refine @Converter(IMG::class, nullable = false) @@ -323,17 +905,54 @@ public fun Convert.toImg(width: Int? = null, height: Int? // region toURL +/** + * Converts values in this [String] column to an [URL]. + * + * @return A new [DataColumn] with an [URL] values. + */ public fun DataColumn.convertToURL(): DataColumn = map { URL(it) } +/** + * Converts values in this [String] column to an [URL]. Preserves null values. + * + * @return A new [DataColumn] with an [URL] nullable values. + */ @JvmName("convertToURLFromStringNullable") public fun DataColumn.convertToURL(): DataColumn = map { it?.let { URL(it) } } +/** + * Converts values in the [String] columns previously selected with [convert] to an [URL], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { webAddress }.toURL() + * ``` + * + * @return A new [DataFrame] with the values converted to an [URL]. + */ @JvmName("toUrlFromStringNullable") @Refine @Converter(URL::class, nullable = true) @Interpretable("ToSpecificType") public fun Convert.toURL(): DataFrame = to { it.convertToURL() } +/** + * Converts values in the [String] columns previously selected with [convert] to an [URL], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { webAddress }.toURL() + * ``` + * + * @return A new [DataFrame] with the values converted to an [URL]. + */ @JvmName("toUrlFromString") @Refine @Converter(URL::class, nullable = false) @@ -344,17 +963,54 @@ public fun Convert.toURL(): DataFrame = to { it.convertToURL() // region toInstant +/** + * Converts values in this [String] column to [Instant]. + * + * @return A new [DataColumn] with the [Instant] values. + */ public fun DataColumn.convertToInstant(): DataColumn = map { Instant.parse(it) } +/** + * Converts values in this [String] column to [Instant]. Preserves null values. + * + * @return A new [DataColumn] with the [Instant] nullable values. + */ @JvmName("convertToInstantFromStringNullable") public fun DataColumn.convertToInstant(): DataColumn = map { it?.let { Instant.parse(it) } } +/** + * Converts values in the [String] columns previously selected with [convert] to the [Instant], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toInstant() + * ``` + * + * @return A new [DataFrame] with the values converted to [Instant]. + */ @JvmName("toInstantFromStringNullable") @Refine @Converter(Instant::class, nullable = true) @Interpretable("ToSpecificType") public fun Convert.toInstant(): DataFrame = to { it.convertToInstant() } +/** + * Converts values in the [String] columns previously selected with [convert] to the [Instant], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toInstant() + * ``` + * + * @return A new [DataFrame] with the values converted to [Instant]. + */ @JvmName("toInstantFromString") @Refine @Converter(Instant::class, nullable = false) @@ -365,21 +1021,55 @@ public fun Convert.toInstant(): DataFrame = to { it.convertToI // region toLocalDate +/** + * Converts values in this [Long] column to [LocalDate]. + * + * @param zone The [TimeZone] used to interpret the [Long] timestamp as a date. Defaults to the system current time zone. + * @return A new [DataColumn] with the [LocalDate] values. + */ @JvmName("convertToLocalDateFromLong") public fun DataColumn.convertToLocalDate(zone: TimeZone = defaultTimeZone): DataColumn = map { it.toLocalDate(zone) } +/** + * Converts values in this [Long] column to [LocalDate]. Preserves null values. + * + * @param zone The [TimeZone] used to interpret the [Long] timestamp as a date. Defaults to the system current time zone. + * @return A new [DataColumn] with the [LocalDate] nullable values. + */ public fun DataColumn.convertToLocalDate(zone: TimeZone = defaultTimeZone): DataColumn = map { it?.toLocalDate(zone) } +/** + * Converts values in this [Int] column to [LocalDate]. + * + * @param zone The [TimeZone] used to interpret the [Int] timestamp as a date. Defaults to the system current time zone. + * @return A new [DataColumn] with the [LocalDate] values. + */ @JvmName("convertToLocalDateFromInt") public fun DataColumn.convertToLocalDate(zone: TimeZone = defaultTimeZone): DataColumn = map { it.toLong().toLocalDate(zone) } +/** + * Converts values in this [Int] column to [LocalDate]. Preserves null values. + * + * @param zone The [TimeZone] used to interpret the [Int] timestamp as a date. Defaults to the system current time zone. + * @return A new [DataColumn] with the [LocalDate] nullable values. + */ @JvmName("convertToLocalDateFromIntNullable") public fun DataColumn.convertToLocalDate(zone: TimeZone = defaultTimeZone): DataColumn = map { it?.toLong()?.toLocalDate(zone) } +/** + * Converts values in this [String] column to [LocalDate]. + * + * Trims each string and attempts to parse it using the specified [pattern] and [locale]. + * Fails with an exception if a value cannot be parsed. + * + * @param pattern An optional date pattern to use for parsing. If `null`, a default parser is used. + * @param locale An optional [Locale] to interpret the date pattern. If `null`, the system locale is used. + * @return A new [DataColumn] with the [LocalDate] values. + */ @JvmName("convertToLocalDateFromString") public fun DataColumn.convertToLocalDate( pattern: String? = null, @@ -389,6 +1079,17 @@ public fun DataColumn.convertToLocalDate( return map { converter(it.trim()) ?: error("Can't convert `$it` to LocalDate") } } +/** + * Converts values in this [String] column to [LocalDate]. + * Preserves null values. + * + * Trims each string and attempts to parse it using the specified [pattern] and [locale]. + * Fails with an exception if a value cannot be parsed. + * + * @param pattern An optional date pattern to use for parsing. If `null`, a default parser is used. + * @param locale An optional [Locale] to interpret the date pattern. If `null`, the system locale is used. + * @return A new [DataColumn] with the [LocalDate] nullable values. + */ @JvmName("convertToLocalDateFromStringNullable") public fun DataColumn.convertToLocalDate( pattern: String? = null, @@ -398,6 +1099,21 @@ public fun DataColumn.convertToLocalDate( return map { it?.let { converter(it.trim()) ?: error("Can't convert `$it` to LocalDate") } } } +/** + * Converts values in the [Long] columns previously selected with [convert] to the [LocalDate], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalDate() + * ``` + * + * @param zone The [TimeZone] used to interpret the [Long] timestamp as a date. Defaults to the system current time zone. + * @return A new [DataFrame] with the values converted to [LocalDate]. + */ @JvmName("toLocalDateFromTLongNullable") @Refine @Converter(LocalDate::class, nullable = true) @@ -405,6 +1121,20 @@ public fun DataColumn.convertToLocalDate( public fun Convert.toLocalDate(zone: TimeZone = defaultTimeZone): DataFrame = to { it.convertToLocalDate(zone) } +/** + * Converts values in the [Long] columns previously selected with [convert] to the [LocalDate], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalDate() + * ``` + * + * @param zone The [TimeZone] used to interpret the [Long] timestamp as a date. Defaults to the system current time zone. + * @return A new [DataFrame] with the values converted to [LocalDate]. + */ @JvmName("toLocalDateFromTLong") @Refine @Converter(LocalDate::class, nullable = false) @@ -412,6 +1142,21 @@ public fun Convert.toLocalDate(zone: TimeZone = defaultTimeZone): public fun Convert.toLocalDate(zone: TimeZone = defaultTimeZone): DataFrame = to { it.convertToLocalDate(zone) } +/** + * Converts values in the [Int] columns previously selected with [convert] to the [LocalDate], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalDate() + * ``` + * + * @param zone The [TimeZone] used to interpret the [Int] timestamp as a date. Defaults to the system current time zone. + * @return A new [DataFrame] with the values converted to [LocalDate]. + */ @JvmName("toLocalDateFromTInt") @Refine @Converter(LocalDate::class, nullable = true) @@ -419,6 +1164,20 @@ public fun Convert.toLocalDate(zone: TimeZone = defaultTimeZone): D public fun Convert.toLocalDate(zone: TimeZone = defaultTimeZone): DataFrame = to { it.convertToLocalDate(zone) } +/** + * Converts values in the [Int] columns previously selected with [convert] to the [LocalDate], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalDate() + * ``` + * + * @param zone The [TimeZone] used to interpret the [Int] timestamp as a date. Defaults to the system current time zone. + * @return A new [DataFrame] with the values converted to [LocalDate]. + */ @JvmName("toLocalDateFromTIntNullable") @Refine @Converter(LocalDate::class, nullable = false) @@ -426,6 +1185,25 @@ public fun Convert.toLocalDate(zone: TimeZone = defaultTimeZone): D public fun Convert.toLocalDate(zone: TimeZone = defaultTimeZone): DataFrame = to { it.convertToLocalDate(zone) } +/** + * Converts values in the [String] columns previously selected with [convert] to the [LocalDate], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * Trims each string and attempts to parse it using the specified [pattern] and [locale]. + * Fails with an exception if a value cannot be parsed. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalDate() + * ``` + * + * @param pattern An optional date pattern to use for parsing. If `null`, a default parser is used. + * @param locale An optional [Locale] to interpret the date pattern. If `null`, the system locale is used. + * @return A new [DataFrame] with the values converted to [LocalDate]. + */ @JvmName("toLocalDateFromStringNullable") @Refine @Converter(LocalDate::class, nullable = true) @@ -433,6 +1211,24 @@ public fun Convert.toLocalDate(zone: TimeZone = defaultTimeZone): Da public fun Convert.toLocalDate(pattern: String? = null, locale: Locale? = null): DataFrame = to { it.convertToLocalDate(pattern, locale) } +/** + * Converts values in the [String] columns previously selected with [convert] to the [LocalDate], + * preserving their original names and positions within the [DataFrame]. + * + * Trims each string and attempts to parse it using the specified [pattern] and [locale]. + * Fails with an exception if a value cannot be parsed. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalDate() + * ``` + * + * @param pattern An optional date pattern to use for parsing. If `null`, a default parser is used. + * @param locale An optional [Locale] to interpret the date pattern. If `null`, the system locale is used. + * @return A new [DataFrame] with the values converted to [LocalDate]. + */ @JvmName("toLocalDateFromString") @Refine @Converter(LocalDate::class, nullable = false) @@ -440,6 +1236,19 @@ public fun Convert.toLocalDate(pattern: String? = null, locale: public fun Convert.toLocalDate(pattern: String? = null, locale: Locale? = null): DataFrame = to { it.convertToLocalDate(pattern, locale) } +/** + * Converts values in the columns previously selected with [convert] to the [LocalDate], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalDate() + * ``` + * + * @return A new [DataFrame] with the values converted to [LocalDate]. + */ @Refine @Converter(LocalDate::class, nullable = false) @Interpretable("ToSpecificType") @@ -449,21 +1258,55 @@ public fun Convert.toLocalDate(): DataFrame = to { it.convertTo.convertToLocalTime(zone: TimeZone = defaultTimeZone): DataColumn = map { it.toLocalTime(zone) } +/** + * Converts values in this [Long] column to [LocalTime]. Preserves null values. + * + * @param zone The [TimeZone] used to interpret the [Long] timestamp as a time. Defaults to the system current time zone. + * @return A new [DataColumn] with the [LocalTime] nullable values. + */ public fun DataColumn.convertToLocalTime(zone: TimeZone = defaultTimeZone): DataColumn = map { it?.toLocalTime(zone) } +/** + * Converts values in this [Int] column to [LocalTime]. + * + * @param zone The [TimeZone] used to interpret the [Int] timestamp as a time. Defaults to the system current time zone. + * @return A new [DataColumn] with the [LocalTime] values. + */ @JvmName("convertToLocalTimeFromInt") public fun DataColumn.convertToLocalTime(zone: TimeZone = defaultTimeZone): DataColumn = map { it.toLong().toLocalTime(zone) } +/** + * Converts values in this [Int] column to [LocalTime]. Preserves null values. + * + * @param zone The [TimeZone] used to interpret the [Int] timestamp as a time. Defaults to the system current time zone. + * @return A new [DataColumn] with the [LocalTime] nullable values. + */ @JvmName("convertToLocalTimeIntNullable") public fun DataColumn.convertToLocalTime(zone: TimeZone = defaultTimeZone): DataColumn = map { it?.toLong()?.toLocalTime(zone) } +/** + * Converts values in this [String] column to [LocalTime]. + * + * Trims each string and attempts to parse it using the specified [pattern] and [locale]. + * Fails with an exception if a value cannot be parsed. + * + * @param pattern An optional date pattern to use for parsing. If `null`, a default parser is used. + * @param locale An optional [Locale] to interpret the date pattern. If `null`, the system locale is used. + * @return A new [DataColumn] with the [LocalTime] values. + */ @JvmName("convertToLocalTimeFromString") public fun DataColumn.convertToLocalTime( pattern: String? = null, @@ -473,6 +1316,17 @@ public fun DataColumn.convertToLocalTime( return map { converter(it.trim()) ?: error("Can't convert `$it` to LocalTime") } } +/** + * Converts values in this [String] column to [LocalTime]. + * Preserves null values. + * + * Trims each string and attempts to parse it using the specified [pattern] and [locale]. + * Fails with an exception if a value cannot be parsed. + * + * @param pattern An optional date pattern to use for parsing. If `null`, a default parser is used. + * @param locale An optional [Locale] to interpret the date pattern. If `null`, the system locale is used. + * @return A new [DataColumn] with the [LocalTime] nullable values. + */ @JvmName("convertToLocalTimeFromStringNullable") public fun DataColumn.convertToLocalTime( pattern: String? = null, @@ -482,6 +1336,21 @@ public fun DataColumn.convertToLocalTime( return map { it?.let { converter(it.trim()) ?: error("Can't convert `$it` to LocalTime") } } } +/** + * Converts values in the [Long] columns previously selected with [convert] to the [LocalDate], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalTime() + * ``` + * + * @param zone The [TimeZone] used to interpret the [Long] timestamp as a time. Defaults to the system current time zone. + * @return A new [DataFrame] with the values converted to [LocalTime]. + */ @JvmName("toLocalTimeFromTLongNullable") @Refine @Converter(LocalTime::class, nullable = true) @@ -489,6 +1358,20 @@ public fun DataColumn.convertToLocalTime( public fun Convert.toLocalTime(zone: TimeZone = defaultTimeZone): DataFrame = to { it.convertToLocalTime(zone) } +/** + * Converts values in the [Long] columns previously selected with [convert] to the [LocalDate], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalTime() + * ``` + * + * @param zone The [TimeZone] used to interpret the [Long] timestamp as a time. Defaults to the system current time zone. + * @return A new [DataFrame] with the values converted to [LocalTime]. + */ @JvmName("toLocalTimeFromTLong") @Refine @Converter(LocalTime::class, nullable = false) @@ -496,6 +1379,21 @@ public fun Convert.toLocalTime(zone: TimeZone = defaultTimeZone): public fun Convert.toLocalTime(zone: TimeZone = defaultTimeZone): DataFrame = to { it.convertToLocalTime(zone) } +/** + * Converts values in the [Int] columns previously selected with [convert] to the [LocalDate], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalTime() + * ``` + * + * @param zone The [TimeZone] used to interpret the [Int] timestamp as a time. Defaults to the system current time zone. + * @return A new [DataFrame] with the values converted to [LocalTime]. + */ @JvmName("toLocalTimeFromTIntNullable") @Refine @Converter(LocalTime::class, nullable = true) @@ -503,6 +1401,20 @@ public fun Convert.toLocalTime(zone: TimeZone = defaultTimeZone): D public fun Convert.toLocalTime(zone: TimeZone = defaultTimeZone): DataFrame = to { it.convertToLocalTime(zone) } +/** + * Converts values in the [Int] columns previously selected with [convert] to the [LocalDate], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalTime() + * ``` + * + * @param zone The [TimeZone] used to interpret the [Int] timestamp as a time. Defaults to the system current time zone. + * @return A new [DataFrame] with the values converted to [LocalTime]. + */ @JvmName("toLocalTimeFromTInt") @Refine @Converter(LocalTime::class, nullable = false) @@ -510,6 +1422,25 @@ public fun Convert.toLocalTime(zone: TimeZone = defaultTimeZone): D public fun Convert.toLocalTime(zone: TimeZone = defaultTimeZone): DataFrame = to { it.convertToLocalTime(zone) } +/** + * Converts values in the [String] columns previously selected with [convert] to the [LocalTime], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * Trims each string and attempts to parse it using the specified [pattern] and [locale]. + * Fails with an exception if a value cannot be parsed. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalTime() + * ``` + * + * @param pattern An optional date pattern to use for parsing. If `null`, a default parser is used. + * @param locale An optional [Locale] to interpret the date pattern. If `null`, the system locale is used. + * @return A new [DataFrame] with the values converted to [LocalTime]. + */ @JvmName("toLocalTimeFromStringNullable") @Refine @Converter(LocalTime::class, nullable = true) @@ -517,6 +1448,24 @@ public fun Convert.toLocalTime(zone: TimeZone = defaultTimeZone): Da public fun Convert.toLocalTime(pattern: String? = null, locale: Locale? = null): DataFrame = to { it.convertToLocalTime(pattern, locale) } +/** + * Converts values in the [String] columns previously selected with [convert] to the [LocalTime], + * preserving their original names and positions within the [DataFrame]. + * + * Trims each string and attempts to parse it using the specified [pattern] and [locale]. + * Fails with an exception if a value cannot be parsed. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalTime() + * ``` + * + * @param pattern An optional date pattern to use for parsing. If `null`, a default parser is used. + * @param locale An optional [Locale] to interpret the date pattern. If `null`, the system locale is used. + * @return A new [DataFrame] with the values converted to [LocalTime]. + */ @JvmName("toLocalTimeFromString") @Refine @Converter(LocalTime::class, nullable = false) @@ -524,6 +1473,19 @@ public fun Convert.toLocalTime(pattern: String? = null, locale: public fun Convert.toLocalTime(pattern: String? = null, locale: Locale? = null): DataFrame = to { it.convertToLocalTime(pattern, locale) } +/** + * Converts values in the columns previously selected with [convert] to the [LocalTime], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalTime() + * ``` + * + * @return A new [DataFrame] with the values converted to [LocalTime]. + */ @Refine @Converter(LocalTime::class, nullable = false) @Interpretable("ToSpecificType") @@ -533,29 +1495,81 @@ public fun Convert.toLocalTime(): DataFrame = to { it.convertTo.convertToLocalDateTime(zone: TimeZone = defaultTimeZone): DataColumn = map { it.toLocalDateTime(zone) } +/** + * Converts values in this [Long] column to [LocalDateTime]. Preserves null values. + * + * @param zone The [TimeZone] used to interpret the [Long] timestamp as a date-time. + * Defaults to the system current time zone. + * @return A new [DataColumn] with the [LocalDateTime] nullable values. + */ public fun DataColumn.convertToLocalDateTime(zone: TimeZone = defaultTimeZone): DataColumn = map { it?.toLocalDateTime(zone) } +/** + * Converts values in this [Instant] column to [LocalDateTime]. + * + * @param zone The [TimeZone] used to interpret the [Instant] timestamp as a date-time. + * Defaults to the system current time zone. + * @return A new [DataColumn] with the [LocalDateTime] values. + */ @JvmName("convertToLocalDateTimeFromInstant") public fun DataColumn.convertToLocalDateTime(zone: TimeZone = defaultTimeZone): DataColumn = map { it.toLocalDateTime(zone) } +/** + * Converts values in this [Instant] column to [LocalDateTime]. Preserves null values. + * + * @param zone The [TimeZone] used to interpret the [Instant] timestamp as a date-time. + * Defaults to the system current time zone. + * @return A new [DataColumn] with the [LocalDateTime] nullable values. + */ @JvmName("convertToLocalDateTimeFromInstantNullable") public fun DataColumn.convertToLocalDateTime(zone: TimeZone = defaultTimeZone): DataColumn = map { it?.toLocalDateTime(zone) } +/** + * Converts values in this [Int] column to [LocalDateTime]. + * + * @param zone The [TimeZone] used to interpret the [Int] timestamp as a date-time. + * Defaults to the system current time zone. + * @return A new [DataColumn] with the [LocalDateTime] values. + */ @JvmName("convertToLocalDateTimeFromInt") public fun DataColumn.convertToLocalDateTime(zone: TimeZone = defaultTimeZone): DataColumn = map { it.toLong().toLocalDateTime(zone) } +/** + * Converts values in this [Int] column to [LocalDateTime]. Preserves null values. + * + * @param zone The [TimeZone] used to interpret the [Int] timestamp as a date-time. + * Defaults to the system current time zone. + * @return A new [DataColumn] with the [LocalDateTime] nullable values. + */ @JvmName("convertToLocalDateTimeFromIntNullable") public fun DataColumn.convertToLocalDateTime(zone: TimeZone = defaultTimeZone): DataColumn = map { it?.toLong()?.toLocalDateTime(zone) } +/** + * Converts values in this [String] column to [LocalDateTime]. + * + * Trims each string and attempts to parse it using the specified [pattern] and [locale]. + * Fails with an exception if a value cannot be parsed. + * + * @param pattern An optional date pattern to use for parsing. If `null`, a default parser is used. + * @param locale An optional [Locale] to interpret the date pattern. If `null`, the system locale is used. + * @return A new [DataColumn] with the [LocalDateTime] values. + */ @JvmName("convertToLocalDateTimeFromString") public fun DataColumn.convertToLocalDateTime( pattern: String? = null, @@ -565,6 +1579,17 @@ public fun DataColumn.convertToLocalDateTime( return map { converter(it.trim()) ?: error("Can't convert `$it` to LocalDateTime") } } +/** + * Converts values in this [String] column to [LocalDateTime]. + * Preserves null values. + * + * Trims each string and attempts to parse it using the specified [pattern] and [locale]. + * Fails with an exception if a value cannot be parsed. + * + * @param pattern An optional date pattern to use for parsing. If `null`, a default parser is used. + * @param locale An optional [Locale] to interpret the date pattern. If `null`, the system locale is used. + * @return A new [DataColumn] with the [LocalDateTime] nullable values. + */ @JvmName("convertToLocalDateTimeFromStringNullable") public fun DataColumn.convertToLocalDateTime( pattern: String? = null, @@ -574,6 +1599,21 @@ public fun DataColumn.convertToLocalDateTime( return map { it?.let { converter(it.trim()) ?: error("Can't convert `$it` to LocalDateTime") } } } +/** + * Converts values in the [Long] columns previously selected with [convert] to the [LocalDateTime], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalDateTime() + * ``` + * + * @param zone The [TimeZone] used to interpret the [Long] timestamp as a time. Defaults to the system current time zone. + * @return A new [DataFrame] with the values converted to [LocalDateTime]. + */ @JvmName("toLocalDateTimeFromTLongNullable") @Refine @Converter(LocalDateTime::class, nullable = true) @@ -581,6 +1621,20 @@ public fun DataColumn.convertToLocalDateTime( public fun Convert.toLocalDateTime(zone: TimeZone = defaultTimeZone): DataFrame = to { it.convertToLocalDateTime(zone) } +/** + * Converts values in the [Long] columns previously selected with [convert] to the [LocalDateTime], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalDateTime() + * ``` + * + * @param zone The [TimeZone] used to interpret the [Long] timestamp as a time. Defaults to the system current time zone. + * @return A new [DataFrame] with the values converted to [LocalDateTime]. + */ @JvmName("toLocalDateTimeFromTLong") @Refine @Converter(LocalDateTime::class, nullable = false) @@ -588,6 +1642,21 @@ public fun Convert.toLocalDateTime(zone: TimeZone = defaultTimeZon public fun Convert.toLocalDateTime(zone: TimeZone = defaultTimeZone): DataFrame = to { it.convertToLocalDateTime(zone) } +/** + * Converts values in the [Instant] columns previously selected with [convert] to the [LocalDateTime], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalDateTime() + * ``` + * + * @param zone The [TimeZone] used to interpret the [Instant] timestamp as a time. Defaults to the system current time zone. + * @return A new [DataFrame] with the values converted to [LocalDateTime]. + */ @JvmName("toLocalDateTimeFromTInstantNullable") @Refine @Converter(LocalDateTime::class, nullable = true) @@ -595,6 +1664,20 @@ public fun Convert.toLocalDateTime(zone: TimeZone = defaultTimeZone public fun Convert.toLocalDateTime(zone: TimeZone = defaultTimeZone): DataFrame = to { it.convertToLocalDateTime(zone) } +/** + * Converts values in the [Instant] columns previously selected with [convert] to the [LocalDateTime], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalDateTime() + * ``` + * + * @param zone The [TimeZone] used to interpret the [Instant] timestamp as a time. Defaults to the system current time zone. + * @return A new [DataFrame] with the values converted to [LocalDateTime]. + */ @JvmName("toLocalDateTimeFromTInstant") @Refine @Converter(LocalDateTime::class, nullable = false) @@ -602,6 +1685,21 @@ public fun Convert.toLocalDateTime(zone: TimeZone = defaultTime public fun Convert.toLocalDateTime(zone: TimeZone = defaultTimeZone): DataFrame = to { it.convertToLocalDateTime(zone) } +/** + * Converts values in the [Int] columns previously selected with [convert] to the [LocalDateTime], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalDateTime() + * ``` + * + * @param zone The [TimeZone] used to interpret the [Int] timestamp as a time. Defaults to the system current time zone. + * @return A new [DataFrame] with the values converted to [LocalDateTime]. + */ @JvmName("toLocalDateTimeFromTIntNullable") @Refine @Converter(LocalDateTime::class, nullable = true) @@ -609,6 +1707,20 @@ public fun Convert.toLocalDateTime(zone: TimeZone = defaultTimeZ public fun Convert.toLocalDateTime(zone: TimeZone = defaultTimeZone): DataFrame = to { it.convertToLocalDateTime(zone) } +/** + * Converts values in the [Int] columns previously selected with [convert] to the [LocalDateTime], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalDateTime() + * ``` + * + * @param zone The [TimeZone] used to interpret the [Int] timestamp as a time. Defaults to the system current time zone. + * @return A new [DataFrame] with the values converted to [LocalDateTime]. + */ @JvmName("toLocalDateTimeFromTInt") @Refine @Converter(LocalDateTime::class, nullable = false) @@ -616,6 +1728,25 @@ public fun Convert.toLocalDateTime(zone: TimeZone = defaultTimeZone public fun Convert.toLocalDateTime(zone: TimeZone = defaultTimeZone): DataFrame = to { it.convertToLocalDateTime(zone) } +/** + * Converts values in the [String] columns previously selected with [convert] to the [LocalDateTime], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * Trims each string and attempts to parse it using the specified [pattern] and [locale]. + * Fails with an exception if a value cannot be parsed. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalTime() + * ``` + * + * @param pattern An optional date pattern to use for parsing. If `null`, a default parser is used. + * @param locale An optional [Locale] to interpret the date-time pattern. If `null`, the system locale is used. + * @return A new [DataFrame] with the values converted to [LocalDateTime]. + */ @JvmName("toLocalDateTimeFromStringNullable") @Refine @Converter(LocalDateTime::class, nullable = true) @@ -623,6 +1754,24 @@ public fun Convert.toLocalDateTime(zone: TimeZone = defaultTimeZone) public fun Convert.toLocalDateTime(pattern: String? = null, locale: Locale? = null): DataFrame = to { it.convertToLocalDateTime(pattern, locale) } +/** + * Converts values in the [String] columns previously selected with [convert] to the [LocalDateTime], + * preserving their original names and positions within the [DataFrame]. + * + * Trims each string and attempts to parse it using the specified [pattern] and [locale]. + * Fails with an exception if a value cannot be parsed. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalTime() + * ``` + * + * @param pattern An optional date pattern to use for parsing. If `null`, a default parser is used. + * @param locale An optional [Locale] to interpret the date-time pattern. If `null`, the system locale is used. + * @return A new [DataFrame] with the values converted to [LocalDateTime]. + */ @JvmName("toLocalDateTimeFromString") @Refine @Converter(LocalDateTime::class, nullable = false) @@ -630,6 +1779,19 @@ public fun Convert.toLocalDateTime(pattern: String? = null, loca public fun Convert.toLocalDateTime(pattern: String? = null, locale: Locale? = null): DataFrame = to { it.convertToLocalDateTime(pattern, locale) } +/** + * Converts values in the columns previously selected with [convert] to the [LocalDateTime], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { timestamp }.toLocalTime() + * ``` + * + * @return A new [DataFrame] with the values converted to [LocalDateTime]. + */ @Refine @Converter(LocalDateTime::class, nullable = false) @Interpretable("ToSpecificType") @@ -637,96 +1799,361 @@ public fun Convert.toLocalDateTime(): DataFrame = to { it.convertTo // endregion +/** + * Converts values in the columns previously selected with [convert] to the [Int], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { age and year }.toInt() + * df.convert { colsOf() }.toInt() + * ``` + * + * @return A new [DataFrame] with the values converted to [Int]. + */ @JvmName("toIntTAny") @Refine @Converter(Int::class, nullable = false) @Interpretable("ToSpecificType") public fun Convert.toInt(): DataFrame = to() +/** + * Converts values in the columns previously selected with [convert] to the [Int], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { age and year }.toInt() + * df.convert { colsOf() }.toInt() + * ``` + * + * @return A new [DataFrame] with the values converted to [Int]. + */ @Refine @Converter(Int::class, nullable = true) @Interpretable("ToSpecificType") public fun Convert.toInt(): DataFrame = to() +/** + * Converts values in the columns previously selected with [convert] to the [Long], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { age and year }.toLong() + * df.convert { colsOf() }.toLong() + * ``` + * + * @return A new [DataFrame] with the values converted to [Long]. + */ @JvmName("toLongTAny") @Refine @Converter(Long::class, nullable = false) @Interpretable("ToSpecificType") public fun Convert.toLong(): DataFrame = to() +/** + * Converts values in the columns previously selected with [convert] to the [Long], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { age and year }.toLong() + * df.convert { colsOf() }.toLong() + * ``` + * + * @return A new [DataFrame] with the values converted to [Long]. + */ @Refine @Converter(Long::class, nullable = true) @Interpretable("ToSpecificType") public fun Convert.toLong(): DataFrame = to() +/** + * Converts values in the columns previously selected with [convert] to the [String], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { age and year }.toStr() + * df.convert { colsOf() }.toStr() + * ``` + * + * @return A new [DataFrame] with the values converted to [String]. + */ @JvmName("toStrTAny") @Refine @Converter(String::class, nullable = false) @Interpretable("ToSpecificType") public fun Convert.toStr(): DataFrame = to() +/** + * Converts values in the columns previously selected with [convert] to the [String], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { age and year }.toStr() + * df.convert { colsOf() }.toStr() + * ``` + * + * @return A new [DataFrame] with the values converted to [String]. + */ @Refine @Converter(String::class, nullable = true) @Interpretable("ToSpecificType") public fun Convert.toStr(): DataFrame = to() +/** + * Converts values in the columns previously selected with [convert] to the [Double], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { age and year }.toDouble() + * df.convert { colsOf() }.toDouble() + * ``` + * + * @return A new [DataFrame] with the values converted to [Double]. + */ @JvmName("toDoubleTAny") @Refine @Converter(Double::class, nullable = false) @Interpretable("ToSpecificType") public fun Convert.toDouble(): DataFrame = to() +/** + * Converts values in the columns previously selected with [convert] to the [Double], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { age and year }.toDouble() + * df.convert { colsOf() }.toDouble() + * ``` + * + * @return A new [DataFrame] with the values converted to [Double]. + */ @Refine @Converter(Double::class, nullable = true) @Interpretable("ToSpecificType") public fun Convert.toDouble(): DataFrame = to() +/** + * Converts values in the columns previously selected with [convert] to the [Float], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { age and year }.toFloat() + * df.convert { colsOf() }.toFloat() + * ``` + * + * @return A new [DataFrame] with the values converted to [Float]. + */ @JvmName("toFloatTAny") @Refine @Converter(Float::class, nullable = false) @Interpretable("ToSpecificType") public fun Convert.toFloat(): DataFrame = to() +/** + * Converts values in the columns previously selected with [convert] to the [Float], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { age and year }.toFloat() + * df.convert { colsOf() }.toFloat() + * ``` + * + * @return A new [DataFrame] with the values converted to [Float]. + */ @Refine @Converter(Float::class, nullable = true) @Interpretable("ToSpecificType") public fun Convert.toFloat(): DataFrame = to() +/** + * Converts values in the columns previously selected with [convert] to the [BigDecimal], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { age and year }.toBigDecimal() + * df.convert { colsOf() }.toBigDecimal() + * ``` + * + * @return A new [DataFrame] with the values converted to [BigDecimal]. + */ @JvmName("toBigDecimalTAny") @Refine @Converter(BigDecimal::class, nullable = false) @Interpretable("ToSpecificType") public fun Convert.toBigDecimal(): DataFrame = to() +/** + * Converts values in the columns previously selected with [convert] to the [BigDecimal], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { age and year }.toBigDecimal() + * df.convert { colsOf() }.toBigDecimal() + * ``` + * + * @return A new [DataFrame] with the values converted to [BigDecimal]. + */ @Refine @Converter(BigDecimal::class, nullable = true) @Interpretable("ToSpecificType") public fun Convert.toBigDecimal(): DataFrame = to() +/** + * Converts values in the columns previously selected with [convert] to the [BigInteger], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { age and year }.toBigInteger() + * df.convert { colsOf() }.toBigInteger() + * ``` + * + * @return A new [DataFrame] with the values converted to [BigInteger]. + */ @JvmName("toBigIntegerTAny") @Refine @Converter(BigInteger::class, nullable = false) @Interpretable("ToSpecificType") public fun Convert.toBigInteger(): DataFrame = to() +/** + * Converts values in the columns previously selected with [convert] to the [BigInteger], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { age and year }.toBigInteger() + * df.convert { colsOf() }.toBigInteger() + * ``` + * + * @return A new [DataFrame] with the values converted to [BigInteger]. + */ @Refine @Converter(BigInteger::class, nullable = true) @Interpretable("ToSpecificType") public fun Convert.toBigInteger(): DataFrame = to() +/** + * Converts values in the columns previously selected with [convert] to the [Boolean], + * preserving their original names and positions within the [DataFrame]. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { isMarked and isFinished }.toBoolean() + * df.convert { colsOf { it.name.startsWith("it") } }.toBoolean() + * ``` + * + * @return A new [DataFrame] with the values converted to [Boolean]. + */ @JvmName("toBooleanTAny") @Refine @Converter(Boolean::class, nullable = false) @Interpretable("ToSpecificType") public fun Convert.toBoolean(): DataFrame = to() +/** + * Converts values in the columns previously selected with [convert] to the [Boolean], + * preserving their original names and positions within the [DataFrame]. + * Preserves null values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { isMarked and isFinished }.toBoolean() + * df.convert { colsOf { it.name.startsWith("it") } }.toBoolean() + * ``` + * + * @return A new [DataFrame] with the values converted to [Boolean]. + */ @Refine @Converter(Boolean::class, nullable = true) @Interpretable("ToSpecificType") public fun Convert.toBoolean(): DataFrame = to() +/** + * Converts a list of lists values in the columns previously selected with [convert] to the [DataFrame], + * preserving their original names and positions within the [DataFrame]. + * + * By default, treats the first inner list as a header (column names), and the remaining lists as rows. + * If [containsColumns] is `true`, interprets each inner list as a column, + * where the first element is used as the column name, and the remaining elements as values. + * + * For more information: {@include [DocumentationUrls.Convert]} + * + * ### Examples: + * ```kotlin + * df.convert { userData }.toDataFrames() + * df.convert { colsOf>>() }.toDataFrames(containsColumns = true) + * ``` + * + * @param containsColumns If `true`, treats each nested list as a column with its first element as the column name. + * Otherwise, the first list is treated as the header. + * Defaults to `false`. + * @return A new [DataFrame] with the values converted to [DataFrame]. + */ public fun Convert>>.toDataFrames(containsColumns: Boolean = false): DataFrame = to { it.toDataFrames(containsColumns) } +/** + * Converts a list of lists values in this [DataColumn] to the [DataFrame]. + * + * By default, treats the first inner list as a header (column names), and the remaining lists as rows. + * If [containsColumns] is `true`, interprets each inner list as a column, + * where the first element is used as the column name, and the remaining elements as values. + * + * @param containsColumns If `true`, treats each nested list as a column with its first element as the column name. + * Otherwise, the first list is treated as the header. + * Defaults to `false`. + * @return A new [DataColumn] with the values converted to [DataFrame]. + */ public fun DataColumn>>.toDataFrames(containsColumns: Boolean = false): DataColumn = map { it.toDataFrame(containsColumns) } diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/group.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/group.kt index cf2c082039..645e1a00fa 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/group.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/group.kt @@ -185,7 +185,7 @@ public fun GroupClause.into(column: ColumnsSelectionDsl.(ColumnW * * For more information: {@include [DocumentationUrls.Group]} * - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.Dsl] * * ### Examples: * ```kotlin diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt index 4563b7728e..0e2e52a5e5 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt @@ -255,8 +255,8 @@ public fun Update.at(rowRange: IntRange): Update = where { in * {@set [ExpressionsGivenRowAndColumn.OPERATION] [update][update]` { age \}.`[perRowCol][perRowCol]} * * ## See Also - * - {@include [SeeAlsoWith]} - * - {@include [SeeAlsoPerCol]} + * - {@include [SeeAlsoUpdateWith]} + * - {@include [SeeAlsoUpdatePerCol]} * @param [expression] The {@include [ExpressionsGivenRowAndColumn.RowColumnExpressionLink]} to provide a new value for every selected cell giving its row and column. */ public inline fun Update.perRowCol(crossinline expression: RowColumnExpression): DataFrame = @@ -264,7 +264,7 @@ public inline fun Update.perRowCol(crossinline expression: RowColum /** [Update per row col][Update.perRowCol] to provide a new value for every selected cell giving its row and column. */ @ExcludeFromSources -private interface SeeAlsoPerRowCol +private interface SeeAlsoUpdatePerRowCol /** * ## Update Expression @@ -280,8 +280,8 @@ public typealias UpdateExpression = AddDataRow.(C) -> R * ## Note * @include [ExpressionsGivenRow.AddDataRowNote] * ## See Also - * - {@include [SeeAlsoPerCol]} - * - {@include [SeeAlsoPerRowCol]} + * - {@include [SeeAlsoUpdatePerCol]} + * - {@include [SeeAlsoUpdatePerRowCol]} * @param [expression] The {@include [ExpressionsGivenRow.RowValueExpressionLink]} to update the rows with. */ @Refine @@ -291,9 +291,10 @@ public inline fun Update.with(crossinline expression: Updat expression(row, value) } -/** [Update with][Update.with] to provide a new value for every selected cell giving its row. */ +/** [Update with][Update.with] to provide a new value for every selected cell giving its row + * and its previous value. */ @ExcludeFromSources -private interface SeeAlsoWith +private interface SeeAlsoUpdateWith /** ## As Frame * @@ -313,8 +314,8 @@ public fun Update>.asFrame(expression: DataFrameExpressi * - {@include [UpdatePerColMap]} * * ### See Also - * - {@include [SeeAlsoWith]} - * - {@include [SeeAlsoPerRowCol]} + * - {@include [SeeAlsoUpdateWith]} + * - {@include [SeeAlsoUpdatePerRowCol]} * ### This Per Col Overload */ @ExcludeFromSources @@ -378,7 +379,7 @@ public fun Update.perCol(valueSelector: ColumnExpression): Da /** [Update per col][Update.perCol] to provide a new value for every selected cell giving its column. */ @ExcludeFromSources -private interface SeeAlsoPerCol +private interface SeeAlsoUpdatePerCol /** Chains up two row value filters together. */ internal infix fun RowValueFilter?.and(other: RowValueFilter): RowValueFilter { diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt index f4dab96c72..7e800c32ee 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt @@ -98,4 +98,7 @@ internal interface DocumentationUrls { /** [See `group` on the documentation website.]({@include [Url]}/ungroup.html) */ interface Ungroup + + /** [See `convert` on the documentation website.]({@include [Url]}/convert.html) */ + interface Convert } diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenRow.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenRow.kt index 0454086f60..f1ea4131e6 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenRow.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenRow.kt @@ -46,7 +46,9 @@ internal interface ExpressionsGivenRow { interface SetDefaultOperationArg /** - * [update with][org.jetbrains.kotlinx.dataframe.api.Update.with]- and [add][org.jetbrains.kotlinx.dataframe.api.add]-like expressions use [AddDataRow] instead of [DataRow] as the DSL's receiver type. + * [update with][org.jetbrains.kotlinx.dataframe.api.Update.with]-, + * [convert with][org.jetbrains.kotlinx.dataframe.api.Convert.with]- + * and [add][org.jetbrains.kotlinx.dataframe.api.add]-like expressions use [AddDataRow] instead of [DataRow] as the DSL's receiver type. * This is an extension to [RowValueExpression][DfRowValueExpression] and * [RowExpression][DfRowExpression] that provides access to * the modified/generated value of the preceding row ([AddDataRow.newValue]). diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/common.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/common.kt index 672a869ab4..7e22381b8e 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/common.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/common.kt @@ -44,6 +44,20 @@ public fun catchHttpResponse(url: URL, body: (InputStream) -> AnyFrame): AnyFram } } +/** + * Converts a list of lists into a [DataFrame]. + * + * By default, treats the first inner list as a header (column names), and the remaining lists as rows. + * If [containsColumns] is `true`, interprets each inner list as a column, + * where the first element is used as the column name, and the remaining elements as values. + * + * @param T The type of elements contained in the nested lists. + * @param containsColumns If `true`, treats each nested list as a column with its first element as the column name. + * Otherwise, the first list is treated as the header. + * Defaults to `false`. + * @return A [DataFrame] containing the data from the nested list structure. + * Returns an empty [DataFrame] if the input is empty or invalid. + */ public fun List>.toDataFrame(containsColumns: Boolean = false): AnyFrame = when { containsColumns -> {