Package 'timenow'

Title: Quick Timezone-Aware Timestamps
Description: Simple helpers to report the current time in UTC and your local timezone, with sensible detection heuristics when the system timezone is UTC. Supports fuzzy matching of timezone names like "Perth Australia".
Authors: Michael Sumner [aut, cre]
Maintainer: Michael Sumner <[email protected]>
License: MIT + file LICENSE
Version: 0.1.0.9001
Built: 2026-06-04 08:30:56 UTC
Source: https://github.com/hypertidy/timenow

Help Index

Detect the local timezone

Description

Uses a cascade of methods to determine the local timezone, useful when the system timezone is set to UTC.

Usage

detect_timezone(quiet = FALSE)

Arguments

quiet

Suppress messages about detection method used

Value

A valid IANA timezone string

Resolve a fuzzy timezone string

Description

Matches partial or fuzzy timezone specifications against IANA timezone names. If the string cannot be matched directly, and the location package is installed, it will attempt to geocode the string via Nominatim and derive the timezone from the resulting coordinates.

Usage

resolve_timezone(tz)

Arguments

tz

A timezone string, possibly fuzzy like "Perth" or "US Eastern", or a place name like "Jackson, TN" (requires location).

Value

A valid IANA timezone string

Examples

resolve_timezone("Perth")
resolve_timezone("new york")
resolve_timezone("tokyo")
## Not run: 
# requires location + lutz packages
resolve_timezone("Jackson, TN")
resolve_timezone("Davis Station, Antarctica")

## End(Not run)

Get current time with timezone awareness

Description

Reports the current timestamp in UTC and optionally in a local or specified timezone. Uses a detection cascade to find your local timezone when the system reports UTC.

Usage

timenow(tz = NULL, quiet = FALSE)

Arguments

tz

Optional timezone specification. Can be:

  • NULL (default): show UTC and detected local timezone

  • A valid IANA timezone name: "Australia/Hobart"

  • A fuzzy string: "Perth Australia", "new york", "tokyo"

  • A place name: "Jackson, TN", "Davis Station, Antarctica" (requires the location package)

quiet

Suppress the local timezone detection message

Details

Timezone detection cascade

When your system timezone is UTC (common on servers), timenow uses this cascade to find your actual local timezone:

  1. getOption("timenow.tz") - set in .Rprofile

  2. Sys.getenv("R_TIMENOW_TZ") - set in .Renviron

  3. ⁠/etc/timezone⁠ file (Debian/Ubuntu)

  4. timedatectl output (systemd)

  5. Sys.timezone() - the R default

Setting your timezone

In ⁠~/.Renviron⁠: 

R_TIMENOW_TZ=Australia/Hobart

Or in ⁠~/.Rprofile⁠: 

options(timenow.tz = "Australia/Hobart")

Value

A named list of class "timenow" with UTC and local times (invisibly)

Examples

timenow()
timenow("Perth")
timenow("US Eastern")

Show timezone configuration help

Description

Prints guidance on setting your local timezone for timenow.

Usage

timenow_help()

Set your local timezone for timenow

Description

Writes your timezone preference to ~/.Renviron so it persists across sessions. Supports fuzzy timezone matching.

Usage

timenow_set(tz, renviron = "~/.Renviron", restart = TRUE)

Arguments

tz

Timezone string (can be fuzzy like "Hobart" or "Perth Australia")
renviron

Path to .Renviron file (default: ~/.Renviron)
restart

Prompt to restart R after setting (default: TRUE)

Value

The resolved timezone string (invisibly)

Examples

## Not run: 
timenow_set("Hobart")
timenow_set("Perth Australia")

## End(Not run)