Period utilities

This page contains the public interface for period manipulation. For the computation details see Period Functors.

Toolbox for manipulation of time period. Two types of time period are proposed, along with shortcuts for list of periods:

time_period : shortcut for boost::posix_time::time_period
extended_period : abstract time_period with an additional attribute
capa_period : time_period with capacity (int64_t)
ratio_period : time_period with a ratio (float)

One can then compute the union, the intersection or the difference between list of periods:

Time_periods : basic interval arithmetic
Capa_periods :
- Union of capa_periods : compute the sum of the capacity (default value being 0)
  - the union of {[a, b, 2]} and {[b, c, 3]}, with a<b<c is {[a, b, 2], [b, c, 3]}
  - the union of {[a, b, 2]} and {[a, b, 3]} is {[a, b, 5]}
  - the union of {[a, c, 2]} and {[a, b, 3]}, with a<b<c, is {[a, b, 5], [b, c, 2]}

Difference of capa_periods : compute the difference of the capacity (default value being 0)

the difference of {[a, b, 3]} and {[a, b, 2]} is {[a, b, 1]}
the difference of {[a, c, 3]} and {[a, b, 1]}, with a<b<c, is {[a, b, 1], [b, c, 3]}

Intersection of capa_periods : limit to the intersection with minimal capacity (default value being 0)

the intersection of {[a, b, 2]} and {[a, b, 3]} is {[a, b, 2]}
the intersection of {[a, c, 2]} and {[a, b, 3]}, with a<b<c, is {[a, b, 2]}

Ratio_periods :

Union of ratio_periods : compute the sum of the ratios (the default value being 0.)
- the union of {[a, b, 2.]} and {[a, b, 3.]} is {[a, b, 5.]}
- the union of {[a, c, 2.]} and {[a, b, 3.]}, with a<b<c, is {[a, b, 5.], [b, c, 2.]}

Intersection of ratio_periods : limit to the intersection with minimal ratio (default value being 0.)

the intersection of {[a, b, 2]} and {[a, b, 3]} is {[a, b, 2.]}
the intersection of {[a, c, 2]} and {[a, b, 3]}, with a<b<c, is {[a, b, 2.]}

Mixing time_period and extended_periods :

Union / Difference / Intersection of time_period and extended_period : works as if both were time_periods
Difference between a capa_period and a time_period : remove the whole capacity during the time_period
- the difference between {[a, c, 2]} and {[a, b]}, with a<b<c, is {[b, c, 2]}
- the difference between {[a, b, 2]} and {[b, c]}, with a<b<c, is {[a, b, 2]}
Intersection between a capa_period and a time_period : limit the capa_period to the time_period
- the intersection between {[a, c, 2]} and {[a, b]}, with a<b<c, is {[a, b, 2]}
- the intersection between {[a, b, 2]} and {[b, c]}, with a<b<c, is {}
Union between a ratio_period and a time_period : during time_period, set the ratio to 1. if no ratio is defined
- the union between {[a, c, 2.]} and {[a, b]}, with a<b<c, is {[a, c, 2.]}
- the union between {[a, b, 2.]} and {[b, c]}, with a<b<c, is {[a, b, 2.], [b, c, 1.]}
Difference between a ratio_period and a time_period : remove the whole ratio during the time_period
- the difference between {[a, c, 2.]} and {[a, b]}, with a<b<c, is {[b, c, 2.]}
- the difference between {[a, b, 2.]} and {[b, c]}, with a<b<c, is {[a, b, 2.]}
Intersection between a ratio_period and a time_period : limit the ratio_period to the time_period
- the intersection between {[a, c, 2.]} and {[a, b]}, with a<b<c, is {[a, b, 2.]}
- the intersection between {[a, b, 2.]} and {[b, c]}, with a<b<c, is {}

Remark

Each method has an optional parameter merge_adjacent telling if one should merge the adjacent periods (with the same capacity or ratio)

Remark

Every capa_period with a capacity of 0 will be removed

Remark

In some case, one may need to keep ‘empty’ periods st. start == end (eg. to compute some ending times)

Warning

Every list must contain sorted and disjoint (or adjacent) periods

Functions

MAKE_DTO_ENUM (TemporalMesh, NONE, DAY, WEEK, MONTH, HORIZON) template< typename PeriodT

Compute the union of two lists of Periods.

Template Parameters:

