From 43044bd37f3febe2275def51dad5f3de2e561bce Mon Sep 17 00:00:00 2001
From: Daniel Reis <idanielreiss@gmail.com>
Date: Mon, 13 May 2024 06:19:33 +0100
Subject: [PATCH] docs: add context to timeuuid using v1 feature (#980)

* docs: adding context to timeuuid using v1 feature

* docs: adding context to timeuuid creation

* docs: adding context to timeuuid using v1 feature
---
 Cargo.lock.msrv                    |  7 ++++
 docs/source/data-types/timeuuid.md | 66 ++++++++++++++++++++++++++----
 examples/Cargo.toml                |  2 +-
 3 files changed, 65 insertions(+), 10 deletions(-)

diff --git a/Cargo.lock.msrv b/Cargo.lock.msrv
index ed60c12bcf..079fe63ef3 100644
--- a/Cargo.lock.msrv
+++ b/Cargo.lock.msrv
@@ -94,6 +94,12 @@ dependencies = [
  "syn 2.0.32",
 ]
 
+[[package]]
+name = "atomic"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c59bdb34bc650a32731b31bd8f0829cc15d24a708ee31559e0bb34f2bc320cba"
+
 [[package]]
 name = "atty"
 version = "0.2.14"
@@ -1998,6 +2004,7 @@ version = "1.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "79daa5ed5740825c40b389c5e50312b9c86df53fccd33f281df655642b43869d"
 dependencies = [
+ "atomic",
  "getrandom",
 ]
 
diff --git a/docs/source/data-types/timeuuid.md b/docs/source/data-types/timeuuid.md
index 2e4679f9e8..0f0349648f 100644
--- a/docs/source/data-types/timeuuid.md
+++ b/docs/source/data-types/timeuuid.md
@@ -1,8 +1,8 @@
 # Timeuuid
 
-`Timeuuid` is represented as `value::CqlTimeuuid`.
-`value::CqlTimeuuid` is a wrapper  for `uuid::Uuid` with custom ordering logic
-which follows Scylla/Cassandra semantics.
+The `Timeuuid` type is represented as `value::CqlTimeuuid`.
+
+Also, `value::CqlTimeuuid` is a wrapper for `uuid::Uuid` with custom ordering logic which follows Scylla/Cassandra semantics.
 
 ```rust
 # extern crate scylla;
@@ -15,16 +15,64 @@ use scylla::frame::value::CqlTimeuuid;
 
 // Insert some timeuuid into the table
 let to_insert: CqlTimeuuid = CqlTimeuuid::from_str("8e14e760-7fa8-11eb-bc66-000000000001")?;
+
 session
     .query("INSERT INTO keyspace.table (a) VALUES(?)", (to_insert,))
     .await?;
 
-// Read timeuuid from the table
-if let Some(rows) = session.query("SELECT a FROM keyspace.table", &[]).await?.rows {
-    for row in rows.into_typed::<(CqlTimeuuid,)>() {
-        let (timeuuid_value,): (CqlTimeuuid,) = row?;
-    }
+// Read Timeuuid from the table
+let result = session.query("SELECT a FROM keyspace.table", &[]).await?;
+
+let mut iter = result.rows_typed::<(CqlTimeuuid, )>()?;
+
+while let Some((timeuuid,)) = iter.next().transpose()? {
+    println!("Read a value from row: {}", timeuuid);
 }
 # Ok(())
 # }
-```
\ No newline at end of file
+```
+
+## Creating your own Timeuuid
+
+To create your own `Timeuuid` objects from timestamp-based `uuid` v1, you need to enable the feature `v1` of `uuid` crate using:
+
+```shell
+cargo add uuid -F v1
+```
+
+and now you're gonna be able to use the `uuid::v1` features: 
+
+```rust
+# extern crate uuid;
+# extern crate scylla;
+# use scylla::Session;
+# use std::error::Error;
+# use std::str::FromStr;
+use scylla::IntoTypedRows;
+use scylla::frame::value::CqlTimeuuid;
+use uuid::Uuid;
+# async fn check_only_compiles(session: &Session) -> Result<(), Box<dyn Error>> {
+
+// Tip: you can use random stable numbers or your MAC Address
+let node_id = [0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC];
+
+// Build your Timeuuid with the current timestamp
+let to_insert = CqlTimeuuid::from(Uuid::now_v1(&node_id));
+
+session
+    .query("INSERT INTO keyspace.table (a) VALUES(?)", (to_insert,))  
+    .await?;
+
+// Read Timeuuid from the table
+let result = session.query("SELECT a FROM keyspace.table", &[]).await?;
+
+let mut iter = result.rows_typed::<(CqlTimeuuid, )>()?;
+
+while let Some((timeuuid,)) = iter.next().transpose()? {
+    println!("Read a value from row: {}", timeuuid);
+}
+# Ok(())
+# }
+```
+
+Learn more about UUID::v1 [here](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)).
\ No newline at end of file
diff --git a/examples/Cargo.toml b/examples/Cargo.toml
index b068ee9e3c..15e8f02074 100644
--- a/examples/Cargo.toml
+++ b/examples/Cargo.toml
@@ -16,7 +16,7 @@ tracing = "0.1.25"
 tracing-subscriber = { version = "0.3.14", features = ["env-filter"] }
 chrono = { version = "0.4", default-features = false }
 time = { version = "0.3.22" }
-uuid = "1.0"
+uuid = { version = "1.0", features = ["v1"]}
 tower = "0.4"
 stats_alloc = "0.1"
 clap = { version = "3.2.4", features = ["derive"] }