nebkor/julid-rs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

spiff the readme

Browse source
This commit is contained in:
Joe Ardent 2024-04-09 15:50:26 -07:00
parent e0150a2161
commit 7dfe1ffb94
2 changed files with 39 additions and 72 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

103
README.md
View file

@ -73,9 +73,8 @@ are always fresh, it's not possible to easily guess a valid Julid if you already
# How to use
The Julid crate can be used in two different ways: as a regular Rust library, declared in your Rust
project's `Cargo.toml` file (say, by running `cargo add julid-rs`), and used as shown above. There's
a rudimentary [benchmark](https://gitlab.com/nebkor/julid/-/blob/main/examples/benchmark.rs) example
in the repo that shows off most of the Rust API. But the primary use case for me was as a loadable
project's `Cargo.toml` file (say, by running `cargo add julid-rs`), and used as shown in the sample
commandline program (see below). But the primary use case for me was as a loadable
SQLite extension. Both are covered in the [documentation](https://docs.rs/julid-rs/latest/julid/),
but let's go over them here, starting with the extension.
@ -123,11 +122,11 @@ For a table created like:
create table if not exists watches (
id blob not null primary key default (julid_new()),
kind int not null, -- enum for movie or tv show or whatev
title text not null, -- this has a secondary index
title text not null,
length int,
release_date int,
release_date date,
added_by blob not null,
last_updated int not null default (unixepoch()),
last_updated date not null default CURRENT_TIMESTAMP,
foreign key (added_by) references users (id)
);
```
@ -153,63 +152,28 @@ the C interface, which is inherently unsafe. If you are not building the plugin,
## Inside a Rust program
Of course, you can also use it outside of a database; the `Julid` type is publicly exported. There's
a simple benchmark in the examples folder of the repo, the important parts of which look like:
a simple commandline program in `src/bin/gen.rs`, and can be run like `cargo run --bin julid-gen`
(or you can `cargo install julid-rs` to get the `julid-gen` program installed on your computer),
which will generate and print one Julid. If you want to see its component pieces, grab the Julid
printed from it, and then run it with the `-d` flag:
``` rust
use julid::Julid;
fn main() {
/* snip some stuff */
let start = Instant::now();
for _ in 0..num {
v.push(Julid::new());
}
let end = Instant::now();
let dur = (end - start).as_micros();
for id in v.iter() {
eprintln!(
"{id}: created_at {}; counter: {}; sortable: {}",
id.created_at(),
id.counter(),
id.sortable()
);
}
println!("{num} Julids generated in {dur}us");
```
$ julid-gen 4
01HV2G2ATR000CJ2WESB7CVC19
01HV2G2ATR000K1AGQPKMX5H0M
01HV2G2ATR001CM27S59BHZ25G
01HV2G2ATR001WPJ8BS7PZHE6A
$ julid-gen -d 01HV2G2ATR001WPJ8BS7PZHE6A
Created at: 2024-04-09 22:36:11.992 UTC
Monotonic counter: 3
Random: 14648252224908081354
```
If you were to run it on a computer like mine (AMD Ryzen 9 3900X, 12-core, 2.2-4.6 GHz), you might
see something like this:
The help is useful:
``` text
$ cargo run --example=benchmark --release -- -n 30000 2> /dev/null
30000 Julids generated in 1240us
```
That's about 24,000 IDs/millisecond; 24 *MILLION* per second!
The default optional Cargo features include implementations of traits for getting Julids into and
out of SQLite with [SQLx](https://github.com/launchbadge/sqlx), and for generally
serializing/deserializing with [Serde](https://serde.rs/), via the `sqlx` and `serde` features,
respectively.
Something to note: don't enable the `plugin` feature in your Cargo.toml if you're using this crate
inside your Rust application, especially if you're *also* loading it as an extension in SQLite in
your application. You'll get a long and confusing runtime panic due to there being multiple
entrypoints defined with the same name.
## On the command line
An even simpler program than the benchmark called `julid-gen` is available to install via cargo:
`cargo install julid-rs --no-default-features`
And then using it is as simple as,
``` text
$ julid-gen -h
Generate and print Julids
Generate, print, and parse Julids
Usage: julid-gen [OPTIONS] [NUM]
@ -221,21 +185,20 @@ Options:
-a, --answer The answer to the meaning of Julid
-h, --help Print help
-V, --version Print version
$ julid-gen
01H9DYRVDX0001X0RE5Y7XFGBC
$ julid-gen 3
01H9DYT48E000EK2EH7P67N8GG
01H9DYT48E000ZBKXVZ91HEZX4
01H9DYT48E0012VX89PYX4HDKP
$ julid-gen -d 01H9DYT48E0012VX89PYX4HDKP
Created at: 2023-09-03 16:42:57.678 UTC
Monotonic counter: 2
Entropy: 3311563785709860470
```
The whole program is just 34 lines, so check it out.
The default optional Cargo features include implementations of traits for getting Julids into and
out of SQLite with [SQLx](https://github.com/launchbadge/sqlx), and for generally
serializing/deserializing with [Serde](https://serde.rs/), via the `sqlx` and `serde` features,
respectively.
Something to note: don't enable the `plugin` feature in your Cargo.toml if you're using this crate
inside your Rust application, especially if you're *also* loading it as an extension in SQLite in
your application. You'll get a long and confusing runtime panic due to there being multiple
entrypoints defined with the same name.
# Thanks
This project wouldn't have happened without a lot of inspiration (and a little shameless stealing)

8
src/bin/gen.rs
View file

@ -2,7 +2,11 @@ use clap::Parser;
use julid::Julid;
#[derive(Debug, Parser)]
#[command(author, version = "1.61803398", about = "Generate and print Julids")]
#[command(
author,
version = "1.618033988",
about = "Generate, print, and parse Julids"
)]
struct Cli {
#[clap(
help = "Print the components of the given Julid",
@ -27,7 +31,7 @@ fn main() {
if let Ok(ts) = Julid::from_str(&ts) {
println!("Created at:\t\t{}", ts.created_at());
println!("Monotonic counter:\t{}", ts.counter());
println!("Entropy:\t\t{}", ts.random());
println!("Random:\t\t\t{}", ts.random());
} else {
eprintln!("Could not parse input '{}' as a Julid", ts);
std::process::exit(1);