PeriodT – the type of first periods
PeriodU – the type of second periods

Parameters:

periods1 – first list
periods2 – second list
merge_adjacent – should we merge the adjacent periods

Pre:

the lists must be sorted and contain disjoint periods

Returns:

the union

PeriodU std::list< PeriodT > get_union (std::list< PeriodT > const &periods1, std::list< PeriodU > const &periods2, bool merge_adjacent=true)

template<typename PeriodT, typename PeriodU> std::list<PeriodT> get_union(PeriodT const &period, std::list<PeriodU> const &periods, bool merge_adjacent = true)

Compute the union of a period and a list of periods.

Template Parameters:

PeriodT – the type of first periods
PeriodU – the type of second periods

Parameters:

period – the period
periods – the list
merge_adjacent – should we merge the adjacent periods

Pre:

the list must be sorted and contain disjoint periods

Returns:

the union

template<typename PeriodT, typename PeriodU> std::list<PeriodT> get_union(std::list<PeriodT> const &periods, PeriodU const &period, bool merge_adjacent = true)

Compute the union of a list of periods and a period.

Template Parameters:

PeriodT – the type of first periods
PeriodU – the type of second periods

Parameters:

period – the period
periods – the list
merge_adjacent – should we merge the adjacent periods

Pre:

the list must be sorted and contain disjoint periods

Returns:

the union

template<typename PeriodT, typename PeriodU> std::list<PeriodT> get_union(PeriodT const &period1, PeriodU const &period2, bool merge_adjacent = true)

Compute the union of two periods.

Template Parameters:

PeriodT – the type of first periods
PeriodU – the type of second periods

Parameters:

period1 – the first period
period2 – the second period
merge_adjacent – should we merge the adjacent periods

Pre:

the list must be sorted and contain disjoint periods

Returns:

the union

template<typename PeriodT, typename PeriodU> std::list<PeriodT> get_diff(std::list<PeriodT> const &periods1, std::list<PeriodU> const &periods2, bool merge_adjacent = true)

Compute the difference of two lists of Periods.

Template Parameters:

PeriodT – the type of first periods
PeriodU – the type of second periods

Parameters:

periods1 – first list
periods2 – second list
merge_adjacent – should we merge the adjacent periods

Pre:

the lists must be sorted and contain disjoint periods

Returns:

the difference

template<typename PeriodT, typename PeriodU> std::list<PeriodT> get_diff(PeriodT const &period, std::list<PeriodU> const &periods, bool merge_adjacent = true)

Compute the difference of a period and a list of periods.

Template Parameters:

PeriodT – the type of first periods
PeriodU – the type of second periods

Parameters:

period – the period
periods – the list
merge_adjacent – should we merge the adjacent periods

Pre:

the list must be sorted and contain disjoint periods

Returns:

the difference

template<typename PeriodT, typename PeriodU> std::list<PeriodT> get_diff(std::list<PeriodT> const &periods, PeriodU const &period, bool merge_adjacent = true)

Compute the difference of a list of periods and a period.

Template Parameters:

PeriodT – the type of first periods
PeriodU – the type of second periods

Parameters:

periods – the list
period – the period
merge_adjacent – should we merge the adjacent periods

Pre:

the list must be sorted and contain disjoint periods

Returns:

the difference

template<typename PeriodT, typename PeriodU> std::list<PeriodT> get_diff(PeriodT const &period1, PeriodU const &period2, bool merge_adjacent = true)

Compute the difference of two periods.

Template Parameters:

PeriodT – the type of first periods
PeriodU – the type of second periods

Parameters:

period1 – the first period
period2 – the second period
merge_adjacent – should we merge the adjacent periods

Pre:

the list must be sorted and contain disjoint periods

Returns:

the difference

template<typename PeriodT, typename PeriodU> std::list<PeriodT> get_inter(std::list<PeriodT> const &periods1, std::list<PeriodU> const &periods2, bool merge_adjacent = true)

Compute the intersection of two lists of Periods.

Template Parameters:

PeriodT – the type of first periods
PeriodU – the type of second periods

Parameters:

periods1 – first list
periods2 – second list
merge_adjacent – should we merge the adjacent periods

Pre:

the lists must be sorted and contain disjoint periods

Returns:

the intersection

template<typename PeriodT, typename PeriodU> std::list<PeriodT> get_inter(PeriodT const &period, std::list<PeriodU> const &periods, bool merge_adjacent = true)

