LibrePCB Developers Documentation
Length Class Reference

The Length class is used to represent a length (for example 12.75 millimeters) More...

#include <length.h>

+ Collaboration diagram for Length:

Public Member Functions

constexpr Length () noexcept
 Default Constructor. More...
 
constexpr Length (const Length &length) noexcept
 Copy Constructor. More...
 
constexpr Length (LengthBase_t nanometers) noexcept
 Constructor with length in nanometers. More...
 
 ~Length ()=default
 Destructor. More...
 
void setLengthNm (LengthBase_t nanometers) noexcept
 Set the length in nanometers. More...
 
void setLengthMm (qreal millimeters)
 Set the length in millimeters. More...
 
void setLengthMm (const QString &millimeters)
 Set the length in millimeters, represented in a QString. More...
 
void setLengthInch (qreal inches)
 Set the length in inches. More...
 
void setLengthMil (qreal mils)
 Set the length in mils (1/1000 inch) More...
 
void setLengthPx (qreal pixels)
 Set the length in pixels (from QGraphics* objects) More...
 
LengthBase_t toNm () const noexcept
 Get the length in nanometers. More...
 
QString toNmString () const noexcept
 Get the length in nanometers as a QString. More...
 
qreal toMicrometers () const noexcept
 Get the length in micrometers. More...
 
qreal toMm () const noexcept
 Get the length in millimeters. More...
 
QString toMmString () const noexcept
 Get the length in millimeters as a QString. More...
 
qreal toInch () const noexcept
 Get the length in inches. More...
 
qreal toMil () const noexcept
 Get the length in mils (1/1000 inches) More...
 
qreal toPx () const noexcept
 Get the length in pixels (for QGraphics* objects) More...
 
Length abs () const noexcept
 Get a Length object with absolute value (mNanometers >= 0) More...
 
LengthmakeAbs () noexcept
 Make the length absolute (mNanometers >= 0) More...
 
Length mappedToGrid (const Length &gridInterval) const noexcept
 Get a Length object which is mapped to a specific grid interval. More...
 
LengthmapToGrid (const Length &gridInterval) noexcept
 Map this Length object to a specific grid interval. More...
 
Length scaled (qreal factor) const noexcept
 Get a Length object which is scaled with a specific factor. More...
 
Lengthscale (qreal factor) noexcept
 Scale this Length object with a specific factor. More...
 
Lengthoperator= (const Length &rhs)
 
Lengthoperator+= (const Length &rhs)
 
Lengthoperator-= (const Length &rhs)
 
Lengthoperator*= (const Length &rhs)
 
Lengthoperator*= (LengthBase_t rhs)
 
Lengthoperator/= (const Length &rhs)
 
Lengthoperator/= (LengthBase_t rhs)
 
Length operator+ (const Length &rhs) const
 
Length operator- () const
 
Length operator- (const Length &rhs) const
 
Length operator* (const Length &rhs) const
 
Length operator* (LengthBase_t rhs) const
 
Length operator/ (const Length &rhs) const
 
Length operator/ (LengthBase_t rhs) const
 
Length operator% (const Length &rhs) const
 
constexpr bool operator> (const Length &rhs) const
 
constexpr bool operator> (LengthBase_t rhs) const
 
constexpr bool operator< (const Length &rhs) const
 
constexpr bool operator< (LengthBase_t rhs) const
 
constexpr bool operator>= (const Length &rhs) const
 
constexpr bool operator>= (LengthBase_t rhs) const
 
constexpr bool operator<= (const Length &rhs) const
 
constexpr bool operator<= (LengthBase_t rhs) const
 
constexpr bool operator== (const Length &rhs) const
 
constexpr bool operator== (LengthBase_t rhs) const
 
constexpr bool operator!= (const Length &rhs) const
 
constexpr bool operator!= (LengthBase_t rhs) const
 

Static Public Member Functions

static bool isValidMm (qreal millimeters) noexcept
 Check if a float value in millimeters is in the allowed range. More...
 
static Length fromMm (qreal millimeters, const Length &gridInterval=Length(0))
 Get a Length object with a specific length and map it to a specific grid. More...
 
static Length fromMm (const QString &millimeters, const Length &gridInterval=Length(0))
 Get a Length object with a specific length and map it to a specific grid. More...
 
static Length fromInch (qreal inches, const Length &gridInterval=Length(0))
 Get a Length object with a specific length and map it to a specific grid. More...
 
static Length fromMil (qreal mils, const Length &gridInterval=Length(0))
 Get a Length object with a specific length and map it to a specific grid. More...
 
