Represents a length in meters
More...
#include "length.h"
Classes  
class  Quantity 
An immutable class which represents a value in a specific length unit. More...  
Public Types  
enum  Unit : uint16_t { Nanometer = 1, Micrometer, Millimeter, Centimeter, Meter, Kilometer, NauticalMile, Inch, Foot, Yard, Mile } 
Units of length in various measurement systems that are supported by the Length class. More...  
Public Member Functions  
Length ()  
Default Constructor. More...  
Length (const std::string &text)  
String Constructor. More...  
Length (double value, const std::string &unit)  
Construct a Length object from a value and a unit string. More...  
Length (double value, Length::Unit unit)  
Construct a Length object from a value and a unit. More...  
Length (Quantity quantity)  
Construct a Length object from a Quantity. More...  
Length (const Length &other)=default  
Copy Constructor. More...  
Length (Length &&other)=default  
Move Constructor. More...  
~Length ()=default  
Destructor. More...  
Quantity  As (Unit unit) const 
Create a Quantity in a specific unit from a Length. More...  
double  GetDouble () const 
Current length value More...  
bool  IsEqual (const Length &other, double tolerance=DEFAULT_TOLERANCE) const 
Check if other is equal in value to this instance. More...  
bool  IsGreater (const Length &other, double tolerance=DEFAULT_TOLERANCE) const 
Check if other is less in value than this instance. More...  
bool  IsGreaterOrEqual (const Length &other, double tolerance=DEFAULT_TOLERANCE) const 
Check if other is equal or less in value than this instance. More...  
bool  IsLess (const Length &other, double tolerance=DEFAULT_TOLERANCE) const 
Check if other is greater in value than this instance. More...  
bool  IsLessOrEqual (const Length &other, double tolerance=DEFAULT_TOLERANCE) const 
Check if other is greater or equal in value than this instance. More...  
bool  IsNotEqual (const Length &other, double tolerance=DEFAULT_TOLERANCE) const 
Check if other is not equal in value to this instance. More...  
Length &  operator= (const Length &other)=default 
Copy Assignment operator. More...  
Length &  operator= (Length &&other)=default 
Move Assignment operator. More...  
Length &  operator= (const Length::Quantity &q) 
Assignment operator. More...  
void  swap (Length &other) 
Swap values with another object More...  
Static Public Member Functions  
static std::tuple< bool, Length >  TryParse (double value, const std::string &unit) 
Attempt to construct a Length object from a value and a unit string. More...  
Static Public Attributes  
static constexpr double  DEFAULT_TOLERANCE = std::numeric_limits<double>::epsilon () 
Default tolerance value used for the member comparison functions (IsEqual, IsLess, etc.) More...  
Private Attributes  
double  m_value 
Length in meters. More...  
Related Functions  
(Note that these are not member functions.)  
int64_t  Div (const Length &numerator, const Length &denominator, Length *remainder=nullptr) 
Calculate how many times numerator can be split into denominator sized pieces. More...  
std::tuple< bool, Length::Unit >  FromString (std::string unitString) 
Find the equivalent Length::Unit for a unit string. More...  
Length  Mod (const Length &numerator, const Length &denominator) 
Calculate the amount remaining after dividing two lengths. More...  
bool  operator!= (const Length &l, const Length &r) 
Compare two length objects for inequality. More...  
Length  operator* (double scalar, const Length &right) 
Multiply a length value by a scalar. More...  
Length  operator* (const Length &left, double scalar) 
Multiply a length value by a scalar. More...  
Length  operator+ (const Length &first, const Length &second) 
Add two length values together. More...  
Length  operator (const Length &first, const Length &second) 
Subtract two length values. More...  
Length  operator/ (const Length &left, double scalar) 
Divide a length value by a scalar. More...  
double  operator/ (const Length &numerator, const Length &denominator) 
Divide a length value by another length value. More...  
bool  operator< (const Length &l, const Length &r) 
Check if l has a value less than r . More...  
std::ostream &  operator<< (std::ostream &stream, const Length &l) 
Write a length value to an output stream. More...  
std::ostream &  operator<< (std::ostream &stream, const Length::Quantity &q) 
Write a Quantity to an output stream. More...  
std::ostream &  operator<< (std::ostream &stream, Length::Unit unit) 
Write a Length::Unit to an output stream. More...  
bool  operator<= (const Length &l, const Length &r) 
Check if l has a value less than or equal to r . More...  
bool  operator== (const Length &left, const Length &right) 
Compare two length objects for equality. More...  
bool  operator> (const Length &l, const Length &r) 
Check if l has a value greater than r . More...  
bool  operator>= (const Length &l, const Length &r) 
Check if l has a value greater than or equal to r . More...  
std::istream &  operator>> (std::istream &stream, Length &l) 
Read a length value from an input stream. More...  
std::string  ToName (Length::Unit unit, bool plural=false) 
Return the name of the supplied unit. More...  
std::string  ToSymbol (Length::Unit unit) 
Return the symbol of the supplied unit. More...  
Length  NanoMeters (double value) 
Construct a Length from nanometers. More...  
Length  MicroMeters (double value) 
Construct a Length from micrometers. More...  
Length  MilliMeters (double value) 
Construct a Length from millimeters. More...  
Length  CentiMeters (double value) 
Construct a Length from centimeters. More...  
Length  Meters (double value) 
Construct a Length from meters. More...  
Length  KiloMeters (double value) 
Construct a Length from kilometers. More...  
Length  NauticalMiles (double value) 
Construct a Length from nautical miles. More...  
Length  Inches (double value) 
Construct a Length from inches. More...  
Length  Feet (double value) 
Construct a Length from feet. More...  
Length  Yards (double value) 
Construct a Length from yards. More...  
Length  Miles (double value) 
Construct a Length from miles. More...  
Represents a length in meters
The purpose of this class is to replace the use of raw numbers (ints, doubles) that have implicit lengths with a class that represents lengths with an explicit unit. Using raw values with implicit units can lead to bugs when a value is assumed to represent one unit but actually represents another. For example, assuming a value represents a length in meters when it in fact represents a length in kilometers.
The Length class prevents this confusion by storing values internally as doubles representing lengths in Meters and providing conversion functions to convert to/from other length units (kilometers, miles, etc.).
Conversion to and from meters is supported for the following units:
Length objects can be constructed in a number of different ways
The string constructor parses strings with the format <number><unit> or <number> <unit> and creates the equivalent Length value in meters. <unit> can be the full name of the unit (nanometer, kilometer, foot, etc.) or the abbreviated name (nm, km, ft, etc.).
Quantity is a class that describes a value and a unit type. For example, meter is a unit while 5 meters is a quantity. The Length constructor takes the quantity instance and converts it to the equivalent value in meters.
Two constructors are provided which take a value and a unit as separate parameters. The difference between the two constructors is that one takes the unit as a string and the other takes the unit as a Length::Unit value. An assertion is triggered if the string does not map to a valid Length::Unit
If the boost::units library is discovered during ns3 configuration an additional constructor is enabled which allows constructing Length objects from boost::unit quantities.
The following arithmetic operations are supported:
Addition is between two Length instances
Subtraction is between two Length instances
Multiplication is only supported between a Length and a unitless scalar value
Division can be between a Length and a scalar or two Length objects.
Division between a Length and a scalar returns a new Length.
Division between two Length objects returns a unitless value.
All the usual arithmetic comparison operations (=, !=, <, <=, >, >=) are supported. There are two forms of comparison operators: free function and member function. The free functions define =, !=, <, <=, >, >= and perform exact comparisons of the underlying double values. The Length class provides comparison operator functions (IsEqual, IsLess, IsGreater, etc.) which accept an additional tolerance value to control how much the underlying double values must match when performing the comparison.
The Length class supports serialization using the << and >> operators. By default the output serialization is in meters. Use Length::As to output the Length value in a different unit.
enum ns3::Length::Unit : uint16_t 
Units of length in various measurement systems that are supported by the Length class.
ns3::Length::Length  (  ) 
Default Constructor.
Initialize with a value of 0 meters.
Definition at line 258 of file length.cc.
References NS_LOG_FUNCTION.
Referenced by TryParse().
ns3::Length::Length  (  const std::string &  text  ) 
String Constructor.
Parses text
and initializes the value with the parsed result.
The expected format of text
is <number> <unit> or <number><unit>
text  Serialized length value 
Definition at line 264 of file length.cc.
References NS_LOG_FUNCTION.
ns3::Length::Length  (  double  value, 
const std::string &  unit  
) 
Construct a Length object from a value and a unit string.
unit
can either be the full name of the unit (meter, kilometer, mile, etc.) or the symbol of the unit (m, km, mi, etc.)
unit
is not a valid unit string. value  Numeric value of the new length 
unit  Unit that the value represents 
Definition at line 274 of file length.cc.
References anonymous_namespace{length.cc}::Convert(), FromString(), m_value, NS_FATAL_ERROR, and NS_LOG_FUNCTION.
ns3::Length::Length  (  double  value, 
Length::Unit  unit  
) 
Construct a Length object from a value and a unit.
unit
is not valid. value  Numeric value of the new length 
unit  Length unit of the value 
Definition at line 294 of file length.cc.
References anonymous_namespace{length.cc}::Convert(), m_value, and NS_LOG_FUNCTION.
ns3::Length::Length  (  Quantity  quantity  ) 

