OMNeT++ Simulation Library  5.6.1
SimTime Class Reference

#include <simtime.h>

Description

int64_t-based, base-10 fixed-point simulation time.

Precision is determined by a scale exponent, which is global (shared by all SimTime instances), and falls in the range -18..0. For example, a scale exponent of -6 means microsecond precision.

Conversions and arithmetic operations are provided specifically for double and cPar, and via template functions for integer types. Performance note: conversion from double uses the scale stored as double, and conversion from integer types uses the scale stored as int64_t; the former eliminates an int64_t-to-double conversion, and the latter allows the compiler to optimize expressions like if (time>0) to a trivial integer operation, without floating-point or int64_t multiplication.

The underlying raw 64-bit integer is also made accessible.

Public Member Functions

Constructors
 SimTime ()
 
 SimTime (double d)
 
 SimTime (cPar &d)
 
 SimTime (int64_t value, SimTimeUnit unit)
 
 SimTime (const SimTime &x)
 

Static Public Attributes

static const SimTime ZERO
 

Arithmetic operations

const SimTimeoperator= (const SimTime &x)
 
const SimTimeoperator= (const cPar &d)
 
const SimTimeoperator= (double d)
 
const SimTimeoperator= (short d)
 
const SimTimeoperator= (int d)
 
const SimTimeoperator= (long d)
 
const SimTimeoperator= (long long d)
 
const SimTimeoperator= (unsigned short d)
 
const SimTimeoperator= (unsigned int d)
 
const SimTimeoperator= (unsigned long d)
 
const SimTimeoperator= (unsigned long long d)
 
bool operator== (const SimTime &x) const
 
bool operator!= (const SimTime &x) const
 
bool operator< (const SimTime &x) const
 
bool operator> (const SimTime &x) const
 
bool operator<= (const SimTime &x) const
 
bool operator>= (const SimTime &x) const
 
SimTime operator- () const
 
const SimTimeoperator+= (const SimTime &x)
 
const SimTimeoperator-= (const SimTime &x)
 
const SimTimeoperator*= (double d)
 
const SimTimeoperator*= (short d)
 
const SimTimeoperator*= (int d)
 
const SimTimeoperator*= (long d)
 
const SimTimeoperator*= (long long d)
 
const SimTimeoperator*= (unsigned short d)
 
const SimTimeoperator*= (unsigned int d)
 
const SimTimeoperator*= (unsigned long d)
 
const SimTimeoperator*= (unsigned long long d)
 
const SimTimeoperator*= (const cPar &p)
 
const SimTimeoperator/= (double d)
 
const SimTimeoperator/= (short d)
 
const SimTimeoperator/= (int d)
 
const SimTimeoperator/= (long d)
 
const SimTimeoperator/= (long long d)
 
const SimTimeoperator/= (unsigned short d)
 
const SimTimeoperator/= (unsigned int d)
 
const SimTimeoperator/= (unsigned long d)
 
const SimTimeoperator/= (unsigned long long d)
 
const SimTimeoperator/= (const cPar &p)
 
const SimTime operator+ (const SimTime &x, const SimTime &y)
 
const SimTime operator- (const SimTime &x, const SimTime &y)
 
const SimTime operator* (const SimTime &x, double d)
 
const SimTime operator* (const SimTime &x, short d)
 
const SimTime operator* (const SimTime &x, int d)
 
const SimTime operator* (const SimTime &x, long d)
 
const SimTime operator* (const SimTime &x, long long d)
 
const SimTime operator* (const SimTime &x, unsigned short d)
 
const SimTime operator* (const SimTime &x, unsigned int d)
 
const SimTime operator* (const SimTime &x, unsigned long d)
 
const SimTime operator* (const SimTime &x, unsigned long long d)
 
const SimTime operator* (const SimTime &x, const cPar &p)
 
const SimTime operator* (double d, const SimTime &x)
 
const SimTime operator* (short d, const SimTime &x)
 
const SimTime operator* (int d, const SimTime &x)
 
const SimTime operator* (long d, const SimTime &x)
 
const SimTime operator* (long long d, const SimTime &x)
 
const SimTime operator* (unsigned short d, const SimTime &x)
 
const SimTime operator* (unsigned int d, const SimTime &x)
 
const SimTime operator* (unsigned long d, const SimTime &x)
 
const SimTime operator* (unsigned long long d, const SimTime &x)
 
const SimTime operator* (const cPar &p, const SimTime &x)
 
const SimTime operator/ (const SimTime &x, double d)
 
const SimTime operator/ (const SimTime &x, short d)
 
const SimTime operator/ (const SimTime &x, int d)
 
const SimTime operator/ (const SimTime &x, long d)
 
const SimTime operator/ (const SimTime &x, long long d)
 
const SimTime operator/ (const SimTime &x, unsigned short d)
 
const SimTime operator/ (const SimTime &x, unsigned int d)
 