static Length fromPx (qreal pixels, const Length &gridInterval=Length(0))
 Get a Length object with a specific length and map it to a specific grid. More...
 
static Length min () noexcept
 Get the smallest possible length value. More...
 
static Length max () noexcept
 Get the highest possible length value. More...
 

Private Member Functions

void setLengthFromFloat (qreal nanometers)
 Set the length from a floating point number in nanometers. More...
 

Static Private Member Functions

static bool checkRange (qreal nanometers, bool doThrow=false)
 Check if a float value in nanometers is in the allowed range. More...
 
static LengthBase_t mapNmToGrid (LengthBase_t nanometers, const Length &gridInterval) noexcept
 Map a length in nanometers to a grid interval in nanometers. More...
 
static LengthBase_t mmStringToNm (const QString &millimeters)
 Convert a length from a QString (in millimeters) to an integer (in nanometers) More...
 

Private Attributes

LengthBase_t mNanometers
 the length in nanometers More...
 

Static Private Attributes

static constexpr LengthBase_t sNmPerInch = 25400000
 1 inch = 25.4mm More...
 
static constexpr LengthBase_t sNmPerMil = 25400
 1 inch = 25.4mm More...
 
static constexpr LengthBase_t sPixelsPerInch
 72 dpi for the QGraphics* objects More...
 
static constexpr qreal sNmPerPixel = (qreal)sNmPerInch / sPixelsPerInch
 
static constexpr qreal sPixelsPerNm = (qreal)sPixelsPerInch / sNmPerInch
 

Detailed Description

The Length class is used to represent a length (for example 12.75 millimeters)

This class is used to represent ALL length values in Symbols, Schematics, Footprints, Layouts and so on. You should never use another length type, like integer or float! It's very important to have a consistent length type over the whole project.

All lengths are stored in the integer base type librepcb::LengthBase_t. The internal unit is always nanometers, but this class provides also some converting methods to other units. Read the documentation of librepcb::LengthBase_t for more details.

Constructor & Destructor Documentation

◆ Length() [1/3]

constexpr Length ( )
inlinenoexcept

Default Constructor.

The length will be initialized with zero nanometers.

+ Here is the caller graph for this function:

◆ Length() [2/3]

constexpr Length ( const Length length)
inlinenoexcept

Copy Constructor.

Parameters
lengthAnother Length object

◆ Length() [3/3]

constexpr Length ( LengthBase_t  nanometers)
inlinenoexcept

Constructor with length in nanometers.

Parameters
nanometersThe length in nanometers
+ Here is the call graph for this function:

◆ ~Length()

~Length ( )
default

Destructor.

+ Here is the caller graph for this function:

Member Function Documentation

◆ setLengthNm()

void setLengthNm ( LengthBase_t  nanometers)
inlinenoexcept

Set the length in nanometers.

Parameters
nanometersThe length in nanometers
+ Here is the caller graph for this function:

◆ setLengthMm() [1/2]

void setLengthMm ( qreal  millimeters)
inline

Set the length in millimeters.

Parameters
millimetersThe length in millimeters
Warning
Please note that this method can decrease the precision of the length! If you need a length which is located exactly on the grid of a QGraphicsView (which is often required), you need to call mapToGrid() afterwards!
Exceptions
RangeErrorIf the argument is out of range, a RangeError exception will be thrown
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ setLengthMm() [2/2]

void setLengthMm ( const QString &  millimeters)
inline

Set the length in millimeters, represented in a QString.

Parameters
millimetersThe length in millimeters in a QString with locale "C"
Note
This method is useful to read lengths from files! The problem with decreased precision does NOT exist by using this method!
Exceptions
ExceptionIf the string is not valid or the number is out of range, an Exception will be thrown
See also
toMmString(), fromMm(const QString&, const Length&)
+ Here is the call graph for this function:

◆ setLengthInch()

void setLengthInch ( qreal  inches)
inline

Set the length in inches.

Parameters
inchesThe length in inches
Warning
Please note that this method can decrease the precision of the length! If you need a length which is located exactly on the grid of a QGraphicsView (which is often required), you need to call mapToGrid() afterwards!
Exceptions
RangeErrorIf the argument is out of range, a RangeError exception will be thrown
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ setLengthMil()

void setLengthMil ( qreal  mils)
inline

Set the length in mils (1/1000 inch)

