Kotlin / Kotlin/dataframe

Clarify prev() usage in fillNA.with and document newValue for forward-fill

Open
#523 2 comments 0 reactions 1 assignee Claimed by @Allex-Nik View on GitHub
documentation
Dominant language
Kotlin
Stars
1.1k
Forks
83
Avg merge
4d 12h
Merged PRs (30d)
30

Description

### Problem

Using `prev()` inside `fillNA.with` is not intuitive for forward-fill scenarios.

Example:

`df.fillNA("ref").with { prev()!!.ref }`

This does not produce expected forward-fill behavior because `prev()` refers to the original row state, not the updated one.

The correct usage is:

`df.fillNA("ref").with { prev()?.newValue() }`

However:
- this is not documented
- API behavior is not obvious
- users expect forward-fill to work with `prev()` directly

### Expected

Clarify and document correct usage of `prev()` in `fillNA.with`.

### Acceptance criteria

- Documentation updated to explain:
- how `prev()` works (original vs updated row)
- how to use `newValue` for forward-fill
- Add example demonstrating forward-fill pattern
- Ensure behavior is consistent and understandable

### Motivation

- Forward-fill is a common data-cleaning operation
- Current API is confusing without documentation
- Users can easily misuse `prev()` and get incorrect results
- Must be clear before 1.0

From @n3utrino

```
Might be a user error, but it feels like the statement

`data.fillNA("ref").with { prev()!!.ref }`

Should fill all the "ref" rows and not only the first empty one.
```
Screenshot 2023-11-29 at 05 43 13

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.