1 /*******************************************************************************
2 * Copyright (c) 2012, 2014 Ericsson
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
10 * Francois Chouinard - Initial API and implementation
11 * Alexandre Montplaisir - Removed concept of precision
12 *******************************************************************************/
14 package org
.eclipse
.tracecompass
.tmf
.core
.timestamp
;
16 import org
.eclipse
.jdt
.annotation
.NonNull
;
17 import org
.eclipse
.tracecompass
.tmf
.core
.event
.ITmfEvent
;
20 * The fundamental time reference in the TMF.
22 * It defines a generic timestamp interface in its most basic form:
24 * <li>timestamp = [value] * 10**[scale] +/- [precision]
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.
35 * @author Francois Chouinard
40 public interface ITmfTimestamp
extends Comparable
<ITmfTimestamp
> {
42 // ------------------------------------------------------------------------
44 // ------------------------------------------------------------------------
47 * The millisecond scale factor (10e0)
52 * The millisecond scale factor (10e-3)
54 int MILLISECOND_SCALE
= -3;
57 * The microsecond scale factor (10e-6)
59 int MICROSECOND_SCALE
= -6;
62 * The nanosecond scale factor (10e-9)
64 int NANOSECOND_SCALE
= -9;
66 // ------------------------------------------------------------------------
68 // ------------------------------------------------------------------------
71 * @return the timestamp value (magnitude)
76 * @return the timestamp scale (exponent)
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.
85 * @return the timestamp converted to a long value of nanoseconds
88 default long toNanos() {
89 if (getScale() == NANOSECOND_SCALE
) {
92 return normalize(0L, NANOSECOND_SCALE
).getValue();
95 // ------------------------------------------------------------------------
97 // ------------------------------------------------------------------------
100 * Normalize (adjust scale and offset) of the timestamp
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
106 @NonNull ITmfTimestamp
normalize(long offset
, int scale
);
109 * Returns the difference between [this] and [ts] as a timestamp
111 * @param ts the other timestamp
112 * @return the time difference (this - other) as an ITmfTimestamp
114 @NonNull ITmfTimestamp
getDelta(ITmfTimestamp ts
);
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)}.
122 * The time range to compare to
123 * @return True if this timestamp is part of the time range, false if not
125 boolean intersects(TmfTimeRange range
);
127 // ------------------------------------------------------------------------
129 // ------------------------------------------------------------------------
132 int compareTo(ITmfTimestamp ts
);
135 * Format the timestamp as per the format provided
137 * @param format the timestamp formatter
138 * @return the formatted timestamp
140 String
toString(final TmfTimestampFormat format
);