Parameters
milsThe length in mils
Warning
Please note that this method can decrease the precision of the length! If you need a length which is located exactly on the grid of a QGraphicsView (which is often required), you need to call mapToGrid() afterwards!
Exceptions
RangeErrorIf the argument is out of range, a RangeError exception will be thrown
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ setLengthPx()

void setLengthPx ( qreal  pixels)
inline

Set the length in pixels (from QGraphics* objects)

Parameters
pixelsThe length in pixels, from a QGraphics* object
Note
This method is useful to read lengths from QGraphics* objects.
Warning
Please note that this method can decrease the precision of the length! If you need a length which is located exactly on the grid of a QGraphicsView (which is often required), you need to call mapToGrid() afterwards!
Exceptions
RangeErrorIf the argument is out of range, a RangeError exception will be thrown
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ toNm()

LengthBase_t toNm ( ) const
inlinenoexcept

Get the length in nanometers.

Returns
The length in nanometers
+ Here is the caller graph for this function:

◆ toNmString()

QString toNmString ( ) const
inlinenoexcept

Get the length in nanometers as a QString.

Returns
The length in nanometers as a QString. The used locale is always "C".
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ toMicrometers()

qreal toMicrometers ( ) const
inlinenoexcept

Get the length in micrometers.

Returns
The length in micrometers
Warning
Be careful with this method, as it can decrease the precision!

◆ toMm()

qreal toMm ( ) const
inlinenoexcept

Get the length in millimeters.

Returns
The length in millimeters
Warning
Be careful with this method, as it can decrease the precision!
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ toMmString()

QString toMmString ( ) const
noexcept

Get the length in millimeters as a QString.

Returns
The length in millimeters as a QString. The used locale is always "C".
Note
This method is useful to store lengths in files. The problem with decreased precision does NOT exist by using this method!
See also
setLengthMm(const QString&), fromMm(const QString&, const Length&)
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ toInch()

qreal toInch ( ) const
inlinenoexcept

Get the length in inches.

Returns
The length in inches
Warning
Be careful with this method, as it can decrease the precision!
+ Here is the caller graph for this function:

◆ toMil()

qreal toMil ( ) const
inlinenoexcept

Get the length in mils (1/1000 inches)

Returns
The length in mils
Warning
Be careful with this method, as it can decrease the precision!
+ Here is the caller graph for this function:

◆ toPx()

qreal toPx ( ) const
inlinenoexcept

Get the length in pixels (for QGraphics* objects)

Returns
The length in QGraphics* pixels
Note
This method is useful to set the length/position of a QGraphics* object.
Warning
Be careful with this method, as it can decrease the precision!
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ abs()

Length abs ( ) const
noexcept

Get a Length object with absolute value (mNanometers >= 0)

Returns
A new Length object with absolute value
See also
librepcb::Length::makeAbs()
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ makeAbs()

Length & makeAbs ( )
noexcept

Make the length absolute (mNanometers >= 0)

Returns
A reference to the modified object
See also
librepcb::Length::abs()
+ Here is the caller graph for this function:

◆ mappedToGrid()

Length mappedToGrid ( const Length gridInterval) const
noexcept

Get a Length object which is mapped to a specific grid interval.

Parameters
gridIntervalThe grid interval in nanometers (e.g. 2540000 for 2.54mm). If this parameter is zero, this method will do nothing.
Returns
A new Length object which is mapped to the grid
See also
mapToGrid()
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mapToGrid()

Length & mapToGrid ( const Length gridInterval)
noexcept

Map this Length object to a specific grid interval.

Parameters
gridIntervalThe grid interval in nanometers (e.g. 2540000 for 2.54mm). If this parameter is zero, this method will do nothing.
Returns
A reference to the modified object
See also
mappedToGrid()
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ scaled()

Length scaled ( qreal  factor) const
noexcept

Get a Length object which is scaled with a specific factor.

Parameters
factorThe scale factor (1.0 does nothing)
Returns
A new Length object which is scaled
Warning
Be careful with this method, as it can decrease the precision! To scale with an integer factor, use operator*() instead.
See also
scale()
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ scale()

Length & scale ( qreal  factor)
noexcept

Scale this Length object with a specific factor.

Parameters
factorThe scale factor (1.0 does nothing)
Returns
A reference to the modified object
Warning
Be careful with this method, as it can decrease the precision! To scale with an integer factor, use operator*=() instead.
See also
scaled()
+ Here is the caller graph for this function:

◆ isValidMm()

static bool isValidMm ( qreal  millimeters)
inlinestaticnoexcept

Check if a float value in millimeters is in the allowed range.

