====== Railway Time API ======
This is the documentation for the [[usage:lines:railway_time]] API.
These functions are accessible for developers at:
  advtrains.lines.rwt.*
These functions are also accessible in the LuaATC environment at:
  rwt.*
===== Railway Time Formats =====
A railway time can be represented by 3 different formats: table, string or seconds. All API functions accept any of the formats as input, and usually output in table form, unless specified otherwise.

==== Table ====
A railway time is represented in a table like this:
  {
    s=45,
    m=23, 
    c=1,
  }

==== String ====
A time string can be either in the form cc;mm;ss or mm;ss. Trailing 0's can be omitted.
mm and ss must be within 0-60.
  1;23;45

==== Seconds ====
A simple integer value counting the seconds since 0;00;00.
  5025

===== Basic Functions =====

  now()
  Returns current railway time in table format

  new(c, m, s)
  Creates a new railway time in table format

  copy(rwtime)
  Explicitly creates a copy of rwtime, so that changes to either object don't affect the other

===== Format conversion =====

  to_table(rwtime)
  Explicitly converts to table format

  to_secs(rwtime, [c_over])
  Explicitly converts to seconds format.
  c_over: if given, overrides the "cycle" value to this value before conversion, while not changing rwtime

  to_string(rwtime_p, [no_cycle])
  Explicitly converts to string format
  no_cycle: if true, omits the cycle value, outputting a value of mm;ss

  add(t1, t2)
  Adds two railway times

  diff(t1, t2)
  Returns the time in seconds from t1 to t2 (=t2-t1)
  Note the argument order: diff("00;15", "00;35") = 20

  sub(t1, t2)
  Subtracts t2 from t1, result is in table form.
  The argument order is reverse to diff().

===== Repeating Times =====

Sometimes, you need to work with times like "at 15;30 every cycle" or "every two minutes". Such expressions are called "repeating time". They are characterized by an interval ("every ii;ii") and an offset ("at oo;oo").

Example: The times 05;00 25;00 45;00 would be expressed by interval 20;00, offset 05;00.

  time_to_next_rpt(rwtime, rpt_interval, rpt_offset)
  Returns number of seconds until this repeating time occurs the next time

  time_from_last_rpt(rwtime, rpt_interval, rpt_offset)
  Returns number of seconds until this repeating time occured the last time

  last_rpt(rwtime, rpt_interval, rpt_offset)
  Returns time when this repeating time occured the last time

  next_rpt(rwtime, rpt_interval, rpt_offset)
  Returns time when this repeating time occurs the next time