Crate memtable[−][src]

Expand description

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:

[dependencies]
memtable = "0.2"

In the situation where you would like to derive typed tables based on user-defined structs, you can include the macros feature:

[dependencies]
memtable = { version = "0.2", features = ["macros"] }

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:

[dependencies]
# For no_std without alloc support
memtable = { version = "0.2", default-features = false }

# For no_std with alloc support
memtable = { version = "0.2", default-features = false, features = ["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 memtable::prelude::*;

// Create a 2x3 (row x column) table of integers
let mut table = FixedTable::from([
    [1, 2, 3],
    [4, 5, 6],
]);

// Examine one of the values, replace it, and examine again
assert_eq!(table[(1, 2)], 6);
table.insert_cell(1, 2, 999);
assert_eq!(table[(1, 2)], 999);

The Tables

In the core library, you will find four primary tables:

DynamicTable: table with a dynamic capacity for rows & columns
FixedTable: table with a fixed capacity for rows & columns
FixedRowTable: table with a fixed capacity for rows & dynamic capacity for columns
FixedColumnTable: 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 tables
iter::CellIter: 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 Extra 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 CSV support and
- exts::csv::FromCsv: convert CSV into an inmemory table
- exts::csv::ToCsv: convert an inmemory table to CSV
cell: enables exts::cell::Cell2 and more up to exts::cell::Cell26, 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 the Table trait to be able to store some struct into a dedicated, inmemory table
serde: enables serde support on all table & cell implementations
sled: enables exts::sled::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 memtable::Table;

#[derive(Table)]
struct User {
    name: &'static str,
    age: u8,
}

// Derives a new struct, User{Table}, that can contain instances of User
// that are broken up into their individual fields
let mut table = UserTable::new();

// Inserting is straightforward as a User is considered a singular row
table.push_row(User {
    name: "Fred Flintstone",
    age: 51,
});

// You can also pass in a tuple of the fields in order of declaration
table.push_row(("Wilma Flintstone", 47));

// Retrieval by row will provide the fields by ref as a tuple
let (name, age) = table.row(0).unwrap();
assert_eq!(*name, "Fred Flintstone");
assert_eq!(*age, 51);

// Tables of course provide a variety of other methods to inspect data
let mut names = table.name_column();
assert_eq!(names.next(), Some(&"Fred Flintstone"));
assert_eq!(names.next(), Some(&"Wilma Flintstone"));
assert_eq!(names.next(), None);

The License

^{Licensed under either of Apache License, Version
2.0 or MIT license at your option.}
_{Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in vimvar by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.}

Modules

exts

Contains extensions to the library based on extra features

iter

Contains iterators and associated traits for traversing portions of tables

list

Contains lists and associated traits for storing items

prelude

Contains relevant top-level traits, structs, and more to make use of this library

Structs

DynamicTable

Represents an inmemory table containing rows & columns of some data T, capable of growing and shrinking in size dynamically

FixedColumnTable

Represents an inmemory table containing rows & columns of some data T with a fixed capacity across columns, but ability to grow dynamically with rows

FixedRowTable

Represents an inmemory table containing rows & columns of some data T with a fixed capacity across rows, but ability to grow dynamically with columns

FixedTable

Represents an inmemory table containing rows & columns of some data T with a fixed capacity across both rows and columns

Position

Represents the position of a cell in a table