Skip to main content

vortex_array/arrays/primitive/array/
patch.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use std::ops::Range;
5
6use vortex_buffer::Buffer;
7use vortex_error::VortexExpect;
8use vortex_error::VortexResult;
9
10use crate::ExecutionCtx;
11use crate::IntoArray;
12use crate::arrays::PrimitiveArray;
13use crate::dtype::IntegerPType;
14use crate::dtype::NativePType;
15use crate::dtype::UnsignedPType;
16use crate::match_each_integer_ptype;
17use crate::match_each_ptype_width;
18use crate::patches::PATCH_CHUNK_SIZE;
19use crate::patches::Patches;
20use crate::validity::Validity;
21
22impl PrimitiveArray {
23    pub fn patch(self, patches: &Patches, ctx: &mut ExecutionCtx) -> VortexResult<Self> {
24        let patch_indices = patches.indices().clone().execute::<PrimitiveArray>(ctx)?;
25        let patch_values = patches.values().clone().execute::<PrimitiveArray>(ctx)?;
26
27        assert_eq!(self.ptype(), patch_values.ptype());
28
29        let patch_validity = patch_values.validity()?;
30        let patched_validity = self.validity()?.patch(
31            self.len(),
32            patches.offset(),
33            &patch_indices.clone().into_array(),
34            &patch_validity,
35            ctx,
36        )?;
37
38        Ok(match_each_integer_ptype!(patch_indices.ptype(), |I| {
39            match_each_ptype_width!(
40                self.ptype(),
41                |W| {
42                    self.patch_typed::<W, I>(
43                        patch_indices,
44                        patches.offset(),
45                        patch_values,
46                        patched_validity,
47                    )
48                },
49                _ => { unreachable!("primitive widths are specialized") },
50            )
51        }))
52    }
53
54    fn patch_typed<const W: usize, I>(
55        self,
56        patch_indices: PrimitiveArray,
57        patch_indices_offset: usize,
58        patch_values: PrimitiveArray,
59        patched_validity: Validity,
60    ) -> Self
61    where
62        I: IntegerPType,
63    {
64        let ptype = self.ptype();
65        let values = self.into_data_parts().buffer.into_host_sync();
66        let alignment = values.alignment();
67        let mut own_values =
68            Buffer::<[u8; W]>::from_byte_buffer_aligned(values, alignment).into_mut();
69
70        let patch_indices = patch_indices.as_slice::<I>();
71        let patch_values = patch_values
72            .buffer_handle()
73            .as_host_opt()
74            .vortex_expect("patch values require host storage")
75            .as_slice()
76            .as_chunks::<W>()
77            .0;
78
79        for (idx, value) in itertools::zip_eq(patch_indices, patch_values) {
80            own_values[idx.as_() - patch_indices_offset] = *value;
81        }
82
83        Self::from_byte_buffer(
84            own_values.freeze().into_byte_buffer(),
85            ptype,
86            patched_validity,
87        )
88    }
89}
90
91/// Computes the index range for a chunk, accounting for slice offset.
92///
93/// # Arguments
94///
95/// * `chunk_idx` - Index of the chunk
96/// * `offset` - Offset from slice
97/// * `array_len` - Length of the sliced array
98#[inline]
99pub fn chunk_range(chunk_idx: usize, offset: usize, array_len: usize) -> Range<usize> {
100    let offset_in_chunk = offset % PATCH_CHUNK_SIZE;
101    let local_start = (chunk_idx * PATCH_CHUNK_SIZE).saturating_sub(offset_in_chunk);
102    let local_end = ((chunk_idx + 1) * PATCH_CHUNK_SIZE)
103        .saturating_sub(offset_in_chunk)
104        .min(array_len);
105    local_start..local_end
106}
107
108/// Patches a chunk of decoded values.
109///
110/// # Arguments
111///
112/// * `decoded_values` - Mutable slice of decoded values to be patched
113/// * `patches_indices` - Indices indicating which positions to patch
114/// * `patches_values` - Values to apply at the patched indices
115/// * `patches_offset` - Absolute position where the slice starts
116/// * `chunk_offsets_slice` - Slice containing offsets for each chunk
117/// * `chunk_idx` - Index of the chunk to patch
118/// * `offset_within_chunk` - Number of patches to skip at the start of the first chunk
119pub fn patch_chunk<T, I, C>(
120    decoded_values: &mut [T],
121    patches_indices: &[I],
122    patches_values: &[T],
123    patches_offset: usize,
124    chunk_offsets_slice: &[C],
125    chunk_idx: usize,
126    offset_within_chunk: usize,
127) where
128    T: NativePType,
129    I: UnsignedPType,
130    C: UnsignedPType,
131{
132    // Compute base_offset from the first chunk offset.
133    let base_offset: usize = chunk_offsets_slice[0].as_();
134
135    // Use the same logic as patches slice implementation for calculating patch ranges.
136    let patches_start_idx =
137        (chunk_offsets_slice[chunk_idx].as_() - base_offset).saturating_sub(offset_within_chunk);
138    // Clamp: chunk_offsets are sliced at chunk granularity but patches at element
139    // granularity, so the next chunk offset may exceed the actual patches length.
140    let patches_end_idx = if chunk_idx + 1 < chunk_offsets_slice.len() {
141        (chunk_offsets_slice[chunk_idx + 1].as_() - base_offset)
142            .saturating_sub(offset_within_chunk)
143            .min(patches_indices.len())
144    } else {
145        patches_indices.len()
146    };
147
148    let chunk_start = chunk_range(chunk_idx, patches_offset, /* ignore */ usize::MAX).start;
149
150    for patches_idx in patches_start_idx..patches_end_idx {
151        let chunk_relative_index =
152            (patches_indices[patches_idx].as_() - patches_offset) - chunk_start;
153        decoded_values[chunk_relative_index] = patches_values[patches_idx];
154    }
155}
156
157#[cfg(test)]
158mod tests {
159    use std::sync::LazyLock;
160
161    use vortex_buffer::buffer;
162    use vortex_session::VortexSession;
163
164    use super::*;
165    use crate::VortexSessionExecute;
166    use crate::assert_arrays_eq;
167    use crate::validity::Validity;
168
169    static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
170
171    /// Regression: patch_chunk must not OOB when chunk_offsets (chunk granularity)
172    /// reference more patches than patches_indices (element granularity) contains.
173    #[test]
174    fn patch_chunk_no_oob_on_mid_chunk_slice() {
175        let mut decoded_values = vec![0.0f64; PATCH_CHUNK_SIZE];
176        // 10 patches, but chunk_offsets claim 15 exist past offset adjustment.
177        let patches_indices: Vec<u64> = (0..10)
178            .map(|i| (PATCH_CHUNK_SIZE as u64) + i * 10)
179            .collect();
180        let patches_values: Vec<f64> = (0..10).map(|i| (i + 1) as f64 * 100.0).collect();
181        // chunk_offsets [5, 12, 20]: for chunk_idx=1 with offset_within_chunk=3,
182        // unclamped end = (20-5)-3 = 12, which exceeds patches len of 10.
183        let chunk_offsets: Vec<u32> = vec![5, 12, 20];
184
185        patch_chunk(
186            &mut decoded_values,
187            &patches_indices,
188            &patches_values,
189            0,
190            &chunk_offsets,
191            1,
192            3,
193        );
194
195        let mut expected = vec![0.0; PATCH_CHUNK_SIZE];
196        for (index, value) in [
197            (40, 500.0),
198            (50, 600.0),
199            (60, 700.0),
200            (70, 800.0),
201            (80, 900.0),
202            (90, 1_000.0),
203        ] {
204            expected[index] = value;
205        }
206        assert_eq!(decoded_values, expected);
207    }
208
209    #[test]
210    fn patch_sliced() {
211        let mut ctx = SESSION.create_execution_ctx();
212        let input = PrimitiveArray::new(buffer![2u32; 10], Validity::AllValid);
213        let sliced = input.slice(2..8).unwrap();
214        assert_arrays_eq!(
215            sliced,
216            PrimitiveArray::new(buffer![2u32; 6], Validity::AllValid),
217            &mut ctx
218        );
219    }
220}