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.
*/

using System;
using System.Collections;
using System.Collections.Generic;
using System.Linq;

namespace DataStructures;

/// <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>
public class Timeline<TValue> : ICollection<(DateTime Time, TValue Value)>, IEquatable<Timeline<TValue>>
{
    /// <summary>
    ///     Inner collection storing the timeline events as key-tuples.
    /// </summary>
    private readonly List<(DateTime Time, TValue Value)> timeline = new();

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

    /// <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>
    public Timeline(DateTime time, TValue value)
        => timeline = new List<(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>
    public Timeline(params (DateTime, TValue)[] timeline)
        => this.timeline = timeline
            .OrderBy(pair => pair.Item1)
            .ToList();

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

    /// <summary>
    ///     Gets all events that has occurred in this timeline.
    /// </summary>
    public int ValuesCount
        => 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>
    public TValue[] this[DateTime time]
    {
        get => GetValuesByTime(time);
        set
        {
            var overridenEvents = timeline.Where(@event => @event.Time == time).ToList();
            foreach (var @event in overridenEvents)
            {
                timeline.Remove(@event);
            }

            foreach (var v in value)
            {
                Add(time, v);
            }
        }
    }

    /// <inheritdoc />
    bool ICollection<(DateTime Time, TValue Value)>.IsReadOnly
        => false;

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

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

    /// <summary>
    ///     Copy a value to an array.
    /// </summary>
    /// <param name="array">Destination array.</param>
    /// <param name="arrayIndex">The start index.</param>
    public void CopyTo((DateTime, TValue)[] array, int arrayIndex)
        => 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>
    void ICollection<(DateTime Time, TValue Value)>.Add((DateTime Time, TValue Value) 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>
    bool ICollection<(DateTime Time, TValue Value)>.Contains((DateTime Time, TValue Value) 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>
    bool ICollection<(DateTime Time, TValue Value)>.Remove((DateTime Time, TValue Value) item)
        => Remove(item.Time, item.Value);

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

    /// <inheritdoc />
    IEnumerator<(DateTime Time, TValue Value)> IEnumerable<(DateTime Time, TValue Value)>.GetEnumerator()
        => timeline.GetEnumerator();

    /// <inheritdoc />
    public bool Equals(Timeline<TValue>? other)
        => other is 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>
    public static bool operator ==(Timeline<TValue> left, Timeline<TValue> right)
    {
        var leftArray = left.ToArray();
        var rightArray = right.ToArray();

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

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

        return true;
    }

    /// <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>
    public static bool operator !=(Timeline<TValue> left, Timeline<TValue> right)
        => !(left == right);

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

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

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

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

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

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

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

    /// <summary>
    ///     Get all <see cref="TValue" /> before <paramref name="time" />.
    /// </summary>
    public Timeline<TValue> GetValuesAfter(DateTime time)
        => 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>
    public Timeline<TValue> GetValuesByMillisecond(int millisecond)
        => 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>
    public Timeline<TValue> GetValuesBySecond(int second)
        => 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>
    public Timeline<TValue> GetValuesByMinute(int minute)
        => 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>
    public Timeline<TValue> GetValuesByHour(int hour)
        => 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>
    public Timeline<TValue> GetValuesByDay(int day)
        => 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>
    public Timeline<TValue> GetValuesByTimeOfDay(TimeSpan timeOfDay)
        => 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>
    public Timeline<TValue> GetValuesByDayOfWeek(DayOfWeek dayOfWeek)
        => 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>
    public Timeline<TValue> GetValuesByDayOfYear(int dayOfYear)
        => 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>
    public Timeline<TValue> GetValuesByMonth(int month)
        => 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>
    public Timeline<TValue> GetValuesByYear(int year)
        => 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>
    public void Add(DateTime time, TValue value)
    {
        timeline.Add((time, value));
    }

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

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

    /// <summary>
    ///     Add a <paramref name="value" /> associated with <see cref="DateTime.Now" /> to the timeline.
    /// </summary>
    public void AddNow(params TValue[] value)
    {
        var now = DateTime.Now;
        foreach (var v in value)
        {
            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>
    public bool Contains(DateTime time, TValue value)
        => 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>
    public bool Contains(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>
    public bool Contains(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>
    public bool ContainsTime(params DateTime[] times)
    {
        var storedTimes = GetAllTimes();
        return times.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>
    public bool ContainsValue(params TValue[] values)
    {
        var storedValues = GetAllValues();
        return values.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>
    public bool Remove(DateTime time, TValue value)
        => 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>
    public bool Remove(params (DateTime, TValue)[] timeline)
    {
        var result = false;
        foreach (var (time, value) in timeline)
        {
            result |= this.timeline.Remove((time, value));
        }

        return result;
    }

    /// <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>
    public bool Remove(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>
    public bool RemoveTimes(params DateTime[] times)
    {
        var isTimeContainedInTheTimeline = times.Any(time => GetAllTimes().Contains(time));

        if (!isTimeContainedInTheTimeline)
        {
            return false;
        }

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

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

        return true;
    }

    /// <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>
    public bool RemoveValues(params TValue[] values)
    {
        var isValueContainedInTheTimeline = values.Any(v => GetAllValues().Contains(v));

        if (!isValueContainedInTheTimeline)
        {
            return false;
        }

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

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

        return true;
    }

    /// <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 (DateTime Time, TValue Value)[] 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>
    public IList<(DateTime Time, TValue Value)> 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>
    public IDictionary<DateTime, TValue> ToDictionary()
        => timeline.ToDictionary(@event => @event.Time, @event => @event.Value);

    /// <inheritdoc />
    public override bool Equals(object? obj)
        => obj is Timeline<TValue> otherTimeline
           && this == otherTimeline;

    /// <inheritdoc />
    public override int GetHashCode()
        => timeline.GetHashCode();
}