Compute the intersection of a period and a list of periods.

Template Parameters:

PeriodT – the type of first period
PeriodU – the type of second periods

Parameters:

period – the period
periods – the list
merge_adjacent – should we merge the adjacent periods

Pre:

the list must be sorted and contain disjoint periods

Returns:

the intersection

template<typename PeriodT, typename PeriodU> std::list<PeriodT> get_inter(std::list<PeriodT> const &periods, PeriodU const &period, bool merge_adjacent = true)

Compute the intersection of a list of periods and a period.

Template Parameters:

PeriodT – the type of first periods
PeriodU – the type of second period

Parameters:

periods – the list
period – the period
merge_adjacent – should we merge the adjacent periods

Pre:

the list must be sorted and contain disjoint periods

Returns:

the intersection

template<typename PeriodT, typename PeriodU> std::list<PeriodT> get_inter(PeriodT const &period1, PeriodU const &period2, bool merge_adjacent = true)

Compute the intersection of two period.

Template Parameters:

PeriodT – the type of first period
PeriodU – the type of second period

Parameters:

period1 – the first period
period2 – the second period
merge_adjacent – should we merge the adjacent periods

Pre:

the list must be sorted and contain disjoint periods

Returns:

the intersection

template<typename PeriodT, typename PeriodU> std::list<PeriodT> get_inter_with_empty(std::list<PeriodT> const &periods1, std::list<PeriodU> const &periods2, bool merge_adjacent = true)

Compute the intersection of two lists of Periods and keep the periods with just one time stamp.

Template Parameters:

PeriodT – the type of first periods
PeriodU – the type of second periods

Parameters:

periods1 – first list
periods2 – second list
merge_adjacent – should we merge the adjacent periods

Pre:

the lists must be sorted and contain disjoint periods

Returns:

the intersection

template<typename PeriodT, typename PeriodU> std::list<PeriodT> get_inter_with_empty(PeriodT const &period, std::list<PeriodU> const &periods, bool merge_adjacent = true)

Compute the intersection of two lists of Periods and keep the periods with just one time stamp.

Template Parameters:

PeriodT – the type of first period
PeriodU – the type of second periods

Parameters:

period – the period
periods – the list
merge_adjacent – should we merge the adjacent periods

Pre:

the list must be sorted and contain disjoint periods

Returns:

the intersection

template<typename PeriodT, typename PeriodU> std::list<PeriodT> get_inter_with_empty(std::list<PeriodT> const &periods, PeriodU const &period, bool merge_adjacent = true)

Compute the intersection of two lists of Periods and keep the periods with just one time stamp.

Template Parameters:

PeriodT – the type of first periods
PeriodU – the type of second period

Parameters:

periods – the list
period – the period
merge_adjacent – should we merge the adjacent periods
keep_empty – should we keep the empty periods

Pre:

the list must be sorted and contain disjoint periods

Returns:

the intersection

template<typename PeriodT, typename PeriodU> std::list<PeriodT> get_inter_with_empty(PeriodT const &period1, PeriodU const &period2, bool merge_adjacent = true)

Compute the intersection of two lists of Periods and keep the periods with just one time stamp.

Template Parameters:

PeriodT – the type of first period
PeriodU – the type of second period

Parameters:

period1 – the first period
period2 – the second period
merge_adjacent – should we merge the adjacent periods

Pre:

the list must be sorted and contain disjoint periods

Returns:

the intersection

boost::posix_time::time_duration compute_relative_duration(boost::posix_time::time_duration duration, float ratio)

Compute a relative duration (duration multiplied by ratio)

Parameters:

duration – the absolute duration
ratio – the ratio to apply

Returns:

the relative duration

boost::posix_time::time_duration compute_theoretical_duration(boost::posix_time::time_duration duration, float ratio)

Compute an absolute duration (duration divided by ratio)

Parameters:

duration – the relative duration
ratio – the ratio to apply

Returns:

the absolute duration

template<typename PeriodT> boost::posix_time::time_duration get_total_duration(std::list<PeriodT> const &periods)

Compute the cumulative duration of a list of periods.

Template Parameters:: PeriodT – the type of periods
Parameters:: periods – the periods of production
Returns:: the cumulative duration

boost::posix_time::time_duration get_relative_duration(LRatioPeriod const &periods)

