tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/timestamp/ITmfTimestamp.java

   1 /*******************************************************************************
   2  * Copyright (c) 2012, 2014 Ericsson
   3  *
   4  * All rights reserved. This program and the accompanying materials are
   5  * made available under the terms of the Eclipse Public License v1.0 which
   6  * accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors:
  10  *   Francois Chouinard - Initial API and implementation
  11  *   Alexandre Montplaisir - Removed concept of precision
  12  *******************************************************************************/
  13
  14 package org.eclipse.tracecompass.tmf.core.timestamp;
  15
  16 import org.eclipse.jdt.annotation.NonNull;
  17 import org.eclipse.tracecompass.tmf.core.event.ITmfEvent;
  18
  19 /**
  20  * The fundamental time reference in the TMF.
  21  * <p>
  22  * It defines a generic timestamp interface in its most basic form:
  23  * <ul>
  24  * <li>timestamp = [value] * 10**[scale] +/- [precision]
  25  * </ul>
  26  * Where:
  27  * <ul>
  28  * <li>[value] is an unstructured integer value
  29  * <li>[scale] is the magnitude of the value wrt some application-specific
  30  * base unit (e.g. the second)
  31  * <li>[precision] indicates the error on the value (useful for comparing
  32  * timestamps in different scales). Default: 0.
  33  * </ul>
  34  *
  35  * @author Francois Chouinard
  36  *
  37  * @see ITmfEvent
  38  * @see TmfTimeRange
  39  */
  40 public interface ITmfTimestamp extends Comparable<ITmfTimestamp> {
  41
  42     // ------------------------------------------------------------------------
  43     // Constants
  44     // ------------------------------------------------------------------------
  45
  46     /**
  47      * The millisecond scale factor (10e0)
  48      */
  49     int SECOND_SCALE = 0;
  50
  51     /**
  52      * The millisecond scale factor (10e-3)
  53      */
  54     int MILLISECOND_SCALE = -3;
  55
  56     /**
  57      * The microsecond scale factor (10e-6)
  58      */
  59     int MICROSECOND_SCALE = -6;
  60
  61     /**
  62      * The nanosecond scale factor (10e-9)
  63      */
  64     int NANOSECOND_SCALE = -9;
  65
  66     // ------------------------------------------------------------------------
  67     // Getters
  68     // ------------------------------------------------------------------------
  69
  70     /**
  71      * @return the timestamp value (magnitude)
  72      */
  73     long getValue();
  74
  75     /**
  76      * @return the timestamp scale (exponent)
  77      */
  78     int getScale();
  79
  80     /**
  81      * Gets the timestamp converted to nanoseconds, if the timestamp is larger
  82      * than {@link Long#MAX_VALUE} or smaller than {@link Long#MIN_VALUE} it
  83      * will be clamped to those values.
  84      *
  85      * @return the timestamp converted to a long value of nanoseconds
  86      * @since 2.0
  87      */
  88     default long toNanos(){
  89         if (getScale() == NANOSECOND_SCALE) {
  90             return getValue();
  91         }
  92         return normalize(0L, NANOSECOND_SCALE).getValue();
  93     }
  94
  95     // ------------------------------------------------------------------------
  96     // Operations
  97     // ------------------------------------------------------------------------
  98
  99     /**
 100      * Normalize (adjust scale and offset) of the timestamp
 101      *
 102      * @param offset the offset to apply to the timestamp value (after scaling)
 103      * @param scale the new timestamp scale
 104      * @return a new 'adjusted' ITmfTimestamp
 105      */
 106     @NonNull ITmfTimestamp normalize(long offset, int scale);
 107
 108     /**
 109      * Returns the difference between [this] and [ts] as a timestamp
 110      *
 111      * @param ts the other timestamp
 112      * @return the time difference (this - other) as an ITmfTimestamp
 113      */
 114     @NonNull ITmfTimestamp getDelta(ITmfTimestamp ts);
 115
 116     /**
 117      * Returns if this timestamp intersects the given time range. Borders are
 118      * inclusive (for more fine-grained behavior, you can use
 119      * {@link #compareTo(ITmfTimestamp)}.
 120      *
 121      * @param range
 122      *            The time range to compare to
 123      * @return True if this timestamp is part of the time range, false if not
 124      */
 125     boolean intersects(TmfTimeRange range);
 126
 127     // ------------------------------------------------------------------------
 128     // Comparable
 129     // ------------------------------------------------------------------------
 130
 131     @Override
 132     int compareTo(ITmfTimestamp ts);
 133
 134     /**
 135      * Format the timestamp as per the format provided
 136      *
 137      * @param format the timestamp formatter
 138      * @return the formatted timestamp
 139      */
 140     String toString(final TmfTimestampFormat format);
 141
 142 }