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     // Operations
  82     // ------------------------------------------------------------------------
  83
  84     /**
  85      * Normalize (adjust scale and offset) of the timestamp
  86      *
  87      * @param offset the offset to apply to the timestamp value (after scaling)
  88      * @param scale the new timestamp scale
  89      * @return a new 'adjusted' ITmfTimestamp
  90      */
  91     @NonNull ITmfTimestamp normalize(long offset, int scale);
  92
  93     /**
  94      * Returns the difference between [this] and [ts] as a timestamp
  95      *
  96      * @param ts the other timestamp
  97      * @return the time difference (this - other) as an ITmfTimestamp
  98      */
  99     @NonNull ITmfTimestamp getDelta(ITmfTimestamp ts);
 100
 101     /**
 102      * Returns if this timestamp intersects the given time range. Borders are
 103      * inclusive (for more fine-grained behavior, you can use
 104      * {@link #compareTo(ITmfTimestamp)}.
 105      *
 106      * @param range
 107      *            The time range to compare to
 108      * @return True if this timestamp is part of the time range, false if not
 109      */
 110     boolean intersects(TmfTimeRange range);
 111
 112     // ------------------------------------------------------------------------
 113     // Comparable
 114     // ------------------------------------------------------------------------
 115
 116     @Override
 117     int compareTo(ITmfTimestamp ts);
 118
 119     /**
 120      * Format the timestamp as per the format provided
 121      *
 122      * @param format the timestamp formatter
 123      * @return the formatted timestamp
 124      */
 125     String toString(final TmfTimestampFormat format);
 126
 127 }