Parameters
millimetersThe value to check
Return values
trueValue is valid, can construct a Length from it.
falseValue is invalid, constructing a Length would throw.
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ fromMm() [1/2]

Length fromMm ( qreal  millimeters,
const Length gridInterval = Length(0) 
)
static

Get a Length object with a specific length and map it to a specific grid.

Parameters
millimetersSee setLengthMm(qreal)
gridIntervalSee mapToGrid()
Returns
A new Length object with a length which is mapped to the specified grid
Warning
Please note that this method can decrease the precision of the length! If you need a length which is located exactly on the grid of a QGraphicsView (which is often required), you need to call mapToGrid() afterwards!
Exceptions
RangeErrorIf the argument is out of range, a RangeError exception will be thrown
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ fromMm() [2/2]

Length fromMm ( const QString &  millimeters,
const Length gridInterval = Length(0) 
)
static

Get a Length object with a specific length and map it to a specific grid.

This method can be used to create a Length object from a QString which contains a floating point number in millimeters, like QString("123.456") for 123.456 millimeters. The string must not depend on the locale settings (see QLocale), it have always to represent a number in the "C" locale. The maximum count of decimals after the decimal point is 6, because the 6th decimal represents one nanometer.

Parameters
millimetersSee setLengthMm(const QString&)
gridIntervalSee mapToGrid()
Returns
A new Length object with a length which is mapped to the specified grid
Note
This method is useful to read lengths from files! The problem with decreased precision does NOT exist by using this method!
Exceptions
ExceptionIf the argument is invalid or out of range, an Exception will be thrown
See also
setLengthMm(const QString&), toMmString()
+ Here is the call graph for this function:

◆ fromInch()

Length fromInch ( qreal  inches,
const Length gridInterval = Length(0) 
)
static

Get a Length object with a specific length and map it to a specific grid.

Parameters
inchesSee setLengthInch()
gridIntervalSee mapToGrid()
Returns
A new Length object with a length which is mapped to the specified grid
Warning
Please note that this method can decrease the precision of the length! If you need a length which is located exactly on the grid of a QGraphicsView (which is often required), you need to call mapToGrid() afterwards!
Exceptions
RangeErrorIf the argument is out of range, a RangeError exception will be thrown
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ fromMil()

Length fromMil ( qreal  mils,
const Length gridInterval = Length(0) 
)
static

Get a Length object with a specific length and map it to a specific grid.

Parameters
milsSee setLengthMil()
gridIntervalSee mapToGrid()
Returns
A new Length object with a length which is mapped to the specified grid
Warning
Please note that this method can decrease the precision of the length! If you need a length which is located exactly on the grid of a QGraphicsView (which is often required), you need to call mapToGrid() afterwards!
Exceptions
RangeErrorIf the argument is out of range, a RangeError exception will be thrown
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ fromPx()

Length fromPx ( qreal  pixels,
const Length gridInterval = Length(0) 
)
static

Get a Length object with a specific length and map it to a specific grid.

Parameters
pixelsSee setLengthPx()
gridIntervalSee mapToGrid()
Returns
A new Length object with a length which is mapped to the specified grid
Note
This method is useful to set the length/position of a QGraphics* object.
Warning
Please note that this method can decrease the precision of the length! If you need a length which is located exactly on the grid of a QGraphicsView (which is often required), you need to call mapToGrid() afterwards!
Exceptions
RangeErrorIf the argument is out of range, a RangeError exception will be thrown
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ min()

Length min ( )
staticnoexcept

Get the smallest possible length value.

Returns
Smallest possible length
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ max()

Length max ( )
staticnoexcept

Get the highest possible length value.

Returns
Highest possible length
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ operator=()

Length& operator= ( const Length rhs)
inline

◆ operator+=()

Length& operator+= ( const Length rhs)
inline

◆ operator-=()

Length& operator-= ( const Length rhs)
inline

◆ operator*=() [1/2]

Length& operator*= ( const Length rhs)
inline

◆ operator*=() [2/2]

Length& operator*= ( LengthBase_t  rhs)
inline

◆ operator/=() [1/2]

Length& operator/= ( const Length rhs)
inline

◆ operator/=() [2/2]

Length& operator/= ( LengthBase_t  rhs)
inline

◆ operator+()

Length operator+ ( const Length rhs) const
inline
+ Here is the call graph for this function:

◆ operator-() [1/2]

Length operator- ( ) const
inline
+ Here is the call graph for this function:

◆ operator-() [2/2]

