Clarify behavior of first() and last()#7056
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #7056 +/- ##
=======================================
Coverage 98.69% 98.69%
=======================================
Files 79 79
Lines 14676 14676
=======================================
Hits 14485 14485
Misses 191 191 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
| are passed through to \code{xts}'s first/last. } | ||
| } | ||
| \details{ | ||
| Note: \code{first(x)} and \code{last(x)} are not exact replacements for \code{x[1]} and \code{x[length(x)]}. They differ in handling of zero-length vectors (returning a zero-length vector instead of \code{NA}) and do not preserve attributes like names. |
There was a problem hiding this comment.
good!
perhaps mention that this is intentionally similar to head(,1) ?
> x <- integer(0)
> first(x)
integer(0)
> head(x,1)
integer(0)
> x[1]
[1] NA
| } | ||
| \details{ | ||
| Note: \code{first(x)} and \code{last(x)} are not exact replacements for \code{x[1]} and \code{x[length(x)]}. They differ in handling of zero-length vectors (returning a zero-length vector instead of \code{NA}) and do not preserve attributes like names. | ||
| Note: \code{first(x)} and \code{last(x)} are designed to behave like \code{head(x, 1)} and \code{tail(x, 1)}, respectively. Consequently, they differ from base R subsetting (\code{x[1]}): they return a zero-length vector for empty inputs (instead of \code{NA}) and do not preserve attributes like names. |
There was a problem hiding this comment.
The way its read can imply that head() and tail() do not preserve attributes (since the current text emphasizes that first and last are designed to behave like them), when in fact they do, including names - The analogy holds for zero-length vectors only
There was a problem hiding this comment.
Thanks! Does below this seems right to you? Can you please rephrase it with your suggestions.
first(x) and last(x) are not exact replacements for base R subsetting (e.g. x[1]). For zero-length vectors, they are designed to behave like head(x, 1) and tail(x, 1), returning an empty vector instead of NA. However, unlike both head(x, 1) and base subsetting, they do not preserve attributes like names.
There was a problem hiding this comment.
Factually accurate, so I think what you wrote here sounds good!
I would just make it slightly more concise:
'For zero-length vectors, first(x) and last(x) mimic head(x, 1) and tail(x, 1) by returning an empty vector instead of NA. However, unlike head()/tail() and base R subsetting (e.g., x[1]), they do not preserve attributes like names.'
There was a problem hiding this comment.
(Avoid repetition wherever possible)
|
thanks! |
| are passed through to \code{xts}'s first/last. } | ||
| } | ||
| \details{ | ||
| Note: For zero-length vectors, \code{first(x)} and \code{last(x)} mimic \code{head(x, 1)} and \code{tail(x, 1)} by returning an empty vector instead of \code{NA}. However, unlike \code{head()}/\code{tail()} and base R subsetting (e.g., \code{x[1]}), they do not preserve attributes like names. |
There was a problem hiding this comment.
there is a Rd keyword note that seems more feasible here rather than details, considering sentence starts with "Note:".
example:
Line 33 in ca65511
There was a problem hiding this comment.
Thanks! so do I have to submit a new PR?
4 participants
Closes #2002 and #2487
Adds a note to the documentation for
first()andlast()to clarify they are not direct replacements for base R subsetting (i.e.,x[1]andx[length(x)]).The note explains the different handling of zero-length vectors and the stripping of attributes. This helps prevent common user errors.
@tdhock @jangorecki @Anirban166 could you please review these docs update.