Skip to content

Commit 4d33a78

Browse files
connortsui20connortsui20
committed
move documentation around
Signed-off-by: Connor Tsui <[email protected]>
1 parent 784bad9 commit 4d33a78

File tree

15 files changed

+433
-448
lines changed

15 files changed

+433
-448
lines changed

‎vortex-vector/src/bool/mod.rs‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,54 @@
22
// SPDX-FileCopyrightText: Copyright the Vortex contributors
33

44
//! Definition and implementation of [`BoolVector`] and [`BoolVectorMut`].
5+
//!
6+
//! # Examples
7+
//!
8+
//! ## Extending and appending
9+
//!
10+
//! ```
11+
//! use vortex_vector::{BoolVectorMut, VectorMutOps};
12+
//!
13+
//! let mut vec1 = BoolVectorMut::from_iter([true, false].map(Some));
14+
//! let vec2 = BoolVectorMut::from_iter([true, true].map(Some)).freeze();
15+
//!
16+
//! // Extend from another vector.
17+
//! vec1.extend_from_vector(&vec2);
18+
//! assert_eq!(vec1.len(), 4);
19+
//!
20+
//! // Append null values.
21+
//! vec1.append_nulls(2);
22+
//! assert_eq!(vec1.len(), 6);
23+
//! ```
24+
//!
25+
//! ## Splitting and unsplitting
26+
//!
27+
//! ```
28+
//! use vortex_vector::{BoolVectorMut, VectorMutOps};
29+
//!
30+
//! let mut vec = BoolVectorMut::from_iter([true, false, true, false, true].map(Some));
31+
//!
32+
//! // Split the vector at index 3.
33+
//! let mut second_half = vec.split_off(3);
34+
//! assert_eq!(vec.len(), 3);
35+
//! assert_eq!(second_half.len(), 2);
36+
//!
37+
//! // Rejoin the vectors.
38+
//! vec.unsplit(second_half);
39+
//! assert_eq!(vec.len(), 5);
40+
//! ```
41+
//!
42+
//! ## Converting to immutable
43+
//!
44+
//! ```
45+
//! use vortex_vector::{BoolVectorMut, VectorMutOps, VectorOps};
46+
//!
47+
//! let mut vec = BoolVectorMut::from_iter([true, false, true].map(Some));
48+
//!
49+
//! // Freeze into an immutable vector.
50+
//! let immutable = vec.freeze();
51+
//! assert_eq!(immutable.len(), 3);
52+
//! ```
553
654
mod vector;
755
pub use vector::BoolVector;

‎vortex-vector/src/bool/vector.rs‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,7 @@ use crate::{BoolVectorMut, VectorOps};
1111

