Struct timespan::Span

pub struct Span<T> {
    pub start: T,
    pub end: T,
}

This describes a span of something that is Spanable by providing a start and end point.

When the provided Spanable type T is Formatable the span can be serialized to a string. For deserialization from a string the Parsable trait must be implemented by T. Support for serde is available when the timespan crate is configured with the with-serde feature.

This type implements operations known from the set theory. However, there are only operations allowed that produce a single span (e.g. the resulting span is continuous) that must not be empty. When an operation would violate these restrictions an error is emitted.

Developer note: A Span may accept all possible input values without leading to errors in the future by producing an iterator over the results allowing an arbitrary amount of resulting spans.

Example

use timespan::Span;
use chrono::NaiveTime;

let start = "12:30:00".parse().unwrap();
let end = "14:45:00".parse().unwrap();
let span: Span<NaiveTime> = Span::new(start, end).unwrap();

assert!(format!("{}", span) == "12:30:00 - 14:45:00");

Fields

start: T

The starting point of the span.

end: T

The end point of the span.

Implementations

impl<T> Span<T>where
    T: Spanable,

pub fn new(start: T, end: T) -> Result<Span<T>, Error>

Create a new span with a given starting point and a given end point.

This method emits an Error::Ordering error when the end point lies before the start point.

pub fn duration(&self) -> Duration

Get the total duration of the span as a chrono::Duration.

pub fn difference(&self, other: &Span<T>) -> Result<Span<T>, Error>

Calculate the mathematical difference of two spans with the same Spanable type.

The difference of span self and other includes the parts of span self that are not included in span other.

This method produces an error when

• the resulting difference would produce an empty span (Error::Empty)
• the resulting difference is not continuous (e.g. splitted) (Error::NotContinuous)

pub fn symmetric_difference(&self, other: &Span<T>) -> Result<Span<T>, Error>

Calculate the mathematical symmetric difference of two spans with the same Spanable type.

The symmetric difference of span self and other includes the parts of span self that are not included in span other and the parts of span other that are not included in span self.

This method produces an error when the resulting symmetric difference is not continuous (e.g. splitted) (Error::NotContinuous). As this is only not the case when the two spans are adjacent this method will most likely produce an error.

pub fn intersection(&self, other: &Span<T>) -> Result<Span<T>, Error>

Calculate the mathematical intersection of two spans with the same Spanable type.

The intersection of span self and other includes the parts that are included in span self and span other.

This method produces an Error::Empty error when there is no intersection between the two spans.

pub fn union(&self, other: &Span<T>) -> Result<Span<T>, Error>

Calculate the mathematical union of two spans with the same Spanable type.

The union of span self and other includes the parts that are included in span self or span other.

This method produces an Error::NotContinuous error when the two spans are not intersecting or adjacent to each other.

pub fn contains(&self, item: &T) -> bool

Returns true when a given Spanable is included in self. Otherwise returns false.

pub fn is_disjoint(&self, other: &Span<T>) -> bool

Returns true when self has no parts in common with other. Otherwise returns false.

pub fn is_subset(&self, other: &Span<T>) -> bool

Returns true when self is completely included in other. Otherwise returns false.

pub fn is_superset(&self, other: &Span<T>) -> bool

Returns true when other is completely included in self. Otherwise returns false.

pub fn split_off(&self, at: &T) -> Result<(Span<T>, Span<T>), Error>

Split self at a given time point at into two spans of the same Spanable type.

This emits an Error::OutOfRange error when at is not included in self.

pub fn append(&mut self, time: &Duration) -> Result<(), Error>

Move the end point forward in time by a given duration.

This emits an Error::Empty error when the operation would produce an empty span (e.g. the duration is negative).

pub fn prepend(&mut self, time: &Duration) -> Result<(), Error>

Move the start point backward in time by a given duration.

This emits an Error::Empty error when the operation would produce an empty span. (e.g. the duration is negative).

pub fn pop(&mut self, time: &Duration) -> Result<(), Error>

Move the end point backward in time by a given duration.

This emits an Error::Empty error when the operation would produce an empty span.

pub fn shift(&mut self, time: &Duration) -> Result<(), Error>

Move the start point forward in time by a given duration.

This emits an Error::Empty error when the operation would produce an empty span.

impl<T> Span<T>where
    T: Spanable + Formatable,

pub fn format<'a>(
    &self,
    fmt: &'a str,
    start: &'a str,
    end: &'a str
) -> DelayedFormat<'a, T>

Formats the span with the specified format strings.

