Indxvec
The following will import everything
use ;
Description
This crate is lightweight and has no dependencies. The methods of all four traits can be functionally chained together to achieve numerous manipulations of vectors and their indices in compact form.
The facilities provided are:
- ranking, sorting (merge sort and hash sort), merging, searching, indexing, selecting, partitioning
- many useful operations on generic vectors and their indices
- set operations
- serialising generic slices and slices of vectors to Strings:
to_plainstr()
- printing generic slices and slices of vectors:
pvec()
- writing generic slices and slices of vectors to files:
wvec(&mut f)
- coloured pretty printing (ANSI terminal output, mainly for testing)
- macro
here!()
for more informative errors reporting
It is highly recommended to read and run tests/tests.rs
to learn from examples of usage. Use a single thread to run them. It may be a bit slower but it will write the results in the right order:
Struct and utility functions
use ;
- Struct
Minmax
is holds minimum and maximum values of aVec
and their indices. here!()
is a macro giving the filename, line number and function name of the place from where it was invoked. It can be interpolated into any error/tracing messages and reports.pub fn tof64<T>(s: &[T]) -> Vec<f64>...
utility that converts generic (numeric) Vecs toVec<f64>
.
Trait Indices
use ;
The methods of this trait are implemented for slices of subscripts, i.e. they take the type &[usize]
as input (self) and produce new index Vec<usize>
, new data vector Vec<T>
or Vec<f64>
, or other results, as appropriate. Please see the Glossary below for descriptions of the indices and operations on them.
/// Methods to manipulate indices of `Vec<usize>` type.
Trait Vecops
use ;
The methods of this trait are applicable to generic slices &[T]
(the data). Thus they will work on all Rust primitive numeric end types, such as f64. They can also work on slices holding any arbitrarily complex end type T
, as long as the required traits, PartialOrd
and/or Copy
, are implemented for T
.
/// Methods to manipulate Vecs
Trait Mutsort
use ;
This trait contains muthashsort
, which overwrites self
with sorted data. When we do not need to keep the original order, this is the most efficient way to sort.
Nota bene: muthashsort
really wins on longer Vecs. For about one thousand items upwards, it is on average about 25%-30% faster than the default Rust (Quicksort) sort_unstable
.
Trait Printing
use Printing; // the trait methods
use *; // the colour constants
This trait provides utility methods to 'stringify' (serialise) generic slices and slices of Vec
s. Also, methods for writing or printing them. Optionally, it enables printing them in bold ANSI terminal colours for adding emphasis. See tests/tests.rs
for examples of usage.
The methods of this trait are implemented for generic individual items T
, for slices &[T]
for slices of slices &[&[T]]
and for slices of vecs &[Vec<T>]
. Note that these types are normally unprintable in Rust (do not have Display
implemented).
The following methods: .to_plainstr
, .to_str()
, .gr()
, .rd()
, .yl()
.bl()
, .mg()
, .cy()
convert all these types to printable strings. The colouring methods just add the relevant colouring to the formatted output of .to_str()
.
fn wvec(self,f:&mut File) -> Result<(), io::Error> where Self: Sized;
writes plain space separated values (.ssv
) to files, possibly raising io::Error(s).
fn pvec(self) where Self: Sized;
prints to stdout.
For finer control of the colouring, import the colour constants from module printing
and use them in any formatting strings manually. For example,
switching colours:
use *; // ANSI colours constants
println!;
Note that all of these methods and interpolations set their own new colour regardless of the previous settings. Interpolating {UN}
resets the terminal to its default foreground rendering.
UN
is automatically appended at the end of strings produced by the colouring methods rd()..cy()
. Be careful to always close with one of these, or explicit {UN}
, otherwise all the following output will continue with the last selected colour foreground rendering.
Example from tests/tests.rs
:
println!;
memsearch
returns Option(None)
, when midval
is not found in vm
. Here, None
will be printed in red, while any found item will be in green. This is also an example of how to process Option
s without long-winded match
statements.
Glossary
-
Sort Index - is obtained by stable merge sort
sort_indexed
or byhashsort_indexed
. The original data is immutable (unchanged). The sort index produced is a list of subscripts to the data, such that the first subscript identifies the smallest item in the data, and so on (in ascending order). Suitable for bulky data that are not easily moved. It answers the question: what data item occupies a given sort position? -
Reversing an index - Sort Index can be reversed, by standard reversal operation
revindex()
. This has the effect of changing between ascending/descending sort orders without re-sorting or reversing the (possibly bulky) actual data. -
Rank Index - corresponds to the given data order, listing the sort positions (ranks) for the data items, e.g.the third entry in the rank index gives the rank of the third data item. Some statistical measures require ranks of data. It answers the question: what is the sort position of a given data item?
-
Inverting an index - Sort Index and Rank Index are mutually inverse. Thus they can be easily switched by
invindex()
. This is usually the best way to obtain a Rank Index. They will both be equal to0..n
for data that is already in order. -
Complement of an index - beware that the standard reversal will not convert directly between ascending and descending ranks. For this purpose, it is necessary to use
complindex()
. Alternatively, to applyinvindex()
to a descending sort index. -
Unindexing - given a sort index and some data,
unindex()
will reorder the data into the new order defined by the sort index. It can be used to efficiently transform lots of data vectors into the same (fixed) order. For example: Suppose we have vectors:keys
anddata_1..data_n
, not explicitly joined together in some bulky Struct elements. The sort index obtained bykeys.sort_indexed()
can then be efficiently applied to sort all the data vectors.
Release Notes (Latest First)
Version 1.2.3 - Added binsearch_indexed
and binsearchdesc_indexed
and their tests, for symmetry with memsearch
versions which only search for members, whereas binsearch
finds order position for a non-member.
Version 1.2.2 - Minor test clarification. Expanded the glossary.
Version 1.2.1 - Removed the functions module merge.rs
, it has been replaced by traits Vecops
and Mutsort
. Improved hashsorts. Added some more comments. Added short glossary.
Version 1.2.0 - Changed functions in module merge.rs
to trait methods in two new traits: Vecops
and Mutsort
. Applying trait methods is more idiomatic and easier to read when chained. Narrowed down some trait constraints. Kept the old functions for now for backwards compatibility but they will be removed in the next version to save space.
Version 1.1.9 - Added method to_plainstr()
to Printing
trait to ease writing plain format to files.
Version 1.1.8 - Added method pvec(self)
to Printing
trait. It prints Vec
s to stdout
. Completed all six ANSI terminal primary bold colours. Moved their constants to module printing.rs
. Renamed red()
to rd()
for consistent two letter names. Updated and reorganised readme.
Version 1.1.7 - Added method wvec(self,&mut f)
to Printing. It writes vectors to file f and passes up errors. Added colour bl()
. Added printing test. Prettier readme.md.
Version 1.1.6 - Added simple partition
into three sets (lt,eq,gt).
Version 1.1.5 - Updated dev dependency to ran = "^0.3". Changed partition_indexed
to include equal set. Tweaked printing layout.
Version 1.1.4 - Minor change: hashsort
min,max arguments type changed from T to f64. This is more convenient for a priori known data range limits. Also to be the same as for hashsort_indexed
. Added newindex
and minmax_slice
functions. Updated readme file.
Version 1.1.3 - hashsort
renamed to hashsort_indexed
, in keeping with the naming convention here. New plain hashsort
added: it sorts &mut[T]
in place, just like does the default Rust sort. Suitable for long explicit sorts.
Version 1.1.2 - Added .red()
method to Printing
. Some tidying up of tests.rs
and the docs. hashsort
improved.
Version 1.1.0 - Added superfast n-recursive hashsort
. Suitable for multithreading (to do).
Version 1.0.9 - Minor changes to testing.rs to better test ran
.
Version 1.0.8 - Dependencies reorganization to minimise the footprint. The random numbers generation has now been moved to its own new crate ran
and added here just as a development dependency where it rightfully belongs.
Version 1.0.7 - Renamed function occurs
to occurs_multiple
and added a simple linear count of item occurrences: occurs
.
Version 1.0.6 - Some cosmetic changes to the code, readme and tests, no change of functionality.
Version 1.0.5 - Added partition_indexed
for partitioning into two sets of indices about a pivot. Moved all random number generating functions into new module random.rs
(import changed to: random::*
). Moved the implementations of Printing trait to new module printing.rs
(this has no effect on users).
Version 1.0.4 - here!() now highlights the (first) error in bold red. Added fast random number generation functions ranf64, ranv64, ranvu8, ranvvf64, rannvvu8
.
Version 1.0.3 - Added utilities functions maxt, mint, minmaxt
. Rationalised the functions for printing generic slices and slices of vectors. They are now turned into two chainable methods in trait Printing
: .to_str()
and .gr()
. The latter also serialises slices to strings but additionally makes them bold green.
Version 1.0.2 - Added function occurs
that efficiently counts occurrences of specified items in a set with repetitions.
Version 1.0.1 - Some code style tidying up. Added function binsearchdesc
for completeness and symmetry with binsearch
.
Version 1.0.0 - indxvec
has been stable for some time now, so it gets promoted to v1.0.0. There are some improvements to README.md
to mark the occasion.