Compute the relative duration of a list of periods.

Parameters:: periods – the periods with ratio
Returns:: the relative duration

LRatioPeriod reduce_left(LRatioPeriod const &periods, boost::posix_time::time_duration const &duration)

Reduce a list of periods from the left by a given duration taking into account the ratio of each period.

Parameters:

periods – the list of ratio_periods
duration – the duration

Returns:

the corresponding ratio_periods

LRatioPeriod reduce_right(LRatioPeriod const &periods, boost::posix_time::time_duration const &duration)

Reduce a list of periods from the right by a given duration taking into account the ratio of each period.

Parameters:

periods – the list of ratio_periods
duration – the duration

Returns:

the corresponding ratio_periods

LTimePeriod get_eligible_periods(LCapaPeriod const &periods, int64_t min)

Collect the capa_period with enough capacity and return them as time_period.

Remark

The adjacent periods with enough capacity will be merged together

Parameters:

periods – the list of capa_periods
min – the minimal capacity

Returns:

the corresponding time_periods

Pre:

the lists must be sorted and contain disjoint periods

LCapaPeriod convert(LTimePeriod const &periods, int64_t capa)

Convert a list of time_period into a list of capa_period with a given capacity.

Parameters:

periods – the list of time_periods
capa – the capacity

Returns:

the corresponding capa_periods

time_period make_empty_period(boost::posix_time::ptime ptime)

Create an artificial empty period.

Parameters:: datetime – the ptime
Returns:: a time period [ptime, ptime+10 milliseconds[

bool is_same(boost::posix_time::ptime const &lhs, boost::posix_time::ptime const &rhs, boost::posix_time::time_duration const &tol = boost::posix_time::milliseconds(10))

Checks that two ptime are the same (with a tolerance)

Parameters:

lhs – the first datetime
rhs – the second datetime
tol – the tolerance

bool is_same(boost::posix_time::time_duration const &lhs, boost::posix_time::time_duration const &rhs, boost::posix_time::time_duration const &tol = boost::posix_time::milliseconds(10))

Checks that two durations are the same (with a tolerance)

Parameters:

lhs – the first duration
rhs – the second duration
tol – the tolerance

bool is_same(boost::posix_time::time_period const &lhs, boost::posix_time::time_period const &rhs, boost::posix_time::time_duration const &tol = boost::posix_time::milliseconds(10))

Checks that two durations are the same (with a tolerance)

Parameters:

lhs – the first duration
rhs – the second duration
tol – the tolerance

Period generation

Toolbox for generation of time periods.

Functions

LTimePeriod generate_periods(boost::posix_time::ptime const &start_horizon, boost::posix_time::ptime const &end_horizon, boost::posix_time::time_duration const &start_period, boost::posix_time::time_duration const &end_period)

Generate the time period defined by a couple start/end on an horizon.

Parameters:

start_horizon – the starting date time of the horizon
end_horizon – the ending date time of the horizon
start_period – the starting time of the period
end_period – the ending time of the period

Pre:

end_horizon > start_horizon

Pre:

end_horizon and start_horizon are valid date times

Pre:

00:00:00 <= start_period <= 23:59:59

Pre:

00:00:00 <= end_period <= 23:59:59

LTimePeriod generate_periods(boost::posix_time::ptime const &start_horizon, boost::posix_time::ptime const &end_horizon, TemporalMesh const &temporal_mesh)

Generate the time period defined by a couple start/end on an horizon.

Parameters:

start_horizon – the starting date time of the horizon
end_horizon – the ending date time of the horizon
temporal_mesh – the corresponding mesh

Pre:

end_horizon > start_horizon

LCapaPeriod generate_periods(boost::posix_time::ptime const &start_horizon, boost::posix_time::ptime const &end_horizon, boost::posix_time::time_duration const &start_period, boost::posix_time::time_duration const &end_period, int64_t capa)

Generate the capacitated time period defined by a couple start/end on an horizon.

Parameters:

start_horizon – the starting date time of the horizon
end_horizon – the ending date time of the horizon
start_period – the starting time of the period
end_period – the ending time of the period
capa – the capacity of the periods

Pre:

start_horizon < end_horizon

Pre:

end_horizon and start_horizon are valid date times

Pre:

00:00:00 <= start_period <= 23:59:59

Pre:

00:00:00 <= end_period <= 23:59:59