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

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(())
 # }
-```
+```
+
+## 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)).

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"] }