 A Discrete-Event Network Simulator Home Tutorials  ▼ Documentation  ▼ Development  ▼ API
Length

Management of lengths in real world units. More... Collaboration diagram for Length:

## Modules

Length test suite

## Files

file  length-example.cc
Demonstrates usage of the ns3::Length class.

file  length.cc
ns3::Length implementation

file  length.h
Declaration of ns3::Length class.

## Namespaces

namespace  anonymous_namespace{length.cc}
Unnamed namespace.

## Classes

class  ns3::Length
Represents a length in meters. More...

## Functions

void ArithmeticOperators ()
Demonstrates the use of ns3::Length arithmetic operators. More...

void Constructors ()
Demonstrates the use of ns3::Length constructors. More...

void Conversions ()
Demonstrates the use of ns3::Length conversions. More...

int64_t ns3::Div (const Length &numerator, const Length &denominator, Length *remainder=nullptr)
Calculate how many times `numerator` can be split into `denominator` sized pieces. More...

void DivAndMod ()
Demonstrates the use of ns3::Length multiplications and divisions. More...

void EqualityOperators ()
Demonstrates the use of ns3::Length equality operators. More...

std::optional< Length::Unitns3::FromString (std::string unitString)
Find the equivalent Length::Unit for a unit string. More...

Length ns3::Mod (const Length &numerator, const Length &denominator)
Calculate the amount remaining after dividing two lengths. More...

bool ns3::operator!= (const Length &left, const Length &right)
Compare two length objects for inequality. More...

Length ns3::operator* (const Length &l, double scalar)
Multiply a length value by a scalar. More...

Length ns3::operator* (double scalar, const Length &l)
Multiply a length value by a scalar. More...

Length ns3::operator+ (const Length &left, const Length &right)
Add two length values together. More...

Length ns3::operator- (const Length &left, const Length &right)
Subtract two length values. More...

Length ns3::operator/ (const Length &left, double scalar)
Divide a length value by a scalar. More...

double ns3::operator/ (const Length &numerator, const Length &denominator)
Divide a length value by another length value. More...

bool ns3::operator< (const Length &left, const Length &right)
Check if `left` has a value less than `right`. More...

std::ostream & ns3::operator<< (std::ostream &stream, const Length &l)
Write a length value to an output stream. More...

std::ostream & ns3::operator<< (std::ostream &stream, const Length::Quantity &q)
Write a Quantity to an output stream. More...

std::ostream & ns3::operator<< (std::ostream &stream, Length::Unit unit)
Write a Length::Unit to an output stream. More...

bool ns3::operator<= (const Length &left, const Length &right)
Check if `left` has a value less than or equal to `right`. More...

bool ns3::operator== (const Length &left, const Length &right)
Compare two length objects for equality. More...

bool ns3::operator> (const Length &left, const Length &right)
Check if `left` has a value greater than `right`. More...

bool ns3::operator>= (const Length &left, const Length &right)
Check if `left` has a value greater than or equal to `right`. More...

std::istream & ns3::operator>> (std::istream &stream, Length &l)
Read a length value from an input stream. More...

std::string ns3::ToName (Length::Unit unit, bool plural=false)
Return the name of the supplied unit. More...

std::string ns3::ToSymbol (Length::Unit unit)
Return the symbol of the supplied unit. More...

Length ns3::NanoMeters (double value)
Construct a length from a value in the indicated unit. More...

Length ns3::MicroMeters (double value)
Construct a length from a value in the indicated unit. More...

Length ns3::MilliMeters (double value)
Construct a length from a value in the indicated unit. More...

Length ns3::CentiMeters (double value)
Construct a length from a value in the indicated unit. More...

Length ns3::Meters (double value)
Construct a length from a value in the indicated unit. More...

Length ns3::KiloMeters (double value)
Construct a length from a value in the indicated unit. More...

Length ns3::NauticalMiles (double value)
Construct a length from a value in the indicated unit. More...

Length ns3::Inches (double value)
Construct a length from a value in the indicated unit. More...

Length ns3::Feet (double value)
Construct a length from a value in the indicated unit. More...

Length ns3::Yards (double value)
Construct a length from a value in the indicated unit. More...

Length ns3::Miles (double value)
Construct a length from a value in the indicated unit. More...

## Detailed Description

Management of lengths in real world units.

## ◆ ArithmeticOperators()

 void ArithmeticOperators ( )

