scolapasta_aref/
lib.rs

1#![warn(clippy::all, clippy::pedantic, clippy::undocumented_unsafe_blocks)]
2#![allow(
3    clippy::let_underscore_untyped,
4    reason = "https://github.com/rust-lang/rust-clippy/pull/10442#issuecomment-1516570154"
5)]
6#![allow(
7    clippy::question_mark,
8    reason = "https://github.com/rust-lang/rust-clippy/issues/8281"
9)]
10#![allow(clippy::manual_let_else, reason = "manual_let_else was very buggy on release")]
11#![allow(clippy::missing_errors_doc, reason = "A lot of existing code fails this lint")]
12#![allow(
13    clippy::unnecessary_lazy_evaluations,
14    reason = "https://github.com/rust-lang/rust-clippy/issues/8109"
15)]
16#![cfg_attr(
17    test,
18    allow(clippy::non_ascii_literal, reason = "tests sometimes require UTF-8 string content")
19)]
20#![allow(unknown_lints)]
21#![warn(
22    missing_copy_implementations,
23    missing_debug_implementations,
24    missing_docs,
25    rust_2024_compatibility,
26    trivial_casts,
27    trivial_numeric_casts,
28    unused_qualifications,
29    variant_size_differences
30)]
31#![forbid(unsafe_code)]
32// Enable feature callouts in generated documentation:
33// https://doc.rust-lang.org/beta/unstable-book/language-features/doc-cfg.html
34//
35// This approach is borrowed from tokio.
36#![cfg_attr(docsrs, feature(doc_cfg))]
37#![cfg_attr(docsrs, feature(doc_alias))]
38
39//! Functions for working with Ruby containers that respond to `#[]` or "aref".
40//!
41//! # Examples
42//!
43//! Index into arrays:
44//!
45//! ```
46//! # fn example() -> Option<()> {
47//! let data = [1, 2, 3, 4, 5];
48//!
49//! // Positive offset
50//! let offset = 2;
51//! let index = scolapasta_aref::offset_to_index(offset, data.len())?;
52//! assert_eq!(index, 2);
53//! assert_eq!(data[index], 3);
54//!
55//! // Negative offset
56//! let offset = -3;
57//! let index = scolapasta_aref::offset_to_index(offset, data.len())?;
58//! assert_eq!(index, 2);
59//! assert_eq!(data[index], 3);
60//!
61//! // Out-of-bounds offset
62//! let offset = 10;
63//! let index = scolapasta_aref::offset_to_index(offset, data.len())?;
64//! assert_eq!(index, 10);
65//!
66//! // Out-of-bounds negative offset
67//! let offset = -10;
68//! let index = scolapasta_aref::offset_to_index(offset, data.len());
69//! assert_eq!(index, None);
70//! # Some(())
71//! # }
72//! # example().unwrap()
73//! ```
74//!
75//! Index into strings:
76//!
77//! ```
78//! # fn example() -> Option<()> {
79//! let data = "Hello, World!";
80//!
81//! // Positive offset
82//! let offset = 7;
83//! let index = scolapasta_aref::offset_to_index(offset, data.len())?;
84//! assert_eq!(index, 7);
85//! assert_eq!(&data[index..], "World!");
86//!
87//! // Negative offset
88//! let offset = -6;
89//! let index = scolapasta_aref::offset_to_index(offset, data.len())?;
90//! assert_eq!(index, 7);
91//! assert_eq!(&data[index..], "World!");
92//!
93//! // Out-of-bounds offset
94//! let offset = 20;
95//! let index = scolapasta_aref::offset_to_index(offset, data.len())?;
96//! assert_eq!(index, 20);
97//!
98//! // Out-of-bounds negative offset
99//! let offset = -20;
100//! let index = scolapasta_aref::offset_to_index(offset, data.len());
101//! assert_eq!(index, None);
102//! # Some(())
103//! # }
104//! # example().unwrap()
105//! ```
106
107#![no_std]
108
109// Ensure code blocks in `README.md` compile
110#[cfg(doctest)]
111#[doc = include_str!("../README.md")]
112mod readme {}
113
114/// Convert a signed aref offset to a `usize` index into the underlying container.
115///
116/// Negative indexes are interpreted as indexing from the end of the container
117/// as long as their magnitude is less than the given length.
118///
119/// Callers must still check whether the returned index is in bounds for the
120/// container. The returned index may be out of range since this routine can be
121/// used to calculate indexes beyond the length of the container during
122/// assignment (for example, `Array#[]=` may perform length-extension upon an
123/// out-of-bounds index).
124///
125/// # Examples
126///
127/// ```
128/// # fn example() -> Option<()> {
129/// let data = "ABC, 123, XYZ";
130///
131/// let offset = 6;
132/// let index = scolapasta_aref::offset_to_index(offset, data.len())?;
133/// assert_eq!(index, 6);
134/// assert_eq!(&data[index..], "23, XYZ");
135///
136/// let offset = 55;
137/// let index = scolapasta_aref::offset_to_index(offset, data.len())?;
138/// assert_eq!(index, 55);
139///
140/// let offset = -5;
141/// let index = scolapasta_aref::offset_to_index(offset, data.len())?;
142/// assert_eq!(index, 8);
143/// assert_eq!(&data[index..], ", XYZ");
144///
145/// let offset = -44;
146/// let index = scolapasta_aref::offset_to_index(offset, data.len());
147/// assert_eq!(index, None);
148/// # Some(())
149/// # }
150/// # example().unwrap()
151/// ```
152#[must_use]
153pub fn offset_to_index(index: i64, len: usize) -> Option<usize> {
154    // Here's an example of this behavior from `String`. All containers that
155    // respond to `#[]` ("aref") behave similarly.
156    //
157    // ```
158    // [3.0.1] > s = "abc"
159    // => "abc"
160    //
161    // [3.0.1] > s[-2]
162    // => "b"
163    // [3.0.1] > s[-3]
164    // => "a"
165    // [3.0.1] > s[-4]
166    // => nil
167    //
168    // [3.0.1] > s[-2, 10]
169    // => "bc"
170    // [3.0.1] > s[-3, 10]
171    // => "abc"
172    // [3.0.1] > s[-4, 10]
173    //
174    // [3.0.2] > s.byteslice(-2, 10)
175    // => "bc"
176    // [3.0.2] > s.byteslice(-3, 10)
177    // => "abc"
178    // [3.0.2] > s.byteslice(-4, 10)
179    // => nil
180    // => nil
181    // ```
182    match usize::try_from(index) {
183        Ok(index) => Some(index),
184        Err(_) => index
185            .checked_neg()
186            .and_then(|index| usize::try_from(index).ok())
187            .and_then(|index| len.checked_sub(index)),
188    }
189}
190
191#[cfg(test)]
192mod tests {
193    use super::*;
194
195    #[test]
196    fn test_zero_index() {
197        // Test case: `index = 0, len = 0`
198        assert_eq!(offset_to_index(0_i64, 0_usize), Some(0_usize));
199
200        // Test case: `index = 0, len = 1`
201        assert_eq!(offset_to_index(0_i64, 1_usize), Some(0_usize));
202
203        // Test case: `index = 0, len = 10`
204        assert_eq!(offset_to_index(0, 10), Some(0_usize));
205
206        // Test case: `index = 0, len = usize::MAX`
207        assert_eq!(offset_to_index(0_i64, usize::MAX), Some(0_usize));
208    }
209
210    #[test]
211    fn test_positive_index() {
212        // Test case: `index = 1, len = 0`
213        assert_eq!(offset_to_index(1_i64, 0_usize), Some(1_usize));
214
215        // Test case: `index = 1, len = 1`
216        assert_eq!(offset_to_index(1_i64, 1_usize), Some(1_usize));
217
218        // Test case: `index = 1, len = 2`
219        assert_eq!(offset_to_index(1_i64, 2_usize), Some(1_usize));
220
221        // Test case: `index = 1, len = usize::MAX`
222        assert_eq!(offset_to_index(1_i64, usize::MAX), Some(1_usize));
223
224        // Test case: `index = 15, len = 10`
225        assert_eq!(offset_to_index(15, 10), Some(15_usize));
226
227        // Test case: `index = 123, len = 0`
228        assert_eq!(offset_to_index(123_i64, 0_usize), Some(123_usize));
229
230        // Test case: `index = 123, len = 1`
231        assert_eq!(offset_to_index(123_i64, 1_usize), Some(123_usize));
232
233        // Test case: `index = 123, len = 123`
234        assert_eq!(offset_to_index(123_i64, 123_usize), Some(123_usize));
235
236        // Test case: `index = 123, len = 123`
237        assert_eq!(offset_to_index(123_i64, 124_usize), Some(123_usize));
238
239        // Test case: `index = 123, len = 123`
240        assert_eq!(offset_to_index(123_i64, 500_usize), Some(123_usize));
241
242        // Test case: `index = 123, len = usize::MAX`
243        assert_eq!(offset_to_index(123_i64, usize::MAX), Some(123_usize));
244
245        // Test case: `index = i64::MAX, len = 5`
246        #[cfg(target_pointer_width = "64")]
247        assert_eq!(offset_to_index(i64::MAX, 5), Some(usize::try_from(i64::MAX).unwrap()));
248
249        // Test case: `index = i64::MAX, len = usize::MAX`
250        #[cfg(target_pointer_width = "64")]
251        assert_eq!(
252            offset_to_index(i64::MAX, usize::MAX),
253            Some(usize::try_from(i64::MAX).unwrap())
254        );
255
256        // Test case: `index = 100, len = 1000`
257        assert_eq!(offset_to_index(100_i64, 1000_usize), Some(100_usize));
258
259        // Test case: `index = 500, len = 500`
260        assert_eq!(offset_to_index(500_i64, 500_usize), Some(500_usize));
261
262        // Test case: `index = 999, len = 100`
263        assert_eq!(offset_to_index(999_i64, 100_usize), Some(999_usize));
264    }
265
266    #[test]
267    fn test_negative_index() {
268        // Test case: `index = -1, len = 0`
269        assert_eq!(offset_to_index(-1_i64, 0_usize), None);
270
271        // Test case: `index = -1, len = 1`
272        assert_eq!(offset_to_index(-1_i64, 1_usize), Some(0_usize));
273
274        // Test case: `index = -1, len = 2`
275        assert_eq!(offset_to_index(-1_i64, 2_usize), Some(1_usize));
276
277        // Test case: `index = -1, len = 10`
278        assert_eq!(offset_to_index(-1_i64, 10_usize), Some(9_usize));
279
280        // Test case: `index = -1, len = 245`
281        assert_eq!(offset_to_index(-1_i64, 245_usize), Some(244_usize));
282
283        // Test case: `index = -10, len = 0`
284        assert_eq!(offset_to_index(-10_i64, 0_usize), None);
285
286        // Test case: `index = -10, len = 1`
287        assert_eq!(offset_to_index(-10_i64, 1_usize), None);
288
289        // Test case: `index = -10, len = 2`
290        assert_eq!(offset_to_index(-10_i64, 2_usize), None);
291
292        // Test case: `index = -10, len = 10`
293        assert_eq!(offset_to_index(-10_i64, 10_usize), Some(0_usize));
294
295        // Test case: `index = -10, len = 245`
296        assert_eq!(offset_to_index(-10_i64, 245_usize), Some(235_usize));
297
298        // Test case: `index = -123, len = 0`
299        assert_eq!(offset_to_index(-123_i64, 0_usize), None);
300
301        // Test case: `index = -123, len = 1`
302        assert_eq!(offset_to_index(-123_i64, 1_usize), None);
303
304        // Test case: `index = -123, len = 2`
305        assert_eq!(offset_to_index(-123_i64, 2_usize), None);
306
307        // Test case: `index = -123, len = 10`
308        assert_eq!(offset_to_index(-123_i64, 10_usize), None);
309
310        // Test case: `index = -123, len = 245`
311        assert_eq!(offset_to_index(-123_i64, 245_usize), Some(122_usize));
312
313        // Test case: `index = i64::MIN, len = 0`
314        assert_eq!(offset_to_index(i64::MIN, 0_usize), None);
315
316        // Test case: `index = i64::MIN, len = 1`
317        assert_eq!(offset_to_index(i64::MIN, 1_usize), None);
318
319        // Test case: `index = i64::MIN, len = 2`
320        assert_eq!(offset_to_index(i64::MIN, 2_usize), None);
321
322        // Test case: `index = i64::MIN, len = 10`
323        assert_eq!(offset_to_index(i64::MIN, 10_usize), None);
324
325        // Test case: `index = i64::MIN, len = 245`
326        assert_eq!(offset_to_index(i64::MIN, 245_usize), None);
327    }
328
329    #[test]
330    fn test_out_of_bounds_positive_offset() {
331        // Test case: Offset greater than or equal to length
332        //
333        // ```
334        // [3.2.2] > a = [1,2,3,4,5]
335        // => [1, 2, 3, 4, 5]
336        // [3.2.2] > a[10]
337        // => nil
338        // [3.2.2] > a[10] = 'a'
339        // => "a"
340        // [3.2.2] > a
341        // => [1, 2, 3, 4, 5, nil, nil, nil, nil, nil, "a"]
342        // ```
343        assert_eq!(offset_to_index(10, 5), Some(10_usize));
344    }
345
346    #[test]
347    fn test_positive_offset_equal_to_length() {
348        // ```
349        // [3.2.2] > a = [1,2,3,4,5]
350        // => [1, 2, 3, 4, 5]
351        // [3.2.2] > a[5]
352        // => nil
353        // [3.2.2] > a[5, 0]
354        // => []
355        // [3.2.2] > a[5] = 'a'
356        // => "a"
357        // [3.2.2] > a
358        // => [1, 2, 3, 4, 5, "a"]
359        // ```
360        assert_eq!(offset_to_index(5, 5), Some(5_usize));
361    }
362
363    #[test]
364    fn test_negative_offset_of_magnitude_length() {
365        // Test case: Offset equal to negative length
366        //
367        // ```
368        // [3.2.2] > a = [1,2,3,4,5]
369        // => [1, 2, 3, 4, 5]
370        // [3.2.2] > a[-5]
371        // => 1
372        // [3.2.2] > a[-5] = 'a'
373        // => "a"
374        // [3.2.2] > a
375        // => ["a", 2, 3, 4, 5]
376        // ```
377        assert_eq!(offset_to_index(-5, 5), Some(0));
378
379        assert_eq!(offset_to_index(-10, 10), Some(0_usize));
380    }
381
382    #[test]
383    fn test_invalid_negative_offset() {
384        // Test case: Offset less than negative length
385        //
386        // ```
387        // [3.2.2] > a = [1,2,3,4,5]
388        // => [1, 2, 3, 4, 5]
389        // [3.2.2] > a[-10]
390        // => nil
391        // [3.2.2] > a[-10] = 'a'
392        // (irb):5:in `<main>': index -10 too small for array; minimum: -5 (IndexError)
393        // ```
394        assert_eq!(offset_to_index(-10, 5), None);
395    }
396
397    #[test]
398    fn test_edge_cases() {
399        // Test case: Length is zero
400        assert_eq!(offset_to_index(0, 0), Some(0_usize));
401
402        // Test case: Offset is the minimum `i64` value
403        assert_eq!(offset_to_index(i64::MIN, 10), None);
404
405        // Test case: Offset is the maximum `i64` value
406        #[cfg(target_pointer_width = "64")]
407        assert_eq!(offset_to_index(i64::MAX, 10), Some(usize::try_from(i64::MAX).unwrap()));
408
409        // Test case: `index = 0, len = usize::MAX`
410        assert_eq!(offset_to_index(0_i64, usize::MAX), Some(0_usize));
411
412        // Test case: `index = 1, len = usize::MAX`
413        assert_eq!(offset_to_index(1_i64, usize::MAX), Some(1_usize));
414
415        // Test case: `index = -1, len = usize::MAX`
416        assert_eq!(offset_to_index(-1_i64, usize::MAX), Some(usize::MAX - 1));
417
418        // Test case: `index = 10, len = usize::MAX`
419        assert_eq!(offset_to_index(10, usize::MAX), Some(10_usize));
420
421        // Test case: `index = i64::MAX, len = usize::MAX`
422        #[cfg(target_pointer_width = "64")]
423        assert_eq!(
424            offset_to_index(i64::MAX, usize::MAX),
425            Some(usize::try_from(i64::MAX).unwrap())
426        );
427    }
428}
scolapasta_aref/lib.rs

scolapasta_aref/
lib.rs
