Skip to content

Commit ce8e6f4

Browse files
mpuszmpusz
committed
docs: README and documentation index page updated
1 parent 490d18b commit ce8e6f4

File tree

2 files changed

+86
-60
lines changed

2 files changed

+86
-60
lines changed

‎README.md‎

Lines changed: 68 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -18,58 +18,43 @@
1818

1919
# `mp-units` – The Quantities and Units Library for C++
2020

21-
> 🚀 **ISO C++29 Standardization Candidate** – The future of dimensional analysis in C++!
22-
23-
**The `mp-units` library is a candidate for ISO standardization for C++29.**
24-
More context can be found in the following ISO C++ proposals:
25-
26-
- [P1935: A C++ Approach to Physical Units](https://wg21.link/p1935)
27-
- [P2980: A motivation, scope, and plan for a quantities and units library](https://wg21.link/p2980)
28-
- [P3045: Quantities and units library](https://wg21.link/p3045)
29-
30-
> 🤝 **We are actively seeking organizations and individuals interested in**
31-
> **field‑trialing the library!**
32-
33-
34-
## 🌟 Share Your Success Story
35-
36-
**Help shape the future of C++!**
37-
Your testimonials help **demonstrate real-world value** to the ISO C++ Committee and
38-
other potential library users!
39-
40-
Whether you're using mp-units in **production**, **research**, or **education**:
41-
42-
- **Organizations**: Share your production deployments and success stories
43-
- **Academics**: Report research applications and teaching experiences
44-
- **Developers**: Tell us about your innovative use cases and benefits
45-
46-
[![Share Experience](https://img.shields.io/badge/Share_Your-Usage_Experience-blue?style=for-the-badge&labelColor=black&label=🌟%20Share%20Your)](https://github.com/mpusz/mp-units/issues/new?template=usage_experience.yml)
4721

22+
## ⚡ TL;DR
4823

49-
## 📚 Documentation
24+
**`mp-units`** is the only Modern C++ (C++20 and later) library providing the full
25+
spectrum of compile‑time safety for physical quantities and units — from dimensional
26+
analysis to quantity kind safety — built on the ISO 80000 International System of
27+
Quantities (ISQ).
5028

51-
Extensive project documentation is available on the **[project site](https://mpusz.github.io/mp-units)**.
52-
It includes:
29+
### What Sets mp-units Apart?
5330

54-
- **Installation instructions** – Get up and running quickly
55-
- **Detailed user's guide** – Comprehensive usage documentation
56-
- **Design rationale** – Understanding the architectural decisions
57-
- **API reference** – Complete technical documentation
58-
- **Tutorials** – Step-by-step learning resources
59-
- **Workshops** – Hands-on practice exercises
60-
- **Examples** – Real-world usage demonstrations
31+
Beyond standard dimensional analysis and automatic unit converions, **mp-units** provides
32+
safety levels available in no other C++ library:
6133

34+
- 🥇 **The only C++ library with Quantity Kind Safety** — Distinguishes quantities that
35+
share the same dimension but represent fundamentally different physical concepts:
36+
_frequency_ (Hz) ≠ _radioactive activity_ (Bq), _absorbed dose_ (Gy) ≠ _dose equivalent_
37+
(Sv), _plane angle_ (rad) ≠ _solid angle_ (sr). Dimensional analysis alone cannot catch
38+
these errors — **mp-units** prevents them at compile time.
6239

63-
## ⚡ TL;DR
40+
- 🥇 **The only library implementing ISO 80000 (ISQ)** — Built on the International System
41+
of Quantities, functions can require _specific_ quantities: `isq::height` (not just any
42+
`isq::length`), `isq::kinetic_energy` (not just any `isq::energy`). The physics of your
43+
domain becomes part of the type system.
6444

65-
**`mp-units`** is a Modern C++ (C++20 and later) library providing compile‑time
66-
dimensional analysis and safe manipulation of units, quantities, and quantity points.
45+
- 🥇 **Strongly-Typed Numerics for Any Domain** — The quantity framework extends beyond
46+
physics: define semantically distinct types for item counts, financial values, identifiers,
47+
or any numeric abstraction that should never be silently mixed at compile time.
6748

6849
### Key Features
6950

7051
- **Type Safety** – Strongly typed quantities, units, dimensions, and quantity points
7152
- **Zero Runtime Cost** – Compile‑time dimensional analysis with no runtime overhead
7253
- **Unified Design** – Comprehensive model for units, dimensions, quantities, and point origins
54+
- **ISO 80000 / ISQ Hierarchy** – Implements the International System of Quantities (ISQ)
55+
with physics‑correct quantity types and hierarchies
56+
- **Quantity Kind Safety** – Distinguishes physically distinct concepts sharing the same
57+
dimension (e.g., Hz vs. Bq, Gy vs. Sv, rad vs. sr)
7358
- **Rich Text Formatting** – Text formatting support with extensive options &
7459
character sets
7560
- **Flexible Usage** – C++ modules support (when available) and header‑only usage
@@ -160,6 +145,50 @@ int main()
160145
[![Try it live on Compiler Explorer](https://img.shields.io/badge/Try_live_on-Compiler_Explorer-black?style=for-the-badge&logo=compilerexplorer&labelColor=black&color=67C52A)](https://godbolt.org/z/rYq7cfdxY)
161146

162147

148+
## 🚀 ISO C++29 Standardization Candidate
149+
150+
> The future of dimensional analysis in C++!
151+
152+
**The `mp-units` library is a candidate for ISO standardization for C++29.**
153+
More context can be found in the following ISO C++ proposals:
154+
155+
- [P1935: A C++ Approach to Physical Units](https://wg21.link/p1935)
156+
- [P2980: A motivation, scope, and plan for a quantities and units library](https://wg21.link/p2980)
157+
- [P3045: Quantities and units library](https://wg21.link/p3045)
158+
159+
> 🤝 **We are actively seeking organizations and individuals interested in**
160+
> **field‑trialing the library!**
161+
162+
163+
## 🌟 Share Your Success Story
164+
165+
**Help shape the future of C++!**
166+
Your testimonials help **demonstrate real-world value** to the ISO C++ Committee and
167+
other potential library users!
168+
169+
Whether you're using mp-units in **production**, **research**, or **education**:
170+
171+
- **Organizations**: Share your production deployments and success stories
172+
- **Academics**: Report research applications and teaching experiences
173+
- **Developers**: Tell us about your innovative use cases and benefits
174+
175+
[![Share Experience](https://img.shields.io/badge/Share_Your-Usage_Experience-blue?style=for-the-badge&labelColor=black&label=🌟%20Share%20Your)](https://github.com/mpusz/mp-units/issues/new?template=usage_experience.yml)
176+
177+
178+
## 📚 Documentation
179+
180+
Extensive project documentation is available on the **[project site](https://mpusz.github.io/mp-units)**.
181+
It includes:
182+
183+
- **Installation instructions** – Get up and running quickly
184+
- **Detailed user's guide** – Comprehensive usage documentation
185+
- **Design rationale** – Understanding the architectural decisions
186+
- **API reference** – Complete technical documentation
187+
- **Tutorials** – Step-by-step learning resources
188+
- **Workshops** – Hands-on practice exercises
189+
- **Examples** – Real-world usage demonstrations
190+
191+
163192
## 🔍 Try It Out
164193

165194
### Compiler Explorer

‎docs/index.md‎

Lines changed: 18 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -7,26 +7,13 @@ hide:
77
<!-- markdownlint-disable-next-line MD026 -->
88
# Welcome to **mp-units**!
99

10-
**mp-units** is a compile-time enabled feature-rich Modern C++ modular/header-only library
11-
that provides compile-time dimensional analysis and unit/quantity manipulation. Its key
12-
strengths include safety, performance, and developer experience.
10+
**mp-units** is the only Modern C++ (C++20) library providing the full spectrum of
11+
compile‑time safety for physical quantities and units — from dimensional analysis and
12+
unit conversions to **quantity kind safety** — built on the ISO 80000 International
13+
System of Quantities (ISQ).
1314

14-
It is the first library on the market that, besides being **unit-safe** and **dimension-safe**,
15-
is also **quantity-safe**.
16-
17-
The library source code is hosted on [GitHub](https://github.com/mpusz/mp-units) with a permissive
18-
[MIT license](https://github.com/mpusz/units/blob/master/LICENSE.md).
19-
20-
??? info "Supported compilers"
21-
22-
This library tries to provide the best user experience possible with the C++ language.
23-
To achieve that, it extensively uses the latest C++ language features.
24-
25-
Even though the library benefits from the latest C++ versions (if available), C++20 is enough
26-
to compile and use all of the library's functionality.
27-
28-
Please refer to [C++ compiler support chapter](getting_started/cpp_compiler_support.md)
29-
for more details.
15+
The library source code is hosted on [GitHub](https://github.com/mpusz/mp-units) with a
16+
permissive [MIT license](https://github.com/mpusz/units/blob/master/LICENSE.md).
3017

3118
=== "C++ modules"
3219

@@ -91,10 +78,20 @@ Harvard Bridge length = 364.4 smoot (2034.6 ft, 620.14 m) ± 1 εar
9178

9279
More on the smoot unit of length can be found at <https://en.wikipedia.org/wiki/Smoot>.
9380

81+
??? info "Supported compilers"
82+
83+
This library tries to provide the best user experience possible with the C++ language.
84+
To achieve that, it extensively uses the latest C++ language features.
85+
86+
Even though the library benefits from the latest C++ versions (if available), C++20 is enough
87+
to compile and use all of the library's functionality.
88+
89+
Please refer to [C++ compiler support chapter](getting_started/cpp_compiler_support.md)
90+
for more details.
9491

95-
!!! important "Important: Help shape the future of C++!"
92+
!!! important "Help shape the future of C++!"
9693

97-
The **mp-units** library is a candidate for ISO standardization in C++29. To support this effort,
94+
**mp-units** is a candidate for ISO standardization in C++29. To support this effort,
9895
we need your help in demonstrating its real-world value to the ISO C++ Committee.
9996

10097
**We are seeking:**

0 commit comments

Comments
 (0)