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 Length &other)=default | |
Copy 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 (Length &&other)=default | |
Move Constructor. More... | |
Length (Quantity quantity) | |
Construct a Length object from a Quantity. 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= (const Length::Quantity &q) |
Assignment operator. More... | |
Length & | operator= (Length &&other)=default |
Move Assignment operator. More... | |
void | swap (Length &other) |
Swap values with another object. More... | |
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. 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... | |
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 ns-3 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 252 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 258 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 268 of file length.cc.
References anonymous_namespace{length.cc}::Convert(), 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 285 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 379 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 373 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 310 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 349 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 357 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 333 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 341 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 325 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 300 of file length.cc.
References anonymous_namespace{length.cc}::Convert(), 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 365 of file length.cc.
References m_value, and ns3::swap().
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 238 of file length.cc.
References Length(), ns3::FromString(), and NS_LOG_FUNCTION.
Referenced by LengthTestCase::TestTryParseReturnsFalse(), and LengthTestCase::TestTryParseReturnsTrue().
|
staticconstexpr |
|
private |
Length in meters.
Definition at line 619 of file length.h.
Referenced by Length(), As(), GetDouble(), IsEqual(), IsGreater(), IsGreaterOrEqual(), IsLess(), IsLessOrEqual(), IsNotEqual(), operator=(), and swap().