Crate flatk

Flat layout abstraction toolkit.

This library defines low level primitives for organizing flat data arrays into meaningful structures without copying the data.

For example if we have an array of floats representing 3D positions, we may wish to interpret them as triplets:

use flatk::Chunked3;
 
let pos_data = vec![0.0, 0.0, 0.0, 1.0, 1.0, 1.0, 0.0, 1.0, 0.0];
 
let pos = Chunked3::from_flat(pos_data);
 
assert_eq!(pos[0], [0.0; 3]);
assert_eq!(pos[1], [1.0; 3]);
assert_eq!(pos[2], [0.0, 1.0, 0.0]);

Similarly we may have a non-uniform grouping of array elements, which may for represent a directed graph:

use flatk::Chunked;
 
let neighbours = vec![1, 2, 0, 1, 0, 1, 2];
 
let neigh = Chunked::from_sizes(vec![1,2,1,3], neighbours);
 
assert_eq!(&neigh[0][..], &[1][..]);
assert_eq!(&neigh[1][..], &[2, 0][..]);
assert_eq!(&neigh[2][..], &[1][..]);
assert_eq!(&neigh[3][..], &[0, 1, 2][..]);

Here neigh defines the following graph:

0<--->1<--->2
^     ^     ^
 \    |    /
  \   |   /
   \  |  /
    \ | /
     \|/
      3

Re-exports

pub use chunked::*;

Modules

chunked
consts	Type aliases for many constants.

Structs

ChunkedNIter
Chunks	A generic version of the Chunks iterator used by slices. This is used by uniformly (but not statically) chunked collections.
Select	A Set that is a non-contiguous, unordered and possibly duplicated selection of some larger collection. S can be any borrowed collection type that implements Set. Note that it doesn't make much sense to have a Select type own the data that it selects from, although it's possible to create one.
Sparse	A Sparse data set S where the sparsity pattern is given by I as select indices into a larger range.
SparseIter
StaticRange	A type of range whose size is determined at compile time. This represents a range [start..start + N::value()]. This aids UniChunked types when indexing.
Subset	A Set that is a non-contiguous subset of some larger collection. B can be any borrowed collection type that implements the Set, and RemovePrefix traits. For iteration of subsets, the underlying type must also implement SplitFirst and SplitAt traits.
SubsetIter
U	Wrapper around typenum types to prevent downstream trait implementations.
UniChunked	UniChunked Assigns a stride N to the specified collection.
UniChunkedIter	Generic static sized chunk iterater appropriate for any lightweight view type collection.

Traits

Array
AsSlice
AtomIterator
AtomMutIterator
BoundedRange	A definition of a bounded range.
ChunkSize	This trait is used to produce the chunk size of a collection if it contains uniformly chunked elements.
Clear
CloneIntoOther	Clone self into a potentially different collection.
CloneWithStorage
Dimension
Dummy	A helper trait for constructing placeholder sets for use in std::mem::replace. These don't necessarily have to correspond to bona-fide sets and can potentially produce invalid sets. For this reason this function can be unsafe since it can generate collections that don't uphold their invariants for the sake of avoiding allocations.
ExtendFromSlice
Get	An index trait for collection types. Here 'i indicates the lifetime of the input while 'o indicates that of the output.
GetIndex	A helper trait analogous to SliceIndex from the standard library.
IntBound	A helper trait to identify valid types for Range bounds for use as Sets.
IntoChunkIterator	This trait generalizes the method chunks available on slices in the standard library. Collections that can be chunked by a runtime stride should implement this behaviour such that they can be composed with ChunkedN types.
IntoFlat	Convert a collection into its underlying representation, effectively stripping any organizational info.
IntoOwned	An analog to the ToOwned trait from std that works for chunked views. As the name suggests, this version of ToOwned takes self by value.
IntoOwnedData	In contrast to IntoOwned, this trait produces a clone with owned data, but potentially borrowed structure of the collection.
IntoParChunkIterator	Parallel version of IntoChunkIterator.
IntoStaticChunkIterator	Iterate over chunks whose size is determined at compile time. Note that each chunk may not be a simple array, although a statically sized chunk of a slice is an array.
IntoView
Isolate	Since we cannot alias mutable references, in order to index a mutable view of elements, we must consume the original mutable reference. Since we can't use slices for general composable collections, its impossible to match against a &mut self in the getter function to be able to use it with owned collections, so we opt to have an interface that is designed specifically for mutably borrowed collections. For composable collections, this is better described by a subview operator, which is precisely what this trait represents. Incidentally this can also work for owned collections, which is why it's called Isolate instead of SubView.
IsolateIndex	A helper trait like GetIndex but for Isolate types.
OwnedSet
PermuteInPlace
Push	Abstraction for pushing elements of type T onto a collection.
PushArrayTo
PushArrayToVec
PushChunk
ReadSet
ReinterpretAsGrouped
RemovePrefix	A helper trait used to help implement the Subset. This trait allows abstract collections to remove a number of elements from the beginning, which is what we need for subsets.
Reserve	A trait that allows the container to allocate additional space without changing any of the data. The container should allocate space for at least n additional elements.
Set	A trait defining a raw buffer of data. This data is typed but not annotated so it can represent anything. For example a buffer of floats can represent a set of vertex colours or vertex positions.
Sort
SplitAt	A helper trait to split a set into two sets at a given index. This trait is used to implement iteration over ChunkedViews.
SplitFirst	Split out the first element of a collection.
SplitOff	A helper trait to split owned sets into two sets at a given index. This trait is used to implement iteration over Chunkeds.
SplitPrefix	Split off a number of elements from the beginning of the collection where the number is determined at compile time.
StaticallySplittable	A marker trait to indicate a collection type that can be chunked. More precisely this is a type that can be composed with types in this crate.
Storage	Get an immutable reference to the underlying storage type.
StorageInto	Transform the access pattern of the underlying storage type. This is useful when the storage is not just a simple Vec or slice but a combination of independent collections.
StorageMut	Get a mutable reference to the underlying storage type.
StorageView
SwapChunks
Truncate	Truncate the collection to be a specified length.
UniChunkable	A trait intended to be implemented on collection types to define the type of a statically sized chunk in this collection. This trait is required for composing with UniChunked.
ValueType	A marker trait to indicate an owned collection type. This is to distinguish them from borrowed slices, which essential to resolve implementation collisions.
View	A trait defining a collection that can be accessed via an immutable (shared) view. This type of view can be cloned and copied.
ViewIterator	A convenience trait to allow generic implementations to call an iterator over the view. This is necessary because the View trait has an explicit lifetime parameter, which makes it difficult or impossible to use in generic functions. For instance it becomes difficult/impossible to impose constraints like Set on View::Type.
ViewMut	A trait defining a collection that can be accessed via a mutable (unique) view.
ViewMutIterator
Viewed	A marker trait to indicate a viewed collection type. Note that collections can be partially viewed, but only completely viewed collections are marked by Viewed.
WriteSet

Functions

multiple_mut_refs_compile_test

Type Definitions

Chunked1
Chunked2
Chunked3
Chunked4
Chunked5
Chunked6
Chunked7
Chunked8
Chunked9
ChunkedN	Define aliases for common uniform chunked types.
SelectView	A borrowed selection.
SparseView	A borrowed view of a sparse collection.
SubsetView	A borrowed subset.
U1
U2
U3
U4
U5
U6
U7
U8
U9
U10
U11
U12
U13
U14
U15
U16