LibrePCB Developers Documentation
LengthUnit Class Referencefinal

The LengthUnit class represents a length unit (millimeters, inches,...) and provides some useful methods to make the life easier. More...

#include <lengthunit.h>

+ Collaboration diagram for LengthUnit:

Public Member Functions

 LengthUnit () noexcept
 Default constructor which uses millimeters as unit. More...
 
 LengthUnit (const LengthUnit &other) noexcept
 Copy constructor. More...
 
 ~LengthUnit () noexcept
 Destructor. More...
 
int getIndex () const noexcept
 Get the Index of the length unit of this object. More...
 
QString toStr () const noexcept
 Serialize this object into a string. More...
 
QString toStringTr () const noexcept
 Convert the length unit to a localized string. More...
 
QString toShortStringTr () const noexcept
 Convert the length unit to a localized string (short form) More...
 
QString format (const Length &value, const QLocale &locale, const QString &separator=" ") const noexcept
 Get a pretty formatted length value with this unit. More...
 
int getReasonableNumberOfDecimals () const noexcept
 Get a reasonable number of decimals to be shown. More...
 
QStringList getUserInputSuffixes () const noexcept
 Get user input suffixes. More...
 
qreal convertToUnit (const Length &length) const noexcept
 Convert a Length to this length unit. More...
 
QPointF convertToUnit (const Point &point) const noexcept
 Convert a Point to this length unit. More...
 
Length convertFromUnit (qreal length) const
 Convert a floating point number with this unit to a Length object. More...
 
Point convertFromUnit (const QPointF &point) const
 Convert floating point numbers with this unit to a Point object. More...
 
LengthUnitoperator= (const LengthUnit &rhs) noexcept
 
bool operator== (const LengthUnit &rhs) const noexcept
 
bool operator!= (const LengthUnit &rhs) const noexcept
 

Static Public Member Functions

static LengthUnit fromString (const QString &str)
 Get the length unit represented by a string. More...
 
static LengthUnit fromIndex (int index)
 Get the length unit of a specific index (to use with getIndex()) More...
 
static QList< LengthUnitgetAllUnits () noexcept
 Get all available length units. More...
 
static LengthUnit millimeters () noexcept
 
static LengthUnit micrometers () noexcept
 
static LengthUnit nanometers () noexcept
 
static LengthUnit inches () noexcept
 
static LengthUnit mils () noexcept
 

Private Types

enum  LengthUnit_t
 An enum which contains all available length units. More...
 

Private Member Functions

 LengthUnit (LengthUnit_t unit) noexcept
 Private Constructor to create a LengthUnit object with a specific unit. More...
 

Private Attributes

LengthUnit_t mUnit
 Holds the length unit of the object. More...
 

Detailed Description

The LengthUnit class represents a length unit (millimeters, inches,...) and provides some useful methods to make the life easier.

With this class, lengths (librepcb::Length) and points (librepcb::Point) can be converted to other units.

Note
Please note that the classes librepcb::Length and librepcb::Point do not need a length unit as they represent the values always in nanometers! The class LengthUnit is only needed to show these values in the unit which the user wants, and provides some useful methods to do this.
Warning
It's possible to convert lengths and points between all available units. But as the converting methods convertFromUnit() and convertToUnit() work always with floating point numbers, there is a little risk that the conversion is not lossless! Example: If you begin with 1mm and convert via other units back to millimeters, you may get 0,999mm or 1,001mm as result. So be careful on converting lengths and points between different units!

Member Enumeration Documentation

◆ LengthUnit_t

enum LengthUnit_t
strongprivate

An enum which contains all available length units.

The enum items should be sorted (not alphabetical but by meaning) because the enum order will also define the order of these units in comboboxes and other lists/widgets.

Warning
The enum must begin with value 0 and end with _COUNT. Between these values the enum must not contain unused indexes! This is necessary for getIndex() and fromIndex().
Enumerator
Millimeters 
Micrometers 
Nanometers 
Inches 
Mils 
_COUNT 

count of units, must be the last entry of the enum

Constructor & Destructor Documentation

◆ LengthUnit() [1/3]

LengthUnit ( )
inlinenoexcept

Default constructor which uses millimeters as unit.

+ Here is the caller graph for this function:

◆ LengthUnit() [2/3]

LengthUnit ( const LengthUnit other)
inlinenoexcept

Copy constructor.

Parameters
otherAnother LengthUnit object

◆ ~LengthUnit()

~LengthUnit ( )
inlinenoexcept

Destructor.

◆ LengthUnit() [3/3]

LengthUnit ( LengthUnit_t  unit)
inlineexplicitprivatenoexcept

Private Constructor to create a LengthUnit object with a specific unit.

Parameters
unitThe length unit of the new object

Member Function Documentation

◆ getIndex()

int getIndex ( ) const
inlinenoexcept

Get the Index of the length unit of this object.

This method is useful in combination with getAllUnits() to create lists of all available length units (QListWidget, QComboBox, ...). With this method you are able to get the index of this unit in the QList returned by getAllUnits().

Warning
The index of an unit can change between different application versions! So you must never save/load such an index to/from files.
Returns
The index
See also
fromIndex(), getAllUnits()
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ toStr()

QString toStr ( ) const
noexcept

Serialize this object into a string.

