index-ext 0.0.1

Index slices with arbitrary ints and as arrays.
Documentation

Adds more index types.

There are cases where an index type might not be usize, many of them for compatibility reasons. For example, an archive format may choose to always represent its offsets as u32 or the io::Seek trait which uses i64 for that purpose. Translating these indices into the platform native offset type is error prone, potentially lossy, and in case it is done incorrectly leads to subtle platform dependent bugs.

Wouldn't it be better for this conversion to happen implicitly and correctly where the actual indexing takes place? That's precisely what Index provides. (It's a method and a trait of the same name, for both panicking and fallible accessors).

use index_ext::Int;

let fine = [0u8; 2][Int(1u32)];
let also = [0u8; 2][Int(1u128)];

assert_eq!([0u8; 2].get_int(u128::max_value()), None);

Nightly features

  • The RangeTo type is a const generics enabled index that return arrays [T; N] instead of slices. Due to recent advances in parameter deduction, the length parameter need not even be named.

let slice = [0; 4];

use index_ext::array::RangeTo; // Grab an array of three element from a slice. let [r, g, b] = &slice[RangeTo];


## Unfinished features

The marker WIP means it is worked on, Planned that it will be worked on, and Idea that it is
still unevaluated but might be interesting.

[Planned]: An index type `CharAt(n: usize)` that dereferences to the characters of a string at
a particular position, represented by a string wrapper that allows converting into a `char`.
Note that a generic `Chars` would not be constant time which may be surprising if used in index
position.

[Idea]: An index type `InsertWith` for `HashMap` and `BTreeMap` that will construct an
element when an entry is missing, similar to C++, and thus be a panic free alternative. _Maybe_
we could index a `Vec<_>` with this type as well, extending as necessary, but this would again
not be constant time.

[Idea]: An adapter `OrEmpty` that uses `get` internally and substitutes an empty slice instead
of panicking.

## Design notes

The extension traits offered here have a slight ergonomic problem compared to being included in
the standard library. Its `ops::Index` impls on slices are provided by the `SliceIndex` trait.
Since this is a nightly trait _and_ sealed by design we can not use it. However, we also can
not use a generic impl for all `T: crate::SliceIndex<[U]>` as this is forbidden by coherence
rules for foreign types. We thus utilize two kinds of indexing: Implement the Index trait
directly for all concrete applicable types and provide a single newtype which acts as a proxy
for the otherwise unconstrained type parameter of the generic impl. If the types were added to
`core` then this indirection would not be necessary and ergonomics would improve.