time/Period.fz

# This file is part of the Fuzion language implementation.
#
# The Fuzion language implementation is free software: you can redistribute it
# and/or modify it under the terms of the GNU General Public License as published
# by the Free Software Foundation, version 3 of the License.
#
# The Fuzion language implementation is distributed in the hope that it will be
# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
# License for more details.
#
# You should have received a copy of the GNU General Public License along with The
# Fuzion language implementation.  If not, see <https://www.gnu.org/licenses/>.


# -----------------------------------------------------------------------
#
#  Tokiwa Software GmbH, Germany
#
#  Source code of Fuzion standard library feature time.Period
#
#  Author: Fridtjof Siebert (siebert@tokiwa.software)
#
# -----------------------------------------------------------------------

# time.Period -- template for periods
#
# This provides abstract features that define a period of time and that
# permit multiplications with large integers avoiding drift.
#
# An example is a period of 1/60sec. Using `time.duration`, which is a child
# of `Period`, this can only be represented as `16666667 ns`, resulting in
# a drift of 1/3ns per period, which would result in a drift of 1.7ms (a whole
# period) per day. Such inaccuracy can result in catastrophic failure, see
# (The Patriot Missile Failure)[https://www-users.cse.umn.edu/~arnold/disasters/patriot.html].
#
public Period
is

  # this Period represented as a duration.  Note that the duration might
  # be inaccurate since it will be rounded or truncated to full nanoseconds.
  #
  public as_duration time.duration
  pre
    !is_infinity
  => abstract


  # is this period infinite, i.e., it never ends?
  #
  public is_infinity bool
  =>
    abstract


  # this Period multiplied by factor n
  #
  # If n=0, the result is `time.duration.zero` even if `is_infinity`.
  #
  public infix *(n u64) time.duration
  pre
    debug: !is_infinity || n=0
  =>
    abstract