Timeline.cs

/*
 Author: Lorenzo Lotti
 Name: Timeline (DataStructures.Timeline<TValue>)
 Type: Data structure (class)
 Description: A collection of dates/times and values sorted by dates/times easy to query.
 Usage:
 this data structure can be used to represent an ordered series of dates or times with which to associate values.
 An example is a chronology of events:
 306: Constantine is the new emperor,
 312: Battle of the Milvian Bridge,
 313: Edict of Milan,
 330: Constantine move the capital to Constantinople.
*/

usingSystem;
usingSystem.Collections;
usingSystem.Collections.Generic;
usingSystem.Linq;

namespaceDataStructures;

/// <summary>
/// A collection of <see cref="DateTime" /> and <see cref="TValue" />
/// sorted by <see cref="DateTime" /> field.
/// </summary>
/// <typeparam name="TValue">Value associated with a <see cref="DateTime" />.</typeparam>
publicclassTimeline<TValue>:ICollection<(DateTimeTime,TValueValue)>,IEquatable<Timeline<TValue>>
{
/// <summary>
/// Inner collection storing the timeline events as key-tuples.
/// </summary>
privatereadonlyList<(DateTimeTime,TValueValue)>timeline=new();

/// <summary>
/// Initializes a new instance of the <see cref="Timeline{TValue}"/> class.
/// </summary>
publicTimeline()
{
}

/// <summary>
/// Initializes a new instance of the <see cref="Timeline{TValue}"/> class populated with an initial event.
/// </summary>
/// <param name="time">The time at which the given event occurred.</param>
/// <param name="value">The event's content.</param>
publicTimeline(DateTimetime,TValuevalue)
=>timeline=newList<(DateTime,TValue)>
{
(time,value),
};

/// <summary>
/// Initializes a new instance of the <see cref="Timeline{TValue}"/> class containing the provided events
/// ordered chronologically.
/// </summary>
/// <param name="timeline">The timeline to represent.</param>
publicTimeline(params(DateTime,TValue)[]timeline)
=>this.timeline=timeline
.OrderBy(pair =>pair.Item1)
.ToList();

/// <summary>
/// Gets he number of unique times within this timeline.
/// </summary>
publicintTimesCount
=>GetAllTimes().Length;

/// <summary>
/// Gets all events that has occurred in this timeline.
/// </summary>
publicintValuesCount
=>GetAllValues().Length;

/// <summary>
/// Get all values associated with <paramref name="time" />.
/// </summary>
/// <param name="time">Time to get values for.</param>
/// <returns>Values associated with <paramref name="time" />.</returns>
publicTValue[]this[DateTimetime]
{
get=>GetValuesByTime(time);
set
{
varoverridenEvents=timeline.Where(@event =>@event.Time==time).ToList();
foreach(var@eventinoverridenEvents)
{
timeline.Remove(@event);
}

foreach(varvinvalue)
{
Add(time,v);
}
}
}

/// <inheritdoc />
boolICollection<(DateTimeTime,TValueValue)>.IsReadOnly
=>false;

/// <summary>
/// Gets the count of pairs.
/// </summary>
publicintCount
=>timeline.Count;

/// <summary>
/// Clear the timeline, removing all events.
/// </summary>
publicvoidClear()
=>timeline.Clear();

/// <summary>
/// Copy a value to an array.
/// </summary>
/// <param name="array">Destination array.</param>
/// <param name="arrayIndex">The start index.</param>
publicvoidCopyTo((DateTime,TValue)[]array,intarrayIndex)
=>timeline.CopyTo(array,arrayIndex);

/// <summary>
/// Add an event at a given time.
/// </summary>
/// <param name="item">The tuple containing the event date and value.</param>
voidICollection<(DateTimeTime,TValueValue)>.Add((DateTimeTime,TValueValue)item)
=>Add(item.Time,item.Value);

/// <summary>
/// Check whether or not a event exists at a specific date in the timeline.
/// </summary>
/// <param name="item">The tuple containing the event date and value.</param>
/// <returns>True if this event exists at the given date, false otherwise.</returns>
boolICollection<(DateTimeTime,TValueValue)>.Contains((DateTimeTime,TValueValue)item)
=>Contains(item.Time,item.Value);

/// <summary>
/// Remove an event at a specific date.
/// </summary>
/// <param name="item">The tuple containing the event date and value.</param>
/// <returns>True if the event was removed, false otherwise.</returns>
boolICollection<(DateTimeTime,TValueValue)>.Remove((DateTimeTime,TValueValue)item)
=>Remove(item.Time,item.Value);

/// <inheritdoc />
IEnumeratorIEnumerable.GetEnumerator()
=>timeline.GetEnumerator();

/// <inheritdoc />
IEnumerator<(DateTimeTime,TValueValue)>IEnumerable<(DateTimeTime,TValueValue)>.GetEnumerator()
=>timeline.GetEnumerator();

/// <inheritdoc />
publicboolEquals(Timeline<TValue>?other)
=>otheris not null&&this==other;

/// <summary>
/// Checks whether or not two <see cref="Timeline{TValue}"/> are equals.
/// </summary>
/// <param name="left">The first timeline.</param>
/// <param name="right">The other timeline to be checked against the <paramref name="left"/> one.</param>
/// <returns>True if both timelines are similar, false otherwise.</returns>
publicstaticbooloperator==(Timeline<TValue>left,Timeline<TValue>right)
{
varleftArray=left.ToArray();
varrightArray=right.ToArray();

if(left.Count!=rightArray.Length)
{
returnfalse;
}

for(vari=0;i<leftArray.Length;i++)
{
if(leftArray[i].Time!=rightArray[i].Time
&&!leftArray[i].Value!.Equals(rightArray[i].Value))
{
returnfalse;
}
}

returntrue;
}

/// <summary>
/// Checks whether or not two <see cref="Timeline{TValue}"/> are not equals.
/// </summary>
/// <param name="left">The first timeline.</param>
/// <param name="right">The other timeline to be checked against the <paramref name="left"/> one.</param>
/// <returns>False if both timelines are similar, true otherwise.</returns>
publicstaticbooloperator!=(Timeline<TValue>left,Timeline<TValue>right)
=>!(left==right);

/// <summary>
/// Get all <see cref="DateTime" /> of the timeline.
/// </summary>
publicDateTime[]GetAllTimes()
=>timeline.Select(t =>t.Time)
.Distinct()
.ToArray();

/// <summary>
/// Get <see cref="DateTime" /> values of the timeline that have this <paramref name="value" />.
/// </summary>
publicDateTime[]GetTimesByValue(TValuevalue)
=>timeline.Where(pair =>pair.Value!.Equals(value))
.Select(pair =>pair.Time)
.ToArray();

/// <summary>
/// Get all <see cref="DateTime" /> before <paramref name="time" />.
/// </summary>
publicDateTime[]GetTimesBefore(DateTimetime)
=>GetAllTimes()
.Where(t =>t<time)
.OrderBy(t =>t)
.ToArray();

/// <summary>
/// Get all <see cref="DateTime" /> after <paramref name="time" />.
/// </summary>
publicDateTime[]GetTimesAfter(DateTimetime)
=>GetAllTimes()
.Where(t =>t>time)
.OrderBy(t =>t)
.ToArray();

/// <summary>
/// Get all <see cref="TValue" /> of the timeline.
/// </summary>
publicTValue[]GetAllValues()
=>timeline.Select(pair =>pair.Value)
.ToArray();

/// <summary>
/// Get all <see cref="TValue" /> associated with <paramref name="time" />.
/// </summary>
publicTValue[]GetValuesByTime(DateTimetime)
=>timeline.Where(pair =>pair.Time==time)
.Select(pair =>pair.Value)
.ToArray();

/// <summary>
/// Get all <see cref="TValue" /> before <paramref name="time" />.
/// </summary>
publicTimeline<TValue>GetValuesBefore(DateTimetime)
=>new(this.Where(pair =>pair.Time<time).ToArray());

/// <summary>
/// Get all <see cref="TValue" /> before <paramref name="time" />.
/// </summary>
publicTimeline<TValue>GetValuesAfter(DateTimetime)
=>new(this.Where(pair =>pair.Time>time).ToArray());

/// <summary>
/// Gets all values that happened at specified millisecond.
/// </summary>
/// <param name="millisecond">Value to look for.</param>
/// <returns>Array of values.</returns>
publicTimeline<TValue>GetValuesByMillisecond(intmillisecond)
=>new(timeline.Where(pair =>pair.Time.Millisecond==millisecond).ToArray());

/// <summary>
/// Gets all values that happened at specified second.
/// </summary>
/// <param name="second">Value to look for.</param>
/// <returns>Array of values.</returns>
publicTimeline<TValue>GetValuesBySecond(intsecond)
=>new(timeline.Where(pair =>pair.Time.Second==second).ToArray());

/// <summary>
/// Gets all values that happened at specified minute.
/// </summary>
/// <param name="minute">Value to look for.</param>
/// <returns>Array of values.</returns>
publicTimeline<TValue>GetValuesByMinute(intminute)
=>new(timeline.Where(pair =>pair.Time.Minute==minute).ToArray());

/// <summary>
/// Gets all values that happened at specified hour.
/// </summary>
/// <param name="hour">Value to look for.</param>
/// <returns>Array of values.</returns>
publicTimeline<TValue>GetValuesByHour(inthour)
=>new(timeline.Where(pair =>pair.Time.Hour==hour).ToArray());

/// <summary>
/// Gets all values that happened at specified day.
/// </summary>
/// <param name="day">Value to look for.</param>
/// <returns>Array of values.</returns>
publicTimeline<TValue>GetValuesByDay(intday)
=>new(timeline.Where(pair =>pair.Time.Day==day).ToArray());

/// <summary>
/// Gets all values that happened at specified time of the day.
/// </summary>
/// <param name="timeOfDay">Value to look for.</param>
/// <returns>Array of values.</returns>
publicTimeline<TValue>GetValuesByTimeOfDay(TimeSpantimeOfDay)
=>new(timeline.Where(pair =>pair.Time.TimeOfDay==timeOfDay).ToArray());

/// <summary>
/// Gets all values that happened at specified day of the week.
/// </summary>
/// <param name="dayOfWeek">Value to look for.</param>
/// <returns>Array of values.</returns>
publicTimeline<TValue>GetValuesByDayOfWeek(DayOfWeekdayOfWeek)
=>new(timeline.Where(pair =>pair.Time.DayOfWeek==dayOfWeek).ToArray());

/// <summary>
/// Gets all values that happened at specified day of the year.
/// </summary>
/// <param name="dayOfYear">Value to look for.</param>
/// <returns>Array of values.</returns>
publicTimeline<TValue>GetValuesByDayOfYear(intdayOfYear)
=>new(timeline.Where(pair =>pair.Time.DayOfYear==dayOfYear).ToArray());

/// <summary>
/// Gets all values that happened at specified month.
/// </summary>
/// <param name="month">Value to look for.</param>
/// <returns>Array of values.</returns>
publicTimeline<TValue>GetValuesByMonth(intmonth)
=>new(timeline.Where(pair =>pair.Time.Month==month).ToArray());

/// <summary>
/// Gets all values that happened at specified year.
/// </summary>
/// <param name="year">Value to look for.</param>
/// <returns>Array of values.</returns>
publicTimeline<TValue>GetValuesByYear(intyear)
=>new(timeline.Where(pair =>pair.Time.Year==year).ToArray());

/// <summary>
/// Add an event at a given <paramref name="time"/>.
/// </summary>
/// <param name="time">The date at which the event occurred.</param>
/// <param name="value">The event value.</param>
publicvoidAdd(DateTimetime,TValuevalue)
{
timeline.Add((time,value));
}

/// <summary>
/// Add a set of <see cref="DateTime" /> and <see cref="TValue" /> to the timeline.
/// </summary>
publicvoidAdd(params(DateTime,TValue)[]timeline)
{
this.timeline.AddRange(timeline);
}

/// <summary>
/// Append an existing timeline to this one.
/// </summary>
publicvoidAdd(Timeline<TValue>timeline)
=>Add(timeline.ToArray());

/// <summary>
/// Add a <paramref name="value" /> associated with <see cref="DateTime.Now" /> to the timeline.
/// </summary>
publicvoidAddNow(paramsTValue[]value)
{
varnow=DateTime.Now;
foreach(varvinvalue)
{
Add(now,v);
}
}

/// <summary>
/// Check whether or not a event exists at a specific date in the timeline.
/// </summary>
/// <param name="time">The date at which the event occurred.</param>
/// <param name="value">The event value.</param>
/// <returns>True if this event exists at the given date, false otherwise.</returns>
publicboolContains(DateTimetime,TValuevalue)
=>timeline.Contains((time,value));

/// <summary>
/// Check if timeline contains this set of value pairs.
/// </summary>
/// <param name="timeline">The events to checks.</param>
/// <returns>True if any of the events has occurred in the timeline.</returns>
publicboolContains(params(DateTime,TValue)[]timeline)
=>timeline.Any(@event =>Contains(@event.Item1,@event.Item2));

/// <summary>
/// Check if timeline contains any of the event of the provided <paramref name="timeline"/>.
/// </summary>
/// <param name="timeline">The events to checks.</param>
/// <returns>True if any of the events has occurred in the timeline.</returns>
publicboolContains(Timeline<TValue>timeline)
=>Contains(timeline.ToArray());

/// <summary>
/// Check if timeline contains any of the time of the provided <paramref name="times"/>.
/// </summary>
/// <param name="times">The times to checks.</param>
/// <returns>True if any of the times is stored in the timeline.</returns>
publicboolContainsTime(paramsDateTime[]times)
{
varstoredTimes=GetAllTimes();
returntimes.Any(value =>storedTimes.Contains(value));
}

/// <summary>
/// Check if timeline contains any of the event of the provided <paramref name="values"/>.
/// </summary>
/// <param name="values">The events to checks.</param>
/// <returns>True if any of the events has occurred in the timeline.</returns>
publicboolContainsValue(paramsTValue[]values)
{
varstoredValues=GetAllValues();
returnvalues.Any(value =>storedValues.Contains(value));
}

/// <summary>
/// Remove an event at a specific date.
/// </summary>
/// <param name="time">The date at which the event occurred.</param>
/// <param name="value">The event value.</param>
/// <returns>True if the event was removed, false otherwise.</returns>
publicboolRemove(DateTimetime,TValuevalue)
=>timeline.Remove((time,value));

/// <summary>
/// Remove a set of value pairs from the timeline.
/// </summary>
/// <param name="timeline">An collection of all events to remove.</param>
/// <returns>Returns true if the operation completed successfully.</returns>
publicboolRemove(params(DateTime,TValue)[]timeline)
{
varresult=false;
foreach(var(time,value)intimeline)
{
result|=this.timeline.Remove((time,value));
}

returnresult;
}

/// <summary>
/// Remove an existing timeline from this timeline.
/// </summary>
/// <param name="timeline">An collection of all events to remove.</param>
/// <returns>Returns true if the operation completed successfully.</returns>
publicboolRemove(Timeline<TValue>timeline)
=>Remove(timeline.ToArray());

/// <summary>
/// Remove a value pair from the timeline if the time is equal to <paramref name="times" />.
/// </summary>
/// <returns>Returns true if the operation completed successfully.</returns>
publicboolRemoveTimes(paramsDateTime[]times)
{
varisTimeContainedInTheTimeline=times.Any(time =>GetAllTimes().Contains(time));

if(!isTimeContainedInTheTimeline)
{
returnfalse;
}

vareventsToRemove=times.SelectMany(time =>
timeline.Where(@event =>@event.Time==time))
.ToList();

foreach(var@eventineventsToRemove)
{
timeline.Remove(@event);
}

returntrue;
}

/// <summary>
/// Remove a value pair from the timeline if the value is equal to <paramref name="values" />.
/// </summary>
/// <returns>Returns true if the operation completed successfully.</returns>
publicboolRemoveValues(paramsTValue[]values)
{
varisValueContainedInTheTimeline=values.Any(v =>GetAllValues().Contains(v));

if(!isValueContainedInTheTimeline)
{
returnfalse;
}

vareventsToRemove=values.SelectMany(value =>
timeline.Where(@event =>EqualityComparer<TValue>.Default.Equals(@event.Value,value)))
.ToList();

foreach(var@eventineventsToRemove)
{
timeline.Remove(@event);
}

returntrue;
}

/// <summary>
/// Convert the timeline to an array.
/// </summary>
/// <returns>
/// The timeline as an array of tuples of (<see cref="DateTime"/>, <typeparamref name="TValue"/>).
/// </returns>
public(DateTimeTime,TValueValue)[]ToArray()
=>timeline.ToArray();

/// <summary>
/// Convert the timeline to a list.
/// </summary>
/// <returns>
/// The timeline as a list of tuples of (<see cref="DateTime"/>, <typeparamref name="TValue"/>).
/// </returns>
publicIList<(DateTimeTime,TValueValue)>ToList()
=>timeline;

/// <summary>
/// Convert the timeline to a dictionary.
/// </summary>
/// <returns>
/// The timeline as an dictionary of <typeparamref name="TValue"/> by <see cref="DateTime"/>.
/// </returns>
publicIDictionary<DateTime,TValue>ToDictionary()
=>timeline.ToDictionary(@event =>@event.Time, @event =>@event.Value);

/// <inheritdoc />
publicoverrideboolEquals(object?obj)
=>objisTimeline<TValue>otherTimeline
&&this==otherTimeline;

/// <inheritdoc />
publicoverrideintGetHashCode()
=>timeline.GetHashCode();
}