1212
/// An immutable vector of boolean values.
1313
///
14-
/// `BoolVector` can be considered a borrowed / frozen version of [`BoolVectorMut`], which is
15-
/// created via the [`freeze`](crate::VectorMutOps::freeze) method.
16-
///
17-
/// See the documentation for [`BoolVectorMut`] for more information.
14+
/// Internally, this `BoolVector` is a wrapper around a [`BitBuffer`] and a validity mask.
1815
#[derive(Debug, Clone)]
1916
pub struct BoolVector {
2017
/// The bits that we use to represent booleans.

‎vortex-vector/src/bool/vector_mut.rs‎

Lines changed: 1 addition & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -11,57 +11,7 @@ use crate::{BoolVector, VectorMutOps, VectorOps};
1111

1212
/// A mutable vector of boolean values.
1313
///
14-
/// `BoolVectorMut` is the primary way to construct boolean vectors. It provides efficient methods
15-
/// for building vectors incrementally before converting them to an immutable [`BoolVector`] using
16-
/// the [`freeze`](crate::VectorMutOps::freeze) method.
17-
///
18-
/// # Examples
19-
///
20-
/// ## Extending and appending
21-
///
22-
/// ```
23-
/// use vortex_vector::{BoolVectorMut, VectorMutOps};
24-
///
25-
/// let mut vec1 = BoolVectorMut::from_iter([true, false].map(Some));
26-
/// let vec2 = BoolVectorMut::from_iter([true, true].map(Some)).freeze();
27-
///
28-
/// // Extend from another vector.
29-
/// vec1.extend_from_vector(&vec2);
30-
/// assert_eq!(vec1.len(), 4);
31-
///
32-
/// // Append null values.
33-
/// vec1.append_nulls(2);
34-
/// assert_eq!(vec1.len(), 6);
35-
/// ```
36-
///
37-
/// ## Splitting and unsplitting
38-
///
39-
/// ```
40-
/// use vortex_vector::{BoolVectorMut, VectorMutOps};
41-
///
42-
/// let mut vec = BoolVectorMut::from_iter([true, false, true, false, true].map(Some));
43-
///
44-
/// // Split the vector at index 3.
45-
/// let mut second_half = vec.split_off(3);
46-
/// assert_eq!(vec.len(), 3);
47-
/// assert_eq!(second_half.len(), 2);
48-
///
49-
/// // Rejoin the vectors.
50-
/// vec.unsplit(second_half);
51-
/// assert_eq!(vec.len(), 5);
52-
/// ```
53-
///
54-
/// ## Converting to immutable
55-
///
56-
/// ```
57-
/// use vortex_vector::{BoolVectorMut, VectorMutOps, VectorOps};
58-
///
59-
/// let mut vec = BoolVectorMut::from_iter([true, false, true].map(Some));
60-
///
61-
/// // Freeze into an immutable vector.
62-
/// let immutable = vec.freeze();
63-
/// assert_eq!(immutable.len(), 3);
64-
/// ```
14+
/// Internally, this `BoolVectorMut` is a wrapper around a [`BitBufferMut`] and a validity mask.
6515
#[derive(Debug, Clone)]
6616
pub struct BoolVectorMut {
6717
/// The mutable bits that we use to represent booleans.

‎vortex-vector/src/decimal/generic.rs‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,11 @@ use crate::{DVectorMut, VectorOps};
1212

1313
/// An immutable vector of generic decimal values.
1414
///
15-
/// `DVector<D>` can be considered a borrowed / frozen version of [`DVectorMut<D>`], which is
16-
/// created via the [`freeze`](crate::VectorMutOps::freeze) method.
15+
/// `D` is bound by [`NativeDecimalType`], which can be one of the native integer types (`i8`,
16+
/// `i16`, `i32`, `i64`, `i128`) or `i256`. `D` is used to store the decimal values.
1717
///
18-
/// See the documentation for [`DVectorMut<D>`] for more information.
18+
/// The decimal vector maintains a [`PrecisionScale<D>`] that defines the precision (total number of
19+
/// digits) and scale (digits after the decimal point) for all values in the vector.
1920
#[derive(Debug, Clone)]
2021
pub struct DVector<D> {
2122
/// The precision and scale of each decimal in the decimal vector.

‎vortex-vector/src/decimal/generic_mut.rs‎

Lines changed: 0 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -22,139 +22,7 @@ use crate::{DVector, VectorMutOps, VectorOps};
2222
/// modification to ensure values stay within the bounds defined by their precision and scale.
2323
/// This makes operations like "push" fallible, thus we have a [`try_push()`] method instead.
2424
///
25-
/// [`DVectorMut<D>`] is the primary way to construct decimal vectors. It provides methods for
26-
/// building vectors incrementally before converting them to an immutable [`DVector<D>`] using
27-
/// the [`freeze()`] method.
28-
///
2925
/// [`try_push()`]: Self::try_push
30-
/// [`freeze()`]: crate::VectorMutOps::freeze
31-
///
32-
/// # Examples
33-
///
34-
/// ## Creating and building decimal vectors
35-
///
36-
/// ```
37-
/// use vortex_dtype::{DecimalDType, PrecisionScale};
38-
/// use vortex_vector::{DVectorMut, VectorMutOps};
39-
///
40-
/// // Create a decimal vector with precision=9, scale=2 (e.g., up to 9999999.99).
41-
/// let decimal_dtype = DecimalDType::new(9, 2);
42-
/// let mut vec = DVectorMut::<i32>::with_capacity(&decimal_dtype, 5);
43-
/// assert_eq!(vec.len(), 0);
44-
/// assert!(vec.capacity() >= 5);
45-
///
46-
/// // Values are stored as integers scaled by 10^scale.
47-
/// // For scale=2: 123.45 is stored as 12345.
48-
/// vec.try_push(12345).unwrap(); // Represents 123.45.
49-
/// vec.try_push(9999).unwrap(); // Represents 99.99.
50-
/// assert_eq!(vec.len(), 2);
51-
///
52-
/// // Values that exceed precision will fail.
53-
/// let too_large = 10_i32.pow(9); // Would represent 10000000.00.
54-
/// assert!(vec.try_push(too_large).is_err());
55-
///
56-
/// // Create from buffers with validation.
57-
/// use vortex_buffer::BufferMut;
58-
/// use vortex_mask::MaskMut;
59-
/// let elements = BufferMut::from_iter([100_i32, 200, 300]); // 1.00, 2.00, 3.00.
60-
/// let validity = MaskMut::new_true(3);
61-
/// let ps = PrecisionScale::<i32>::try_from(&decimal_dtype).unwrap();
62-
/// let decimal_vec = DVectorMut::new(ps, elements, validity);
63-
/// assert_eq!(decimal_vec.len(), 3);
64-
/// ```
65-
///
66-
/// ## Working with nulls and validity
67-
///
68-
/// ```
69-
/// use vortex_buffer::BufferMut;
70-
/// use vortex_dtype::{DecimalDType, PrecisionScale};
71-
/// use vortex_mask::MaskMut;
72-
/// use vortex_vector::{DVectorMut, VectorMutOps};
73-
///
74-
/// // Create a decimal vector with nulls.
75-
/// let decimal_dtype = DecimalDType::new(5, 2); // Up to 999.99.
76-
/// let ps = PrecisionScale::<i32>::try_from(&decimal_dtype).unwrap();
77-
///
78-
/// // Create with some null values (validity mask: true = not null, false = null).
79-
/// let elements = BufferMut::from_iter([1000_i32, 0, 2500, 0]); // 10.00, null, 25.00, null.
80-
/// let mut validity = MaskMut::with_capacity(4);
81-
/// validity.append_n(true, 1); // index 0: valid
82-
/// validity.append_n(false, 1); // index 1: null
83-
/// validity.append_n(true, 1); // index 2: valid
84-
/// validity.append_n(false, 1); // index 3: null
85-
/// let mut vec = DVectorMut::new(ps, elements, validity);
86-
///
87-
/// // Check element access with nulls.
88-
/// assert_eq!(vec.get(0), Some(&1000)); // 10.00.
89-
/// assert_eq!(vec.get(1), None); // Null.
90-
/// assert_eq!(vec.get(2), Some(&2500)); // 25.00.
91-
///
92-
/// // Append null values.
93-
/// vec.append_nulls(3);
94-
/// assert_eq!(vec.len(), 7);
95-
/// ```
96-
///
97-
/// ## Extending and manipulating vectors
98-
///
99-
/// ```
100-
/// use vortex_dtype::DecimalDType;
101-
/// use vortex_vector::{DVectorMut, VectorMutOps};
102-
///
103-
/// // Create two decimal vectors with scale=3 (3 decimal places).
104-
/// let decimal_dtype = DecimalDType::new(10, 3);
105-
/// let mut vec1 = DVectorMut::<i64>::with_capacity(&decimal_dtype, 10);
106-
/// vec1.try_push(1234567).unwrap(); // 1234.567.
107-
/// vec1.try_push(2345678).unwrap(); // 2345.678.
108-
///
109-
/// let mut vec2 = DVectorMut::<i64>::with_capacity(&decimal_dtype, 10);
110-
/// vec2.try_push(3456789).unwrap(); // 3456.789.
111-
/// vec2.try_push(4567890).unwrap(); // 4567.890.
112-
///
113-
/// // Extend from an immutable vector.
114-
/// let immutable = vec2.freeze();
115-
/// vec1.extend_from_vector(&immutable);
116-
/// assert_eq!(vec1.len(), 4);
117-
///
118-
/// // Split vector at index 3.
119-
/// let mut split = vec1.split_off(3);
120-
/// assert_eq!(vec1.len(), 3);
121-
/// assert_eq!(split.len(), 1);
122-
///
123-
/// // Reserve capacity for future operations.
124-
/// vec1.reserve(10);
125-
/// assert!(vec1.capacity() >= 13);
126-
///
127-
/// // Rejoin the vectors.
128-
/// vec1.unsplit(split);
129-
/// assert_eq!(vec1.len(), 4);
130-
/// ```
131-
///
132-
/// ## Converting between mutable and immutable
133-
///
134-
/// ```
135-
/// use vortex_dtype::DecimalDType;
136-
/// use vortex_vector::{DVectorMut, VectorMutOps, VectorOps};
137-
///
138-
/// // Create a mutable decimal vector.
139-
/// let decimal_dtype = DecimalDType::new(18, 6); // High precision with 6 decimal places.
140-
/// let mut vec_mut = DVectorMut::<i128>::with_capacity(&decimal_dtype, 3);
141-
/// vec_mut.try_push(1000000).unwrap(); // 1.000000.
142-
/// vec_mut.try_push(2500000).unwrap(); // 2.500000.
143-
/// vec_mut.try_push(3333333).unwrap(); // 3.333333.
144-
///
145-
/// // Freeze into an immutable vector.
146-
/// let vec_immutable = vec_mut.freeze();
147-
/// assert_eq!(vec_immutable.len(), 3);
148-
///
149-
/// // Access elements from the immutable vector.
150-
/// assert_eq!(vec_immutable.get(0), Some(&1000000));
151-
/// assert_eq!(vec_immutable.get(1), Some(&2500000));
152-
///
153-
/// // Can also convert immutable back to mutable using try_into_mut.
154-
/// // Note: This may fail if the buffer is shared.
155-
/// // let vec_mut_again = vec_immutable.try_into_mut().unwrap();
156-
/// // assert_eq!(vec_mut_again.len(), 3);
157-
/// ```
15826
#[derive(Debug, Clone)]
15927
pub struct DVectorMut<D> {
16028
/// The precision and scale of each decimal in the decimal vector.

0 commit comments

Comments
 (0)