alamb commented on code in PR #10838:
URL: https://github.com/apache/arrow-rs/pull/10838#discussion_r3857334243
##########
arrow-data/src/data.rs:
##########
@@ -471,7 +476,57 @@ impl ArrayData {
self.len == 0
}
- /// Returns the offset of this [`ArrayData`]
+ /// Returns the offset in elements of this [`ArrayData`]
+ ///
+ /// The offset applies to [`Self::buffers`] and [`Self::child_data`],
+ /// but does NOT apply to [`Self::nulls`], which always represents exactly
+ /// [`Self::len`] elements.
+ ///
+ /// # Offsets for Non-nested types
+ ///
+ /// For non-nested types, the offset skips leading elements in the buffers.
+ /// Logical element `i` is stored at physical position `offset + i`.
+ ///
+ /// For example, with `offset = 2` and `len = 3` the following array
Review Comment:
I spent quite a while trying to make comments and ASCII art that illustrate
what is going on
##########
arrow-data/src/data.rs:
##########
@@ -471,7 +476,57 @@ impl ArrayData {
self.len == 0
}
- /// Returns the offset of this [`ArrayData`]
+ /// Returns the offset in elements of this [`ArrayData`]
+ ///
+ /// The offset applies to [`Self::buffers`] and [`Self::child_data`],
+ /// but does NOT apply to [`Self::nulls`], which always represents exactly
+ /// [`Self::len`] elements.
+ ///
+ /// # Offsets for Non-nested types
+ ///
+ /// For non-nested types, the offset skips leading elements in the buffers.
+ /// Logical element `i` is stored at physical position `offset + i`.
+ ///
+ /// For example, with `offset = 2` and `len = 3` the following array
+ /// represents elements `[C, D, E]`:
+ ///
+ /// ```text
+ /// offset: 2 len: 3
+ /// ◀───────────▶◀────────────────▶
+ /// ┌─────┬─────┬─────┬─────┬─────┬─────┐
+ /// values buffer │ A │ B │ C │ D │ E │ F │
+ /// └─────┴─────┴─────┴─────┴─────┴─────┘
+ /// physical index 0 1 2 3 4 5
+ /// logical index 0 1 2
+ /// ```
+ ///
+ /// # Offsets for Struct types
Review Comment:
I think the offset rules are different for other types (like Unions) but
this PR is already pretty tricky so we can perhaps add more detailed
information as a follow on PR
--
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]
