# Information and management about a registered event
#
# It allows to retrieve static and dynamic information about an event.
# It also allows to register other time-related events with a fluent programming way.
class EventInfo[E]
	# The registered event.
	var event: E

	# The associated event queue.
	#
	# It is used internally for fluent programming.
	var queue: EventQueue[E]

	# Absolute start time for the registered event in the event queue time frame.
	var start: Float

	# Registered duration.
	#
	# Events with a 0.0 duration are called *instant events*.
	var duration: Float

	# Time since the begin of the event, in units of time.
	var time: Float = nan

	# Time since the last update (or the begin of the event if smaller)
	#
	# Note that if the event has expired during the last time lapse,
	# then `dt` also counts the *expired* time between the expiration time
	# and the update time.
	var dt: Float = nan

	# Ratio of completion
	#
	# Usually between 0.0 and 1.
	# It might be > 1.0 if the event has expired during the last time lapse.
	var completion = 0.0

	# Number of times that an event was returned by `update`.
	#
	# If the event just started during the last update, 1 is returned.
	#
	# If the event was not returned by `update` yet, 0 is returned.
	var occurrences = 0

	# Has the event expired?
	#
	# Such an event will be not present in the next `update`.
	#
	# Note that an event can be `has_expired` and have `occurrences == 0` if it
	# is entirely included in the last time lapse.
	# It is especially the case for instant events.
	var has_expired = false

	## Fluent methods

	# Register an event that starts after the end of the current one.
	#
	# `delay` indicates the time between the end of the current event and the begin of the new one.
	# Use 0.0 if both events should be contiguous and not overlap.
	#
	# Returns the new event information that can be used in fluent programming.
	fun add_after(event: E, delay: Float, duration: nullable Float): EventInfo[E]
	do
		return queue.add_at(event, start + self.duration + delay, duration)
	end

	# Register an event that starts with the current one.
	#
	# `delay` indicates the time between the begin of the current event and the begin of the new one.
	# Use 0.0 if both events should start at the same time and overlaps.
	#
	# Returns the new event information that can be used in fluent programming.
	fun add_sync(event: E, delay: Float, duration: nullable Float): EventInfo[E]
	do
		return queue.add_at(event, start + delay, duration)
	end

	# Register an event that finishes before the begin of current one.
	#
	# `delay` indicates the time between the end of the new event and the begin of the current one.
	# Use 0.0 if both event should be contiguous and not overlap.
	#
	# Returns the new event information that can be used in fluent programming.
	fun add_before(event: E, delay: Float, duration: nullable Float): EventInfo[E]
	do
		duration = duration or else 0.0
		return queue.add_at(event, start - delay - duration, duration)
	end

	# Update attributes. Is called by `EventQueue::update`
	private fun update(queue_time, queue_dt: Float)
	do
		time = queue_time - start
		if time >= duration then expire
		dt = queue_dt.min(time)
		completion = time / duration
		occurrences += 1
	end

	# Force the event to expire.
	#
	# The event can be active of not.
	#
	# ~~~
	# var eq = new EventQueue[String]
	# var e1 = eq.add("active", 0.0, 10.0)
	# var e2 = eq.add("not active", 2.0, 10.0)
	# var es = eq.update(1.0)
	# assert es == [e1]
	# e1.expire
	# e2.expire
	# es = eq.update(2.0)
	# assert es.is_empty
	# ~~~
	#
	# Note that when an event is forced to expire,
	# it will not appears in the next `update`.
	fun expire do has_expired = true

	redef fun to_s do return "{event or else "null"}@{start}+{duration}"
end