Demonstrates the use of ns3::Length arithmetic operators.

Definition at line 83 of file length-example.cc.

References ns3::Meters(). Here is the call graph for this function:

## ◆ CentiMeters()

 Length ns3::CentiMeters ( double value )

Construct a length from a value in the indicated unit.

Parameters
 value The numerical value.
Returns
Length object.

Definition at line 796 of file length.cc.

Referenced by LengthTestCase::TestBuilderFreeFunctions(). Here is the caller graph for this function:

## ◆ Constructors()

 void Constructors ( )

Demonstrates the use of ns3::Length constructors.

Definition at line 40 of file length-example.cc.

## ◆ Conversions()

 void Conversions ( )

Demonstrates the use of ns3::Length conversions.

Definition at line 64 of file length-example.cc.

References ns3::Length::As(). Here is the call graph for this function:

## ◆ Div()

 int64_t ns3::Div ( const Length & numerator, const Length & denominator, Length * remainder = `nullptr` )

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.

Parameters
 numerator The value to split denominator The length of each split remainder Location to store the remainder
Returns
The number of times `numerator` can be split into `denominator` sized pieces, rounded down to the nearest whole number

Definition at line 474 of file length.cc.

References ns3::Length::GetDouble(), and NS_FATAL_ERROR. Here is the call graph for this function: Here is the caller graph for this function:

## ◆ DivAndMod()

 void DivAndMod ( )

Demonstrates the use of ns3::Length multiplications and divisions.

Definition at line 146 of file length-example.cc.

References ns3::Length::As(), ns3::Div(), ns3::Feet(), and ns3::Mod(). Here is the call graph for this function:

## ◆ EqualityOperators()

 void EqualityOperators ( )

Demonstrates the use of ns3::Length equality operators.

Definition at line 111 of file length-example.cc.

References ns3::Meters(). Here is the call graph for this function:

## ◆ Feet()

 Length ns3::Feet ( double value )

Construct a length from a value in the indicated unit.

Parameters
 value The numerical value.
Returns
Length object.

Definition at line 826 of file length.cc.

Referenced by DivAndMod(), and LengthTestCase::TestBuilderFreeFunctions(). Here is the caller graph for this function:

## ◆ FromString()

 std::optional< Length::Unit > ns3::FromString ( std::string unitString )

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.

Parameters
 unitString String containing the symbol or name of a length unit
Returns
A std::optional object containing a Length::Unit if a match for the string could be found

Definition at line 572 of file length.cc.

References trim-trailing-whitespace::str.

Referenced by ns3::Length::Length(), and ns3::Length::TryParse(). Here is the caller graph for this function:

## ◆ Inches()

 Length ns3::Inches ( double value )

Construct a length from a value in the indicated unit.

Parameters
 value The numerical value.
Returns
Length object.

Definition at line 820 of file length.cc.

Referenced by LengthTestCase::TestBuilderFreeFunctions(). Here is the caller graph for this function:

## ◆ KiloMeters()

 Length ns3::KiloMeters ( double value )

Construct a length from a value in the indicated unit.

Parameters
 value The numerical value.
Returns
Length object.

Definition at line 808 of file length.cc. Here is the caller graph for this function:

## ◆ Meters()

 Length ns3::Meters ( double value )

Construct a length from a value in the indicated unit.

Parameters
 value The numerical value.
Returns
Length object.

Definition at line 802 of file length.cc. Here is the caller graph for this function:

## ◆ MicroMeters()

 Length ns3::MicroMeters ( double value )

Construct a length from a value in the indicated unit.

Parameters
 value The numerical value.
Returns
Length object.

Definition at line 784 of file length.cc.

Referenced by LengthTestCase::TestBuilderFreeFunctions(). Here is the caller graph for this function:

## ◆ Miles()

 Length ns3::Miles ( double value )

Construct a length from a value in the indicated unit.

Parameters
 value The numerical value.
Returns
Length object.

Definition at line 838 of file length.cc.

Referenced by LengthTestCase::TestBuilderFreeFunctions(). Here is the caller graph for this function:

## ◆ MilliMeters()

 Length ns3::MilliMeters ( double value )

Construct a length from a value in the indicated unit.

Parameters
 value The numerical value.
Returns
Length object.

Definition at line 790 of file length.cc.

Referenced by LengthTestCase::TestBuilderFreeFunctions(). Here is the caller graph for this function:

