Struct iceberg::spec::Datum

pub struct Datum { /* private fields */ }

Literal associated with its type. The value and type pair is checked when construction, so the type and value is guaranteed to be correct when used.

By default, we decouple the type and value of a literal, so we can use avoid the cost of storing extra type info for each literal. But associate type with literal can be useful in some cases, for example, in unbound expression.

Implementations

impl Datum

pub fn try_from_bytes(bytes: &[u8], data_type: PrimitiveType) -> Result<Self>

Create iceberg value from bytes.

See this spec for reference.

pub fn to_bytes(&self) -> ByteBuf

Convert the value to bytes

See this spec for reference.

pub fn bool<T: Into<bool>>(t: T) -> Self

Creates a boolean value.

Example:

use iceberg::spec::{Datum, Literal, PrimitiveLiteral};
let t = Datum::bool(true);

assert_eq!(format!("{}", t), "true".to_string());
assert_eq!(
    Literal::from(t),
    Literal::Primitive(PrimitiveLiteral::Boolean(true))
);

pub fn bool_from_str<S: AsRef<str>>(s: S) -> Result<Self>

Creates a boolean value from string. See Parse bool from str for reference.

Example:

use iceberg::spec::{Datum, Literal, PrimitiveLiteral};
let t = Datum::bool_from_str("false").unwrap();

assert_eq!(&format!("{}", t), "false");
assert_eq!(
    Literal::Primitive(PrimitiveLiteral::Boolean(false)),
    t.into()
);

pub fn int<T: Into<i32>>(t: T) -> Self

Creates an 32bit integer.

Example:

use iceberg::spec::{Datum, Literal, PrimitiveLiteral};
let t = Datum::int(23i8);

assert_eq!(&format!("{}", t), "23");
assert_eq!(Literal::Primitive(PrimitiveLiteral::Int(23)), t.into());

pub fn long<T: Into<i64>>(t: T) -> Self

Creates an 64bit integer.

Example:

use iceberg::spec::{Datum, Literal, PrimitiveLiteral};
let t = Datum::long(24i8);

assert_eq!(&format!("{t}"), "24");
assert_eq!(Literal::Primitive(PrimitiveLiteral::Long(24)), t.into());

pub fn float<T: Into<f32>>(t: T) -> Self

Creates an 32bit floating point number.

Example:

use iceberg::spec::{Datum, Literal, PrimitiveLiteral};
use ordered_float::OrderedFloat;
let t = Datum::float(32.1f32);

assert_eq!(&format!("{t}"), "32.1");
assert_eq!(
    Literal::Primitive(PrimitiveLiteral::Float(OrderedFloat(32.1))),
    t.into()
);

pub fn double<T: Into<f64>>(t: T) -> Self

Creates an 64bit floating point number.

Example:

use iceberg::spec::{Datum, Literal, PrimitiveLiteral};
use ordered_float::OrderedFloat;
let t = Datum::double(32.1f64);

assert_eq!(&format!("{t}"), "32.1");
assert_eq!(
    Literal::Primitive(PrimitiveLiteral::Double(OrderedFloat(32.1))),
    t.into()
);

pub fn date(days: i32) -> Self

Creates date literal from number of days from unix epoch directly.

Example:

use iceberg::spec::{Datum, Literal, PrimitiveLiteral};
// 2 days after 1970-01-01
let t = Datum::date(2);

assert_eq!(&format!("{t}"), "1970-01-03");
assert_eq!(Literal::Primitive(PrimitiveLiteral::Int(2)), t.into());

pub fn date_from_str<S: AsRef<str>>(s: S) -> Result<Self>

Creates date literal in %Y-%m-%d format, assume in utc timezone.

See NaiveDate::from_str.

Example

use iceberg::spec::{Datum, Literal};
let t = Datum::date_from_str("1970-01-05").unwrap();

assert_eq!(&format!("{t}"), "1970-01-05");
assert_eq!(Literal::date(4), t.into());

pub fn date_from_ymd(year: i32, month: u32, day: u32) -> Result<Self>

Create date literal from calendar date (year, month and day).

See NaiveDate::from_ymd_opt.

