Part 20: Utilities

The small standard packages that almost every real program reaches for sooner or later: Time for spans, clocks and calendar dates, TimeZone for the local time in a place, Random and Entropy for numbers you cannot predict — or deliberately can — Hash for fingerprints, and Uuid and NanoId for names nobody else will pick. Each lesson is short and stands on its own, and together they show how the standard library speaks about failure: a step that may not fit returns an optional, and a request the system may refuse returns a fallible.

What you will learn

• Spans of time with Duration, where every step that could overflow says so in its type.
• Measuring elapsed time with Instant, the clock that never goes backwards.
• Calendar dates and the leap-year rule, and reading dates with errors that point at the faulty byte.
• Moments in time: a DateTime with a UtcOffset, RFC 3339 text, and comparing moments through Timestamp.
• Time zones built from POSIX rules, and the local times that happen twice, or never, when the clocks change.
• Seeded generators that replay the same numbers, and distributions that shape them into dice, shuffles and bell curves.
• Unpredictable bytes from the operating system, and why a failure there must never be papered over.
• Fast, non-cryptographic hashes and checksums, all at once or piece by piece.
• Creating, printing and strictly parsing UUIDs, and shorter, URL-safe Nano IDs from any alphabet.

The part at a glance

flowchart LR
    u(["Utilities"]) --> t["Time"]
    u --> r["Randomness"]
    u --> id["Fingerprints and names"]
    t --> span["How long?<br/>Duration, Stopwatch"]
    t --> when["When?<br/>Date, Date and time"]
    t --> where["Where?<br/>Time zone"]
    r --> rep["Repeatable<br/>Random, Distribution"]
    r --> unp["Unguessable<br/>Entropy"]
    id --> h["From data<br/>Hash"]
    id --> uu["From nothing<br/>UUID, Nano ID"]
    unp -. "seeds" .-> rep
    unp -. "random bits" .-> uu

Lessons

Before you start

This part leans on the native outcomes: Part 8: Optionals for every Duration? and Date?, and Part 9: Errors for parsing and for requests the system may refuse. The randomness lessons pass generators as mutable references and call generic functions, and Entropy and Hash hand bytes over through pointers from Part 15: Memory. Each lesson's package is in the Examples repository's Utilities/ folder:

cd Examples/Utilities/Duration
rux run

A few lessons print something different on every run — a random key, a die roll, a fresh UUID or Nano ID. Their pages say which lines to expect to change.

After this part

Part 21: Data formats reads and writes JSON and TOML, the formats programs use to exchange and configure data.

Before moving on, try the checkpoint projects. Guess is a number-guessing game whose secret comes from a generator seeded with entropy; Age works out an age in years, months and days from two dates; Password draws a password straight from the system's entropy without favouring any character; and Launch counts down to a rocket launch with SleepFor.

For the language rules this part relies on, see Structs, Enums and Pointers in the Rux Reference.