A Discrete-Event Network Simulator
API
ns3::Length Class Reference

Represents a length in meters. More...

#include "length.h"

+ Collaboration diagram for ns3::Length:

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...
 
Lengthoperator= (const Length &other)=default
 Copy Assignment operator. More...
 
Lengthoperator= (const Length::Quantity &q)
 Assignment operator. More...
 
Lengthoperator= (Length &&other)=default
 Move Assignment operator. More...
 
void swap (Length &other)
 Swap values with another object. More...
 

Static Public Member Functions

static std::optional< LengthTryParse (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...
 

Detailed Description

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.).

Supported Units

Conversion to and from meters is supported for the following units:

Metric

  • nanometer
  • micrometer
  • millimeter
  • centimeter
  • meter
  • kilometer
  • nautical mile

US Customary

  • inch
  • foot
  • yard
  • mile

Construction

Length objects can be constructed in a number of different ways

String Constructor

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.).

//construct lengths from strings
Length foot ("1foot");
Length cm ("1cm");
Length mile ("1 mile");
Length km ("1 km");
//nautical mile is special because it is two words
Length nautmile ("1 nautical mile");
Length nmi ("1 nmi");
Length()
Default Constructor.
Definition: length.cc:258

Quantity Constructor

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.

//construct a Length representing 2 kilometers
Length::Quantity q (2, Length::Unit::Kilometer);
Length km(q);

Value/Unit Constructor

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

//These two constructors are equivalent
Length l1 (1, "cm");
Length l2 (1, Length::Unit::Centimeter);

boost::units

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.

//construct length from a boost::units quantity
boost::units::quantity<boost::units::si::length> q
= 5 * boost::units::si::meter;
Length meters (q);

Arithmetic Operations

The following arithmetic operations are supported:

Addition

Addition is between two Length instances

std::cout << Length(1, Length::Unit::Meter) + Length (2, Length::Unit::Meter);
// output: "3 m"

Subtraction

Subtraction is between two Length instances

std::cout << Length(3, Length::Unit::Meter) - Length (2, Length::Unit::Meter);
// output: "1 m"

Multiplication

Multiplication is only supported between a Length and a unitless scalar value

std::cout << Length(1, Length::Unit::Meter) * 5; // output: "5 m"
std::cout << 5 * Length (1, Length::Unit::Meter); // output: "5 m"

Division

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.

std::cout << Length(5, Length::Unit::Meter) / 5; // output: "1 m"
std::cout << Length (5, Length::Unit::Meter) / Length (5, Length::Unit::Meter);
// output: 1

Comparison Operations

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.

//check for exact match
Length l (5, Length::Unit::Meter);
bool match = (l == l); // match is true
Length v1 (0.02, Length::Unit::Meter);
Length v2 (0.022, Length::Unit::Meter);
match = (v1 == v2); // match is false
double tolerance = 0.01;
bool mostly_match = v1.IsEqual (v2, tolerance); // mostly_match is true

Serialization

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.

Length m(5, Length::Unit::Meter);
std::cout << m << ", "
<< m.As(Length::Unit::Kilometer) << ", "
<< m.As(Length::Unit::Foot);
//output: 5 m, 0.005 km, 16.4042 ft

Definition at line 243 of file length.h.

Member Enumeration Documentation

◆ Unit

enum ns3::Length::Unit : uint16_t

Units of length in various measurement systems that are supported by the Length class.

Enumerator
Nanometer 

1e-9 meters

Micrometer 

1e-6 meters

Millimeter 

1e-3 meters

Centimeter 

1e-2 meters

Meter 

Base length unit in metric system.

Kilometer 

1e3 meters

NauticalMile 

1,852 meters

Inch 

1/12 of a foot

Foot 

Base length unit in US customary system.

Yard 

3 feet

Mile 

5,280 feet

Definition at line 250 of file length.h.

Constructor & Destructor Documentation

◆ Length() [1/7]

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().

+ Here is the caller graph for this function:

◆ Length() [2/7]

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>

Parameters
textSerialized length value

Definition at line 264 of file length.cc.

References NS_LOG_FUNCTION.

◆ Length() [3/7]

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.)

Warning
NS_FATAL_ERROR is called if unit is not a valid unit string.
Use Length::TryParse to parse potentially bad values without terminating.
Parameters
valueNumeric value of the new length
unitUnit that the value represents

Definition at line 274 of file length.cc.

References anonymous_namespace{length.cc}::Convert(), ns3::FromString(), m_value, NS_FATAL_ERROR, and NS_LOG_FUNCTION.

+ Here is the call graph for this function:

◆ Length() [4/7]

ns3::Length::Length ( double  value,
Length::Unit  unit 
)

Construct a Length object from a value and a unit.

Warning
NS_FATAL_ERROR is called if unit is not valid.
Use Length::TryParse to parse potentially bad values without terminating.
Parameters
valueNumeric value of the new length
unitLength unit of the value

Definition at line 293 of file length.cc.

References anonymous_namespace{length.cc}::Convert(), m_value, and NS_LOG_FUNCTION.

+ Here is the call graph for this function:

◆ Length() [5/7]

ns3::Length::Length ( Quantity  quantity)

Construct a Length object from a Quantity.

Parameters
quantityQuantity representing a length value and unit

Definition at line 301 of file length.cc.

References NS_LOG_FUNCTION.

◆ Length() [6/7]

ns3::Length::Length ( const Length other)
default

Copy Constructor.

Initialize an object with the value from other.

Parameters
otherLength object to copy

◆ Length() [7/7]

ns3::Length::Length ( Length &&  other)
default

Move Constructor.

Initialize an object with the value from other.

After the move completes, other is left in an undefined but usable state.

Parameters
otherLength object to move

◆ ~Length()

ns3::Length::~Length ( )
default

Destructor.

Member Function Documentation

◆ As()

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

Parameters
unitThe desired unit of the returned Quantity
Returns
A quantity representing the length in the requested unit

Definition at line 387 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().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ GetDouble()

double ns3::Length::GetDouble ( ) const

Current length value.

Equivalent to:

As (Length::Unit::Meter).Value ()
double Value() const
The value of the quantity.
Definition: length.h:320
Quantity As(Unit unit) const
Create a Quantity in a specific unit from a Length.
Definition: length.cc:387
Returns
The current value, in meters

Definition at line 381 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().

+ Here is the caller graph for this function:

◆ IsEqual()

bool ns3::Length::IsEqual ( const Length other,
double  tolerance = DEFAULT_TOLERANCE 
) const

Check if other is equal in value to this instance.

Parameters
otherValue to compare against
toleranceSmallest difference allowed between the two values to still be considered equal
Returns
true if the absolute difference between lengths is less than or equal to tolerance

Definition at line 318 of file length.cc.

References m_value, and NS_LOG_FUNCTION.

Referenced by IsLessOrEqual(), IsNotEqual(), LengthTestCase::TestIsEqualReturnsFalse(), LengthTestCase::TestIsEqualReturnsTrue(), LengthTestCase::TestIsEqualWithToleranceReturnsFalse(), and LengthTestCase::TestIsEqualWithToleranceReturnsTrue().

+ Here is the caller graph for this function:

◆ IsGreater()

bool ns3::Length::IsGreater ( const Length other,
double  tolerance = DEFAULT_TOLERANCE 
) const

Check if other is less in value than this instance.

Parameters
otherValue to compare against
toleranceSmallest difference allowed between the two values to still be considered equal

Equivalent to:

!(IsLessOrEqual(other, tolerance))
bool IsLessOrEqual(const Length &other, double tolerance=DEFAULT_TOLERANCE) const
Check if other is greater or equal in value than this instance.
Definition: length.cc:349
Returns
true if the values are not equal and other is less in value

Definition at line 357 of file length.cc.

References IsLessOrEqual(), m_value, and NS_LOG_FUNCTION.

Referenced by LengthTestCase::TestIsGreaterReturnsTrue().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ IsGreaterOrEqual()

bool ns3::Length::IsGreaterOrEqual ( const Length other,
double  tolerance = DEFAULT_TOLERANCE 
) const

Check if other is equal or less in value than this instance.

Parameters
otherValue to compare against
toleranceSmallest difference allowed between the two values to still be considered equal

Equivalent to:

!IsLess(other, tolerance)
bool IsLess(const Length &other, double tolerance=DEFAULT_TOLERANCE) const
Check if other is greater in value than this instance.
Definition: length.cc:341
Returns
true if the values are equal or other is less in value

Definition at line 365 of file length.cc.

References IsLess(), m_value, and NS_LOG_FUNCTION.

+ Here is the call graph for this function:

◆ IsLess()

bool ns3::Length::IsLess ( const Length other,
double  tolerance = DEFAULT_TOLERANCE 
) const

Check if other is greater in value than this instance.

Parameters
otherValue to compare against
toleranceSmallest difference allowed between the two values to still be considered equal
Returns
true if the values are not equal and other is greater in value

Definition at line 341 of file length.cc.

References IsNotEqual(), m_value, and NS_LOG_FUNCTION.

Referenced by IsGreaterOrEqual(), LengthTestCase::TestIsLessReturnsFalse(), LengthTestCase::TestIsLessReturnsTrue(), and LengthTestCase::TestIsLessWithToleranceReturnsFalse().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ IsLessOrEqual()

bool ns3::Length::IsLessOrEqual ( const Length other,
double  tolerance = DEFAULT_TOLERANCE 
) const

Check if other is greater or equal in value than this instance.

Parameters
otherValue to compare against
toleranceSmallest difference allowed between the two values to still be considered equal

Equivalent to:

IsEqual(other, tolerance) || IsLess(other, tolerance)
bool IsEqual(const Length &other, double tolerance=DEFAULT_TOLERANCE) const
Check if other is equal in value to this instance.
Definition: length.cc:318
Returns
true if the values are equal or other is greater in value

Definition at line 349 of file length.cc.

References IsEqual(), m_value, and NS_LOG_FUNCTION.

Referenced by IsGreater().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ IsNotEqual()

bool ns3::Length::IsNotEqual ( const Length other,
double  tolerance = DEFAULT_TOLERANCE 
) const

Check if other is not equal in value to this instance.

Parameters
otherValue to compare against
toleranceSmallest difference allowed between the two values to still be considered equal
Returns
true if the absolute difference between lengths is greater than tolerance

Definition at line 333 of file length.cc.

References IsEqual(), m_value, and NS_LOG_FUNCTION.

Referenced by IsLess(), LengthTestCase::TestIsNotEqualReturnsFalse(), LengthTestCase::TestIsNotEqualReturnsTrue(), LengthTestCase::TestIsNotEqualWithToleranceReturnsFalse(), and LengthTestCase::TestIsNotEqualWithToleranceReturnsTrue().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ operator=() [1/3]

Length& ns3::Length::operator= ( const Length other)
default

Copy Assignment operator.

Replace the current value with the value from other

Parameters
otherLength object to copy
Returns
Reference to the updated object

◆ operator=() [2/3]

Length & ns3::Length::operator= ( const Length::Quantity q)

Assignment operator.

Replace the current value with the value from q

Parameters
qQuantity holding the value to assign
Returns
Reference to the updated object

Definition at line 308 of file length.cc.

References anonymous_namespace{length.cc}::Convert(), m_value, and NS_LOG_FUNCTION.

+ Here is the call graph for this function:

◆ operator=() [3/3]

Length& ns3::Length::operator= ( Length &&  other)
default

Move Assignment operator.

Replace the current value with the value from other After the move, other is left in an undefined but valid state

Parameters
otherLength object to move
Returns
Reference to the updated object

◆ swap()

void ns3::Length::swap ( Length other)

Swap values with another object.

Swap the current value with the value in other.

Equivalent to:

Length temp(*this);
*this = other;
other = temp;
Parameters
otherLength object to swap

Definition at line 373 of file length.cc.

References m_value, and ns3::swap().

Referenced by ns3::operator>>().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ TryParse()

std::optional< Length > ns3::Length::TryParse ( double  value,
const std::string &  unit 
)
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.

Parameters
valueNumeric value of the new length
unitUnit that the value represents
Returns
A std::optional object containing the Length object constructed from the given value and unit, if the attempt to construct the Length object was successful.

Definition at line 244 of file length.cc.

References Length(), ns3::FromString(), and NS_LOG_FUNCTION.

Referenced by LengthTestCase::TestTryParseReturnsFalse(), and LengthTestCase::TestTryParseReturnsTrue().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

Member Data Documentation

◆ DEFAULT_TOLERANCE

constexpr double ns3::Length::DEFAULT_TOLERANCE = std::numeric_limits<double>::epsilon()
staticconstexpr

Default tolerance value used for the member comparison functions (IsEqual, IsLess, etc.)

The default tolerance is set to epsilon which is defined as the difference between 1.0 and the next value that can be represented by a double.

Definition at line 347 of file length.h.

◆ m_value

double ns3::Length::m_value
private

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