Module polars::doc::time

DateTime related functionality

Polars supports all data types in Arrow related to time and dates in any kind. In Arrow times and dates are stored as i32 or i64 integers. This can represent for instance a duration in seconds since the Unix Epoch: 00:00:00 1 january 1970.

Chrono

I can imagine that integer values aren't the most intuitive when dealing with dates and times. For this reason, Polars supports conversion from chrono's NaiveTime and NaiveDate structs to Polars and vice versa.

ChunkedArray<T>'s initialization is represented by the the following traits:

• FromNaiveTime
• FromNaiveDateTime

To cast a ChunkedArray<T> to a Vec<NaiveTime> or a Vec<NaiveDateTime> see:

• AsNaiveTime

Example

use chrono::NaiveTime;
use polars_core::prelude::*;;

// We can create a ChunkedArray from NaiveTime objects
fn from_naive_time_to_time64(time_values: &[NaiveTime]) -> Time64NanosecondChunked {
    Time64NanosecondChunked::new_from_naive_time("name", time_values)
}

// Or from a ChunkedArray to NaiveTime objects
fn from_time64_to_naive_time(ca: &Time64NanosecondChunked) -> Vec<Option<NaiveTime>> {
    ca.as_naive_time()
}

String formatting

We can also directly parse strings given a predifined fmt: &str. This uses chrono's NaiveTime::parse_from_str under the hood. So look there for the different formatting options. If the string parsing is not succesful, the value will be None.

Examples

NaiveTime

use polars_core::prelude::*;
use chrono::NaiveTime;

// String values to parse, Note that the 2nd value is not a correct time value.
let time_values = &["23:56:04", "26:00:99", "12:39:08"];
// Parsing fmt
let fmt = "%H:%M:%S";
// Create the ChunkedArray
let ca = Time64NanosecondChunked::parse_from_str_slice("Time as ns since midnight", time_values, fmt);

// Assert that we've got a ChunkedArray with a single None value.
assert_eq!(ca.as_naive_time(),
    &[NaiveTime::parse_from_str(time_values[0], fmt).ok(),
    None,
    NaiveTime::parse_from_str(time_values[2], fmt).ok()]);

NaiveDateTime

use polars_core::prelude::*;
use chrono::NaiveDateTime;

// String values to parse, Note that the 2nd value is not a correct time value.
let datetime_values = &[
            "1988-08-25 00:00:16",
            "2015-09-05 23:56:04",
            "2012-12-21 00:00:00",
        ];
// Parsing fmt
let fmt = "%Y-%m-%d %H:%M:%S";

// Create the ChunkedArray
let ca = Date64Chunked::parse_from_str_slice("datetime as ms since Epoch", datetime_values, fmt);

// or dates in different precision (days)
let ca = Date32Chunked::parse_from_str_slice("date as days since Epoch", datetime_values, fmt);

Temporal Data Types

Polars supports some of the time datatypes supported by Apache Arrow. These store the time values in different precisions and bytes:

Time

• Time64NanosecondChunked
  • A ChunkedArray which stores time with nanosecond precision as 64 bit signed integer.

Date

• Date32Chunked
  • A ChunkedArray storing the date as elapsed days since the Unix Epoch as 32 bit signed integer.

DateTime

• Date64Chunked
  • A ChunkedArray storing the date as elapsed milliseconds since the Unix Epoch as 64 bit signed integer.