## ◆ Mod()

 Length ns3::Mod ( const Length & numerator, const Length & denominator )

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.

Parameters
 numerator The value to split denominator The length of each split
Returns
The amount remaining after splitting `numerator` into `denominator` sized pieces.

Definition at line 493 of file length.cc.

References ns3::Length::GetDouble(), and NS_FATAL_ERROR. Here is the call graph for this function: Here is the caller graph for this function:

## ◆ NanoMeters()

 Length ns3::NanoMeters ( double value )

Construct a length from a value in the indicated unit.

Parameters
 value The numerical value.
Returns
Length object.

Definition at line 778 of file length.cc.

Referenced by LengthTestCase::TestBuilderFreeFunctions(). Here is the caller graph for this function:

## ◆ NauticalMiles()

 Length ns3::NauticalMiles ( double value )

Construct a length from a value in the indicated unit.

Parameters
 value The numerical value.
Returns
Length object.

Definition at line 814 of file length.cc.

Referenced by LengthTestCase::TestBuilderFreeFunctions(). Here is the caller graph for this function:

## ◆ operator!=()

 bool ns3::operator!= ( const Length & left, const Length & right )

Compare two length objects for inequality.

Equivalent to:

left.IsNotEqual(right, 0);
Parameters
 left Left length object right Right length object
Returns
true if `left` and `right` do not have the same value

Definition at line 395 of file length.cc.

References ns3::Length::GetDouble(). Here is the call graph for this function:

## ◆ operator*() [1/2]

 Length ns3::operator* ( const Length & l, double scalar )

Multiply a length value by a scalar.

Multiplies the value `l` by `scalar` and returns a new Length object containing the result.

Parameters
 l The Length object scalar Multiplication factor
Returns
A newly constructed Length object containing the result of `l * scalar`.

Definition at line 439 of file length.cc.

References ns3::Length::GetDouble(). Here is the call graph for this function:

## ◆ operator*() [2/2]

 Length ns3::operator* ( double scalar, const Length & l )

Multiply a length value by a scalar.

Multiplies the value `l` by `scalar` and returns a new Length object containing the result.

Parameters
 l The Length object scalar Multiplication factor
Returns
A newly constructed Length object containing the result of `l * scalar`.

Definition at line 446 of file length.cc.

## ◆ operator+()

 Length ns3::operator+ ( const Length & left, const Length & right )

Adds the values of `left` to `right` and returns a new Length object containing the result.

Parameters
 left A Length object right A Length object
Returns
A newly constructed Length object containing the result of `left + right`.

Definition at line 425 of file length.cc.

References ns3::Length::GetDouble(). Here is the call graph for this function:

## ◆ operator-()

 Length ns3::operator- ( const Length & left, const Length & right )

Subtract two length values.

Subtracts the value of `right` from `left` and returns a new Length object containing the result.

Parameters
 left A Length object right A Length object
Returns
A newly constructed Length object containing the result of `left - right`.

Definition at line 432 of file length.cc.

References ns3::Length::GetDouble(). Here is the call graph for this function:

## ◆ operator/() [1/2]

 Length ns3::operator/ ( const Length & left, double scalar )

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

Parameters
 left Length value scalar Multiplication factor
Returns
A newly constructed Length object containing the result of `left / scalar`.

Definition at line 452 of file length.cc.

References NS_FATAL_ERROR.

## ◆ operator/() [2/2]

 double ns3::operator/ ( const Length & numerator, const Length & denominator )

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.

Parameters
 numerator The top value of the division denominator The bottom value of the division
Returns
A scalar value that is the result of `numerator / denominator` or NaN if `denominator` is 0.

Definition at line 463 of file length.cc.

References ns3::Length::GetDouble(). Here is the call graph for this function:

## ◆ operator<()

 bool ns3::operator< ( const Length & left, const Length & right )

Check if `left` has a value less than `right`.

Equivalent to:

left.IsLess(right, 0);
Parameters
 left Left length object right Right length object
Returns
true if `left` is less than `right`

Definition at line 400 of file length.cc.

References ns3::Length::GetDouble(). Here is the call graph for this function:

## ◆ operator<<() [1/3]

 std::ostream & ns3::operator<< ( std::ostream & stream, const Length & l )

Write a length value to an output stream.

The output of the length is in meters.

Equivalent to:

stream << l.As (Meter);
Parameters
 stream Output stream l Length value to write to the stream