default 
Copy Constructor.
Initialize an object with the value from other
.
other  Length object to copy 

default 
Move Constructor.
Initialize an object with the value from other
.
After the move completes, other
is left in an undefined but useable state.
other  Length object to move 

default 
Destructor.
Length::Quantity ns3::Length::As  (  Length::Unit  unit  )  const 
Create a Quantity in a specific unit from a Length.
Converts the current length value to the equivalent value specified by unit
and returns a Quantity object with the converted value and unit
unit  The desired unit of the returned Quantity 
Definition at line 388 of file length.cc.
References anonymous_namespace{length.cc}::Convert(), m_value, and NS_LOG_FUNCTION.
Referenced by Conversions(), DivAndMod(), ns3::operator<<(), LengthTestCase::TestLengthSerialization(), and LengthValueTestCase::TestSetAttributeUsingStringValue().
double ns3::Length::GetDouble  (  void  )  const 
Current length value
Equivalent to:
Definition at line 382 of file length.cc.
References m_value.
Referenced by ns3::Div(), ns3::Mod(), ns3::operator!=(), ns3::operator*(), ns3::operator+(), ns3::operator(), ns3::operator/(), ns3::operator<(), ns3::operator<=(), ns3::operator==(), ns3::operator>(), ns3::operator>=(), LengthTestCase::TestAddingLengthAndQuantity(), LengthTestCase::TestAddingQuantityAndLength(), LengthTestCase::TestAddingTwoLengths(), LengthTestCase::TestConstructLengthFromQuantity(), LengthTestCase::TestConstructLengthFromSIUnits(), LengthTestCase::TestConstructLengthFromUSUnits(), LengthTestCase::TestCopyAssignment(), LengthTestCase::TestDefaultLengthIsZero(), LengthTestCase::TestDivideLengthByLength(), LengthTestCase::TestDivideLengthByScalar(), LengthTestCase::TestDivReturnsCorrectRemainder(), LengthTestCase::TestDivReturnsZeroRemainder(), LengthTestCase::TestLengthCopyConstructor(), LengthTestCase::TestLengthMoveConstructor(), LengthTestCase::TestMoveAssignment(), LengthTestCase::TestMultiplyLengthByScalar(), LengthTestCase::TestMultiplyScalarByLength(), LengthTestCase::TestSubtractingLengthAndQuantity(), LengthTestCase::TestSubtractingQuantityAndLength(), LengthTestCase::TestSubtractingTwoLengths(), and LengthTestCase::TestTryParseReturnsTrue().
bool ns3::Length::IsEqual  (  const Length &  other, 
double  tolerance = DEFAULT_TOLERANCE 

)  const 
Check if other
is equal in value to this instance.
other  Value to compare against 
tolerance  Smallest difference allowed between the two values to still be considered equal 
tolerance
Definition at line 319 of file length.cc.
References m_value, and NS_LOG_FUNCTION.
Referenced by IsLessOrEqual(), IsNotEqual(), LengthTestCase::TestIsEqualReturnsFalse(), LengthTestCase::TestIsEqualReturnsTrue(), LengthTestCase::TestIsEqualWithToleranceReturnsFalse(), and LengthTestCase::TestIsEqualWithToleranceReturnsTrue().
bool ns3::Length::IsGreater  (  const Length &  other, 
double  tolerance = DEFAULT_TOLERANCE 

)  const 
Check if other
is less in value than this instance.
other  Value to compare against 
tolerance  Smallest difference allowed between the two values to still be considered equal 
Equivalent to:
other
is less in value Definition at line 358 of file length.cc.
References IsLessOrEqual(), m_value, and NS_LOG_FUNCTION.
Referenced by LengthTestCase::TestIsGreaterReturnsFalse(), LengthTestCase::TestIsGreaterReturnsTrue(), and LengthTestCase::TestIsGreaterWithToleranceReturnsFalse().
bool ns3::Length::IsGreaterOrEqual  (  const Length &  other, 
double  tolerance = DEFAULT_TOLERANCE 

)  const 
Check if other
is equal or less in value than this instance.
other  Value to compare against 
tolerance  Smallest difference allowed between the two values to still be considered equal 
Equivalent to:
other
is less in value Definition at line 366 of file length.cc.
References IsLess(), m_value, and NS_LOG_FUNCTION.
bool ns3::Length::IsLess  (  const Length &  other, 
double  tolerance = DEFAULT_TOLERANCE 

)  const 
Check if other
is greater in value than this instance.
other  Value to compare against 
tolerance  Smallest difference allowed between the two values to still be considered equal 
other
is greater in value Definition at line 342 of file length.cc.
References IsNotEqual(), m_value, and NS_LOG_FUNCTION.
Referenced by IsGreaterOrEqual(), LengthTestCase::TestIsLessReturnsFalse(), LengthTestCase::TestIsLessReturnsTrue(), and LengthTestCase::TestIsLessWithToleranceReturnsFalse().
bool ns3::Length::IsLessOrEqual  (  const Length &  other, 
double  tolerance = DEFAULT_TOLERANCE 

)  const 
Check if other
is greater or equal in value than this instance.
other  Value to compare against 
tolerance  Smallest difference allowed between the two values to still be considered equal 
Equivalent to:
other
is greater in value Definition at line 350 of file length.cc.
References IsEqual(), m_value, and NS_LOG_FUNCTION.
Referenced by IsGreater().
bool ns3::Length::IsNotEqual  (  const Length &  other, 
double  tolerance = DEFAULT_TOLERANCE 

)  const 
Check if other
is not equal in value to this instance.
other  Value to compare against 
tolerance  Smallest difference allowed between the two values to still be considered equal 
tolerance
Definition at line 334 of file length.cc.
References IsEqual(), m_value, and NS_LOG_FUNCTION.
Referenced by IsLess(), LengthTestCase::TestIsNotEqualReturnsFalse(), LengthTestCase::TestIsNotEqualReturnsTrue(), LengthTestCase::TestIsNotEqualWithToleranceReturnsFalse(), and LengthTestCase::TestIsNotEqualWithToleranceReturnsTrue().
Copy Assignment operator.
Replace the current value with the value from other
other  Length object to copy 
Move Assignment operator.
Replace the current value with the value from other
After the move, other
is left in an undefined but valid state
other  Length object to move 
Length & ns3::Length::operator=  (  const Length::Quantity &  q  ) 
Assignment operator.
Replace the current value with the value from q
q  Quantity holding the value to assign 
Definition at line 309 of file length.cc.
References anonymous_namespace{length.cc}::Convert(), m_value, and NS_LOG_FUNCTION.
void ns3::Length::swap  (  Length &  other  ) 
Swap values with another object
Swap the current value with the value in other
.
Equivalent to:
other  Length object to swap 
Definition at line 374 of file length.cc.
References m_value.
Referenced by ns3::operator>>().

