Skip to content

Commit 7ffcf0d

Browse files
authored
Add more documentation for FixedSizeBinary arrays (apache#9866)
# Which issue does this PR close? - related to https://github.com/apache/arrow-rs/pull/9850/changes#r3170266352 # Rationale for this change While working on apache#9850 I felt it would help to have some better docs about what a FixedSizeBinaryArray actually was, so I made some # What changes are included in this PR? Add some more background / explanatory docs about this array # Are these changes tested? By CI # Are there any user-facing changes? Docs only
1 parent 1ddb4d9 commit 7ffcf0d

1 file changed

Lines changed: 38 additions & 1 deletion

File tree

arrow-array/src/array/fixed_size_binary_array.rs

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,44 @@ use arrow_schema::{ArrowError, DataType};
2525
use std::any::Any;
2626
use std::sync::Arc;
2727

28-
/// An array of [fixed size binary arrays](https://arrow.apache.org/docs/format/Columnar.html#fixed-size-primitive-layout)
28+
/// An array of [fixed-size binary values](https://arrow.apache.org/docs/format/Columnar.html#fixed-size-primitive-layout)
29+
///
30+
/// Each element in a [`FixedSizeBinaryArray`] has `value_length` bytes, where
31+
/// `value_length` is defined by the schema.
32+
///
33+
/// This array type is useful for storing fixed-length values such as 16-byte
34+
/// UUIDs (`value_length = 16`).
35+
///
36+
/// # Layout
37+
///
38+
/// Values in a [`FixedSizeBinaryArray`] are stored contiguously in a single
39+
/// buffer. The byte offset for the `i`-th element can be calculated as
40+
/// `i * value_length`.
41+
///
42+
/// Nulls are stored in a standard optional Arrow [`NullBuffer`].
43+
///
44+
/// For example, a 100-value [`FixedSizeBinaryArray`] with `value_length = 12`
45+
/// is shown below.
46+
///
47+
/// ```text
48+
/// ┌──────────────────────────────────────────┐
49+
/// │ Computed byte offsets │
50+
/// │ ┌──────────────────────┐ ┌────┐ │
51+
/// │ │┌────────────────────┐│ │ │ │
52+
/// │ 0 ││value 0 (12 bytes) ││ │ 1 │ │
53+
/// │ │├────────────────────┤│ │ │ │
54+
/// │ 12 ││value 1 (12 bytes) ││ │ 0 │ │
55+
/// │ │├────────────────────┤│ │ │ │
56+
/// │ 24 ││value 2 (12 bytes) ││ │ 1 │ │
57+
/// │ │└────────────────────┘│ │ │ │
58+
/// │ │ ... │ │... │ │
59+
/// │ │┌───────────────────┐ │ │ │ │
60+
/// │ 1188 ││value 99 (12 bytes)│ │ │ 1 │ │
61+
/// │ │└───────────────────┘ │ │ │ │
62+
/// │ └──────────────────────┘ └────┘ │
63+
/// │ value_data nulls │
64+
/// └──────────────────────────────────────────┘
65+
/// ```
2966
///
3067
/// # Examples
3168
///

0 commit comments

Comments
 (0)