Returns
This object as a string
+ Here is the caller graph for this function:

◆ toStringTr()

QString toStringTr ( ) const
noexcept

Convert the length unit to a localized string.

This method uses the application's locale settings to translate the name of the length unit to the user's language.

Returns
The unit as a localized string (like "Millimeters" or "Millimeter")
+ Here is the caller graph for this function:

◆ toShortStringTr()

QString toShortStringTr ( ) const
noexcept

Convert the length unit to a localized string (short form)

Returns
The unit as a localized short string (like "mm", "μm" or "″")
+ Here is the caller graph for this function:

◆ format()

QString format ( const Length value,
const QLocale &  locale,
const QString &  separator = " " 
) const
noexcept

Get a pretty formatted length value with this unit.

Uses up to getReasonableNumberOfDecimals() decimals, but without trailing zeros.

Parameters
valueThe value to format.
localeThe locale to use for the number format.
separatorSeparator between value and unit (defaults to one space).
Returns
Formatted string like "-0.5 mm".
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ getReasonableNumberOfDecimals()

int getReasonableNumberOfDecimals ( ) const
noexcept

Get a reasonable number of decimals to be shown.

When displaying length values to the user, often it makes sense to limit the displayed number of decimal places. But since this number depends on the unit, this helper method is provided.

Note
The returned number of decimals will NOT be enough to represent all possiblle librepcb::Length values without losing precision! So a value with truncated number of decimal places may not be converted back to a librepcb::Length object since this might lead to a different value!
Returns
Reasonable number of decimals.
+ Here is the caller graph for this function:

◆ getUserInputSuffixes()

QStringList getUserInputSuffixes ( ) const
noexcept

Get user input suffixes.

Returns a list of suffixes the user might use to represent this unit. For example "um" is a typical user input to mean Micrometers since "μm" is more difficult to write.

Returns
A list of user input suffixes
+ Here is the caller graph for this function:

◆ convertToUnit() [1/2]

qreal convertToUnit ( const Length length) const
noexcept

Convert a Length to this length unit.

This method calls the method Length::to*() (* = the unit of this object)

Parameters
lengthThe length to convert (the Length object will not be modified)
Returns
The specified length in the unit of this object
Warning
As this method always returns a floating point number, there is a little risk that the conversion is not lossless. So be careful with it.
+ Here is the caller graph for this function:

◆ convertToUnit() [2/2]

QPointF convertToUnit ( const Point point) const
noexcept

Convert a Point to this length unit.

This method calls the method Point::to*QPointF() (* = the unit of this object)

Parameters
pointThe point to convert (the Point object will not be modified)
Returns
The specified point in the unit of this object
Warning
As this method always returns floating point numbers, there is a little risk that the conversion is not lossless. So be careful with it.

◆ convertFromUnit() [1/2]

Length convertFromUnit ( qreal  length) const

Convert a floating point number with this unit to a Length object.

This method calls the method Length::from*() (* = the unit of this object)

Parameters
lengthA length in the unit of this object
Returns
A Length object with the converted length
Warning
As this method always uses floating point numbers, there is a little risk that the conversion is not lossless. So be careful with it.
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ convertFromUnit() [2/2]

Point convertFromUnit ( const QPointF &  point) const

Convert floating point numbers with this unit to a Point object.

This method calls the method Point::from*() (* = the unit of this object)

Parameters
pointA point in the unit of this object
Returns
A Point object with the converted point
Warning
As this method always uses floating point numbers, there is a little risk that the conversion is not lossless. So be careful with it.
+ Here is the call graph for this function:

◆ fromString()

LengthUnit fromString ( const QString &  str)
static

Get the length unit represented by a string.

Parameters
strThe toStr() representation of the unit.
Returns
The LengthUnit of the string.
Exceptions
ExceptionIf the string did not contain a valid unit.
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ fromIndex()

LengthUnit fromIndex ( int  index)
static

Get the length unit of a specific index (to use with getIndex())

Parameters
indexThe index of the unit in the list of getAllUnits(). This number equals to the number returned by getIndex().
Returns
The LengthUnit object with the specified index
Exceptions
ExceptionIf index was invalid
See also
getIndex(), getAllUnits()
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ getAllUnits()

QList< LengthUnit > getAllUnits ( )
staticnoexcept

Get all available length units.

This method returns a list of all available length units. The index of the objects in the list equals to the value from getIndex() of them.

Returns
A list of all available length units
See also
getIndex(), fromIndex()
+ Here is the caller graph for this function:

◆ millimeters()

static LengthUnit millimeters ( )
inlinestaticnoexcept
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ micrometers()

static LengthUnit micrometers ( )
inlinestaticnoexcept
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ nanometers()

static LengthUnit nanometers ( )
inlinestaticnoexcept
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ inches()

static LengthUnit inches ( )
inlinestaticnoexcept
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ mils()

static LengthUnit mils ( )
inlinestaticnoexcept
+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ operator=()

LengthUnit& operator= ( const LengthUnit rhs)
inlinenoexcept

◆ operator==()

bool operator== ( const LengthUnit rhs) const
inlinenoexcept

◆ operator!=()

bool operator!= ( const LengthUnit rhs) const
inlinenoexcept

Member Data Documentation

◆ mUnit

LengthUnit_t mUnit
private

Holds the length unit of the object.


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