Example:

 use iceberg::spec::{Datum, Literal};
 let t = Datum::date_from_ymd(1970, 1, 5).unwrap();

 assert_eq!(&format!("{t}"), "1970-01-05");
 assert_eq!(Literal::date(4), t.into());

pub fn time_micros(value: i64) -> Result<Self>

Creates time literal in microseconds directly.

It will return error when it’s negative or too large to fit in 24 hours.

Example:

use iceberg::spec::{Datum, Literal};
let micro_secs = {
    1 * 3600 * 1_000_000 + // 1 hour
    2 * 60 * 1_000_000 +   // 2 minutes
    1 * 1_000_000 + // 1 second
    888999 // microseconds
};

let t = Datum::time_micros(micro_secs).unwrap();

assert_eq!(&format!("{t}"), "01:02:01.888999");
assert_eq!(Literal::time(micro_secs), t.into());

let negative_value = -100;
assert!(Datum::time_micros(negative_value).is_err());

let too_large_value = 36 * 60 * 60 * 1_000_000; // Too large to fit in 24 hours.
assert!(Datum::time_micros(too_large_value).is_err());

pub fn time_from_str<S: AsRef<str>>(s: S) -> Result<Self>

Creates time literal in microseconds in %H:%M:%S:.f format.

See NaiveTime::from_str for details.

Example:

use iceberg::spec::{Datum, Literal};
let t = Datum::time_from_str("01:02:01.888999777").unwrap();

assert_eq!(&format!("{t}"), "01:02:01.888999");

pub fn time_from_hms_micro( hour: u32, min: u32, sec: u32, micro: u32, ) -> Result<Self>

Creates time literal from hour, minute, second, and microseconds.

See NaiveTime::from_hms_micro_opt.

Example:

use iceberg::spec::{Datum, Literal};
let t = Datum::time_from_hms_micro(22, 15, 33, 111).unwrap();

assert_eq!(&format!("{t}"), "22:15:33.000111");

pub fn timestamp_micros(value: i64) -> Self

Creates a timestamp from unix epoch in microseconds.

Example:

use iceberg::spec::Datum;
let t = Datum::timestamp_micros(1000);

assert_eq!(&format!("{t}"), "1970-01-01 00:00:00.001");

pub fn timestamp_nanos(value: i64) -> Self

Creates a timestamp from unix epoch in nanoseconds.

Example:

use iceberg::spec::Datum;
let t = Datum::timestamp_nanos(1000);

assert_eq!(&format!("{t}"), "1970-01-01 00:00:00.000001");

pub fn timestamp_from_datetime(dt: NaiveDateTime) -> Self

Creates a timestamp from DateTime.

Example:

use chrono::{NaiveDate, NaiveDateTime, TimeZone, Utc};
use iceberg::spec::Datum;
let t = Datum::timestamp_from_datetime(
    NaiveDate::from_ymd_opt(1992, 3, 1)
        .unwrap()
        .and_hms_micro_opt(1, 2, 3, 88)
        .unwrap(),
);

assert_eq!(&format!("{t}"), "1992-03-01 01:02:03.000088");

pub fn timestamp_from_str<S: AsRef<str>>(s: S) -> Result<Self>

Parse a timestamp in [%Y-%m-%dT%H:%M:%S%.f] format.

See NaiveDateTime::from_str.

Example:

use chrono::{DateTime, FixedOffset, NaiveDate, NaiveDateTime, NaiveTime};
use iceberg::spec::{Datum, Literal};
let t = Datum::timestamp_from_str("1992-03-01T01:02:03.000088").unwrap();

assert_eq!(&format!("{t}"), "1992-03-01 01:02:03.000088");

pub fn timestamptz_micros(value: i64) -> Self

Creates a timestamp with timezone from unix epoch in microseconds.

Example:

use iceberg::spec::Datum;
let t = Datum::timestamptz_micros(1000);

assert_eq!(&format!("{t}"), "1970-01-01 00:00:00.001 UTC");

pub fn timestamptz_nanos(value: i64) -> Self

Creates a timestamp with timezone from unix epoch in nanoseconds.

Example:

