Clarify prev() usage in fillNA.with and document newValue for forward-fill
- 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.
```
Contributor guide
Assessment
This issue has not been assessed yet.