static 
Attempt to construct a Length object from a value and a unit string.
unit
can either be the full name of the unit (meter, kilometer, mile, etc.) or the symbol of the unit (m, km, mi, etc.)
This function will return false if unit
does not map to a known type.
value  Numeric value of the new length 
unit  Unit that the value represents 
Definition at line 239 of file length.cc.
References FromString(), Length(), and NS_LOG_FUNCTION.
Referenced by LengthTestCase::TestTryParseReturnsFalse(), and LengthTestCase::TestTryParseReturnsTrue().

related 
Calculate how many times numerator
can be split into denominator
sized pieces.
If the result of numerator
/ denominator
is not a whole number, the result is rounded toward zero to the nearest whole number. The amount remaining after the division can be retrieved by passing a pointer to a Length in remainder
. The remainder will be less than denominator
and have the same sign as numerator
.
NS_FATAL_ERROR is called if denominator
is 0.
numerator  The value to split 
denominator  The length of each split 
remainder  Location to store the remainder 
numerator
can be split into denominator
sized pieces, rounded down to the nearest whole number

related 
Find the equivalent Length::Unit for a unit string.
The string value can be a symbol or name (plural or singular).
The string comparison ignores case so strings like "NanoMeter", "centiMeter", "METER" will all match the correct unit.
Leading and trailing whitespace are trimmed from the string before searching for a match.
unitString  String containing the symbol or name of a length unit 
Definition at line 586 of file length.cc.
Referenced by Length(), and TryParse().
Calculate the amount remaining after dividing two lengths.
The returned value will be less than denominator
and have the same sign as numerator
.
NS_FATAL_ERROR is called if denominator
is 0.
numerator  The value to split 
denominator  The length of each split 
numerator
into denominator
sized pieces. Divide a length value by a scalar.
Divides the value left
by scalar
and returns a new Length object containing the result.
scalar
must contain a non zero value. NS_FATAL_ERROR is called if scalar
is zero
left  Length value 
scalar  Multiplication factor 
Divide a length value by another length value.
Divides the value numerator
by the value denominator
and returns a scalar value containing the result.
The return value will be NaN if denominator
is 0.
numerator  The top value of the division 
denominator  The bottom value of the division 
denominator
is 0

related 

related 

related 
Write a Length::Unit to an output stream.
Writes the name of unit
to the output stream
Equivalent to:
stream  Output stream 
unit  Length unit to output 

related 
Read a length value from an input stream.
The expected format of the input is <number> <unit> or <number><unit> This function calls NS_ABORT if the input stream does not contain a valid length string
stream  Input stream 
l  Object where the deserialized value will be stored 

related 
Return the name of the supplied unit.
The value returned by this function is the common name of unit
. The output is always lowercase.
If plural
is true, then the plural form of the common name is returned instead.
unit  The unit to name 
plural  Boolean indicating if the returned string should contain the plural form of the name 
unit

related 

static 

private 
Length in meters.
Definition at line 611 of file length.h.
Referenced by As(), GetDouble(), IsEqual(), IsGreater(), IsGreaterOrEqual(), IsLess(), IsLessOrEqual(), IsNotEqual(), Length(), operator=(), and swap().