This is an automated email from the ASF dual-hosted git repository.
kou pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/main by this push:
new de1e40f527 MINOR: [Doc] Fix columnar.rst buffer layout table
inconsistencies (#36822)
de1e40f527 is described below
commit de1e40f5270e819191a319678653d0a4c0749181
Author: Jin Shang <[email protected]>
AuthorDate: Mon Jul 24 09:36:11 2023 +0800
MINOR: [Doc] Fix columnar.rst buffer layout table inconsistencies (#36822)
### Rationale for this change
1. Some buffer layouts write out "padding" explicitly while some don't. I
believe writing it out is help to distinguish paddings and null values.
2. Most cells start with a space while some don't.
### What changes are included in this PR?
Fixed the above two inconsistencies.
### Are these changes tested?
No need.
### Are there any user-facing changes?
No.
Authored-by: Jin Shang <[email protected]>
Signed-off-by: Sutou Kouhei <[email protected]>
---
docs/source/format/Columnar.rst | 132 ++++++++++++++++++++--------------------
1 file changed, 66 insertions(+), 66 deletions(-)
diff --git a/docs/source/format/Columnar.rst b/docs/source/format/Columnar.rst
index b90e2c97ad..3390f1b7b5 100644
--- a/docs/source/format/Columnar.rst
+++ b/docs/source/format/Columnar.rst
@@ -256,15 +256,15 @@ Would look like: ::
* Length: 5, Null count: 1
* Validity bitmap buffer:
- |Byte 0 (validity bitmap) | Bytes 1-63 |
- |-------------------------|-----------------------|
- | 00011101 | 0 (padding) |
+ | Byte 0 (validity bitmap) | Bytes 1-63 |
+ |--------------------------|-----------------------|
+ | 00011101 | 0 (padding) |
* Value Buffer:
- |Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes 16-19 |
Bytes 20-63 |
-
|------------|-------------|-------------|-------------|-------------|-------------|
- | 1 | unspecified | 2 | 4 | 8 |
unspecified |
+ | Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes 16-19 |
Bytes 20-63 |
+
|-------------|-------------|-------------|-------------|-------------|-----------------------|
+ | 1 | unspecified | 2 | 4 | 8 |
unspecified (padding) |
**Example Layout: Non-null int32 Array**
@@ -279,9 +279,9 @@ Would look like: ::
* Value Buffer:
- |Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | bytes 12-15 | bytes 16-19 |
Bytes 20-63 |
-
|------------|-------------|-------------|-------------|-------------|-------------|
- | 1 | 2 | 3 | 4 | 8 |
unspecified |
+ | Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes 16-19 |
Bytes 20-63 |
+
|-------------|-------------|-------------|-------------|-------------|-----------------------|
+ | 1 | 2 | 3 | 4 | 8 |
unspecified (padding) |
or with the bitmap elided: ::
@@ -289,9 +289,9 @@ or with the bitmap elided: ::
* Validity bitmap buffer: Not required
* Value Buffer:
- |Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | bytes 12-15 | bytes 16-19 |
Bytes 20-63 |
-
|------------|-------------|-------------|-------------|-------------|-------------|
- | 1 | 2 | 3 | 4 | 8 |
unspecified |
+ | Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | bytes 12-15 | bytes 16-19 |
Bytes 20-63 |
+
|-------------|-------------|-------------|-------------|-------------|-----------------------|
+ | 1 | 2 | 3 | 4 | 8 |
unspecified (padding) |
Variable-size Binary Layout
---------------------------
@@ -342,13 +342,13 @@ will be represented as follows: ::
| Bytes 0-19 | Bytes 20-63 |
|----------------|-----------------------|
- | 0, 3, 3, 3, 7 | unspecified |
+ | 0, 3, 3, 3, 7 | unspecified (padding) |
* Value buffer:
- | Bytes 0-6 | Bytes 7-63 |
- |----------------|----------------------|
- | joemark | unspecified |
+ | Bytes 0-6 | Bytes 7-63 |
+ |----------------|-----------------------|
+ | joemark | unspecified (padding) |
.. _variable-size-list-layout:
@@ -388,18 +388,18 @@ will have the following representation: ::
* Offsets buffer (int32)
- | Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes 16-19 |
Bytes 20-63 |
-
|------------|-------------|-------------|-------------|-------------|-------------|
- | 0 | 3 | 3 | 7 | 7 |
unspecified |
+ | Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes 16-19 |
Bytes 20-63 |
+
|------------|-------------|-------------|-------------|-------------|-----------------------|
+ | 0 | 3 | 3 | 7 | 7 |
unspecified (padding) |
* Values array (Int8array):
* Length: 7, Null count: 0
* Validity bitmap buffer: Not required
* Values buffer (int8)
- | Bytes 0-6 | Bytes 7-63 |
- |------------------------------|-------------|
- | 12, -7, 25, 0, -127, 127, 50 | unspecified |
+ | Bytes 0-6 | Bytes 7-63 |
+ |------------------------------|-----------------------|
+ | 12, -7, 25, 0, -127, 127, 50 | unspecified (padding) |
**Example Layout: ``List<List<Int8>>``**
@@ -412,9 +412,9 @@ will be represented as follows: ::
* Validity bitmap buffer: Not required
* Offsets buffer (int32)
- | Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes 16-63 |
- |------------|------------|------------|-------------|-------------|
- | 0 | 2 | 5 | 6 | unspecified |
+ | Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes 16-63
|
+
|------------|------------|------------|-------------|-----------------------|
+ | 0 | 2 | 5 | 6 | unspecified
(padding) |
* Values array (`List<Int8>`)
* Length: 6, Null count: 1
@@ -426,17 +426,17 @@ will be represented as follows: ::
* Offsets buffer (int32)
- | Bytes 0-27 | Bytes 28-63 |
- |----------------------|-------------|
- | 0, 2, 4, 7, 7, 8, 10 | unspecified |
+ | Bytes 0-27 | Bytes 28-63 |
+ |----------------------|-----------------------|
+ | 0, 2, 4, 7, 7, 8, 10 | unspecified (padding) |
* Values array (Int8):
* Length: 10, Null count: 0
* Validity bitmap buffer: Not required
- | Bytes 0-9 | Bytes 10-63 |
- |-------------------------------|-------------|
- | 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 | unspecified |
+ | Bytes 0-9 | Bytes 10-63 |
+ |-------------------------------|-----------------------|
+ | 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 | unspecified (padding) |
Fixed-Size List Layout
----------------------
@@ -511,9 +511,9 @@ The layout for ``[{'joe', 1}, {null, 2}, null, {'mark',
4}]`` would be: ::
* Length: 4, Null count: 1
* Validity bitmap buffer:
- |Byte 0 (validity bitmap) | Bytes 1-63 |
- |-------------------------|-----------------------|
- | 00001011 | 0 (padding) |
+ | Byte 0 (validity bitmap) | Bytes 1-63 |
+ |--------------------------|-----------------------|
+ | 00001011 | 0 (padding) |
* Children arrays:
* field-0 array (`VarBinary`):
@@ -528,13 +528,13 @@ The layout for ``[{'joe', 1}, {null, 2}, null, {'mark',
4}]`` would be: ::
| Bytes 0-19 | Bytes 20-63 |
|----------------|-----------------------|
- | 0, 3, 3, 3, 7 | unspecified |
+ | 0, 3, 3, 3, 7 | unspecified (padding) |
* Value buffer:
| Bytes 0-6 | Bytes 7-63 |
|----------------|-----------------------|
- | joemark | unspecified |
+ | joemark | unspecified (padding) |
* field-1 array (int32 array):
* Length: 4, Null count: 1
@@ -546,9 +546,9 @@ The layout for ``[{'joe', 1}, {null, 2}, null, {'mark',
4}]`` would be: ::
* Value Buffer:
- |Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes 16-63
|
-
|------------|-------------|-------------|-------------|-------------|
- | 1 | 2 | unspecified | 4 | unspecified
|
+ | Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes
16-63 |
+
|-------------|-------------|-------------|-------------|-----------------------|
+ | 1 | 2 | unspecified | 4 |
unspecified (padding) |
Struct Validity
~~~~~~~~~~~~~~~
@@ -610,15 +610,15 @@ will have the following layout: ::
* Length: 4, Null count: 0
* Types buffer:
- |Byte 0 | Byte 1 | Byte 2 | Byte 3 | Bytes 4-63 |
- |---------|-------------|----------|----------|-------------|
- | 0 | 0 | 0 | 1 | unspecified |
+ | Byte 0 | Byte 1 | Byte 2 | Byte 3 | Bytes 4-63 |
+ |----------|-------------|----------|----------|-----------------------|
+ | 0 | 0 | 0 | 1 | unspecified (padding) |
* Offset buffer:
- |Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes 16-63 |
- |----------|-------------|------------|-------------|-------------|
- | 0 | 1 | 2 | 0 | unspecified |
+ | Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes 16-63
|
+
|-----------|-------------|------------|-------------|-----------------------|
+ | 0 | 1 | 2 | 0 | unspecified
(padding) |
* Children arrays:
* Field-0 array (f: Float32):
@@ -627,9 +627,9 @@ will have the following layout: ::
* Value Buffer:
- | Bytes 0-11 | Bytes 12-63 |
- |----------------|-------------|
- | 1.2, null, 3.4 | unspecified |
+ | Bytes 0-11 | Bytes 12-63 |
+ |----------------|-----------------------|
+ | 1.2, null, 3.4 | unspecified (padding) |
* Field-1 array (i: Int32):
@@ -638,9 +638,9 @@ will have the following layout: ::
* Value Buffer:
- | Bytes 0-3 | Bytes 4-63 |
- |-----------|-------------|
- | 5 | unspecified |
+ | Bytes 0-3 | Bytes 4-63 |
+ |-----------|-----------------------|
+ | 5 | unspecified (padding) |
Sparse Union
~~~~~~~~~~~~
@@ -677,29 +677,29 @@ will have the following layout: ::
* Length: 6, Null count: 4
* Validity bitmap buffer:
- |Byte 0 (validity bitmap) | Bytes 1-63 |
- |-------------------------|-----------------------|
- |00010001 | 0 (padding) |
+ | Byte 0 (validity bitmap) | Bytes 1-63 |
+ |--------------------------|-----------------------|
+ | 00010001 | 0 (padding) |
* Value buffer:
- |Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes 16-19
| Bytes 20-23 | Bytes 24-63 |
-
|------------|-------------|-------------|-------------|-------------|--------------|-----------------------|
- | 5 | unspecified | unspecified | unspecified | 4
| unspecified | unspecified (padding) |
+ | Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes
16-19 | Bytes 20-23 | Bytes 24-63 |
+
|-------------|-------------|-------------|-------------|-------------|--------------|-----------------------|
+ | 5 | unspecified | unspecified | unspecified | 4
| unspecified | unspecified (padding) |
* f (Float32):
* Length: 6, Null count: 4
* Validity bitmap buffer:
- |Byte 0 (validity bitmap) | Bytes 1-63 |
- |-------------------------|-----------------------|
- | 00001010 | 0 (padding) |
+ | Byte 0 (validity bitmap) | Bytes 1-63 |
+ |--------------------------|-----------------------|
+ | 00001010 | 0 (padding) |
* Value buffer:
- |Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes
16-19 | Bytes 20-23 | Bytes 24-63 |
-
|-------------|-------------|-------------|-------------|-------------|--------------|-----------------------|
- | unspecified | 1.2 | unspecified | 3.4 |
unspecified | unspecified | unspecified (padding) |
+ | Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes
16-19 | Bytes 20-23 | Bytes 24-63 |
+
|--------------|-------------|-------------|-------------|-------------|-------------|-----------------------|
+ | unspecified | 1.2 | unspecified | 3.4 |
unspecified | unspecified | unspecified (padding) |
* s (`VarBinary`)
* Length: 6, Null count: 4
@@ -711,9 +711,9 @@ will have the following layout: ::
* Offsets buffer (Int32)
- | Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes 16-19
| Bytes 20-23 | Bytes 24-27 | Bytes 28-63 |
-
|------------|-------------|-------------|-------------|-------------|-------------|-------------|-------------|
- | 0 | 0 | 0 | 3 | 3
| 3 | 7 | unspecified |
+ | Bytes 0-3 | Bytes 4-7 | Bytes 8-11 | Bytes 12-15 | Bytes 16-19
| Bytes 20-23 | Bytes 24-27 | Bytes 28-63 |
+
|------------|-------------|-------------|-------------|-------------|-------------|-------------|------------------------|
+ | 0 | 0 | 0 | 3 | 3
| 3 | 7 | unspecified (padding) |
* Values buffer:
