R3::basic_position_qty

namespace nin::R3 {
    template <std::floating_point T>
    struct basic_position_qty;

    using point_qty = basic_position_qty<double>;
}

A 3D point quantity. It holds three length components (x, y, z) expressed as length quantities. It is a container of raw measurements with no relation to any coordinate system. The components are accessible through a range-based interface.

The type alias R3::point_qty is provided for R3::basic_position_qty<double>.

Data members

Member Type

x

units::length_v<T>

y

units::length_v<T>

z

units::length_v<T>

Nested types

Type Definition

arithmetic_type

T

unit_type

units::length_v<T>

value_type

length

reference

length &

const_reference

length const&

size_type

std::size_t

difference_type

std::ptrdiff_t

iterator

forward iterator over the three components

const_iterator

const forward iterator over the three components

Member functions

(Constructor)

basic_position_qty()

(1)

basic_position_qty(length x0, length y0 = {}, length z0 = {})

(2)

  • (1) Default constructor. All components are zero.

  • (2) Component constructor.

Example
import ninbot;
using namespace nin;
int main() {
    R3::point_qty pointq_0;                       // (0, 0, 0) (m)
    R3::point_qty pointq_1 = {1_m, 2_m, 3_m};     // (1, 2, 3) (m)
}

operator[]

component access by index

length & operator [] (size_type i)

(1)

length operator [] (size_type i) const

(2)

Index 0 returns x; index 1 returns y; any other index returns z.

Example
import ninbot;
using namespace nin;
int main() {
    R3::point_qty pointq = {1_m, 2_m, 3_m};
    units::length length_z = pointq[2];     // 3_m
}

begin, cbegin

iterator to the first component

iterator begin()

(1)

const_iterator begin() const

(2)

const_iterator cbegin() const

(3)

Returns an iterator to the x component.

Example
import ninbot;
using namespace nin;
int main() {
    R3::point_qty p = {1_m, 2_m, 3_m};
    for (units::length q : p)
        { /* iterates over x, y, then z */ }
}

end, cend

sentinel

iterator end()

(1)

const_iterator end() const

(2)

const_iterator cend() const

(3)

Returns a sentinel for iterating over the components.

Example
import ninbot;
using namespace nin;
int main() {
    R3::point_qty pointq = {1_m, 2_m, 3_m};
    for (units::length q : pointq)
        { /* iterates over x, y, then z */ }
}

size

number of components

size_t size()

(1)

Returns 3.

max_size

maximum number of components

size_t max_size()

(1)

Returns 3.

empty

whether the container holds no components

bool empty()

(1)

Returns false.

operator==

equality comparison

friend bool operator == (basic_position_qty, basic_position_qty)

(1)

Component-wise equality.

This is an exact-value comparison operator: f⁻¹(f(q)) == q may be false.

Non-member functions

std::formatter<>

STL overload for the std::format and std::print families.

std::format("{:<format-spec>}", p)

(1)

Adds a specialization of std::formatter that formats the three components in the order x, y, z.

The <format-spec> syntax is

[<float-spec>]  ["_" [<unit>]]  ["|" <separator>]

with the following rules:

  • <float-spec> — anything before the first _ is forwarded verbatim to the STL formatter for floating points and applied to each component.

  • <unit> — the text between and | (or the end of the spec) selects the unit used both for the displayed values and the trailing unit label. When the is present but <unit> is empty, the unit label is suppressed and magnitudes are formatted in SI units.

  • Parentheses — when the format-spec contains no | separator, the output is wrapped in parentheses.

  • Separator — the text after | is placed between the components. The is not required in order to specify a separator: when is omitted, the trailing unit label is the default SI label (e.g. ` (m)), and parentheses are dropped as soon as `| is present. When neither _ nor | is given, <separator> defaults to ", ".

Example
import ninbot;
#include <print>
int main() {
    nin::R3::point_qty p = {1.5_m, 2.0_m, 300_mm};
    std::println("{}", p);                    // "(1.5, 2, 0.3) (m)"
    std::println("{:_}", p);                  // "(1.5, 2, 0.3)"
    std::println("{:|, }", p);                // "1.5, 2, 0.3 (m)"
    std::println("{:.2f| }", p);              // "1.50 2.00 0.30 (m)"
    std::println("{:_|}", p);                 // "1.520.3"
    std::println("{:_cm}", p);                // "(150, 200, 30) (cm)"
    std::println("{:_cm|, }", p);             // "150, 200, 30 (cm)"
    std::println("{:.2f_m}", p);              // "(1.50, 2.00, 0.30) (m)"
    std::println("{:.2f_m|; }", p);           // "1.50; 2.00; 0.30 (m)"
    std::println("({:.3f_cm| - })", p);       // "(150.000 - 200.000 - 30.000 (cm))"
    std::println("{:.2f_|, } m",    p);       // "1.50, 2.00, 0.30 m"
}