alamb opened a new pull request, #22592:
URL: https://github.com/apache/datafusion/pull/22592
## Which issue does this PR close?
- Part of #22577 (consolidate `ScalarValue` cast implementations).
## Rationale for this change
`ScalarValue::cast_to` and `try_cast_literal_to_type` are easy to confuse —
they have the same shape ("cast a scalar to a target type") but very different
contracts, and getting the wrong one is a real correctness footgun (`cast_to`
will happily parse `"123"` into an integer, format a number as a string,
truncate `1.5` to `1`, or turn a `Date` into a `Timestamp`, none of which is
safe when unwrapping casts in comparison predicates).
Document on each function how it differs from the other, so the choice is
obvious from the docs alone.
## What changes are included in this PR?
Docs-only change.
-
**[`ScalarValue::cast_to`](https://github.com/apache/datafusion/blob/main/datafusion/common/src/scalar/mod.rs)**
/ `cast_to_with_options` (`datafusion/common/src/scalar/mod.rs`): note that it
is the general-purpose, Arrow cast-kernel-based cast, can lose information, and
point readers to `try_cast_literal_to_type` for the value-preserving variant.
-
**[`try_cast_literal_to_type`](https://github.com/apache/datafusion/blob/main/datafusion/expr-common/src/casts.rs)**
(`datafusion/expr-common/src/casts.rs`): expand the doc comment to explain
it's a restricted, value-preserving cast used to unwrap `CAST(col AS T) <op>
literal` predicates, enumerate which casts it attempts, and note the one quirk
— `Timestamp → Timestamp` unit conversions are allowed to truncate and overflow
yields a `NULL` literal.
## Are these changes tested?
Docs-only; verified with `cargo doc -D rustdoc::broken_intra_doc_links -D
rustdoc::private_intra_doc_links` (clean) and `cargo fmt`.
## Are there any user-facing changes?
Doc comments only. No code or API changes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
