Skip to main content

​
Overview

DateTimeAxis provides calendar-aware tick generation for time series data. It automatically aligns ticks to calendar boundaries (midnight, month start, etc.) and formats them using strftime patterns.

​
Usage

use kuva::prelude::*;

let layout = Layout::auto_from_plots(&plots)
    .with_x_datetime(DateTimeAxis::days("%Y-%m-%d"));

​
Constructors

​
DateTimeAxis::years

Creates a year-based axis. 
let axis = DateTimeAxis::years("%Y");

​
DateTimeAxis::months

Creates a month-based axis. 
let axis = DateTimeAxis::months("%b %Y");  // "Jan 2024"

​
DateTimeAxis::weeks

Creates a week-based axis (ticks on Mondays). 
let axis = DateTimeAxis::weeks("%Y-%m-%d");

​
DateTimeAxis::days

Creates a day-based axis (ticks at midnight). 
let axis = DateTimeAxis::days("%m-%d");

​
DateTimeAxis::hours

Creates an hour-based axis. 
let axis = DateTimeAxis::hours("%H:00");

​
DateTimeAxis::minutes

Creates a minute-based axis. 
let axis = DateTimeAxis::minutes("%H:%M");

​
DateTimeAxis::auto

Automatically selects unit and format based on data range.
​
min
f64
required
Minimum timestamp (Unix seconds)
​
max
f64
required
Maximum timestamp (Unix seconds)
let min_ts = ymd(2024, 1, 1);
let max_ts = ymd(2024, 12, 31);
let axis = DateTimeAxis::auto(min_ts, max_ts);  // Chooses days
Auto-selection rules:
  • < 2 min: seconds
  • < 2 hours: minutes
  • < 3 days: hours
  • < 90 days: days
  • < 3 years: months
  • = 3 years: years

​
Methods

​
with_step

Sets the step interval for tick generation. 
let axis = DateTimeAxis::hours("%H:00")
    .with_step(3);  // Every 3 hours

​
generate_ticks

Generates tick positions aligned to calendar boundaries.
​
min
f64
required
Minimum timestamp
​
max
f64
required
Maximum timestamp
Returns: Vec<f64> - Tick positions as Unix timestamps 
let ticks = axis.generate_ticks(min_ts, max_ts);

​
format_tick

Formats a timestamp using the configured strftime format.
​
ts
f64
required
Unix timestamp to format
Returns: String - Formatted date/time string 
let label = axis.format_tick(1704067200.0);  // "2024-01-01"

​
Helper Functions

​
ymd

Converts year-month-day to Unix timestamp. 
use kuva::render::datetime::ymd;

let ts = ymd(2024, 3, 15);  // March 15, 2024 at midnight UTC

​
ymd_hms

Converts year-month-day-hour-minute-second to Unix timestamp. 
use kuva::render::datetime::ymd_hms;

let ts = ymd_hms(2024, 3, 15, 14, 30, 0);  // March 15, 2024 at 14:30:00 UTC

​
Complete Example

use kuva::prelude::*;

let data = vec![
    (ymd(2024, 1, 1), 10.0),
    (ymd(2024, 1, 15), 12.0),
    (ymd(2024, 2, 1), 11.0),
    (ymd(2024, 2, 15), 13.0),
];

let line = LinePlot::new()
    .with_data(data.clone());

let plots = vec![line.into()];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Time Series")
    .with_x_datetime(DateTimeAxis::days("%b %d"))
    .with_x_label("Date")
    .with_y_label("Value");

let svg = render_to_svg(plots, layout);

​
Format Specifiers

Common strftime format codes:
CodeMeaningExample
%Y4-digit year2024
%y2-digit year24
%mMonth (01-12)03
%bMonth abbrMar
%BMonth fullMarch
%dDay (01-31)15
%HHour (00-23)14
%MMinute (00-59)30
%SSecond (00-59)45

​
Source

src/render/datetime.rs

Build docs developers (and LLMs) love

Get started for freeTalk to us