pub struct Span<T> {
pub start: T,
pub end: T,
}
Expand description
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§
source§impl<T: TimeZone> Span<Date<T>>
impl<T: TimeZone> Span<Date<T>>
sourcepub fn from_local_datespan(span: &NaiveDateSpan, tz: &T) -> Result<Self, Error>
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.
sourcepub fn from_utc_datespan(span: &NaiveDateSpan, tz: &T) -> Self
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");
source§impl<T: TimeZone> Span<DateTime<T>>
impl<T: TimeZone> Span<DateTime<T>>
sourcepub fn from_local_datetimespan(
span: &NaiveDateTimeSpan,
tz: &T
) -> Result<Self, Error>
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.
sourcepub fn from_utc_datetimespan(span: &NaiveDateTimeSpan, tz: &T) -> Self
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");
source§impl<T> Span<T>where
T: Spanable,
impl<T> Span<T>where
T: Spanable,
sourcepub fn new(start: T, end: T) -> Result<Span<T>, Error>
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.
sourcepub fn difference(&self, other: &Span<T>) -> Result<Span<T>, Error>
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
)
sourcepub fn symmetric_difference(&self, other: &Span<T>) -> Result<Span<T>, Error>
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.
sourcepub fn intersection(&self, other: &Span<T>) -> Result<Span<T>, 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.
sourcepub fn union(&self, other: &Span<T>) -> Result<Span<T>, Error>
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.
sourcepub fn contains(&self, item: &T) -> bool
pub fn contains(&self, item: &T) -> bool
Returns true
when a given Spanable
is included in self
. Otherwise returns false
.
sourcepub fn is_disjoint(&self, other: &Span<T>) -> bool
pub fn is_disjoint(&self, other: &Span<T>) -> bool
Returns true
when self
has no parts in common with other
. Otherwise returns false
.
sourcepub fn is_subset(&self, other: &Span<T>) -> bool
pub fn is_subset(&self, other: &Span<T>) -> bool
Returns true
when self
is completely included in other
. Otherwise returns false
.
sourcepub fn is_superset(&self, other: &Span<T>) -> bool
pub fn is_superset(&self, other: &Span<T>) -> bool
Returns true
when other
is completely included in self
. Otherwise returns false
.
sourcepub fn split_off(&self, at: &T) -> Result<(Span<T>, Span<T>), Error>
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
.
sourcepub fn append(&mut self, time: &Duration) -> Result<(), Error>
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).
sourcepub fn prepend(&mut self, time: &Duration) -> Result<(), Error>
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).
source§impl<T> Span<T>where
T: Spanable + Formatable,
impl<T> Span<T>where
T: Spanable + Formatable,
sourcepub fn format<'a>(
&self,
fmt: &'a str,
start: &'a str,
end: &'a str
) -> DelayedFormat<'a, T>
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 thestart
point of the span{end}
to match theend
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");
source§impl<T> Span<T>
impl<T> Span<T>
sourcepub fn parse_from_str(
s: &str,
fmt: &str,
start: &str,
end: &str
) -> Result<Span<T>, Error>
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 thestart
point of the span{end}
to match theend
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");
Trait Implementations§
source§impl<T> Debug for Span<T>where
T: Spanable + Formatable,
impl<T> Debug for Span<T>where
T: Spanable + Formatable,
Formats a Span
in the format {start} - {end}
.
source§impl<'de, T> Deserialize<'de> for Span<T>
impl<'de, T> Deserialize<'de> for Span<T>
source§fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>where
D: Deserializer<'de>,
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>where
D: Deserializer<'de>,
source§impl<T> Display for Span<T>where
T: Spanable + Formatable,
impl<T> Display for Span<T>where
T: Spanable + Formatable,
Formats a Span
in the format {start} - {end}
.