diff --git a/src/algorithms/randomness/rand-choose.md b/src/algorithms/randomness/rand-choose.md index d034ece8..1fc8335f 100644 --- a/src/algorithms/randomness/rand-choose.md +++ b/src/algorithms/randomness/rand-choose.md @@ -1,5 +1,3 @@ -[ex-rand-choose]: #ex-rand-choose - ## Create random passwords from a set of user-defined characters [![rand-badge]][rand] [![cat-os-badge]][cat-os] diff --git a/src/algorithms/randomness/rand-custom.md b/src/algorithms/randomness/rand-custom.md index 26eb6eec..7113dbb7 100644 --- a/src/algorithms/randomness/rand-custom.md +++ b/src/algorithms/randomness/rand-custom.md @@ -1,5 +1,3 @@ -[ex-rand-custom]: #ex-rand-custom - ## Generate random values of a custom type [![rand-badge]][rand] [![cat-science-badge]][cat-science] diff --git a/src/algorithms/randomness/rand-dist.md b/src/algorithms/randomness/rand-dist.md index 8aed991d..a562103d 100644 --- a/src/algorithms/randomness/rand-dist.md +++ b/src/algorithms/randomness/rand-dist.md @@ -1,11 +1,8 @@ -[ex-rand-dist]: #ex-rand-dist - - ## Generate random numbers with given distribution [![rand-badge]][rand] [![cat-science-badge]][cat-science] -By default, random numbers are generated with [uniform distribution]. +By default, random numbers have [uniform distribution]. To generate numbers with other distributions you instantiate a distribution, then sample from that distribution using [`IndependentSample::ind_sample`] with help of a random-number diff --git a/src/algorithms/randomness/rand-passwd.md b/src/algorithms/randomness/rand-passwd.md index b2c4fe11..95f1a7e0 100644 --- a/src/algorithms/randomness/rand-passwd.md +++ b/src/algorithms/randomness/rand-passwd.md @@ -1,5 +1,3 @@ -[ex-rand-passwd]: #ex-rand-passwd - ## Create random passwords from a set of alphanumeric characters [![rand-badge]][rand] [![cat-os-badge]][cat-os] diff --git a/src/algorithms/randomness/rand-range.md b/src/algorithms/randomness/rand-range.md index 14f0678d..f414b700 100644 --- a/src/algorithms/randomness/rand-range.md +++ b/src/algorithms/randomness/rand-range.md @@ -18,7 +18,7 @@ fn main() { } ``` -Alternatively, one can use [`Range`] to obtain values with [uniform distribution]. +[`Range`] can obtain values with [uniform distribution]. This has the same effect, but may be faster when repeatedly generating numbers in the same range. @@ -41,6 +41,6 @@ fn main() { } ``` -[`Range`]: https://doc.rust-lang.org/rand/rand/distributions/range/struct.Range.html -[`Rng::gen_range`]: https://doc.rust-lang.org/rand/rand/trait.Rng.html#method.gen_range +[`Range`]: https://doc.rust-lang.org/rand/*/rand/distributions/range/struct.Range.html +[`Rng::gen_range`]: https://doc.rust-lang.org/rand/*/rand/trait.Rng.html#method.gen_range [uniform distribution]: https://en.wikipedia.org/wiki/Uniform_distribution_(continuous) diff --git a/src/algorithms/randomness/rand.md b/src/algorithms/randomness/rand.md index c742541d..370f593e 100644 --- a/src/algorithms/randomness/rand.md +++ b/src/algorithms/randomness/rand.md @@ -1,5 +1,3 @@ -[ex-rand]: #ex-rand - ## Generate random numbers [![rand-badge]][rand] [![cat-science-badge]][cat-science] diff --git a/src/cli/arguments.md b/src/cli/arguments.md index 0e866551..a7b900aa 100644 --- a/src/cli/arguments.md +++ b/src/cli/arguments.md @@ -1,3 +1,3 @@ -{{#include clap-basic.md}} +{{#include arguments/clap-basic.md}} {{#include ../links.md}} diff --git a/src/cli/clap-basic.md b/src/cli/arguments/clap-basic.md similarity index 88% rename from src/cli/clap-basic.md rename to src/cli/arguments/clap-basic.md index e68d4624..26fed208 100644 --- a/src/cli/clap-basic.md +++ b/src/cli/arguments/clap-basic.md @@ -1,9 +1,16 @@ -[ex-clap-basic]: #ex-clap-basic - ## Parse command line arguments [![clap-badge]][clap] [![cat-command-line-badge]][cat-command-line] +This application describes the structure of its command-line interface using +`clap`'s builder style. The [documentation] gives two other possible ways to +instantiate an application. + +In the builder style, `with_name` is the unique identifier that `value_of` will +use to retrieve the value passed. The `short` and `long` options control the +flag the user will be expected to type; short flags look like `-f` and long +flags look like `--file`. + ```rust extern crate clap; @@ -45,19 +52,6 @@ fn main() { } ``` -The `clap` crate is a simple-to-use, efficient, and full-featured library for -parsing command line arguments and subcommands when writing console/terminal -applications. - -The application can describe the structure of its command-line interface using -`clap`'s builder style. The [documentation] gives two other possible ways to -instantiate an application. - -In the builder style, `with_name` is the unique identifier that `value_of` will -use to retrieve the value passed. The `short` and `long` options control the -flag the user will be expected to type; short flags look like `-f` and long -flags look like `--file`. - Usage information is generated by `clap`. The usage for the example application looks like this. diff --git a/src/compression/tar/tar-compress.md b/src/compression/tar/tar-compress.md index c460d16c..0e3d9c33 100644 --- a/src/compression/tar/tar-compress.md +++ b/src/compression/tar/tar-compress.md @@ -1,10 +1,8 @@ -[ex-tar-compress]: #ex-tar-compress - ## Compress a directory into tarball [![flate2-badge]][flate2] [![tar-badge]][tar] [![cat-compression-badge]][cat-compression] -Compresses `/var/log` directory into `archive.tar.gz`. +Compress `/var/log` directory into `archive.tar.gz`. Creates a [`File`] wrapped in [`GzEncoder`] and [`tar::Builder`].
Adds contents of `/var/log` directory recursively into the archive diff --git a/src/compression/tar/tar-decompress.md b/src/compression/tar/tar-decompress.md index 6a8e2a57..895c3930 100644 --- a/src/compression/tar/tar-decompress.md +++ b/src/compression/tar/tar-decompress.md @@ -1,12 +1,11 @@ -[ex-tar-decompress]: #ex-tar-decompress - ## Decompress a tarball [![flate2-badge]][flate2] [![tar-badge]][tar] [![cat-compression-badge]][cat-compression] Decompress ([`GzDecoder`]) and extract ([`Archive::unpack`]) all files from a compressed tarball -named `archive.tar.gz` located in the current working directory. +named `archive.tar.gz` located in the current working directory +to the same location. ```rust,no_run # #[macro_use] diff --git a/src/compression/tar/tar-strip-prefix.md b/src/compression/tar/tar-strip-prefix.md index f63601f3..d9a18510 100644 --- a/src/compression/tar/tar-strip-prefix.md +++ b/src/compression/tar/tar-strip-prefix.md @@ -1,13 +1,9 @@ -[ex-tar-strip-prefix]: #ex-tar-strip-prefix - ## Decompress a tarball while removing a prefix from the paths [![flate2-badge]][flate2] [![tar-badge]][tar] [![cat-compression-badge]][cat-compression] -Strip a path prefix from the entries of a tarball before unpacking them. - -We iterate over the [`Archive::entries`], using [`Path::strip_prefix`] to remove -the specified path prefix (`bundle/logs`) before extracting the [`tar::Entry`] +Iterate over the [`Archive::entries`]. Use [`Path::strip_prefix`] to remove +the specified path prefix (`bundle/logs`). Finally, extract the [`tar::Entry`] via [`Entry::unpack`]. ```rust,no_run diff --git a/src/concurrency/parallel/rayon-any-all.md b/src/concurrency/parallel/rayon-any-all.md index ffc4c8ba..110dd0b6 100644 --- a/src/concurrency/parallel/rayon-any-all.md +++ b/src/concurrency/parallel/rayon-any-all.md @@ -1,5 +1,3 @@ -[ex-rayon-any-all]: #ex-rayon-any-all - ## Test in parallel if any or all elements of a collection match a given predicate [![rayon-badge]][rayon] [![cat-concurrency-badge]][cat-concurrency] diff --git a/src/concurrency/parallel/rayon-iter-mut.md b/src/concurrency/parallel/rayon-iter-mut.md index 4f2f5d65..992727a6 100644 --- a/src/concurrency/parallel/rayon-iter-mut.md +++ b/src/concurrency/parallel/rayon-iter-mut.md @@ -1,11 +1,10 @@ - ## Mutate the elements of an array in parallel [![rayon-badge]][rayon] [![cat-concurrency-badge]][cat-concurrency] The example uses the `rayon` crate, which is a data parallelism library for Rust. `rayon` provides the [`par_iter_mut`] method for any parallel iterable data type. -It lets us write iterator-like chains that execute in parallel. +This is an iterator-like chain that potentially executes in parallel. ```rust extern crate rayon; diff --git a/src/concurrency/parallel/rayon-map-reduce.md b/src/concurrency/parallel/rayon-map-reduce.md index 522c09fc..b5a2aa0a 100644 --- a/src/concurrency/parallel/rayon-map-reduce.md +++ b/src/concurrency/parallel/rayon-map-reduce.md @@ -1,18 +1,15 @@ -[ex-rayon-map-reduce]: #ex-rayon-map-reduce - ## Map-reduce in parallel [![rayon-badge]][rayon] [![cat-concurrency-badge]][cat-concurrency] This example uses [`rayon::filter`], [`rayon::map`], and [`rayon::reduce`] -to calculate the conditional average age of a vector of `Person` objects. - -[`rayon::filter`] allows (in parallel) conditional inclusion of elements from -a collection that satisfy the given predicate. Similarly, [`rayon::map`] and -[`rayon::reduce`] allow us to transform the filtered elements via a unary -operation and reduce them to a single value via a given binary operation, -respectively. Also shows use of [`rayon::sum`], which has the same result as -the reduce operation in this example. +to calculate the average age of `Person` objects whose age is over 30. + +[`rayon::filter`] returns elements from a collection that satisfy the given +predicate. [`rayon::map`] performs an operation on every element, creating a +new iteration, and [`rayon::reduce`] performs an operation given the previous +reduction and the current element. Also shows use of [`rayon::sum`], +which has the same result as the reduce operation in this example. ```rust extern crate rayon; diff --git a/src/concurrency/parallel/rayon-parallel-search.md b/src/concurrency/parallel/rayon-parallel-search.md index 43196bf5..71e6f411 100644 --- a/src/concurrency/parallel/rayon-parallel-search.md +++ b/src/concurrency/parallel/rayon-parallel-search.md @@ -1,5 +1,3 @@ -[ex-rayon-parallel-search]: #ex-rayon-parallel-search - ## Search items using given predicate in parallel [![rayon-badge]][rayon] [![cat-concurrency-badge]][cat-concurrency] @@ -8,11 +6,11 @@ This example uses [`rayon::find_any`] and [`par_iter`] to search a vector in parallel for an element satisfying the predicate in the given closure. If there are multiple elements satisfying the predicate defined in the closure -argument of [`rayon::find_any`], we are only guaranteed that one of them will be -found, but not necessarily that the first will be found. +argument of [`rayon::find_any`], `rayon` returns the first one found, not +necessarily the first one. Also note that the argument to the closure is a reference to a reference -(`&&x`). Please see the discussion on [`std::find`] for additional details. +(`&&x`). See the discussion on [`std::find`] for additional details. ```rust extern crate rayon; diff --git a/src/concurrency/parallel/rayon-parallel-sort.md b/src/concurrency/parallel/rayon-parallel-sort.md index 1b5b37a9..9984f0de 100644 --- a/src/concurrency/parallel/rayon-parallel-sort.md +++ b/src/concurrency/parallel/rayon-parallel-sort.md @@ -1,19 +1,13 @@ -[ex-rayon-parallel-sort]: #ex-rayon-parallel-sort - ## Sort a vector in parallel [![rayon-badge]][rayon] [![rand-badge]][rand] [![cat-concurrency-badge]][cat-concurrency] This example will sort in parallel a vector of Strings. -[1] We start by preallocating a vector of empty Strings, so we can mutate the information in parallel later, -to populate the vector with random Strings. - -[2] `par_iter_mut().for_each` takes a closure and applies it in parallel on all the elements of the vector.
-[3] Inside the passed closure we modify the element in the vector with a 5 character-long String, random generated. - -[4] We have [multiple options] to sort an Iterable data type, we chose here to use [`par_sort_unstable`] -because it is usually faster than [stable sorting] algorithms which `rayon` also supports. +Allocate a vector of empty Strings. `par_iter_mut().for_each` populates random +values in parallel. Although [multiple options] +exist to sort an enumerable data type, [`par_sort_unstable`] +is usually faster than [stable sorting] algorithms. ```rust extern crate rand; diff --git a/src/concurrency/parallel/rayon-thumbnails.md b/src/concurrency/parallel/rayon-thumbnails.md index 62b98501..21e78753 100644 --- a/src/concurrency/parallel/rayon-thumbnails.md +++ b/src/concurrency/parallel/rayon-thumbnails.md @@ -1,12 +1,12 @@ -[ex-rayon-thumbnails]: #ex-rayon-thumbnails - ## Generate jpg thumbnails in parallel [![rayon-badge]][rayon] [![glob-badge]][glob] [![image-badge]][image] [![cat-concurrency-badge]][cat-concurrency] [![cat-filesystem-badge]][cat-filesystem] -This example generates thumbnails for all .jpg in the current directory and saves them in a new folder called `thumbnails`. +This example generates thumbnails for all .jpg files in the current directory +then saves them in a new folder called `thumbnails`. -Files are found using [`glob::glob_with`] to match case insensitively on both `.jpg` and `.JPG`. `rayon` is then used to resize images in parallel using [`par_iter`] along with the `make_thumbnail()` helper function which internally uses [`DynamicImage::resize`]. +[`glob::glob_with`] finds jpeg files in current directory. `rayon` resizes +images in parallel using [`par_iter`] calling [`DynamicImage::resize`]. ```rust,no_run # #[macro_use] diff --git a/src/concurrency/thread/crossbeam-spawn.md b/src/concurrency/thread/crossbeam-spawn.md index 5bdf3d69..201065b8 100644 --- a/src/concurrency/thread/crossbeam-spawn.md +++ b/src/concurrency/thread/crossbeam-spawn.md @@ -1,5 +1,3 @@ -[ex-crossbeam-spawn]: #ex-crossbeam-spawn - ## Spawn a short-lived thread [![crossbeam-badge]][crossbeam] [![cat-concurrency-badge]][cat-concurrency] @@ -9,6 +7,8 @@ for concurrent and parallel programming. [`Scope::spawn`] spawns a new scoped th to terminate before returning from the closure that passed into [`crossbeam::scope`] function, meaning that you can reference data from the calling function. +This example splits the array in half and performs the work in separate threads. + ```rust extern crate crossbeam; diff --git a/src/concurrency/thread/global-mut-state.md b/src/concurrency/thread/global-mut-state.md index 85922ea2..8196cd2a 100644 --- a/src/concurrency/thread/global-mut-state.md +++ b/src/concurrency/thread/global-mut-state.md @@ -1,12 +1,10 @@ -[ex-global-mut-state]: #ex-global-mut-state - ## Maintain global mutable state [![lazy_static-badge]][lazy_static] [![cat-rust-patterns-badge]][cat-rust-patterns] -Declares some global state using [lazy_static]. Since [lazy_static] -creates a globally available `static ref` we also need to wrap our state -in a [`Mutex`] to allow mutation (also see [`RwLock`]). The [`Mutex`] ensures +Declare global state using [lazy_static]. [lazy_static] +creates a globally available `static ref` which requires a [`Mutex`] +to allow mutation (also see [`RwLock`]). The [`Mutex`] wrap ensures the state cannot be simultaneously accessed by multiple threads, preventing race conditions. A [`MutexGuard`] must be acquired to read or mutate the value stored in a [`Mutex`]. diff --git a/src/concurrency/thread/threadpool-fractal.md b/src/concurrency/thread/threadpool-fractal.md index a2fe4060..437fa607 100644 --- a/src/concurrency/thread/threadpool-fractal.md +++ b/src/concurrency/thread/threadpool-fractal.md @@ -1,20 +1,20 @@ -[ex-threadpool-fractal]: #ex-threadpool-fractal - ## Draw fractal dispatching work to a thread pool [![threadpool-badge]][threadpool] [![num-badge]][num] [![num_cpus-badge]][num_cpus] [![image-badge]][image] [![cat-concurrency-badge]][cat-concurrency][![cat-science-badge]][cat-science][![cat-rendering-badge]][cat-rendering] -This example draws a fractal from [Julia set] to an image utilizing a thread pool for computation. +This example generates an image by drawing a fractal from the [Julia set] +with a thread pool for distributed computation. -Firstly, the example allocates memory for output image of given width and height with [`ImageBuffer::new`] -and pre-calculates all possible RGB pixel values using [`Rgb::from_channels`]. -Secondly, creates a new [`ThreadPool`] with thread count equal to number of -logical cores in CPU obtained with [`num_cpus::get`]. -Subsequently, dispatches calculation to thread pool [`ThreadPool::execute`]. +Allocate memory for output image of given width and height with [`ImageBuffer::new`]. +[`Rgb::from_channels`] calculates RGB pixel values. +Create [`ThreadPool`] with thread count equal to number of cores with [`num_cpus::get`]. +[`ThreadPool::execute`] receives each pixel as a separate job. -Lastly, collects calculation results via [`mpsc::channel`] with [`Receiver::recv`], draws them with [`ImageBuffer::put_pixel`] and encodes the final image into `output.png` using [`ImageBuffer::save`]. +[`mpsc::channel`] receives the jobs and [`Receiver::recv`] retrieves them. +[`ImageBuffer::put_pixel`] uses the data to set the pixel color. +[`ImageBuffer::save`] writes the image to `output.png`. ```rust,no_run # #[macro_use] diff --git a/src/concurrency/thread/threadpool-walk.md b/src/concurrency/thread/threadpool-walk.md index 968e97ef..a7cef26f 100644 --- a/src/concurrency/thread/threadpool-walk.md +++ b/src/concurrency/thread/threadpool-walk.md @@ -1,11 +1,12 @@ -[ex-threadpool-walk]: #ex-threadpool-walk - - ## Calculate SHA1 sum of iso files concurrently [![threadpool-badge]][threadpool] [![num_cpus-badge]][num_cpus] [![walkdir-badge]][walkdir] [![ring-badge]][ring] [![cat-concurrency-badge]][cat-concurrency][![cat-filesystem-badge]][cat-filesystem] -This example calculates the SHA1 for every file present in the current directory. A threadpool is created using the number of cpus present in the system with [`num_cpus::get`]. Then every returned by [`Walkdir::new`] is passed into this pool to perform the operations of reading and computing SHA1. At the end the program waits for all jobs to finish. To get better results, compile this program in release mode. +This example calculates the SHA1 for every file with iso extension in the +current directory. A threadpool generates threads equal to the number of cores +present in the system found with [`num_cpus::get`]. [`Walkdir::new`] iterates +the current directory and calls [`execute`] to perform the operations of reading +and computing SHA1 hash. ```rust,no_run # #[macro_use] @@ -83,5 +84,6 @@ fn run() -> Result<()> { # quick_main!(run); ``` +[`execute`]: https://docs.rs/threadpool/*/threadpool/struct.ThreadPool.html#method.execute [`num_cpus::get`]: https://docs.rs/num_cpus/*/num_cpus/fn.get.html [`Walkdir::new`]: https://docs.rs/walkdir/*/walkdir/struct.WalkDir.html#method.new diff --git a/src/cryptography/encryption/pbkdf2.md b/src/cryptography/encryption/pbkdf2.md index 1cfd5a59..f6b186f0 100644 --- a/src/cryptography/encryption/pbkdf2.md +++ b/src/cryptography/encryption/pbkdf2.md @@ -4,7 +4,7 @@ [![ring-badge]][ring] [![data-encoding-badge]][data-encoding] [![cat-cryptography-badge]][cat-cryptography] Uses [`ring::pbkdf2`] to hash a salted password using the PBKDF2 key derivation -function [`pbkdf2::derive`] and then verifies the hash is correct with +function [`pbkdf2::derive`]. Verifies the hash is correct with [`pbkdf2::verify`]. The salt is generated using [`SecureRandom::fill`], which fills the salt byte array with securely generated random numbers. @@ -73,7 +73,7 @@ fn run() -> Result<()> { # quick_main!(run); ``` -[`pbkdf2::derive`]: https://docs.rs/ring/v0.4/ring/pbkdf2/fn.derive.html -[`pbkdf2::verify`]: https://docs.rs/ring/v0.4/ring/pbkdf2/fn.verify.html -[`ring::pbkdf2`]: https://docs.rs/ring/v0.4/ring/pbkdf2/index.html -[`SecureRandom::fill`]: https://docs.rs/ring/*/ring/rand/trait.SecureRandom.html#tymethod.fill +[`pbkdf2::derive`]: https://briansmith.org/rustdoc/ring/pbkdf2/fn.derive.html +[`pbkdf2::verify`]: https://briansmith.org/rustdoc/ring/pbkdf2/fn.verify.html +[`ring::pbkdf2`]: https://briansmith.org/rustdoc/ring/pbkdf2/index.html +[`SecureRandom::fill`]: https://briansmith.org/rustdoc/ring/rand/trait.SecureRandom.html#tymethod.fill diff --git a/src/cryptography/hashing/hmac.md b/src/cryptography/hashing/hmac.md index 8fbd6fe4..fbfe1162 100644 --- a/src/cryptography/hashing/hmac.md +++ b/src/cryptography/hashing/hmac.md @@ -1,4 +1,3 @@ - ## Sign and verify a message with HMAC digest [![ring-badge]][ring] [![cat-cryptography-badge]][cat-cryptography] @@ -35,5 +34,5 @@ fn run() -> Result<()> { # quick_main!(run); ``` -[`hmac::Signature`]: https://docs.rs/ring/v0.4/ring/hmac/struct.Signature.html -[`ring::hmac`]: https://docs.rs/ring/v0.4/ring/hmac/ +[`hmac::Signature`]: https://briansmith.org/rustdoc/ring/hmac/struct.Signature.html +[`ring::hmac`]: https://briansmith.org/rustdoc/ring/hmac/ diff --git a/src/cryptography/hashing/sha-digest.md b/src/cryptography/hashing/sha-digest.md index 2f1be880..64f0d703 100644 --- a/src/cryptography/hashing/sha-digest.md +++ b/src/cryptography/hashing/sha-digest.md @@ -1,4 +1,3 @@ - ## Calculate the SHA-256 digest of a file [![ring-badge]][ring] [![data-encoding-badge]][data-encoding] [![cat-cryptography-badge]][cat-cryptography] @@ -58,5 +57,5 @@ fn run() -> Result<()> { # quick_main!(run); ``` -[`digest::Context`]: https://docs.rs/ring/*/ring/digest/struct.Context.html -[`digest::Digest`]: https://docs.rs/ring/*/ring/digest/struct.Digest.html +[`digest::Context`]: https://briansmith.org/rustdoc/ring/digest/struct.Context.html +[`digest::Digest`]: https://briansmith.org/rustdoc/ring/digest/struct.Digest.html diff --git a/src/data_structures/constant/lazy-constant.md b/src/data_structures/constant/lazy-constant.md index 3ec78300..3de4aa0d 100644 --- a/src/data_structures/constant/lazy-constant.md +++ b/src/data_structures/constant/lazy-constant.md @@ -1,4 +1,3 @@ - ## Declare lazily evaluated constant [![lazy_static-badge]][lazy_static] [![cat-caching-badge]][cat-caching] [![cat-rust-patterns-badge]][cat-rust-patterns] diff --git a/src/data_structures/custom/bitfield.md b/src/data_structures/custom/bitfield.md index 4ff0422b..ffd76789 100644 --- a/src/data_structures/custom/bitfield.md +++ b/src/data_structures/custom/bitfield.md @@ -1,9 +1,8 @@ - ## Define and operate on a type represented as a bitfield [![bitflags-badge]][bitflags] [![cat-no-std-badge]][cat-no-std] -Creates typesafe bitfield type `MyFlags` with help of [`bitflags!`] macro +Creates type safe bitfield type `MyFlags` with help of [`bitflags!`] macro and implements elementary `clear` operation as well as [`Display`] trait for it. Subsequently, shows basic bitwise operations and formatting. diff --git a/src/datetime/duration/checked.md b/src/datetime/duration/checked.md index 1b8bcc40..4a4042f3 100644 --- a/src/datetime/duration/checked.md +++ b/src/datetime/duration/checked.md @@ -1,4 +1,5 @@ ## Perform checked date and time calculations + [![chrono-badge]][chrono] [![cat-date-and-time-badge]][cat-date-and-time] Calculates and displays the date and time two weeks from now using diff --git a/src/datetime/duration/current.md b/src/datetime/duration/current.md index 3c422cf9..4573feb3 100644 --- a/src/datetime/duration/current.md +++ b/src/datetime/duration/current.md @@ -1,4 +1,5 @@ ## Examine the date and time + [![chrono-badge]][chrono] [![cat-date-and-time-badge]][cat-date-and-time] Gets the current UTC [`DateTime`] and its hour/minute/second via [`Timelike`] diff --git a/src/datetime/parse/format.md b/src/datetime/parse/format.md index 6b0e7710..bf8b6552 100644 --- a/src/datetime/parse/format.md +++ b/src/datetime/parse/format.md @@ -1,4 +1,5 @@ ## Display formatted date and time + [![chrono-badge]][chrono] [![cat-date-and-time-badge]][cat-date-and-time] Gets and displays the current time in UTC using [`Utc::now`]. Formats the diff --git a/src/datetime/parse/string.md b/src/datetime/parse/string.md index 57d8e53f..4066f0a3 100644 --- a/src/datetime/parse/string.md +++ b/src/datetime/parse/string.md @@ -1,4 +1,5 @@ ## Parse string into DateTime struct + [![chrono-badge]][chrono] [![cat-date-and-time-badge]][cat-date-and-time] Parses a [`DateTime`] struct from strings representing the well-known formats @@ -52,9 +53,12 @@ fn run() -> Result<()> { [`chrono::format::strftime`]: https://docs.rs/chrono/*/chrono/format/strftime/index.html [`DateTime::format`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.format +[`DateTime::parse_from_rfc2822`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.parse_from_rfc2822 +[`DateTime::parse_from_rfc3339`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.parse_from_rfc3339 [`DateTime::parse_from_str`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.parse_from_str [`DateTime::to_rfc2822`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.to_rfc2822 [`DateTime::to_rfc3339`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.to_rfc3339 +[`DateTime`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html [`NaiveDate`]: https://docs.rs/chrono/*/chrono/naive/struct.NaiveDate.html [`NaiveDateTime`]: https://docs.rs/chrono/*/chrono/naive/struct.NaiveDateTime.html [`NaiveTime`]: https://docs.rs/chrono/*/chrono/naive/struct.NaiveTime.html diff --git a/src/datetime/parse/timestamp.md b/src/datetime/parse/timestamp.md index c08c9e95..d94fd0a8 100644 --- a/src/datetime/parse/timestamp.md +++ b/src/datetime/parse/timestamp.md @@ -28,3 +28,5 @@ fn main() { [`NaiveDateTime::from_timestamp`]: https://docs.rs/chrono/*/chrono/naive/struct.NaiveDateTime.html#method.from_timestamp [`NaiveDateTime::timestamp`]: https://docs.rs/chrono/*/chrono/naive/struct.NaiveDateTime.html#method.timestamp [`NaiveTime::from_hms`]: https://docs.rs/chrono/*/chrono/naive/struct.NaiveTime.html#method.from_hms + +[UNIX timestamp]: https://en.wikipedia.org/wiki/Unix_time diff --git a/src/datetime/parse/timezone.md b/src/datetime/parse/timezone.md index 3739f42a..a0bb508a 100644 --- a/src/datetime/parse/timezone.md +++ b/src/datetime/parse/timezone.md @@ -1,4 +1,5 @@ ## Convert a local time to an another UTC timezone and vice versa + [![chrono-badge]][chrono] [![cat-date-and-time-badge]][cat-date-and-time] Gets the local time and displays it using [`offset::Local::now`] and then converts it to the UTC standard using the [`DateTime::from_utc`] struct method. A time is then converted using the [`offset::FixedOffset`] struct and the UTC time is then converted to UTC+8 and UTC-2. diff --git a/src/development_tools/build_tools.md b/src/development_tools/build_tools.md index f889692b..c5006076 100644 --- a/src/development_tools/build_tools.md +++ b/src/development_tools/build_tools.md @@ -5,28 +5,12 @@ Conventionally, build-time code lives in a **build.rs** file and is commonly ref Common use cases include rust code generation and compilation of bundled C/C++/asm code. See crates.io's [documentation on the matter][build-script-docs] for more information. - - - {{#include build_tools/cc-bundled-static.md}} - - {{#include build_tools/cc-bundled-cpp.md}} {{#include build_tools/cc-defines.md}} {{#include ../links.md}} - - -[`cc::Build::define`]: https://docs.rs/cc/*/cc/struct.Build.html#method.define -[`Option`]: https://doc.rust-lang.org/std/option/enum.Option.html [build-script-docs]: http://doc.crates.io/build-script.html -[cargo-env]: http://doc.crates.io/environment-variables.html#environment-variables-cargo-sets-for-crates -[cc-build-compile]: https://docs.rs/cc/*/cc/struct.Build.html#method.compile -[cc-build-cpp]: https://docs.rs/cc/*/cc/struct.Build.html#method.cpp -[cc-build-flag]: https://docs.rs/cc/*/cc/struct.Build.html#method.flag -[cc-build-include]: https://docs.rs/cc/*/cc/struct.Build.html#method.include -[cc-build]: https://docs.rs/cc/*/cc/struct.Build.html -[playground]: https://play.rust-lang.org diff --git a/src/development_tools/build_tools/cc-bundled-cpp.md b/src/development_tools/build_tools/cc-bundled-cpp.md index 7d273846..3d35e1b3 100644 --- a/src/development_tools/build_tools/cc-bundled-cpp.md +++ b/src/development_tools/build_tools/cc-bundled-cpp.md @@ -1,5 +1,3 @@ -[ex-cc-static-bundled-cpp]: #ex-cc-static-bundled-cpp - ## Compile and link statically to a bundled C++ library [![cc-badge]][cc] [![cat-development-tools-badge]][cat-development-tools] @@ -56,3 +54,5 @@ fn main(){ } } ``` + +[cc-build-cpp]: https://docs.rs/cc/*/cc/struct.Build.html#method.cpp diff --git a/src/development_tools/build_tools/cc-bundled-static.md b/src/development_tools/build_tools/cc-bundled-static.md index e2590ab4..3e24c130 100644 --- a/src/development_tools/build_tools/cc-bundled-static.md +++ b/src/development_tools/build_tools/cc-bundled-static.md @@ -1,5 +1,3 @@ -[ex-cc-static-bundled]: #ex-cc-static-bundled - ## Compile and link statically to a bundled C library [![cc-badge]][cc] [![cat-development-tools-badge]][cat-development-tools] @@ -8,7 +6,7 @@ To accommodate scenarios where additional C, C++, or assembly is required in a p offers a simple api for compiling bundled C/C++/asm code into static libraries (**.a**) that can be statically linked to by **rustc**. The following example has some bundled C code (**src/hello.c**) that will be used from rust. -Before compiling our rust source code, the "build" file (**build.rs**) specified in **Cargo.toml** will run. +Before compiling rust source code, the "build" file (**build.rs**) specified in **Cargo.toml** runs. Using the [**cc**][cc] crate, a static library file will be produced (in this case, **libhello.a**, see [`compile` docs][cc-build-compile]) which can then be used from rust by declaring the external function signatures in an `extern` block. @@ -95,3 +93,11 @@ fn run() -> Result<()> { # # quick_main!(run); ``` + +[`cc::Build::define`]: https://docs.rs/cc/*/cc/struct.Build.html#method.define +[`Option`]: https://doc.rust-lang.org/std/option/enum.Option.html +[cc-build-compile]: https://docs.rs/cc/*/cc/struct.Build.html#method.compile +[cc-build-cpp]: https://docs.rs/cc/*/cc/struct.Build.html#method.cpp +[cc-build-flag]: https://docs.rs/cc/*/cc/struct.Build.html#method.flag +[cc-build-include]: https://docs.rs/cc/*/cc/struct.Build.html#method.include +[cc-build]: https://docs.rs/cc/*/cc/struct.Build.html diff --git a/src/development_tools/build_tools/cc-defines.md b/src/development_tools/build_tools/cc-defines.md index fc92ba91..19f8d0f4 100644 --- a/src/development_tools/build_tools/cc-defines.md +++ b/src/development_tools/build_tools/cc-defines.md @@ -1,12 +1,10 @@ -[ex-cc-custom-defines]: #ex-cc-custom-defines - ## Compile a C library while setting custom defines [![cc-badge]][cc] [![cat-development-tools-badge]][cat-development-tools] It is simple to build bundled C code with custom defines using [`cc::Build::define`]. -It takes an [`Option`] value, so it is possible to create defines such as `#define APP_NAME "foo"` -as well as `#define WELCOME` (pass `None` as the value for a value-less defne). This example builds +The method takes an [`Option`] value, so it is possible to create defines such as `#define APP_NAME "foo"` +as well as `#define WELCOME` (pass `None` as the value for a value-less define). This example builds a bundled C file with dynamic defines set in `build.rs` and prints "**Welcome to foo - version 1.0.2**" when run. Cargo sets some [environment variables][cargo-env] which may be useful for some custom defines. @@ -64,3 +62,5 @@ fn main(){ } } ``` + +[cargo-env]: https://doc.rust-lang.org/cargo/reference/environment-variables.html diff --git a/src/development_tools/debugging/config_log/log-custom.md b/src/development_tools/debugging/config_log/log-custom.md index 0b8d840f..fa68233b 100644 --- a/src/development_tools/debugging/config_log/log-custom.md +++ b/src/development_tools/debugging/config_log/log-custom.md @@ -1,14 +1,15 @@ - ## Log messages to a custom location [![log-badge]][log] [![log4rs-badge]][log4rs] [![cat-debugging-badge]][cat-debugging] -Configures log to be output into custom location with [log4rs]. [log4rs] can use either an external YAML file or a programmatically constructed configuration. +[log4rs] configures log output to a custom location. [log4rs] can use either an +external YAML file or a builder configuration. -Firstly creates the log configuration with [`log4rs::append::file::FileAppender`] -using a custom pattern from [`log4rs::encode::pattern`]. - -Secondly assigns it to the [`log4rs::config::Config`] which has a root appender that uses the previously created `logfile` appender. Subsequently sets the default [`log::LevelFilter`] so that any logs with `Info` level or higher will be sent to the logger. +Create the log configuration with [`log4rs::append::file::FileAppender`]. An +appender defines the logging destination. The configuration continues with +encoding using a custom pattern from [`log4rs::encode::pattern`]. +Assigns the configuration to [`log4rs::config::Config`] and sets the default +[`log::LevelFilter`]. ```rust,no_run # #[macro_use] diff --git a/src/development_tools/debugging/config_log/log-env-variable.md b/src/development_tools/debugging/config_log/log-env-variable.md index c76fed3f..b56a0ffc 100644 --- a/src/development_tools/debugging/config_log/log-env-variable.md +++ b/src/development_tools/debugging/config_log/log-env-variable.md @@ -1,13 +1,12 @@ - ## Use a custom environment variable to set up logging [![log-badge]][log] [![env_logger-badge]][env_logger] [![cat-debugging-badge]][cat-debugging] -Logging is configured with [`Builder`]. +[`Builder`] configures logging. [`Builder::parse`] parses `MY_APP_LOG` -environmental variable contents in the form of [`RUST_LOG`] syntax. -Then [`Builder::init`] initializes the logger. +environment variable contents in the form of [`RUST_LOG`] syntax. +Then, [`Builder::init`] initializes the logger. All these steps are normally done internally by [`env_logger::init`]. ```rust diff --git a/src/development_tools/debugging/config_log/log-mod.md b/src/development_tools/debugging/config_log/log-mod.md index bbf78eef..f337b5a2 100644 --- a/src/development_tools/debugging/config_log/log-mod.md +++ b/src/development_tools/debugging/config_log/log-mod.md @@ -1,4 +1,3 @@ - ## Enable log levels per module [![log-badge]][log] [![env_logger-badge]][env_logger] [![cat-debugging-badge]][cat-debugging] @@ -37,16 +36,16 @@ fn main() { } ``` -[`env_logger`][env_logger] output is controlled by [`RUST_LOG`] environmental -variable on per module basis with comma separated entries in format `path::to::module=log_level`. -Running the `test` application as follows: +[`RUST_LOG`] environment variable controls [`env_logger`][env_logger] output. +Module declarations take comma separated entries formatted like +`path::to::module=log_level`. Run the `test` application as follows: ```bash RUST_LOG="warn,test::foo=info,test::foo::bar=debug" ./test ``` -Sets the default [`log::Level`] to `warn`, module's `foo` and module's `foo::bar` -respectively to `info` and `debug`. The output is: +Sets the default [`log::Level`] to `warn`, module `foo` and module `foo::bar` +to `info` and `debug`. ```bash WARN:test: [root] warn diff --git a/src/development_tools/debugging/config_log/log-timestamp.md b/src/development_tools/debugging/config_log/log-timestamp.md index a866acf7..f8c8f360 100644 --- a/src/development_tools/debugging/config_log/log-timestamp.md +++ b/src/development_tools/debugging/config_log/log-timestamp.md @@ -1,4 +1,3 @@ - ## Include timestamp in log messages [![log-badge]][log] [![env_logger-badge]][env_logger] [![chrono-badge]][chrono] [![cat-debugging-badge]][cat-debugging] @@ -19,18 +18,19 @@ use std::env; use std::io::Write; use chrono::Local; use env_logger::Builder; +use log::LevelFilter; fn main() { Builder::new() .format(|buf, record| { - write!(buf, + writeln!(buf, "{} [{}] - {}", Local::now().format("%Y-%m-%dT%H:%M:%S"), record.level(), record.args() ) }) - .parse(&env::var("MY_APP_LOG").unwrap_or_default()) + .filter(None, LevelFilter::Info) .init(); warn!("warn"); @@ -38,7 +38,7 @@ fn main() { debug!("debug"); } ``` -Calling `MY_APP_LOG="info" cargo run` will result in similar output: +stderr output will contain ``` 2017-05-22T21:57:06 [WARN] - warn 2017-05-22T21:57:06 [INFO] - info diff --git a/src/development_tools/debugging/log/log-custom-logger.md b/src/development_tools/debugging/log/log-custom-logger.md index 39828f67..4c105fb0 100644 --- a/src/development_tools/debugging/log/log-custom-logger.md +++ b/src/development_tools/debugging/log/log-custom-logger.md @@ -1,11 +1,10 @@ - ## Log messages with a custom logger [![log-badge]][log] [![cat-debugging-badge]][cat-debugging] Implements a custom logger `ConsoleLogger` which prints to stdout. In order to use the logging macros, `ConsoleLogger` implements -the [`log::Log`] trait and has to be installed via [`log::set_logger`]. +the [`log::Log`] trait and [`log::set_logger`] installs it. ```rust # #[macro_use] diff --git a/src/development_tools/debugging/log/log-debug.md b/src/development_tools/debugging/log/log-debug.md index 4c036e4e..2ab725e5 100644 --- a/src/development_tools/debugging/log/log-debug.md +++ b/src/development_tools/debugging/log/log-debug.md @@ -1,10 +1,10 @@ - ## Log a debug message to the console [![log-badge]][log] [![env_logger-badge]][env_logger] [![cat-debugging-badge]][cat-debugging] The `log` crate provides logging utilities. The `env_logger` crate configures -logging via an environment variable. +logging via an environment variable. The [`debug!`] macro works like other +[`std::fmt`] formatted strings. ```rust #[macro_use] @@ -15,25 +15,28 @@ fn execute_query(query: &str) { debug!("Executing query: {}", query); } -fn main { +fn main() { env_logger::init(); execute_query("DROP TABLE students"); } ``` -If you run this code, you'll notice that no output is printed. By default, the +No output prints when running this code. By default, the log level is `error`, and any lower levels are dropped. -We can change that easily by setting the `RUST_LOG` environment variable: +Set the `RUST_LOG` environment variable to print the message: ``` $ RUST_LOG=debug cargo run ``` -After running this, you'll likely see a pile of logs from cargo, as well as the +Cargo prints debugging information then the following line at the very end of the output: ``` DEBUG:main: Executing query: DROP TABLE students ``` + +[`debug!`]: https://docs.rs/log/*/log/macro.debug.html +[`std::fmt`]: https://doc.rust-lang.org/std/fmt/ diff --git a/src/development_tools/debugging/log/log-error.md b/src/development_tools/debugging/log/log-error.md index 0e11f434..52dd9235 100644 --- a/src/development_tools/debugging/log/log-error.md +++ b/src/development_tools/debugging/log/log-error.md @@ -1,17 +1,17 @@ - ## Log an error message to the console [![log-badge]][log] [![env_logger-badge]][env_logger] [![cat-debugging-badge]][cat-debugging] +Proper error handling considers exceptions exceptional. Here, an error logs +to stderr with `log`'s convenience macro [`error!`]. + ```rust #[macro_use] extern crate log; extern crate env_logger; -fn execute_query(_query: &str) -> Result<()> { - // Do the thing, or maybe not - - bail!("I'm afraid I can't do that") +fn execute_query(_query: &str) -> Result<(), &'static str> { + Err("I'm afraid I can't do that") } fn main() { @@ -19,14 +19,9 @@ fn main() { let response = execute_query("DROP TABLE students"); if let Err(err) = response { - // Log the error message and continue error!("Failed to execute query: {}", err); } } ``` -Run this code with `cargo run` and you should see the following line: - -``` -DEBUG:main: Failed to execute query: I'm afraid I can't do that -``` +[`error!`]: https://docs.rs/log/*/log/macro.error.html diff --git a/src/development_tools/debugging/log/log-stdout.md b/src/development_tools/debugging/log/log-stdout.md index e8145ae9..9a28dfec 100644 --- a/src/development_tools/debugging/log/log-stdout.md +++ b/src/development_tools/debugging/log/log-stdout.md @@ -1,4 +1,3 @@ - ## Log to stdout instead of stderr [![log-badge]][log] [![env_logger-badge]][env_logger] [![cat-debugging-badge]][cat-debugging] @@ -10,7 +9,7 @@ Creates a custom logger configuration using the [`Builder::target`] to set the t extern crate log; extern crate env_logger; -use env_logger::{LogBuilder, LogTarget}; +use env_logger::{Builder, Target}; fn main() { Builder::new() diff --git a/src/development_tools/debugging/log/log-syslog.md b/src/development_tools/debugging/log/log-syslog.md index 0372b850..8bf7a881 100644 --- a/src/development_tools/debugging/log/log-syslog.md +++ b/src/development_tools/debugging/log/log-syslog.md @@ -1,13 +1,13 @@ - ## Log to the Unix syslog [![log-badge]][log] [![syslog-badge]][syslog] [![cat-debugging-badge]][cat-debugging] Logs messages to [UNIX syslog]. Initializes logger backend -with [`syslog::init`]. [`syslog::Facility`] indicates type of program submitting log, [`log::LevelFilter`] denotes allowed log verbosity +with [`syslog::init`]. [`syslog::Facility`] records the program submitting +the log entry's classification, [`log::LevelFilter`] denotes allowed log verbosity and `Option<&str>` holds optional application name. -```rust,no_run +```rust # #![allow(unused_imports)] # #[macro_use] # extern crate error_chain; diff --git a/src/development_tools/errors/main.md b/src/development_tools/errors/main.md index 58c0cd57..d7387a3c 100644 --- a/src/development_tools/errors/main.md +++ b/src/development_tools/errors/main.md @@ -4,8 +4,7 @@ Handles error that occur when trying to open a file that does not exist. It is achieved by using [error-chain], a library that takes -care of a lot of boilerplate code needed in order to [handle errors in -Rust]. +care of a lot of boilerplate code needed in order to [handle errors in Rust]. `Io(std::io::Error)` inside [`foreign_links`] allows automatic conversion from [`std::io::Error`] into [`error_chain!`] defined type @@ -15,6 +14,9 @@ The below recipe will tell how long the system has been running by opening the Unix file `/proc/uptime` and parse the content to get the first number. Returns uptime unless there is an error. +Other recipes in this book will hide the [error-chain] boilerplate, and can be +seen by expanding the code with the ⤢ button. + ```rust #[macro_use] extern crate error_chain; @@ -52,3 +54,5 @@ fn main() { [`Error`]: https://doc.rust-lang.org/std/error/trait.Error.html [`foreign_links`]: https://docs.rs/error-chain/*/error_chain/#foreign-links [`std::io::Error`]: https://doc.rust-lang.org/std/io/struct.Error.html + +[handle errors in Rust]: https://doc.rust-lang.org/book/second-edition/ch09-00-error-handling.html diff --git a/src/development_tools/errors/retain.md b/src/development_tools/errors/retain.md index 11f36637..6147a43c 100644 --- a/src/development_tools/errors/retain.md +++ b/src/development_tools/errors/retain.md @@ -2,18 +2,15 @@ [![error-chain-badge]][error-chain] [![cat-rust-patterns-badge]][cat-rust-patterns] -[Matching] on different error types returned by a function is possible -and relatively compact with [error-chain] crate. To do so, -[`ErrorKind`] is used to determine the error type. +The [error-chain] crate makes [matching] on different error types returned by +a function possible and relatively compact. [`ErrorKind`] determines the error +type. -To illustrate the error matching, a random integer generator web -service will be queried via [reqwest] and then the response will be -parsed. Errors can be generated by the Rust standard library, -[reqwest] and by the web service. [`foreign_links`] are used for well -defined Rust errors. The `errors` block of the `error_chain!` macro is -used to create an additional [`ErrorKind`] variant for the web service -error. Finally, a regular `match` can be used to react differently -according to the raised error. +Uses [reqwest] to query a random integer generator web service. Converts +the string response into an integer. The Rust standard library, +[reqwest], and the web service can all generate errors. Well defined Rust errors +use [`foreign_links`]. An additional [`ErrorKind`] variant for the web service +error uses `errors` block of the `error_chain!` macro. ```rust #[macro_use] diff --git a/src/development_tools/versioning/semver-command.md b/src/development_tools/versioning/semver-command.md index e7330d8c..8849acdf 100644 --- a/src/development_tools/versioning/semver-command.md +++ b/src/development_tools/versioning/semver-command.md @@ -1,11 +1,11 @@ -[ex-semver-command]: #ex-semver-command - ## Check external command version for compatibility + [![semver-badge]][semver] [![cat-text-processing-badge]][cat-text-processing] [![cat-os-badge]][cat-os] -Runs `git --version` using [`Command`], then parses the version number into a [`semver::Version`] -using [`Version::parse`]. A [`semver::VersionReq`] is used to compare the parsed version to a -minimum version requirement. +Runs `git --version` using [`Command`], then parses the version number into a +[`semver::Version`] using [`Version::parse`]. [`VersionReq::matches`] compares +[`semver::VersionReq`] to the parsed version. The command output resembles +"git version x.y.z". ```rust,no_run # #[macro_use] @@ -34,7 +34,6 @@ fn run() -> Result<()> { } let stdout = String::from_utf8(output.stdout)?; - // `git --version` output: "git version x.y.z" let version = stdout.split(" ").last().ok_or_else(|| { "Invalid command output" })?; @@ -55,3 +54,4 @@ fn run() -> Result<()> { [`semver::Version`]: https://docs.rs/semver/*/semver/struct.Version.html [`semver::VersionReq`]: https://docs.rs/semver/*/semver/struct.VersionReq.html [`Version::parse`]: https://docs.rs/semver/*/semver/struct.Version.html#method.parse +[`VersionReq::matches`]: https://docs.rs/semver/*/semver/struct.VersionReq.html#method.matches diff --git a/src/development_tools/versioning/semver-complex.md b/src/development_tools/versioning/semver-complex.md index 16b4d43d..2e7df610 100644 --- a/src/development_tools/versioning/semver-complex.md +++ b/src/development_tools/versioning/semver-complex.md @@ -1,5 +1,3 @@ -[ex-semver-complex]: #ex-semver-complex - ## Parse a complex version string. [![semver-badge]][semver] [![cat-config-badge]][cat-config] diff --git a/src/development_tools/versioning/semver-increment.md b/src/development_tools/versioning/semver-increment.md index d3629289..39714cda 100644 --- a/src/development_tools/versioning/semver-increment.md +++ b/src/development_tools/versioning/semver-increment.md @@ -1,12 +1,14 @@ -[ex-semver-increment]: #ex-semver-increment - ## Parse and increment a version string. [![semver-badge]][semver] [![cat-config-badge]][cat-config] -Constructs a [`semver::Version`] from a string literal using [`Version::parse`], then increments it by patch, minor, and major version number one by one. +Constructs a [`semver::Version`] from a string literal using [`Version::parse`], +then increments it by patch, minor, and major version number one by one. -Note that in accordance with the [Semantic Versioning Specification], incrementing the minor version number resets the patch version number to 0 and incrementing the major version number resets both the minor and patch version numbers to 0. +Note that in accordance with the [Semantic Versioning Specification], +incrementing the minor version number resets the patch version number to 0 and +incrementing the major version number resets both the minor and patch version +numbers to 0. ```rust # #[macro_use] diff --git a/src/development_tools/versioning/semver-latest.md b/src/development_tools/versioning/semver-latest.md index 2f717a91..03bd0460 100644 --- a/src/development_tools/versioning/semver-latest.md +++ b/src/development_tools/versioning/semver-latest.md @@ -1,9 +1,10 @@ -[ex-semver-latest]: #ex-semver-latest - ## Find the latest version satisfying given range + [![semver-badge]][semver] [![cat-config-badge]][cat-config] -Given a list of version &strs, finds the latest [`semver::Version`] that satisfying a given [`semver::VersionReq`] using [`VersionReq::matches`]. +Given a list of version &strs, finds the latest [`semver::Version`]. +[`semver::VersionReq`] filters the list with [`VersionReq::matches`]. +Also demonstrates `semver` pre-release preferences. ```rust # #[macro_use] @@ -40,7 +41,6 @@ fn run() -> Result<()> { Some(Version::parse("1.0.0")?) ); - // Shows Semver precedence for pre-release tags assert_eq!( find_max_matching_version( ">1.2.3-alpha.3", diff --git a/src/development_tools/versioning/semver-prerelease.md b/src/development_tools/versioning/semver-prerelease.md index eafeac5b..f0e6416d 100644 --- a/src/development_tools/versioning/semver-prerelease.md +++ b/src/development_tools/versioning/semver-prerelease.md @@ -1,10 +1,8 @@ -[ex-semver-prerelease]: #ex-semver-prerelease - ## Check if given version is pre-release. [![semver-badge]][semver] [![cat-config-badge]][cat-config] -Given two versions, we assert (by using [`is_prerelease`]) that one is pre-release and that the other is not. +Given two versions, [`is_prerelease`] asserts that one is pre-release and the other is not. ```rust # #[macro_use] diff --git a/src/encoding.md b/src/encoding.md index c501c5e1..2a7d93ff 100644 --- a/src/encoding.md +++ b/src/encoding.md @@ -28,7 +28,7 @@ [ex-serialize-csv]: encoding/csv.html#serialize-records-to-csv [ex-csv-serde]: encoding/csv.html#serialize-records-to-csv-using-serde [ex-csv-transform-column]: encoding/csv.html#transform-csv-column -[ex-json-value]: complex.html#serialize-and-deserialize-unstructured-json +[ex-json-value]: encoding/complex.html#serialize-and-deserialize-unstructured-json [ex-toml-config]: encoding/complex.html#deserialize-a-toml-configuration-file [ex-byteorder-le]: encoding/complex.html#read-and-write-integers-in-little-endian-byte-order