memtable - Inmemory tables for use in Rust
Overview
memtable provides a collection of table-oriented features for use inmemory.
This crate acts as the aggregator of all subcrates such as memtable-core
and memtable-macros
and should be the only crate imported when using
features from either.
Installation
At its core, you can import the dependency by adding the following to your
Cargo.toml
:
[]
= "0.2"
In the situation where you would like to derive typed tables based on
user-defined structs, you can include the macros
feature:
[]
= { = "0.2", = ["macros"] }
no-std support
Additionally, this library has support for no_std
, both with and without
inclusion of alloc
. This is done by turning off default features (std
is
the only default feature). From there, if you would like to include alloc
support, then add that feature:
[]
# For no_std without alloc support
= { = "0.2", = false }
# For no_std with alloc support
= { = "0.2", = false, = ["alloc"] }
Please keep in mind that relying only on the core
made available by default
will limit your table options to FixedTable
. You are also still able to use
the macros
feature to derive typed tables, but you must explicitly set the
mode to fixed
.
Usage
Most often, you will want to import the prelude
to bring in relevant
traits and structs:
use *;
// Create a 2x3 (row x column) table of integers
let mut table = from;
// Examine one of the values, replace it, and examine again
assert_eq!;
table = 999;
assert_eq!;
The Tables
In the core library, you will find four primary tables:
DynamicTable
: table with a dynamic capacity for rows & columnsFixedTable
: table with a fixed capacity for rows & columnsFixedRowTable
: table with a fixed capacity for rows & dynamic capacity for columnsFixedColumnTable
: table with a dynamic capacity for rows & fixed capacity for columns
The Traits
Table
: primary trait that exposes majority of common operations to perform on tablesCellIter
: common trait that table iterators focused on individual cells that enables zipping with a cell's position and getting the current row & column of the iterator
The Features
Alongside the essentials, the library also provides several features that provide extensions to the table arsenal:
- alloc: opts into the alloc crate in the situation that
no_std
is in effect - csv: enables
FromCsv
(convert CSV into an inmemory table) andToCsv
(convert an inmemory table to CSV) - cell: enables
Cell2
and more up toCell26
, which represent generic enums that can be used as the data type for a table to enable multiple data types within a table (e.g.DynamicTable<Cell2<String, bool>>
) - macros: enables
Table
macro to derive new struct that implements theTable
trait to be able to store some struct into a dedicated, inmemory table - serde: enables serde support on all table & cell implementations
- sled: enables
SledTable
, which provides persistent storage on top of other tables via the sled database - std: (enabled by default) opts into the std library; if removed then
no_std
is enabled
The Macros
Currently, there is a singular macro, Table
, which is used to
derive a table to contain zero or more of a specific struct.
use Table;
// Derives a new struct, User{Table}, that can contain instances of User
// that are broken up into their individual fields
let mut table = new;
// Inserting is straightforward as a User is considered a singular row
table.push_row;
// You can also pass in a tuple of the fields in order of declaration
table.push_row;
// Retrieval by row will provide the fields by ref as a tuple
let = table.row.unwrap;
assert_eq!;
assert_eq!;
// Tables of course provide a variety of other methods to inspect data
let mut names = table.name_column;
assert_eq!;
assert_eq!;
assert_eq!;