For the start and end format strings see the chrono::format::strftime module.

The fmt string is used to format the span to a string. It must contain the following substrings:

• {start} to match the start point of the span
• {end} to match the end point of the span

Example

use timespan::NaiveTimeSpan;

let span: NaiveTimeSpan = "12:30:00 - 14:45:00".parse().unwrap();

let f = span.format("from {start} to {end}", "%H.%M", "%H.%M");
assert!(f.to_string() == "from 12.30 to 14.45");
assert!(format!("{}", f) == "from 12.30 to 14.45");

impl<T> Span<T>where
    T: Spanable + Parsable,

pub fn parse_from_str(
    s: &str,
    fmt: &str,
    start: &str,
    end: &str
) -> Result<Span<T>, Error>

Parses the span with the specified format strings from a given string s.

For the start and end format strings see the chrono::format::strftime module.

The fmt string is used to parse a span from a string. It must contain the following substrings:

• {start} to match the start point of the span
• {end} to match the end point of the span

Example

use timespan::NaiveTimeSpan;

let span = NaiveTimeSpan::parse_from_str(
    "from 12.30 to 14.45",
    "from {start} to {end}",
    "%H.%M",
    "%H.%M",
).unwrap();

assert!(format!("{}", span) == "12:30:00 - 14:45:00");

impl<T: TimeZone> Span<Date<T>>

pub fn from_local_datespan(span: &NaiveDateSpan, tz: &T) -> Result<Self, Error>

Create a DateSpan from a NaiveDateSpan with the time zone set to the local time zone.

Currently the result handling of the internally used TimeZone::from_local_date is not implemented properly. Therefore only date spans with a single local time zone can be created. Ambigious local time zones will lead to Error::LocalAmbigious.

To avoid this from_utc_datespan should be prefered.

pub fn from_utc_datespan(span: &NaiveDateSpan, tz: &T) -> Self

Create a DateSpan from a NaiveDateSpan with the time zone set to UTC.

As a DateSpan cannot be parsed from a string this method is the preferred way of creating a DateSpan.

Example

use timespan::DateSpan;
use chrono_tz::Europe::Berlin;

let a = DateSpan::from_utc_datespan(
    &"2017-05-21 - 2017-05-27".parse().unwrap(),
    &Berlin,
);

assert!(format!("{}", a) == "2017-05-21CEST - 2017-05-27CEST");

impl<T: TimeZone> Span<DateTime<T>>

pub fn from_local_datetimespan(
    span: &NaiveDateTimeSpan,
    tz: &T
) -> Result<Self, Error>

Create a DateTimeSpan from a NaiveDateTimeSpan with the time zone set to the local time zone.

Currently the result handling of the internally used TimeZone::from_local_datetime is not implemented properly. Therefore only date spans with a single local time zone can be created. Ambigious local time zones will lead to Error::LocalAmbigious.

To avoid this from_utc_datetimespan should be prefered.

pub fn from_utc_datetimespan(span: &NaiveDateTimeSpan, tz: &T) -> Self

Create a DateTimeSpan from a NaiveDateTimeSpan with the time zone set to UTC.

Example

use timespan::DateTimeSpan;
use chrono_tz::America::Puerto_Rico;

let a = DateTimeSpan::from_utc_datetimespan(
    &"2017-03-12T12:00:00 - 2017-03-15T14:00:00".parse().unwrap(),
    &Puerto_Rico,
);

assert!(format!("{}", a) == "2017-03-12 08:00:00 AST - 2017-03-15 10:00:00 AST");

Trait Implementations

impl<T: Clone> Clone for Span<T>

fn clone(&self) -> Span<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Span<T>where
    T: Spanable + Formatable,

Formats a Span in the format {start} - {end}.

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

Formats the value using the given formatter.

impl<'de, T> Deserialize<'de> for Span<T>where
    T: Spanable + Parsable,

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

Deserialize this value from the given Serde deserializer.

impl<T> Display for Span<T>where
    T: Spanable + Formatable,

Formats a Span in the format {start} - {end}.

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

Formats the value using the given formatter.

impl<T> FromStr for Span<T>where
    T: Spanable + Parsable,

Parses a Span from a string in the format {start} - {end}.

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl<T: PartialEq> PartialEq<Span<T>> for Span<T>

fn eq(&self, other: &Span<T>) -> 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<T> Serialize for Span<T>where
    T: Spanable + Formatable,

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

Serialize this value into the given Serde serializer.

impl<T> StructuralPartialEq for Span<T>