From 7dfe1ffb9485980ce648db2de547cee5b250502d Mon Sep 17 00:00:00 2001 From: Joe Ardent Date: Tue, 9 Apr 2024 15:50:26 -0700 Subject: [PATCH] spiff the readme --- README.md | 103 ++++++++++++++++--------------------------------- src/bin/gen.rs | 8 +++- 2 files changed, 39 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index 4813c01..44ac5c4 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/src/bin/gen.rs b/src/bin/gen.rs index aa71586..683becc 100644 --- a/src/bin/gen.rs +++ b/src/bin/gen.rs @@ -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);