timecmp

Documentation

Overview

Package timecmp provides utility functions for comparing apiserver and stdlib times.

There are a couple big pitfalls when using apiserver time types.

First, the apiserver time types (metav1.Time & metav1.MicroTime) have second and microsecond granularity once serialized, respectively. Internally, however, they are wrappers around the Go stdlib times. As a result, initialized values that have not yet round-tripped to the server can have more granularity than they should.

To address this issue, there are convenience constructors in tilt/pkg/apis that should be used for conversions from Go stdlib time types, including Now(). These are similar to the ones provided by metav1 itself except that they _immediately_ truncate.

The second issue is addressed by this package, which is that internal timestamps within the Tilt engine often have higher granularity, which means comparisons can be problematic. For example, if an internal timestamp of an operation is held as a Go stdlib time.Time value and then stored on an entity as a metav1.Time object, future comparisons might not behave as expected since the latter value will be truncated.

The comparison functions provided by this package normalize values to the lowest granularity of the values being compared before performing the actual comparison.

Index

• func After(a, b commonTime) bool
• func AfterOrEqual(a, b commonTime) bool
• func AssertTimeEqual(t testing.TB, expected stringableTimeValue, actual stringableTimeValue) (equal bool)
• func Before(a, b commonTime) bool
• func BeforeOrEqual(a, b commonTime) bool
• func Equal(a, b commonTime) bool
• func RequireTimeEqual(t testing.TB, expected stringableTimeValue, actual stringableTimeValue)

Functions

func After

func After(a, b commonTime) bool

After returns true if the normalized version of a is strictly after the normalized version of b.

Values are normalized to the lowest granularity between the two values: seconds if either is metav1.Time, microseconds if either is metav1.MicroTime, or monotonically-stripped if both are time.Time. Nil time values are normalized to the zero-time.

func AfterOrEqual

func AfterOrEqual(a, b commonTime) bool

AfterOrEqual returns true if the normalized version of a is after or equal to the normalized version of b.

Values are normalized to the lowest granularity between the two values: seconds if either is metav1.Time, microseconds if either is metav1.MicroTime, or monotonically-stripped if both are time.Time. Nil time values are normalized to the zero-time.

func AssertTimeEqual

func AssertTimeEqual(t testing.TB, expected stringableTimeValue, actual stringableTimeValue) (equal bool)

AssertTimeEqual compares two time values using timecmp.Equal and fails the test if not equal.

This simplifies comparing Go stdlib time.Time values with apiserver metav1.Time / metav1.MicroTime values based on the minimum granularity between the two values.

func Before

func Before(a, b commonTime) bool

Before returns true if the normalized version of a is strictly before the normalized version of b.

Values are normalized to the lowest granularity between the two values: seconds if either is metav1.Time, microseconds if either is metav1.MicroTime, or monotonically-stripped if both are time.Time. Nil time values are normalized to the zero-time.

func BeforeOrEqual

func BeforeOrEqual(a, b commonTime) bool

BeforeOrEqual returns true if the normalized version of a is before or equal to the normalized version of b.

Values are normalized to the lowest granularity between the two values: seconds if either is metav1.Time, microseconds if either is metav1.MicroTime, or monotonically-stripped if both are time.Time. Nil time values are normalized to the zero-time.

func Equal

func Equal(a, b commonTime) bool

Equal returns true of the normalized versions of a and b are equal.

Values are normalized to the lowest granularity between the two values: seconds if either is metav1.Time, microseconds if either is metav1.MicroTime, or monotonically-stripped if both are time.Time. Nil time values are normalized to the zero-time.

func RequireTimeEqual

func RequireTimeEqual(t testing.TB, expected stringableTimeValue, actual stringableTimeValue)

RequireTimeEqual compares two time values using timecmp.Equal and fails the test immediately if not equal.

This simplifies comparing Go stdlib time.Time values with apiserver metav1.Time / metav1.MicroTime values based on the minimum granularity between the two values.