[GitHub] [arrow-rs] alamb commented on a diff in pull request #4607: Add more docs and examples for ListArray and OffsetsBuffer

["alamb (via GitHub)" <gi...@apache.org>]

alamb commented on code in PR #4607:
URL: https://github.com/apache/arrow-rs/pull/4607#discussion_r1280440567


##########
arrow-buffer/src/buffer/offset.rs:
##########
@@ -19,7 +19,43 @@ use crate::buffer::ScalarBuffer;
 use crate::{ArrowNativeType, MutableBuffer};
 use std::ops::Deref;
 
-/// A non-empty buffer of monotonically increasing, positive integers
+/// A non-empty buffer of monotonically increasing, positive integers.
+///
+/// [`OffsetBuffer`] are used to represent ranges of offsets. An
+/// `OffsetBuffer` of `N+1` items contains `N` such ranges. The start
+/// offset for element `i` is `offsets[i]` and the end offset is
+/// `offsets[i+1]`. Equal offsets represent an empty range.
+///
+/// # Example
+///
+/// This example shows how 5 distinct ranges, are represented using a
+/// 6 entry `OffsetBuffer`. The first entry `(0, 3)` represents the
+/// three offsets `0, 1, 2` entry `(3,3)` represent no offsets
+/// (e.g. an empty list).
+///
+/// ```text
+///   ┌───────┐                ┌───┐
+///   │ (0,3) │                │ 0 │
+///   ├───────┤                ├───┤
+///   │ (3,3) │                │ 3 │
+///   ├───────┤                ├───┤
+///   │ (3,4) │                │ 4 │
+///   ├───────┤                ├───┤
+///   │ (4,5) │                │ 5 │
+///   ├───────┤                ├───┤
+///   │ (5,7) │                │ 5 │
+///   └───────┘                ├───┤
+///                            │ 7 │
+///                            └───┘
+///
+///                        Offsets Buffer

Review Comment:
   Thank you 



-- 
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: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org