Returns
Reference to the output stream

Definition at line 656 of file length.cc.

References ns3::Length::As(). Here is the call graph for this function:

## ◆ operator<<() [2/3]

 std::ostream & ns3::operator<< ( std::ostream & stream, const Length::Quantity & q )

Write a Quantity to an output stream.

The data written to the output stream will have the format <value> <symbol>

Equivalent to:

stream << q.Value () << ' ' << ToSymbol (q.Unit());
std::string ToSymbol(Length::Unit unit)
Return the symbol of the supplied unit.
Definition: length.cc:506
Parameters
 stream Output stream q Quantity to write to the output stream
Returns
Reference to the output stream

Definition at line 664 of file length.cc. Here is the call graph for this function:

## ◆ operator<<() [3/3]

 std::ostream & ns3::operator<< ( std::ostream & stream, Length::Unit unit )

Write a Length::Unit to an output stream.

Writes the name of `unit` to the output stream

Equivalent to:

stream << ToName (unit);
std::string ToName(Length::Unit unit, bool plural)
Return the name of the supplied unit.
Definition: length.cc:536
Parameters
 stream Output stream unit Length unit to output
Returns
Reference to the output stream

Definition at line 672 of file length.cc.

References ns3::ToName(). Here is the call graph for this function:

## ◆ operator<=()

 bool ns3::operator<= ( const Length & left, const Length & right )

Check if `left` has a value less than or equal to `right`.

Equivalent to:

left.IsLessOrEqual(right, 0);
Parameters
 left Left length object right Right length object
Returns
true if `left` is less than or equal to `right`

Definition at line 406 of file length.cc.

References ns3::Length::GetDouble(). Here is the call graph for this function:

## ◆ operator==()

 bool ns3::operator== ( const Length & left, const Length & right )

Compare two length objects for equality.

Equivalent to:

left.IsEqual(right, 0);
Parameters
 left Left length object right Right length object
Returns
true if `left` and `right` have the same value

Definition at line 389 of file length.cc.

References ns3::Length::GetDouble(). Here is the call graph for this function:

## ◆ operator>()

 bool ns3::operator> ( const Length & left, const Length & right )

Check if `left` has a value greater than `right`.

Equivalent to:

left.IsGreater(right, 0);
Parameters
 left Left length object right Right length object
Returns
true if `left` is greater than `right`

Definition at line 413 of file length.cc.

References ns3::Length::GetDouble(). Here is the call graph for this function:

## ◆ operator>=()

 bool ns3::operator>= ( const Length & left, const Length & right )

Check if `left` has a value greater than or equal to `right`.

Equivalent to:

left.IsGreaterOrEqual(right, 0);
Parameters
 left Left length object right Right length object
Returns
true if `left` is greater than or equal to `right`

Definition at line 419 of file length.cc.

References ns3::Length::GetDouble(). Here is the call graph for this function:

## ◆ operator>>()

 std::istream & ns3::operator>> ( std::istream & stream, Length & l )

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

Parameters
 stream Input stream l Object where the deserialized value will be stored
Returns
Reference to the input stream

Definition at line 732 of file length.cc.

References NS_LOG_LOGIC, ns3::ParseLengthString(), and ns3::Length::swap(). Here is the call graph for this function:

## ◆ ToName()

 std::string ns3::ToName ( Length::Unit unit, bool plural = `false` )

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.

Parameters
 unit The unit to name plural Boolean indicating if the returned string should contain the plural form of the name
Returns
String containing the full name of `unit`

Definition at line 536 of file length.cc.

References NS_FATAL_ERROR.

Referenced by ns3::operator<<(). Here is the caller graph for this function:

## ◆ ToSymbol()

 std::string ns3::ToSymbol ( Length::Unit unit )

Return the symbol of the supplied unit.

The symbol of the unit is the shortened form of the unit name and is usually two or three characters long

Parameters
 unit The unit to symbolize
Returns
String containing the symbol of `unit`

Definition at line 506 of file length.cc.

References NS_FATAL_ERROR.

Referenced by ns3::operator<<(). Here is the caller graph for this function:

## ◆ Yards()

 Length ns3::Yards ( double value )

Construct a length from a value in the indicated unit.

Parameters
 value The numerical value.
Returns
Length object.

Definition at line 832 of file length.cc.

Referenced by LengthTestCase::TestBuilderFreeFunctions(). Here is the caller graph for this function: