Nushell
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
  • 한국어
GitHub
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
  • 한국어
GitHub
  • Introduction
  • Installation
    • Default Shell
  • Getting Started
    • Quick Tour
    • Moving Around the System
    • Thinking in Nu
    • Nushell Cheat Sheet
  • Nu Fundamentals
    • Types of Data
    • Loading Data
    • Data Formats
    • Working with SQLite
    • Pipelines
    • Working with Strings
    • Regular Expressions
    • Working with Binary Data
    • Working with Lists
    • Working with Records
    • Working with Numbers
    • Working with Tables
    • Working with Paths
    • Navigating and Accessing Structured Data
    • Special Variables
  • Programming in Nu
    • Custom Commands
    • Aliases
    • Operators
    • Variables
    • Control Flow
    • Scripts
    • Modules
      • Using Modules
      • Creating Modules
    • Overlays
    • Sorting
    • Testing your Nushell Code
    • Debugging Scripts
    • Language Server
    • Best Practices
  • Nu as a Shell
    • Configuration
    • Configuration Reference
    • Environment
    • Stdout, Stderr, and Exit Codes
    • Working with the Terminal
    • Running System (External) Commands
    • How to Configure 3rd Party Prompts
    • Directory Stack
    • Reedline, Nu's Line Editor
    • Custom Completions
    • Externs
    • Coloring and Theming in Nu
    • Hooks
    • Background Jobs
  • Coming to Nu
    • Coming from Bash
    • Coming from CMD.EXE
    • Coming from PowerShell
    • Nu map from other shells and domain specific languages
    • Nu Map from Imperative Languages
    • Nu Map from Functional Languages
    • Nushell operator map
  • Design Notes
    • How Nushell Code Gets Run
  • (Not So) Advanced
    • Standard Library
      • std/assert
      • std/bench
      • std/clip
      • std/config
      • std/dt
      • std/formats
      • std/help
      • std/input
      • std/iter
      • std/log
      • std/math
      • std/random
      • std/util
      • std/xml
      • std-rfc
    • Dataframes
      • Dataframe Operations
      • Column Selectors
      • Math Expressions
      • String Expressions
      • Dates and Times in Dataframes
      • Masks and Conditionals
      • Aggregations and Window Functions
    • Metadata
    • Creating Your Own Errors
    • Parallelism
    • Plugins
    • explore
    • Building TUIs with tui
    • MCP Server

std/dt

The std/dt module measures the time between two dates in calendar units: years, months and days, down to nanoseconds. Subtracting one datetime from another gives a duration, and a duration stops at weeks, because months and years don't have a fixed length:

2024-03-01T12:00:00Z - 2023-01-31T08:30:00Z
# => 56wk 3day 3hr 30min

Import the commands without a prefix:

use std/dt *

After use std/dt without the glob, they are dt datetime-diff and dt pretty-print-duration.

datetime-diff

datetime-diff takes the later datetime first and the earlier one second, as arguments rather than pipeline input. It returns a record with one field for each unit from year to nanosecond:

datetime-diff 2024-03-01T12:00:00Z 2023-01-31T08:30:00Z
# => ╭─────────────┬────╮
# => │ year        │ 1  │
# => │ month       │ 1  │
# => │ day         │ 1  │
# => │ hour        │ 3  │
# => │ minute      │ 30 │
# => │ second      │ 0  │
# => │ millisecond │ 0  │
# => │ microsecond │ 0  │
# => │ nanosecond  │ 0  │
# => ╰─────────────┴────╯

It counts whole months first and then the days that are left. When a month is too short for the starting day, the day moves to the end of that month, so January 31 plus one month is February 28 or 29. Here, 2023-01-31 plus 13 months is 2024-02-29, and March 1 is one day later.

Both datetimes are converted to UTC before the comparison, so their time zones don't matter. datetime-diff 2024-01-01T00:00:00+01:00 2023-12-31T23:00:00Z is all zeros, because both are the same moment.

If the first datetime is earlier than the second, datetime-diff fails:

datetime-diff 2023-01-31T08:30:00Z 2024-03-01T12:00:00Z
# => Error: nu::shell::error
# =>
# =>   × Incompatible arguments
# =>    ╭─[repl_entry #1:1:15]
# =>  1 │ datetime-diff 2023-01-31T08:30:00Z 2024-03-01T12:00:00Z
# =>    ·               ────────────────────┬────────────────────
# =>    ·                                   ╰── First datetime must be >= second, but was actually -56wk 3day 3hr 30min less than it.
# =>    ╰────

pretty-print-duration

pretty-print-duration turns a record from datetime-diff into text. It also takes the record as an argument, not as pipeline input:

pretty-print-duration (datetime-diff 2024-03-01T12:00:00Z 2023-01-31T08:30:00Z) | to nuon
# => "1yr 1month 1day 3hrs 30mins "

It leaves out the units that are zero and uses the singular for a value of 1. The units are yr/yrs, month/months, day/days, hr/hrs, min/mins and sec/secs, then ms, µs and ns. Every unit is followed by a space, so the text ends with one. When all fields are zero, the result is an empty string.

The welcome banner uses these two commands for its "It's been this long since Nushell's first commit" line.

Edit this page on GitHub
Contributors: fdncred
Prev
std/config
Next
std/formats