Bug 3002 - Add Time section of manual to avoid double usage.
Add Time section of manual to avoid double usage.
Product: ns-3
Classification: Unclassified
Component: core
PC Linux
: P5 normal
Assigned To: Peter Barnes
Depends on:
  Show dependency treegraph
Reported: 2018-10-23 06:42 EDT by natale.patriciello
Modified: 2018-10-23 09:37 EDT (History)
4 users (show)

See Also:

Patch (3.67 KB, patch)
2018-10-23 06:42 EDT, natale.patriciello
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description natale.patriciello 2018-10-23 06:42:49 EDT
Created attachment 3195 [details]

As discussed in the mailing list, this is my proposal.
Comment 1 Biljana Bojović 2018-10-23 07:11:12 EDT
Thank you Nat for writing this down. It is clearly explained.
Comment 2 Tom Henderson 2018-10-23 09:37:42 EDT
This is a good start, thanks.

Some comments:

1) I would not advise to use auto in the example code.  Almost no ns-3 code does it this way, and IMO it does not improve readability to use auto here.  So in general, I would do the following:

-     auto t1 = ns3::MilliSeconds (2000);
+     Time t1 = MilliSeconds (2000);

and also show the other prevalent usage pattern is equivalent:

      Time t1 (MilliSeconds (2000));

(note also dropping the 'ns3::'; what does it add here?)

2) There is another available example of floating point issues to add to your 'Seconds to integer' t4 case, which is a simple 'integer to Seconds' case:

    Time t5 = ns3::MilliSeconds (2);
    std::cout << t5.As (Time::S) << std::endl;


3) suggest this editorial change:

- IEEE 754 model is not precise (but no one in the world has come up with a better proposal)
+ IEEE 754 standard for floating point arithmetic has limits on the set of possible numbers that can be represented exactly.

4) Towards the end, it gives an example

    // auto t4 = ns3::Seconds (0.075); // Wrong
    auto t4 = ns3::MilliSeconds (75); // Right
    Again, the correct ns-3 way to store times is to use the Time class.

The problem here is not the usage of the Time class, it is the usage of a floating point argument to set the Time value.  Can you please clarify?

5) Can you please expand to recommend guidance for operators?  I think that sometimes this is what induces the pattern of 'convert to double' usage that you are trying to avoid.   e.g. times can be added and subtracted.  Times can be multiplied and divided by integers, but Time * Time and Time/Time are not allowed.  Users should avoid converting to double to perform arithmetic and then converting back to Time; instead try to find an operation using native Time operators.