const SimTime operator/ (const SimTime &x, unsigned long d)
 
const SimTime operator/ (const SimTime &x, unsigned long long d)
 
const SimTime operator/ (const SimTime &x, const cPar &p)
 
double operator/ (const SimTime &x, const SimTime &y)
 
double operator/ (double x, const SimTime &y)
 
double operator/ (short x, const SimTime &y)
 
double operator/ (int x, const SimTime &y)
 
double operator/ (long x, const SimTime &y)
 
double operator/ (long long x, const SimTime &y)
 
double operator/ (unsigned short x, const SimTime &y)
 
double operator/ (unsigned int x, const SimTime &y)
 
double operator/ (unsigned long x, const SimTime &y)
 
double operator/ (unsigned long long x, const SimTime &y)
 
double operator/ (const cPar &p, const SimTime &x)
 

Misc operations and utilities

bool isZero () const
 
double dbl () const
 
int64_t inUnit (SimTimeUnit unit) const
 
SimTime trunc (SimTimeUnit unit) const
 
SimTime remainderForUnit (SimTimeUnit unit) const
 
void split (SimTimeUnit unit, int64_t &outValue, SimTime &outRemainder) const
 
std::string str () const
 
char * str (char *buf) const
 
std::string ustr () const
 
std::string ustr (SimTimeUnit unit) const
 
int64_t raw () const
 
const SimTimesetRaw (int64_t l)
 
static SimTime fromRaw (int64_t l)
 
static const SimTime getMaxTime ()
 
static int64_t getScale ()
 
static int getScaleExp ()
 
static void setScaleExp (int e)
 
static const SimTime parse (const char *s)
 
static const SimTime parse (const char *s, const char *&endp)
 
static char * ttoa (char *buf, int64_t t, int scaleexp, char *&endp)
 

Constructor & Destructor Documentation

◆ SimTime() [1/5]

SimTime ( )
inline

Constructor initializes to zero.

◆ SimTime() [2/5]

SimTime ( double  d)
inline

Initialize simulation time from a double-precision number. This constructor is recommended if the value is the result of some computation done in double. For integer-based computations and time constants, the SimTime(int64_t x, int exponent) constructor is usually a better choice, because it does not have rounding errors caused by double-to-integer conversion.

◆ SimTime() [3/5]

SimTime ( cPar d)
inline

Initialize simulation time from a module or channel parameter. It uses conversion to double. It currently does not check the measurement unit of the parameter (@unit NED property), although this may change in future releases.

◆ SimTime() [4/5]

SimTime ( int64_t  value,
SimTimeUnit  unit 
)

Initialize simulation time from value specified in the given units. This constructor allows one to specify precise constants, without conversion errors incurred by the double constructor. An error will be thrown if the resulting value cannot be represented (overflow) or it cannot be represented precisely (precision loss) with the current resolution (i.e. scale exponent). Note that the unit parameter actually represents a base-10 exponent, so the constructor will also work correctly for values not in the SimTimeUnit enum.

Examples: Simtime(15, SIMTIME_US) -> 15us Simtime(-3, SIMTIME_S) -> -1s Simtime(5, (SimTimeUnit)2) -> 500s;

◆ SimTime() [5/5]

SimTime ( const SimTime x)
inline

Copy constructor.

References SimTime::dbl(), and SimTime::raw().

Member Function Documentation

◆ isZero()

bool isZero ( ) const
inline

Returns true if this simulation time is zero, false otherwise. This is more efficient than comparing the variable to a (double) 0.0, and shorter than comparing against SimTime::ZERO.

◆ dbl()

double dbl ( ) const
inline

Converts simulation time (in seconds) to a double. Note that conversion to and from double may lose precision. We do not provide implicit conversion to double as it would conflict with other overloaded operators, and would cause ambiguities during compilation.

Referenced by cStatistic::collect(), cLongHistogram::collect(), cStatistic::collectWeighted(), omnetpp::exponential(), cComponent::exponential(), omnetpp::normal(), cComponent::normal(), cOutVector::record(), cComponent::recordScalar(), cOutVector::recordWithTimestamp(), SimTime::SimTime(), omnetpp::truncnormal(), cComponent::truncnormal(), omnetpp::uniform(), and cComponent::uniform().

◆ inUnit()

int64_t inUnit ( SimTimeUnit  unit) const

Converts the simulation time to the given time unit, discarding the fractional part (i.e. rounding towards zero). If the return type is not wide enough to hold the result, an error will be thrown.

Examples: 1.7ms in us –> 1700; 3.8ms in ms –> 3; -3.8ms in ms –> -3; 999ms in s –> 0

◆ trunc()

SimTime trunc ( SimTimeUnit  unit) const
inline

Returns a new simulation time that is truncated (rounded towards zero) to the precision of the specified time unit.

Examples: 3750ms truncated to s –> 3; -3750ms truncated to s –> -3

