Jefffrey commented on code in PR #9019: URL: https://github.com/apache/arrow-rs/pull/9019#discussion_r2637186123
########## arrow-buffer/src/buffer/run.rs: ########## @@ -18,75 +18,107 @@ use crate::ArrowNativeType; use crate::buffer::ScalarBuffer; -/// A slice-able buffer of monotonically increasing, positive integers used to store run-ends +/// A slice-able buffer of monotonically increasing, positive integers used to +/// store run-ends. /// -/// # Logical vs Physical -/// -/// A [`RunEndBuffer`] is used to encode runs of the same value, the index of each run is -/// called the physical index. The logical index is then the corresponding index in the logical -/// run-encoded array, i.e. a single run of length `3`, would have the logical indices `0..3`. +/// Used to compactly represent runs of the same value. Values being represented +/// are stored in a separate buffer from this struct. /// -/// Each value in [`RunEndBuffer::values`] is the cumulative length of all runs in the -/// logical array, up to that physical index. +/// # Logical vs Physical /// -/// Consider a [`RunEndBuffer`] containing `[3, 4, 6]`. The maximum physical index is `2`, -/// as there are `3` values, and the maximum logical index is `5`, as the maximum run end -/// is `6`. The physical indices are therefore `[0, 0, 0, 1, 2, 2]` +/// Physically, each value in the `run_ends` buffer is the cumulative length of +/// all runs in the logical representation, up to that physical index. Consider +/// the following example: /// /// ```text -/// ┌─────────┐ ┌─────────┐ ┌─────────┐ -/// │ 3 │ │ 0 │ ─┬──────▶ │ 0 │ -/// ├─────────┤ ├─────────┤ │ ├─────────┤ -/// │ 4 │ │ 1 │ ─┤ ┌────▶ │ 1 │ -/// ├─────────┤ ├─────────┤ │ │ ├─────────┤ -/// │ 6 │ │ 2 │ ─┘ │ ┌──▶ │ 2 │ -/// └─────────┘ ├─────────┤ │ │ └─────────┘ -/// run ends │ 3 │ ───┘ │ physical indices -/// ├─────────┤ │ -/// │ 4 │ ─────┤ -/// ├─────────┤ │ -/// │ 5 │ ─────┘ -/// └─────────┘ -/// logical indices +/// physical logical +/// ┌─────────┬─────────┐ ┌─────────┬─────────┐ +/// │ 3 │ 0 │ ◄──────┬─ │ A │ 0 │ +/// ├─────────┼─────────┤ │ ├─────────┼─────────┤ +/// │ 4 │ 1 │ ◄────┐ ├─ │ A │ 1 │ +/// ├─────────┼─────────┤ │ │ ├─────────┼─────────┤ +/// │ 6 │ 2 │ ◄──┐ │ └─ │ A │ 2 │ +/// └─────────┴─────────┘ │ │ ├─────────┼─────────┤ +/// run-ends index │ └─── │ B │ 3 │ +/// │ ├─────────┼─────────┤ +/// logical_offset = 0 ├───── │ C │ 4 │ +/// logical_length = 6 │ ├─────────┼─────────┤ +/// └───── │ C │ 5 │ +/// └─────────┴─────────┘ +/// values index /// ``` /// +/// A [`RunEndBuffer`] is physically the buffer and offset with length on the left. +/// In this case, the offset and length represent the whole buffer, so it is essentially +/// unsliced. See the section below on slicing for more details on how this buffer +/// handles slicing. +/// +/// We can see how logically the values are represented by the same physical index, +/// how multiple logical indices map to the same physical index. So the [`RunEndBuffer`] Review Comment: Thanks, hands got away from my brain there a bit it seems -- 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]