Length operator- ( const Length rhs) const
inline
+ Here is the call graph for this function:

◆ operator*() [1/2]

Length operator* ( const Length rhs) const
inline
+ Here is the call graph for this function:

◆ operator*() [2/2]

Length operator* ( LengthBase_t  rhs) const
inline
+ Here is the call graph for this function:

◆ operator/() [1/2]

Length operator/ ( const Length rhs) const
inline
+ Here is the call graph for this function:

◆ operator/() [2/2]

Length operator/ ( LengthBase_t  rhs) const
inline
+ Here is the call graph for this function:

◆ operator%()

Length operator% ( const Length rhs) const
inline
+ Here is the call graph for this function:

◆ operator>() [1/2]

constexpr bool operator> ( const Length rhs) const
inline

◆ operator>() [2/2]

constexpr bool operator> ( LengthBase_t  rhs) const
inline

◆ operator<() [1/2]

constexpr bool operator< ( const Length rhs) const
inline

◆ operator<() [2/2]

constexpr bool operator< ( LengthBase_t  rhs) const
inline

◆ operator>=() [1/2]

constexpr bool operator>= ( const Length rhs) const
inline

◆ operator>=() [2/2]

constexpr bool operator>= ( LengthBase_t  rhs) const
inline

◆ operator<=() [1/2]

constexpr bool operator<= ( const Length rhs) const
inline

◆ operator<=() [2/2]

constexpr bool operator<= ( LengthBase_t  rhs) const
inline

◆ operator==() [1/2]

constexpr bool operator== ( const Length rhs) const
inline

◆ operator==() [2/2]

constexpr bool operator== ( LengthBase_t  rhs) const
inline

◆ operator!=() [1/2]

constexpr bool operator!= ( const Length rhs) const
inline

◆ operator!=() [2/2]

constexpr bool operator!= ( LengthBase_t  rhs) const
inline
+ Here is the call graph for this function:

◆ setLengthFromFloat()

void setLengthFromFloat ( qreal  nanometers)
private

Set the length from a floating point number in nanometers.

This is a helper method for the setLength*() methods.

Parameters
nanometersA floating point number in nanometers.
Note
The parameter is NOT an integer although we don't use numbers smaller than one nanometer. This way, the range of this parameter is much greater and we can compare the value with the range of an integer. If the value is outside the range of an integer, we will throw an exception. If we would pass the length as an integer, we couldn't detect such under-/overflows!
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ checkRange()

bool checkRange ( qreal  nanometers,
bool  doThrow = false 
)
staticprivate

Check if a float value in nanometers is in the allowed range.

Parameters
nanometersThe value to check
doThrowIf true, throw a librepcb::RangeError if out of range instead of returning the result
Return values
trueValue is valid, can construct a Length from it.
falseValue is invalid, constructing a Length would throw.
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mapNmToGrid()

LengthBase_t mapNmToGrid ( LengthBase_t  nanometers,
const Length gridInterval 
)
staticprivatenoexcept

Map a length in nanometers to a grid interval in nanometers.

This is a helper function for mapToGrid().

Parameters
nanometersThe length we want to map to the grid
gridIntervalThe grid interval
Returns
The length which is mapped to the grid (always a multiple of gridInterval)
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mmStringToNm()

LengthBase_t mmStringToNm ( const QString &  millimeters)
staticprivate

Convert a length from a QString (in millimeters) to an integer (in nanometers)

This is a helper function for Length(const QString&) and setLengthMm().

Parameters
millimetersA QString which contains a floating point number with maximum six decimals after the decimal point. The locale of the string have to be "C"! Example: QString("-1234.56") for -1234.56mm
Returns
The length in nanometers
+ Here is the caller graph for this function:

Member Data Documentation

◆ mNanometers

LengthBase_t mNanometers
private

the length in nanometers

◆ sNmPerInch

constexpr LengthBase_t sNmPerInch = 25400000
staticprivate

1 inch = 25.4mm

◆ sNmPerMil

constexpr LengthBase_t sNmPerMil = 25400
staticprivate

1 inch = 25.4mm

◆ sPixelsPerInch

constexpr LengthBase_t sPixelsPerInch
staticprivate
Initial value:
=
72

72 dpi for the QGraphics* objects

◆ sNmPerPixel

constexpr qreal sNmPerPixel = (qreal)sNmPerInch / sPixelsPerInch
staticprivate

◆ sPixelsPerNm

constexpr qreal sPixelsPerNm = (qreal)sPixelsPerInch / sNmPerInch
staticprivate

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