◆ remainderForUnit()

SimTime remainderForUnit ( SimTimeUnit  unit) const
inline

Returns a simtime that is the difference between the simulation time and its truncated value (see trunc()).

That is, t == t.trunc(unit) + t.remainderforUnit(unit) for any unit.

◆ split()

void split ( SimTimeUnit  unit,
int64_t &  outValue,
SimTime outRemainder 
) const

Convenience method: splits the simulation time into a whole and a fractional part with regard to a time unit. t.split(exponent, outValue, outRemainder) is equivalent to:

outValue = t.inUnit(unit);
outRemainder = t.remainderForUnit(unit);

◆ str() [1/2]

std::string str ( ) const
inline

Converts the time to a numeric string. The number expresses the simulation time precisely (including all significant digits), in seconds. The measurement unit (seconds) is not part of the string.

References SimTime::str().

Referenced by SimTime::str().

◆ str() [2/2]

char* str ( char *  buf) const
inline

Converts to a string in the same way as str() does. Use this variant over str() where performance is critical. The result is placed somewhere in the given buffer (pointer is returned), but for performance reasons, not necessarily at the buffer's beginning. Please read the documentation of ttoa() for the minimum required buffer size.

References SimTime::ttoa().

◆ ustr() [1/2]

std::string ustr ( ) const

Converts the time to a numeric string with unit in the same format as ustr(SimTimeUnit) does, but chooses the time unit automatically. The function tries to choose the "natural" time unit, e.g. 0.0033 is returned as "3.3ms".

◆ ustr() [2/2]

std::string ustr ( SimTimeUnit  unit) const

Converts the time to a numeric string in the given time unit. The unit can be "s", "ms", "us", "ns", "ps", "fs", or "as". The result represents the simulation time precisely (includes all significant digits), and the unit is appended.

◆ raw()

int64_t raw ( ) const
inline

Returns the underlying 64-bit integer.

Referenced by SimTime::getScaleExp(), and SimTime::SimTime().

◆ fromRaw()

static SimTime fromRaw ( int64_t  l)
inlinestatic

Creates a SimTime by setting its underlying 64-bit integer.

◆ setRaw()

const SimTime& setRaw ( int64_t  l)
inline

Directly sets the underlying 64-bit integer.

Referenced by SimTime::getMaxTime().

◆ getMaxTime()

static const SimTime getMaxTime ( )
inlinestatic

Returns the largest simulation time that can be represented using the present scale exponent.

References SimTime::setRaw().

◆ getScale()

static int64_t getScale ( )
inlinestatic

Returns the time resolution as the number of units per second, e.g. for microsecond resolution it returns 1000000.

◆ getScaleExp()

static int getScaleExp ( )
inlinestatic

Returns the scale exponent, which is an integer in the range -18..0. For example, for microsecond resolution it returns -6.

References SimTime::raw(), and SimTime::ttoa().

◆ setScaleExp()

static void setScaleExp ( int  e)
static

Sets the scale exponent, and thus the resolution of time. Accepted values are -18..0; for example, setScaleExp(-6) selects microsecond resolution. Normally, the scale exponent is set from the configuration file (omnetpp.ini) on simulation startup.

The scale exponent can only be set ONCE, and cannot be changed afterwards. Any attempt to change it after it got initialized will result in a runtime error. Reason: the simtime exponent is a global variable, and changing it would silently change the value of existing SimTime variables.

◆ parse() [1/2]

static const SimTime parse ( const char *  s)
static

Converts the given string to simulation time. Throws an error if there is an error during conversion. Accepted format is: <number> or (<number><unit>)+.

◆ parse() [2/2]

static const SimTime parse ( const char *  s,
const char *&  endp 
)
static

Converts a prefix of the given string to simulation time, up to the first character that cannot occur in simulation time strings: not (digit or letter or "." or "+" or "-" or whitespace). Throws an error if there is an error during conversion of the prefix. If the prefix is empty (whitespace only), then 0 is returned, and endp is set equal to s; otherwise, endp is set to point to the first character that was not converted.

◆ ttoa()

static char* ttoa ( char *  buf,
int64_t  t,
int  scaleexp,
char *&  endp 
)
static

Utility function to convert a 64-bit fixed point number into a string buffer. scaleexp must be in the -18..0 range, and the buffer must be at least 64 bytes long. A pointer to the result string will be returned. A pointer to the terminating '\0' will be returned in endp.

ATTENTION: For performance reasons, the returned pointer will point somewhere into the buffer, but NOT necessarily at the beginning.

Referenced by SimTime::getScaleExp(), and SimTime::str().

Member Data Documentation

◆ ZERO

const SimTime ZERO
static

Represents the zero simulation time. Using SimTime::ZERO may be faster than writing SimTime() or conversion from 0.0, because the constructor call may be spared.


The documentation for this class was generated from the following file: