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.  
Length (const Length &other)=default  
Copy Constructor.  
Length (const std::string &text)  
String Constructor.  
Length (double value, const std::string &unit)  
Construct a Length object from a value and a unit string.  
Length (double value, Length::Unit unit)  
Construct a Length object from a value and a unit.  
Length (Length &&other)=default  
Move Constructor.  
Length (Quantity quantity)  
Construct a Length object from a Quantity.  
~Length ()=default  
Destructor.  
Quantity  As (Unit unit) const 
Create a Quantity in a specific unit from a Length.  
double  GetDouble () const 
Current length value.  
bool  IsEqual (const Length &other, double tolerance=DEFAULT_TOLERANCE) const 
Check if other is equal in value to this instance.  
bool  IsGreater (const Length &other, double tolerance=DEFAULT_TOLERANCE) const 
Check if other is less in value than this instance.  
bool  IsGreaterOrEqual (const Length &other, double tolerance=DEFAULT_TOLERANCE) const 
Check if other is equal or less in value than this instance.  
bool  IsLess (const Length &other, double tolerance=DEFAULT_TOLERANCE) const 
Check if other is greater in value than this instance.  
bool  IsLessOrEqual (const Length &other, double tolerance=DEFAULT_TOLERANCE) const 
Check if other is greater or equal in value than this instance.  
bool  IsNotEqual (const Length &other, double tolerance=DEFAULT_TOLERANCE) const 
Check if other is not equal in value to this instance.  
Length &  operator= (const Length &other)=default 
Copy Assignment operator.  
Length &  operator= (const Length::Quantity &q) 
Assignment operator.  
Length &  operator= (Length &&other)=default 
Move Assignment operator.  
void  swap (Length &other) 
Swap values with another object.  
Static Public Member Functions  
static std::optional< Length >  TryParse (double value, const std::string &unit) 
Attempt to construct a Length object from a value and a unit string.  
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.)  
Private Attributes  
double  m_value 
Length in meters.  
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 247 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 253 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 263 of file length.cc.
References ns3::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 282 of file length.cc.
References 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 usable 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 376 of file length.cc.
References m_value, and NS_LOG_FUNCTION.
Referenced by Conversions(), DivAndMod(), ns3::operator<<(), LengthTestCase::TestLengthSerialization(), and LengthValueTestCase::TestSetAttributeUsingStringValue().
double ns3::Length::GetDouble  (  )  const 
Current length value.
Equivalent to:
Definition at line 370 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::TestConstructLengthFromString(), LengthTestCase::TestConstructLengthFromUSUnits(), LengthTestCase::TestCopyAssignment(), LengthTestCase::TestDefaultLengthIsZero(), LengthTestCase::TestDivideLengthByLength(), LengthTestCase::TestDivideLengthByScalar(), LengthTestCase::TestDivReturnsCorrectRemainder(), LengthTestCase::TestDivReturnsZeroRemainder(), LengthTestCase::TestInputStreamOperator(), LengthTestCase::TestLengthCopyConstructor(), LengthTestCase::TestLengthMoveConstructor(), LengthTestCase::TestMoveAssignment(), LengthTestCase::TestMultiplyLengthByScalar(), LengthTestCase::TestMultiplyScalarByLength(), LengthTestCase::TestSubtractingLengthAndQuantity(), LengthTestCase::TestSubtractingQuantityAndLength(), and LengthTestCase::TestSubtractingTwoLengths().
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 307 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 346 of file length.cc.
References IsLessOrEqual(), m_value, and NS_LOG_FUNCTION.
Referenced by LengthTestCase::TestIsGreaterReturnsTrue().
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 354 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 330 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 338 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 322 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 
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 297 of file length.cc.
References m_value, and NS_LOG_FUNCTION.
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 
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 362 of file length.cc.
References m_value, and swap().
Referenced by ns3::operator>>(), and swap().
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 233 of file length.cc.
References Length(), ns3::FromString(), and NS_LOG_FUNCTION.
Referenced by LengthTestCase::TestTryParseReturnsFalse(), and LengthTestCase::TestTryParseReturnsTrue().

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