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.

	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.

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");

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"

ns3::Length::Length

Length()

Default Constructor.

Definition: length.cc:258

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	1e³ 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

text	Serialized 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

value	Numeric value of the new length
unit	Unit that the value represents

Definition at line 274 of file length.cc.

References 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

value	Numeric value of the new length
unit	Length unit of the value

Definition at line 293 of file length.cc.

References m_value, and NS_LOG_FUNCTION.

◆ Length() [5/7]

ns3::Length::Length ( Quantity quantity )

Construct a Length object from a Quantity.

Parameters

quantity Quantity 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

other Length 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

other Length 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

unit	The 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 m_value, and NS_LOG_FUNCTION.

Referenced by Conversions(), DivAndMod(), ns3::operator<<(), LengthTestCase::TestLengthSerialization(), and LengthValueTestCase::TestSetAttributeUsingStringValue().

Here is the caller graph for this function:

◆ GetDouble()

double ns3::Length::GetDouble ( ) const

Current length value.

Equivalent to:

As (Length::Unit::Meter).Value ()

ns3::Length::Quantity::Value

double Value() const

The value of the quantity.

Definition: length.h:320

ns3::Length::As

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.

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

other	Value to compare against
tolerance	Smallest 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

other	Value to compare against
tolerance	Smallest difference allowed between the two values to still be considered equal

Equivalent to:

!(IsLessOrEqual(other, tolerance))

ns3::Length::IsLessOrEqual

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

other	Value to compare against
tolerance	Smallest difference allowed between the two values to still be considered equal

Equivalent to:

!IsLess(other, tolerance)

ns3::Length::IsLess

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

other	Value to compare against
tolerance	Smallest 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

other	Value to compare against
tolerance	Smallest difference allowed between the two values to still be considered equal

Equivalent to:

IsEqual(other, tolerance) || IsLess(other, tolerance)

ns3::Length::IsEqual

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

other	Value to compare against
tolerance	Smallest 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

other Length 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

q	Quantity holding the value to assign

Returns: Reference to the updated object

Definition at line 308 of file length.cc.

References m_value, and NS_LOG_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

other Length 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

other Length object to swap

Definition at line 373 of file length.cc.

References m_value, and swap().

Referenced by ns3::operator>>(), and swap().

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

value	Numeric value of the new length
unit	Unit 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

Length in meters.

Definition at line 620 of file length.h.

Referenced by Length(), As(), GetDouble(), IsEqual(), IsGreater(), IsGreaterOrEqual(), IsLess(), IsLessOrEqual(), IsNotEqual(), operator=(), and swap().

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

src/core/model/length.h
src/core/model/length.cc

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Attributes

Detailed Description

Supported Units

Metric

US Customary

Construction

String Constructor

Quantity Constructor

Value/Unit Constructor

boost::units

Arithmetic Operations

Addition

Subtraction

Multiplication

Division

Comparison Operations

Serialization

Member Enumeration Documentation

◆ Unit

Constructor & Destructor Documentation

◆ Length() [1/7]

◆ Length() [2/7]

◆ Length() [3/7]

◆ Length() [4/7]

◆ Length() [5/7]

◆ Length() [6/7]

◆ Length() [7/7]

◆ ~Length()

Member Function Documentation

◆ As()

◆ GetDouble()

◆ IsEqual()

◆ IsGreater()

◆ IsGreaterOrEqual()

◆ IsLess()

◆ IsLessOrEqual()

◆ IsNotEqual()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ swap()

◆ TryParse()

Member Data Documentation

◆ DEFAULT_TOLERANCE

◆ m_value