feedc0de/mp-units
1
0
Fork 0
forked from mpusz/mp-units
Code Pull Requests Activity
Files
5092f01adb21dba94de76b708e55582c10f2eac4
mp-units/2.3/users_guide/framework_basics/interface_introduction/index.html
T
Mateusz Pusz 32808bef78 Reinit docs to shrink git repo
2024-11-05 18:52:17 +01:00

2747 lines
77 KiB
HTML
Raw Blame History

<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="The quantities and units library for C++">
<meta name="author" content="mp-units Team">
<link rel="canonical" href="https://mpusz.github.io/mp-units/2.3/users_guide/framework_basics/interface_introduction/">
<link rel="prev" href="../../terms_and_definitions/">
<link rel="next" href="../design_overview/">
<link rel="alternate" type="application/rss+xml" title="RSS feed" href="../../../feed_rss_created.xml">
<link rel="alternate" type="application/rss+xml" title="RSS feed of updated content" href="../../../feed_rss_updated.xml">
<link rel="icon" href="../../../assets/images/mp-units-color.svg">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.38">
<title>Interface Introduction - mp-units</title>
<link rel="stylesheet" href="../../../assets/stylesheets/main.8c3ca2c6.min.css">
<link rel="stylesheet" href="../../../assets/stylesheets/palette.06af60db.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
<link rel="stylesheet" href="../../../stylesheets/extra.css">
<script>__md_scope=new URL("../../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
<meta property="og:type" content="website" >
<meta property="og:title" content="Interface Introduction - mp-units" >
<meta property="og:description" content="The quantities and units library for C++" >
<meta property="og:image" content="https://mpusz.github.io/mp-units/2.3/assets/images/social/users_guide/framework_basics/interface_introduction.png" >
<meta property="og:image:type" content="image/png" >
<meta property="og:image:width" content="1200" >
<meta property="og:image:height" content="630" >
<meta property="og:url" content="https://mpusz.github.io/mp-units/2.3/users_guide/framework_basics/interface_introduction/" >
<meta name="twitter:card" content="summary_large_image" >
<meta name="twitter:title" content="Interface Introduction - mp-units" >
<meta name="twitter:description" content="The quantities and units library for C++" >
<meta name="twitter:image" content="https://mpusz.github.io/mp-units/2.3/assets/images/social/users_guide/framework_basics/interface_introduction.png" >
</head>
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#interface-introduction" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<div data-md-color-scheme="default" data-md-component="outdated" hidden>
<aside class="md-banner md-banner--warning">
<div class="md-banner__inner md-grid md-typeset">
You're not viewing the latest version.
<a href="../../../..">
<strong>Click here to go to latest.</strong>
</a>
</div>
<script>var el=document.querySelector("[data-md-component=outdated]"),outdated=__md_get("__outdated",sessionStorage);!0===outdated&&el&&(el.hidden=!1)</script>
</aside>
</div>
<header class="md-header" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href="../../.." title="mp-units" class="md-header__button md-logo" aria-label="mp-units" data-md-component="logo">
<img src="../../../assets/images/mp-units-transparent-white.svg" alt="logo">
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
mp-units
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Interface Introduction
</span>
</div>
</div>
</div>
<form class="md-header__option" data-md-component="palette">
<input class="md-option" data-md-color-media="(prefers-color-scheme)" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo" aria-label="Switch to light mode" type="radio" name="__palette" id="__palette_0">
<label class="md-header__button md-icon" title="Switch to light mode" for="__palette_1" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7a5 5 0 0 0-5 5 5 5 0 0 0 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1M8 13h8v-2H8zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4a5 5 0 0 0 5-5 5 5 0 0 0-5-5"/></svg>
</label>
<input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="custom" data-md-color-accent="custom" aria-label="Switch to dark mode" type="radio" name="__palette" id="__palette_1">
<label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_2" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 7a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5m0 2a3 3 0 0 0-3 3 3 3 0 0 0 3 3 3 3 0 0 0 3-3 3 3 0 0 0-3-3m0-7 2.39 3.42C13.65 5.15 12.84 5 12 5s-1.65.15-2.39.42zM3.34 7l4.16-.35A7.2 7.2 0 0 0 5.94 8.5c-.44.74-.69 1.5-.83 2.29zm.02 10 1.76-3.77a7.131 7.131 0 0 0 2.38 4.14zM20.65 7l-1.77 3.79a7.02 7.02 0 0 0-2.38-4.15zm-.01 10-4.14.36c.59-.51 1.12-1.14 1.54-1.86.42-.73.69-1.5.83-2.29zM12 22l-2.41-3.44c.74.27 1.55.44 2.41.44.82 0 1.63-.17 2.37-.44z"/></svg>
</label>
<input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="black" data-md-color-accent="custom" aria-label="Switch to system preference" type="radio" name="__palette" id="__palette_2">
<label class="md-header__button md-icon" title="Switch to system preference" for="__palette_0" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m17.75 4.09-2.53 1.94.91 3.06-2.63-1.81-2.63 1.81.91-3.06-2.53-1.94L12.44 4l1.06-3 1.06 3zm3.5 6.91-1.64 1.25.59 1.98-1.7-1.17-1.7 1.17.59-1.98L15.75 11l2.06-.05L18.5 9l.69 1.95zm-2.28 4.95c.83-.08 1.72 1.1 1.19 1.85-.32.45-.66.87-1.08 1.27C15.17 23 8.84 23 4.94 19.07c-3.91-3.9-3.91-10.24 0-14.14.4-.4.82-.76 1.27-1.08.75-.53 1.93.36 1.85 1.19-.27 2.86.69 5.83 2.89 8.02a9.96 9.96 0 0 0 8.02 2.89m-1.64 2.02a12.08 12.08 0 0 1-7.8-3.47c-2.17-2.19-3.33-5-3.49-7.82-2.81 3.14-2.7 7.96.31 10.98 3.02 3.01 7.84 3.12 10.98.31"/></svg>
</label>
</form>
<script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<a href="javascript:void(0)" class="md-search__icon md-icon" title="Share" aria-label="Share" data-clipboard data-clipboard-text="" data-md-component="search-share" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18 16.08c-.76 0-1.44.3-1.96.77L8.91 12.7c.05-.23.09-.46.09-.7s-.04-.47-.09-.7l7.05-4.11c.54.5 1.25.81 2.04.81a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3c0 .24.04.47.09.7L8.04 9.81C7.5 9.31 6.79 9 6 9a3 3 0 0 0-3 3 3 3 0 0 0 3 3c.79 0 1.5-.31 2.04-.81l7.12 4.15c-.05.21-.08.43-.08.66 0 1.61 1.31 2.91 2.92 2.91s2.92-1.3 2.92-2.91A2.92 2.92 0 0 0 18 16.08"/></svg>
</a>
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
</button>
</nav>
<div class="md-search__suggest" data-md-component="search-suggest"></div>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list" role="presentation"></ol>
</div>
</div>
</div>
</div>
</div>
<div class="md-header__source">
<a href="https://github.com/mpusz/mp-units" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg>
</div>
<div class="md-source__repository">
mpusz/mp-units
</div>
</a>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
<div class="md-grid">
<ul class="md-tabs__list">
<li class="md-tabs__item">
<a href="../../.." class="md-tabs__link">
Home
</a>
</li>
<li class="md-tabs__item">
<a href="../../../getting_started/introduction/" class="md-tabs__link">
Getting Started
</a>
</li>
<li class="md-tabs__item md-tabs__item--active">
<a href="../../terms_and_definitions/" class="md-tabs__link">
User's Guide
</a>
</li>
<li class="md-tabs__item">
<a href="../../../api_reference/" class="md-tabs__link">
API Reference
</a>
</li>
<li class="md-tabs__item">
<a href="../../../blog/" class="md-tabs__link">
Blog
</a>
</li>
<li class="md-tabs__item">
<a href="../../../release_notes/" class="md-tabs__link">
Release Notes
</a>
</li>
</ul>
</div>
</nav>
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary md-nav--lifted md-nav--integrated" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href="../../.." title="mp-units" class="md-nav__button md-logo" aria-label="mp-units" data-md-component="logo">
<img src="../../../assets/images/mp-units-transparent-white.svg" alt="logo">
</a>
mp-units
</label>
<div class="md-nav__source">
<a href="https://github.com/mpusz/mp-units" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg>
</div>
<div class="md-source__repository">
mpusz/mp-units
</div>
</a>
</div>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../.." class="md-nav__link">
<span class="md-ellipsis">
Home
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" >
<label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="0">
<span class="md-ellipsis">
Getting Started
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_2">
<span class="md-nav__icon md-icon"></span>
Getting Started
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../../getting_started/introduction/" class="md-nav__link">
<span class="md-ellipsis">
Introduction
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../getting_started/quick_start/" class="md-nav__link">
<span class="md-ellipsis">
Quick Start
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../getting_started/look_and_feel/" class="md-nav__link">
<span class="md-ellipsis">
Look and Feel
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../getting_started/project_structure/" class="md-nav__link">
<span class="md-ellipsis">
Project Structure
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../getting_started/cpp_compiler_support/" class="md-nav__link">
<span class="md-ellipsis">
C++ compiler support (API/ABI)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../getting_started/installation_and_usage/" class="md-nav__link">
<span class="md-ellipsis">
Installation and Usage
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../getting_started/contributing/" class="md-nav__link">
<span class="md-ellipsis">
Contributing
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../getting_started/faq/" class="md-nav__link">
<span class="md-ellipsis">
FAQ
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" checked>
<label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="">
<span class="md-ellipsis">
User's Guide
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_3">
<span class="md-nav__icon md-icon"></span>
User's Guide
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../terms_and_definitions/" class="md-nav__link">
<span class="md-ellipsis">
Terms and Definitions
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_2" checked>
<label class="md-nav__link" for="__nav_3_2" id="__nav_3_2_label" tabindex="0">
<span class="md-ellipsis">
Framework Basics
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_2_label" aria-expanded="true">
<label class="md-nav__title" for="__nav_3_2">
<span class="md-nav__icon md-icon"></span>
Framework Basics
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
Interface Introduction
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
Interface Introduction
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#new-style-of-definitions" class="md-nav__link">
<span class="md-ellipsis">
New style of definitions
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#strong-types-instead-of-aliases" class="md-nav__link">
<span class="md-ellipsis">
Strong types instead of aliases
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#entities-composability" class="md-nav__link">
<span class="md-ellipsis">
Entities composability
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#value-based-equations" class="md-nav__link">
<span class="md-ellipsis">
Value-based equations
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#expression-templates" class="md-nav__link">
<span class="md-ellipsis">
Expression templates
</span>
</a>
<nav class="md-nav" aria-label="Expression templates">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#identities" class="md-nav__link">
<span class="md-ellipsis">
Identities
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#supported-operations-and-their-results" class="md-nav__link">
<span class="md-ellipsis">
Supported operations and their results
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#simplifying-the-resulting-expression-templates" class="md-nav__link">
<span class="md-ellipsis">
Simplifying the resulting expression templates
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="#example" class="md-nav__link">
<span class="md-ellipsis">
Example
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../design_overview/" class="md-nav__link">
<span class="md-ellipsis">
Design Overview
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../systems_of_quantities/" class="md-nav__link">
<span class="md-ellipsis">
Systems of Quantities
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../systems_of_units/" class="md-nav__link">
<span class="md-ellipsis">
Systems of Units
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../simple_and_typed_quantities/" class="md-nav__link">
<span class="md-ellipsis">
Simple and Typed Quantities
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../value_conversions/" class="md-nav__link">
<span class="md-ellipsis">
Value Conversions
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../character_of_a_quantity/" class="md-nav__link">
<span class="md-ellipsis">
Character of a Quantity
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../dimensionless_quantities/" class="md-nav__link">
<span class="md-ellipsis">
Dimensionless Quantities
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../quantity_arithmetics/" class="md-nav__link">
<span class="md-ellipsis">
Quantity Arithmetics
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../generic_interfaces/" class="md-nav__link">
<span class="md-ellipsis">
Generic Interfaces
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../faster_than_lightspeed_constants/" class="md-nav__link">
<span class="md-ellipsis">
Faster-than-lightspeed Constants
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../the_affine_space/" class="md-nav__link">
<span class="md-ellipsis">
The Affine Space
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../obtaining_metadata/" class="md-nav__link">
<span class="md-ellipsis">
Obtaining Metadata
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../concepts/" class="md-nav__link">
<span class="md-ellipsis">
Concepts
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../text_output/" class="md-nav__link">
<span class="md-ellipsis">
Text Output
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_3" >
<label class="md-nav__link" for="__nav_3_3" id="__nav_3_3_label" tabindex="0">
<span class="md-ellipsis">
Systems
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_3_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_3">
<span class="md-nav__icon md-icon"></span>
Systems
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../systems/introduction/" class="md-nav__link">
<span class="md-ellipsis">
Introduction
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../systems/isq/" class="md-nav__link">
<span class="md-ellipsis">
International System of Quantities (ISQ)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../systems/si/" class="md-nav__link">
<span class="md-ellipsis">
International System of Units (SI)
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../systems/strong_angular_system/" class="md-nav__link">
<span class="md-ellipsis">
Strong Angular System
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../systems/natural_units/" class="md-nav__link">
<span class="md-ellipsis">
Natural Units
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_4" >
<label class="md-nav__link" for="__nav_3_4" id="__nav_3_4_label" tabindex="0">
<span class="md-ellipsis">
Use Cases
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_4_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_4">
<span class="md-nav__icon md-icon"></span>
Use Cases
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../use_cases/pure_dimensional_analysis/" class="md-nav__link">
<span class="md-ellipsis">
Pure Dimensional Analysis
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../use_cases/working_with_legacy_interfaces/" class="md-nav__link">
<span class="md-ellipsis">
Working with Legacy Interfaces
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../use_cases/using_custom_representation_types/" class="md-nav__link">
<span class="md-ellipsis">
Using Custom Representation Types
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../use_cases/interoperability_with_other_libraries/" class="md-nav__link">
<span class="md-ellipsis">
Interoperability with Other Libraries
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../use_cases/extending_the_library/" class="md-nav__link">
<span class="md-ellipsis">
Extending the Library
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../use_cases/wide_compatibility/" class="md-nav__link">
<span class="md-ellipsis">
Wide Compatibility
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_5" >
<label class="md-nav__link" for="__nav_3_5" id="__nav_3_5_label" tabindex="0">
<span class="md-ellipsis">
Examples
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_5_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_5">
<span class="md-nav__icon md-icon"></span>
Examples
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../examples/tags_index/" class="md-nav__link">
<span class="md-ellipsis">
Tags Index
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_5_2" >
<label class="md-nav__link" for="__nav_3_5_2" id="__nav_3_5_2_label" tabindex="0">
<span class="md-ellipsis">
All Examples
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="3" aria-labelledby="__nav_3_5_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_5_2">
<span class="md-nav__icon md-icon"></span>
All Examples
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../examples/hello_units/" class="md-nav__link">
<span class="md-ellipsis">
hello_units
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../examples/avg_speed/" class="md-nav__link">
<span class="md-ellipsis">
avg_speed
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../examples/si_constants/" class="md-nav__link">
<span class="md-ellipsis">
si_constants
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../examples/hw_voltage/" class="md-nav__link">
<span class="md-ellipsis">
hw_voltage
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3_6" >
<label class="md-nav__link" for="__nav_3_6" id="__nav_3_6_label" tabindex="0">
<span class="md-ellipsis">
Appendix
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_3_6_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_3_6">
<span class="md-nav__icon md-icon"></span>
Appendix
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../../appendix/glossary/" class="md-nav__link">
<span class="md-ellipsis">
Glossary
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../appendix/references/" class="md-nav__link">
<span class="md-ellipsis">
References
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../../../api_reference/" class="md-nav__link">
<span class="md-ellipsis">
API Reference
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" >
<div class="md-nav__link md-nav__container">
<a href="../../../blog/" class="md-nav__link ">
<span class="md-ellipsis">
Blog
</span>
</a>
<label class="md-nav__link " for="__nav_5" id="__nav_5_label" tabindex="0">
<span class="md-nav__icon md-icon"></span>
</label>
</div>
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_5">
<span class="md-nav__icon md-icon"></span>
Blog
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5_2" >
<label class="md-nav__link" for="__nav_5_2" id="__nav_5_2_label" tabindex="0">
<span class="md-ellipsis">
Archive
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_5_2_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_5_2">
<span class="md-nav__icon md-icon"></span>
Archive
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../../blog/archive/2024/" class="md-nav__link">
<span class="md-ellipsis">
2024
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../blog/archive/2023/" class="md-nav__link">
<span class="md-ellipsis">
2023
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item md-nav__item--nested">
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5_3" >
<label class="md-nav__link" for="__nav_5_3" id="__nav_5_3_label" tabindex="0">
<span class="md-ellipsis">
Categories
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_5_3_label" aria-expanded="false">
<label class="md-nav__title" for="__nav_5_3">
<span class="md-nav__icon md-icon"></span>
Categories
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../../../blog/category/releases/" class="md-nav__link">
<span class="md-ellipsis">
Releases
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../../../blog/category/wg21/" class="md-nav__link">
<span class="md-ellipsis">
WG21
</span>
</a>
</li>
</ul>
</nav>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../../../release_notes/" class="md-nav__link">
<span class="md-ellipsis">
Release Notes
</span>
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<a href="https://github.com/mpusz/mp-units/edit/master/docs/users_guide/framework_basics/interface_introduction.md" title="Edit this page" class="md-content__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M10 20H6V4h7v5h5v3.1l2-2V8l-6-6H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h4zm10.2-7c.1 0 .3.1.4.2l1.3 1.3c.2.2.2.6 0 .8l-1 1-2.1-2.1 1-1c.1-.1.2-.2.4-.2m0 3.9L14.1 23H12v-2.1l6.1-6.1z"/></svg>
</a>
<a href="https://github.com/mpusz/mp-units/raw/master/docs/users_guide/framework_basics/interface_introduction.md" title="View source of this page" class="md-content__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M17 18c.56 0 1 .44 1 1s-.44 1-1 1-1-.44-1-1 .44-1 1-1m0-3c-2.73 0-5.06 1.66-6 4 .94 2.34 3.27 4 6 4s5.06-1.66 6-4c-.94-2.34-3.27-4-6-4m0 6.5a2.5 2.5 0 0 1-2.5-2.5 2.5 2.5 0 0 1 2.5-2.5 2.5 2.5 0 0 1 2.5 2.5 2.5 2.5 0 0 1-2.5 2.5M9.27 20H6V4h7v5h5v4.07c.7.08 1.36.25 2 .49V8l-6-6H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h4.5a8.2 8.2 0 0 1-1.23-2"/></svg>
</a>
<h1 id="interface-introduction">Interface Introduction<a class="headerlink" href="#interface-introduction" title="Permanent link">&para;</a></h1>
<h2 id="new-style-of-definitions">New style of definitions<a class="headerlink" href="#new-style-of-definitions" title="Permanent link">&para;</a></h2>
<p>The <strong>mp-units</strong> library decided to use a rather unusual pattern to define entities.
Here is how we define <code>metre</code> and <code>second</code> <a href="../../../appendix/glossary/#si">SI</a> base units:</p>
<div class="language-cpp highlight"><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kr">inline</span><span class="w"> </span><span class="k">constexpr</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">metre</span><span class="w"> </span><span class="k">final</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">named_unit</span><span class="o">&lt;</span><span class="s">&quot;m&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">kind_of</span><span class="o">&lt;</span><span class="n">isq</span><span class="o">::</span><span class="n">length</span><span class="o">&gt;&gt;</span><span class="w"> </span><span class="p">{}</span><span class="w"> </span><span class="n">metre</span><span class="p">;</span>
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kr">inline</span><span class="w"> </span><span class="k">constexpr</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">second</span><span class="w"> </span><span class="k">final</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">named_unit</span><span class="o">&lt;</span><span class="s">&quot;s&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">kind_of</span><span class="o">&lt;</span><span class="n">isq</span><span class="o">::</span><span class="n">time</span><span class="o">&gt;&gt;</span><span class="w"> </span><span class="p">{}</span><span class="w"> </span><span class="n">second</span><span class="p">;</span>
</span></code></pre></div>
<p>Please note that the above reuses the same identifier for a type and its value. The rationale
behind this is that:</p>
<ul>
<li>Users always work with values and never have to spell such a type name.</li>
<li>The types appear in the compilation errors and during debugging.</li>
</ul>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>To improve compiler errors' readability and make it easier to correlate them with
a user's written code, a new idiom in the library is to use the same identifier for
a type and its instance.</p>
<p>Also, to prevent possible issues in compile-time logic, all of the library's entities must be
marked <code>final</code>. This prevents the users to derive own strong types from them, which would
prevent expression template simplification of equivalent entities.</p>
</div>
<h2 id="strong-types-instead-of-aliases">Strong types instead of aliases<a class="headerlink" href="#strong-types-instead-of-aliases" title="Permanent link">&para;</a></h2>
<p>Let's look again at the above units definitions. Another important point to notice is that
all the types describing entities in the library are short, nicely named identifiers
that derive from longer, more verbose class template instantiations. This is really important
to improve the user experience while debugging the program or analyzing the compilation error.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Such a practice is rare in the industry. Some popular C++ physical units libraries
generate enormously long error messages where even only the first line failed to fit
on a slide with a tiny font.</p>
</div>
<h2 id="entities-composability">Entities composability<a class="headerlink" href="#entities-composability" title="Permanent link">&para;</a></h2>
<p>Many physical units libraries (in C++ or any other programming language) assign strong types
to library entities (e.g., derived units). While <code>metre_per_second</code> as a type may not look too
scary, consider, for example, units of angular momentum. If we followed this path, its
<a href="../../../appendix/glossary/#coherent-derived-unit">coherent unit</a> would look like
<code>kilogram_metre_sq_per_second</code>. Now, consider how many scaled versions of this unit you would
predefine in the library to ensure that all users are happy with your choice?
How expensive would it be from the implementation point of view?
What about potential future standardization efforts?</p>
<p>This is why in <strong>mp-units</strong>, we put a strong requirement to make everything as composable as
possible. For example, to create a quantity with a unit of speed, one may write:</p>
<div class="language-cpp highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="n">quantity</span><span class="o">&lt;</span><span class="n">si</span><span class="o">::</span><span class="n">metre</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">si</span><span class="o">::</span><span class="n">second</span><span class="o">&gt;</span><span class="w"> </span><span class="n">q</span><span class="p">;</span>
</span></code></pre></div>
<p>In case we use such a unit often and would prefer to have a handy helper for it, we can
always do something like this:</p>
<div class="language-cpp highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="k">constexpr</span><span class="w"> </span><span class="k">auto</span><span class="w"> </span><span class="n">metre_per_second</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">si</span><span class="o">::</span><span class="n">metre</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">si</span><span class="o">::</span><span class="n">second</span><span class="p">;</span>
</span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="n">quantity</span><span class="o">&lt;</span><span class="n">metre_per_second</span><span class="o">&gt;</span><span class="w"> </span><span class="n">q</span><span class="p">;</span>
</span></code></pre></div>
<p>or choose any shorter identifier of our choice.</p>
<p>Coming back to the angular momentum case, thanks to the composability of units, a user can
create such a quantity in the following way:</p>
<div class="language-cpp highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="k">using</span><span class="w"> </span><span class="k">namespace</span><span class="w"> </span><span class="nn">mp_units</span><span class="o">::</span><span class="nn">si</span><span class="o">::</span><span class="nn">unit_symbols</span><span class="p">;</span>
</span><span id="__span-3-2"><a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a><span class="k">auto</span><span class="w"> </span><span class="n">q</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">la_vector</span><span class="p">{</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">}</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">isq</span><span class="o">::</span><span class="n">angular_momentum</span><span class="p">[</span><span class="n">kg</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">m2</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">s</span><span class="p">];</span>
</span></code></pre></div>
<p>It is a much better solution. It is terse and easy to understand. Please also notice how
easy it is to obtain any scaled version of such a unit (e.g., <code>mg * square(mm) / min</code>)
without having to introduce hundreds of types to predefine them.</p>
<h2 id="value-based-equations">Value-based equations<a class="headerlink" href="#value-based-equations" title="Permanent link">&para;</a></h2>
<p>The <strong>mp-units</strong> library is based on C++20, significantly improving user experience. One of
such improvements is the usage of value-based equations.</p>
<p>As we have learned above, the entities are being used as values in the code, and they compose.
Moreover, derived entities can be defined in the library using such value-based equations.
This is a huge improvement compared to what we can find in other physical units libraries or
what we have to deal with when we want to write some equations for <code>std::ratio</code>.</p>
<p>For example, below are a few definitions of the SI derived units showing the power of C++20
extensions to Non-Type Template Parameters, which allow us to directly pass a result of
the value-based <a href="../../../appendix/glossary/#unit-equation">unit equation</a> to a class template
definition:</p>
<div class="language-cpp highlight"><pre><span></span><code><span id="__span-4-1"><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="kr">inline</span><span class="w"> </span><span class="k">constexpr</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">newton</span><span class="w"> </span><span class="k">final</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">named_unit</span><span class="o">&lt;</span><span class="s">&quot;N&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">kilogram</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">metre</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">square</span><span class="p">(</span><span class="n">second</span><span class="p">)</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{}</span><span class="w"> </span><span class="n">newton</span><span class="p">;</span>
</span><span id="__span-4-2"><a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a><span class="kr">inline</span><span class="w"> </span><span class="k">constexpr</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">pascal</span><span class="w"> </span><span class="k">final</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">named_unit</span><span class="o">&lt;</span><span class="s">&quot;Pa&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">newton</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">square</span><span class="p">(</span><span class="n">metre</span><span class="p">)</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{}</span><span class="w"> </span><span class="n">pascal</span><span class="p">;</span>
</span><span id="__span-4-3"><a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="kr">inline</span><span class="w"> </span><span class="k">constexpr</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">joule</span><span class="w"> </span><span class="k">final</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="n">named_unit</span><span class="o">&lt;</span><span class="s">&quot;J&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">newton</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">metre</span><span class="o">&gt;</span><span class="w"> </span><span class="p">{}</span><span class="w"> </span><span class="n">joule</span><span class="p">;</span>
</span></code></pre></div>
<h2 id="expression-templates">Expression templates<a class="headerlink" href="#expression-templates" title="Permanent link">&para;</a></h2>
<p>The previous chapter provided a rationale for not having predefined types for derived entities.
In many libraries, such an approach results in long and unreadable compilation errors, as
framework-generated types are typically far from being easy to read and understand.</p>
<p>The <strong>mp-units</strong> library greatly improves the user experience by extensively using
expression templates. Such expressions are used consistently throughout the entire library
to describe the results of:</p>
<ul>
<li><a href="../../../appendix/glossary/#dimension-equation">dimension equation</a> - the result is put into
the <code>derived_dimension&lt;&gt;</code> class template</li>
<li><a href="../../../appendix/glossary/#quantity-equation">quantity equation</a> - the result is put into
the <code>derived_quantity_spec&lt;&gt;</code> class template</li>
<li><a href="../../../appendix/glossary/#unit-equation">unit equation</a> - the result is put into the
<code>derived_unit&lt;&gt;</code> class template</li>
</ul>
<p>For example, if we take the above-defined base units and put the results of their division into
the quantity class template like this:</p>
<div class="language-cpp highlight"><pre><span></span><code><span id="__span-5-1"><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="n">quantity</span><span class="o">&lt;</span><span class="n">metre</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">second</span><span class="o">&gt;</span><span class="w"> </span><span class="n">q</span><span class="p">;</span>
</span></code></pre></div>
<p>we will observe the following type in the debugger</p>
<div class="language-text highlight"><pre><span></span><code><span id="__span-6-1"><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a>(gdb) ptype q
</span><span id="__span-6-2"><a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a>type = class mp_units::quantity&lt;mp_units::derived_unit&lt;metre, mp_units::per&lt;second&gt;&gt;(), double&gt; [with Rep = double] {
</span></code></pre></div>
<p>The same type identifier will be visible in the compilation error (in case it happens).</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>Expressions templates are extensively used throughout the library to improve the readability
of the resulting types.</p>
</div>
<h3 id="identities">Identities<a class="headerlink" href="#identities" title="Permanent link">&para;</a></h3>
<p>As mentioned above, equations can be performed on dimensions, quantities, and units. Each such domain must
introduce an identity object that can be used in the resulting expressions. Here is the list of
identities used in the library:</p>
<table>
<thead>
<tr>
<th>Domain Concept</th>
<th style="text-align: center;">Identity</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>Dimension</code></td>
<td style="text-align: center;"><code>dimension_one</code></td>
</tr>
<tr>
<td><code>QuantitySpec</code></td>
<td style="text-align: center;"><code>dimensionless</code></td>
</tr>
<tr>
<td><code>Unit</code></td>
<td style="text-align: center;"><code>one</code></td>
</tr>
</tbody>
</table>
<p>In the equations, a user can explicitly refer to an identity object. For example:</p>
<div class="language-cpp highlight"><pre><span></span><code><span id="__span-7-1"><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a><span class="k">constexpr</span><span class="w"> </span><span class="k">auto</span><span class="w"> </span><span class="n">my_unit</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">one</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">second</span><span class="p">;</span>
</span></code></pre></div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Another way to achieve the same result is to call an <code>inverse()</code> function:</p>
<div class="language-cpp highlight"><pre><span></span><code><span id="__span-8-1"><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a><span class="k">constexpr</span><span class="w"> </span><span class="k">auto</span><span class="w"> </span><span class="n">my_unit</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">inverse</span><span class="p">(</span><span class="n">second</span><span class="p">);</span>
</span></code></pre></div>
<p>Both cases will result in the same expression template being generated and put into the wrapper
class template.</p>
</div>
<h3 id="supported-operations-and-their-results">Supported operations and their results<a class="headerlink" href="#supported-operations-and-their-results" title="Permanent link">&para;</a></h3>
<p>There are only a few operations that one can do on such entities, and the result of each of them has
its unique representation in the library:</p>
<table>
<thead>
<tr>
<th style="text-align: center;">Operation</th>
<th style="text-align: center;">Resulting template expression arguments</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: center;"><code>A * B</code></td>
<td style="text-align: center;"><code>A, B</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>B * A</code></td>
<td style="text-align: center;"><code>A, B</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>A * A</code></td>
<td style="text-align: center;"><code>power&lt;A, 2&gt;</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>{identity} * A</code></td>
<td style="text-align: center;"><code>A</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>A * {identity}</code></td>
<td style="text-align: center;"><code>A</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>A / B</code></td>
<td style="text-align: center;"><code>A, per&lt;B&gt;</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>A / A</code></td>
<td style="text-align: center;"><code>{identity}</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>A / {identity}</code></td>
<td style="text-align: center;"><code>A</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>{identity} / A</code></td>
<td style="text-align: center;"><code>{identity}, per&lt;A&gt;</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>pow&lt;2&gt;(A)</code></td>
<td style="text-align: center;"><code>power&lt;A, 2&gt;</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>pow&lt;2&gt;({identity})</code></td>
<td style="text-align: center;"><code>{identity}</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>sqrt(A)</code> or <code>pow&lt;1, 2&gt;(A)</code></td>
<td style="text-align: center;"><code>power&lt;A, 1, 2&gt;</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>sqrt({identity})</code> or <code>pow&lt;1, 2&gt;({identity})</code></td>
<td style="text-align: center;"><code>{identity}</code></td>
</tr>
</tbody>
</table>
<h3 id="simplifying-the-resulting-expression-templates">Simplifying the resulting expression templates<a class="headerlink" href="#simplifying-the-resulting-expression-templates" title="Permanent link">&para;</a></h3>
<p>To limit the length and improve the readability of generated types, there are many rules to simplify
the resulting expression template.</p>
<ol>
<li>
<p><strong>Ordering</strong></p>
<p>The resulting comma-separated arguments of multiplication are always sorted according to
a specific predicate. This is why:</p>
<div class="language-cpp highlight"><pre><span></span><code><span id="__span-9-1"><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a><span class="k">static_assert</span><span class="p">(</span><span class="n">A</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">B</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">B</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">A</span><span class="p">);</span>
</span><span id="__span-9-2"><a id="__codelineno-9-2" name="__codelineno-9-2" href="#__codelineno-9-2"></a><span class="k">static_assert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">is_same_v</span><span class="o">&lt;</span><span class="k">decltype</span><span class="p">(</span><span class="n">A</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">B</span><span class="p">),</span><span class="w"> </span><span class="k">decltype</span><span class="p">(</span><span class="n">B</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">A</span><span class="p">)</span><span class="o">&gt;</span><span class="p">);</span>
</span></code></pre></div>
<p>This is probably the most important of all the steps, as it allows comparing types and enables
the rest of the simplification rules.</p>
</li>
<li>
<p><strong>Aggregation</strong></p>
<p>In case two of the same identifiers are found next to each other on the argument list they
will be aggregated in one entry:</p>
<table>
<thead>
<tr>
<th style="text-align: center;">Before</th>
<th style="text-align: center;">After</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: center;"><code>A, A</code></td>
<td style="text-align: center;"><code>power&lt;A, 2&gt;</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>A, power&lt;A, 2&gt;</code></td>
<td style="text-align: center;"><code>power&lt;A, 3&gt;</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>power&lt;A, 1, 2&gt;, power&lt;A, 2&gt;</code></td>
<td style="text-align: center;"><code>power&lt;A, 5, 2&gt;</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>power&lt;A, 1, 2&gt;, power&lt;A, 1, 2&gt;</code></td>
<td style="text-align: center;"><code>A</code></td>
</tr>
</tbody>
</table>
</li>
<li>
<p><strong>Simplification</strong></p>
<p>In case two of the same identifiers are found in the numerator and denominator argument lists;
they are being simplified into one entry:</p>
<table>
<thead>
<tr>
<th style="text-align: center;">Before</th>
<th style="text-align: center;">After</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: center;"><code>A, per&lt;A&gt;</code></td>
<td style="text-align: center;"><code>{identity}</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>power&lt;A, 2&gt;, per&lt;A&gt;</code></td>
<td style="text-align: center;"><code>A</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>power&lt;A, 3&gt;, per&lt;A&gt;</code></td>
<td style="text-align: center;"><code>power&lt;A, 2&gt;</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>A, per&lt;power&lt;A, 2&gt;&gt;</code></td>
<td style="text-align: center;"><code>{identity}, per&lt;A&gt;</code></td>
</tr>
</tbody>
</table>
<p>It is important to notice here that only the elements with exactly the same type are being
simplified. This means that, for example, <code>m/m</code> results in <code>one</code>, but <code>km/m</code> will not be
simplified. The resulting derived unit will preserve both symbols and their relative
magnitude. This allows us to properly print symbols of some units or constants that require
such behavior. For example, the Hubble constant is expressed in <code>km⋅s⁻¹⋅Mpc⁻¹</code>, where both
<code>km</code> and <code>Mpc</code> are units of <em>length</em>.</p>
<p>Also, to prevent possible issues in compile-time logic, all of the library's entities must be
marked <code>final</code>. This prevents the users to derive own strong types from them, which would
prevent expression template simplification of equivalent entities.</p>
</li>
<li>
<p><strong>Repacking</strong></p>
<p>In case an expression uses two results of other operations, the components of its arguments are repacked
into one resulting type and simplified there.</p>
<p>For example, assuming:</p>
<div class="language-cpp highlight"><pre><span></span><code><span id="__span-10-1"><a id="__codelineno-10-1" name="__codelineno-10-1" href="#__codelineno-10-1"></a><span class="k">constexpr</span><span class="w"> </span><span class="k">auto</span><span class="w"> </span><span class="n">X</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">A</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">B</span><span class="p">;</span>
</span></code></pre></div>
<p>then:</p>
<table>
<thead>
<tr>
<th style="text-align: center;">Operation</th>
<th style="text-align: center;">Resulting template expression arguments</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: center;"><code>X * B</code></td>
<td style="text-align: center;"><code>A</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>X * A</code></td>
<td style="text-align: center;"><code>power&lt;A, 2&gt;, per&lt;B&gt;</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>X * X</code></td>
<td style="text-align: center;"><code>power&lt;A, 2&gt;, per&lt;power&lt;B, 2&gt;&gt;</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>X / X</code></td>
<td style="text-align: center;"><code>{identity}</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>X / A</code></td>
<td style="text-align: center;"><code>{identity}, per&lt;B&gt;</code></td>
</tr>
<tr>
<td style="text-align: center;"><code>X / B</code></td>
<td style="text-align: center;"><code>A, per&lt;power&lt;B, 2&gt;&gt;</code></td>
</tr>
</tbody>
</table>
</li>
</ol>
<h2 id="example">Example<a class="headerlink" href="#example" title="Permanent link">&para;</a></h2>
<p>Thanks to all of the features described above, a user may write the code like this one:</p>
<div class="language-cpp highlight"><pre><span></span><code><span id="__span-11-1"><a id="__codelineno-11-1" name="__codelineno-11-1" href="#__codelineno-11-1"></a><span class="k">using</span><span class="w"> </span><span class="k">namespace</span><span class="w"> </span><span class="nn">mp_units</span><span class="o">::</span><span class="nn">si</span><span class="o">::</span><span class="nn">unit_symbols</span><span class="p">;</span>
</span><span id="__span-11-2"><a id="__codelineno-11-2" name="__codelineno-11-2" href="#__codelineno-11-2"></a><span class="n">quantity</span><span class="w"> </span><span class="n">speed</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">60.</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">isq</span><span class="o">::</span><span class="n">speed</span><span class="p">[</span><span class="n">km</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">h</span><span class="p">];</span>
</span><span id="__span-11-3"><a id="__codelineno-11-3" name="__codelineno-11-3" href="#__codelineno-11-3"></a><span class="n">quantity</span><span class="w"> </span><span class="n">duration</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">8</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">s</span><span class="p">;</span>
</span><span id="__span-11-4"><a id="__codelineno-11-4" name="__codelineno-11-4" href="#__codelineno-11-4"></a><span class="n">quantity</span><span class="w"> </span><span class="n">acceleration</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">speed</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">duration</span><span class="p">;</span>
</span><span id="__span-11-5"><a id="__codelineno-11-5" name="__codelineno-11-5" href="#__codelineno-11-5"></a><span class="n">std</span><span class="o">::</span><span class="n">cout</span><span class="w"> </span><span class="o">&lt;&lt;</span><span class="w"> </span><span class="s">&quot;acceleration: &quot;</span><span class="w"> </span><span class="o">&lt;&lt;</span><span class="w"> </span><span class="n">acceleration</span><span class="w"> </span><span class="o">&lt;&lt;</span><span class="w"> </span><span class="s">&quot; (&quot;</span><span class="w"> </span><span class="o">&lt;&lt;</span><span class="w"> </span><span class="n">acceleration</span><span class="p">.</span><span class="n">in</span><span class="p">(</span><span class="n">m</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">s2</span><span class="p">)</span><span class="w"> </span><span class="o">&lt;&lt;</span><span class="w"> </span><span class="s">&quot;)</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">;</span>
</span></code></pre></div>
<p>The <code>acceleration</code> quantity, being the result of the above code, has the following type
(after stripping the <code>mp_units</code> namespace for brevity):</p>
<div class="language-text highlight"><pre><span></span><code><span id="__span-12-1"><a id="__codelineno-12-1" name="__codelineno-12-1" href="#__codelineno-12-1"></a>quantity&lt;reference&lt;derived_quantity_spec&lt;isq::speed, per&lt;isq::time&gt;&gt;{}, derived_unit&lt;si::kilo_&lt;si::metre{}&gt;, per&lt;non_si::hour, si::second&gt;&gt;{}&gt;{}, int&gt;
</span></code></pre></div>
<p>and the text output presents:</p>
<div class="language-text highlight"><pre><span></span><code><span id="__span-13-1"><a id="__codelineno-13-1" name="__codelineno-13-1" href="#__codelineno-13-1"></a>acceleration: 7.5 km h⁻¹ s⁻¹ (2.08333 m/s²)
</span></code></pre></div>
</article>
</div>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
<button type="button" class="md-top md-icon" data-md-component="top" hidden>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg>
Back to top
</button>
</main>
<footer class="md-footer">
<nav class="md-footer__inner md-grid" aria-label="Footer" >
<a href="../../terms_and_definitions/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Terms and Definitions">
<div class="md-footer__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
</div>
<div class="md-footer__title">
<span class="md-footer__direction">
Previous
</span>
<div class="md-ellipsis">
Terms and Definitions
</div>
</div>
</a>
<a href="../design_overview/" class="md-footer__link md-footer__link--next" aria-label="Next: Design Overview">
<div class="md-footer__title">
<span class="md-footer__direction">
Next
</span>
<div class="md-ellipsis">
Design Overview
</div>
</div>
<div class="md-footer__button md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg>
</div>
</a>
</nav>
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
<div class="md-copyright__highlight">
Copyright &copy; 2018-2023 Mateusz Pusz
</div>
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"base": "../../..", "features": ["content.action.edit", "content.action.view", "content.code.annotate", "content.code.copy", "navigation.indexes", "navigation.tabs", "navigation.footer", "navigation.top", "search.highlight", "search.share", "search.suggest", "toc.follow", "toc.integrate"], "search": "../../../assets/javascripts/workers/search.6ce7567c.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"provider": "mike"}}</script>
<script src="../../../assets/javascripts/bundle.d6f25eb3.min.js"></script>
<script src="../../../javascripts/mathjax.js"></script>
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
</body>
</html>
View Git Blame Copy Permalink