use iceberg::spec::Datum;
let t = Datum::timestamptz_nanos(1000);

assert_eq!(&format!("{t}"), "1970-01-01 00:00:00.000001 UTC");

pub fn timestamptz_from_datetime<T: TimeZone>(dt: DateTime<T>) -> Self

Creates a timestamp with timezone from DateTime. Example:

use chrono::{TimeZone, Utc};
use iceberg::spec::Datum;
let t = Datum::timestamptz_from_datetime(Utc.timestamp_opt(1000, 0).unwrap());

assert_eq!(&format!("{t}"), "1970-01-01 00:16:40 UTC");

pub fn timestamptz_from_str<S: AsRef<str>>(s: S) -> Result<Self>

Parse timestamp with timezone in RFC3339 format.

See DateTime::from_str.

Example:

use chrono::{DateTime, FixedOffset, NaiveDate, NaiveDateTime, NaiveTime};
use iceberg::spec::{Datum, Literal};
let t = Datum::timestamptz_from_str("1992-03-01T01:02:03.000088+08:00").unwrap();

assert_eq!(&format!("{t}"), "1992-02-29 17:02:03.000088 UTC");

pub fn string<S: ToString>(s: S) -> Self

Creates a string literal.

Example:

use iceberg::spec::Datum;
let t = Datum::string("ss");

assert_eq!(&format!("{t}"), r#""ss""#);

pub fn uuid(uuid: Uuid) -> Self

Creates uuid literal.

Example:

use iceberg::spec::Datum;
use uuid::uuid;
let t = Datum::uuid(uuid!("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"));

assert_eq!(&format!("{t}"), "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8");

pub fn uuid_from_str<S: AsRef<str>>(s: S) -> Result<Self>

Creates uuid from str. See Uuid::parse_str.

Example:

use iceberg::spec::Datum;
let t = Datum::uuid_from_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8").unwrap();

assert_eq!(&format!("{t}"), "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8");

pub fn fixed<I: IntoIterator<Item = u8>>(input: I) -> Self

Creates a fixed literal from bytes.

Example:

use iceberg::spec::{Datum, Literal, PrimitiveLiteral};
let t = Datum::fixed(vec![1u8, 2u8]);

assert_eq!(&format!("{t}"), "0102");

pub fn binary<I: IntoIterator<Item = u8>>(input: I) -> Self

Creates a binary literal from bytes.

Example:

use iceberg::spec::Datum;
let t = Datum::binary(vec![1u8, 100u8]);

assert_eq!(&format!("{t}"), "0164");

pub fn decimal_from_str<S: AsRef<str>>(s: S) -> Result<Self>

Creates decimal literal from string. See [Decimal::from_str_exact].

Example:

use iceberg::spec::Datum;
use itertools::assert_equal;
use rust_decimal::Decimal;
let t = Datum::decimal_from_str("123.45").unwrap();

assert_eq!(&format!("{t}"), "123.45");

pub fn decimal(value: impl Into<Decimal>) -> Result<Self>

Try to create a decimal literal from [Decimal].

Example:

use iceberg::spec::Datum;
use rust_decimal::Decimal;

let t = Datum::decimal(Decimal::new(123, 2)).unwrap();

assert_eq!(&format!("{t}"), "1.23");

pub fn to(self, target_type: &Type) -> Result<Datum>

Convert the datum to target_type.

pub fn literal(&self) -> &PrimitiveLiteral

Get the primitive literal from datum.

pub fn data_type(&self) -> &PrimitiveType

Get the primitive type from datum.

pub fn is_nan(&self) -> bool

Returns true if the Literal represents a primitive type that can be a NaN, and that it’s value is NaN

Trait Implementations

impl Clone for Datum

fn clone(&self) -> Datum

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Datum

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Datum

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Display for Datum

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Datum> for Literal

fn from(value: Datum) -> Self

Converts to this type from the input type.

impl From<Datum> for PrimitiveLiteral

fn from(value: Datum) -> Self

Converts to this type from the input type.

impl Hash for Datum

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Datum

fn eq(&self, other: &Datum) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Datum

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Datum

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl Eq for Datum

impl StructuralPartialEq for Datum