mirror of
https://github.com/mpusz/mp-units.git
synced 2025-07-30 18:37:15 +02:00
docs: project blog added
This commit is contained in:
6
docs/blog/.authors.yml
Normal file
6
docs/blog/.authors.yml
Normal file
@ -0,0 +1,6 @@
|
|||||||
|
authors:
|
||||||
|
mpusz:
|
||||||
|
name: Mateusz Pusz
|
||||||
|
description: Creator
|
||||||
|
avatar: https://avatars.githubusercontent.com/u/506260
|
||||||
|
url: https://github.com/mpusz
|
1
docs/blog/index.md
Normal file
1
docs/blog/index.md
Normal file
@ -0,0 +1 @@
|
|||||||
|
# Blog
|
130
docs/blog/posts/2.0.0-released.md
Normal file
130
docs/blog/posts/2.0.0-released.md
Normal file
@ -0,0 +1,130 @@
|
|||||||
|
---
|
||||||
|
date: 2023-09-24
|
||||||
|
authors:
|
||||||
|
- mpusz
|
||||||
|
categories:
|
||||||
|
- Releases
|
||||||
|
---
|
||||||
|
|
||||||
|
# What's new in mp-units 2.0?
|
||||||
|
|
||||||
|
**After a year of hard work, we've just released mp-units 2.0.0. It can be obtained from
|
||||||
|
[GitHub](https://github.com/mpusz/mp-units/releases/tag/v2.0.0) and
|
||||||
|
[Conan](https://conan.io/center/recipes/mp-units?version=2.0.0).**
|
||||||
|
|
||||||
|
In this post, we will describe all the changes introduced by the new version.
|
||||||
|
|
||||||
|
<!-- more -->
|
||||||
|
|
||||||
|
## Why 2.0 if 1.0 was never released?
|
||||||
|
|
||||||
|
Version 2 of the **mp-units** project is a huge change and a new quality for the users.
|
||||||
|
We did not want to pretend that 2.0 is an evolutionary upgrade of the previous version of the
|
||||||
|
project. It feels like a different product.
|
||||||
|
|
||||||
|
We could start a new repo named "mp-units-v2" similarly to [range-v3](https://github.com/ericniebler/range-v3)
|
||||||
|
but we decided not to go this path. We kept the same repo and made the scope of the changes and
|
||||||
|
potential breakage explicit with a drastic bump in the project version.
|
||||||
|
|
||||||
|
## What has changed?
|
||||||
|
|
||||||
|
The answer is "nearly everything". The whole library and its documentation were rewritten nearly
|
||||||
|
from scratch.
|
||||||
|
|
||||||
|
Here are the significant changes that the users can observe:
|
||||||
|
|
||||||
|
- **Repository name**
|
||||||
|
|
||||||
|
If you didn't notice, the repository name was changed from "mpusz/units" to "mpusz/mp-units".
|
||||||
|
|
||||||
|
- **Header files content and layout**
|
||||||
|
|
||||||
|
Previously, all the header files resided in the _include/units_ directory, and now they can be
|
||||||
|
found in _include/mp-units_. The project file tree was significantly changed as well. Many
|
||||||
|
files were moved to different subdirectories or renamed.
|
||||||
|
|
||||||
|
- **Namespace**
|
||||||
|
|
||||||
|
Previously, all the definitions were provided in the `units` namespace, and now they are in the
|
||||||
|
`mp_units` one.
|
||||||
|
|
||||||
|
- **Abstractions, interfaces, definitions**
|
||||||
|
|
||||||
|
The interfaces of all of the types were refactored, and we have a new way to construct a `quantity`
|
||||||
|
and `quantity_point`, we got unit symbols, and nearly all of the template arguments are now passed
|
||||||
|
by values thanks to class NTTP extensions in C++20. Also, systems definitions are much terser now
|
||||||
|
thanks to a new design approach.
|
||||||
|
|
||||||
|
*[NTTP]: Non-Type Template Parameter
|
||||||
|
|
||||||
|
- **Conan 2.0**
|
||||||
|
|
||||||
|
Also, now we support Conan 2.0, which provides an updated way of handling dependencies.
|
||||||
|
|
||||||
|
## What is gone?
|
||||||
|
|
||||||
|
Some cornerstones of the initial design did not prove in practice and were removed while
|
||||||
|
we moved to version 2.
|
||||||
|
|
||||||
|
### The downcasting facility
|
||||||
|
|
||||||
|
The first and the most important of such features was removing the downcasting facility.
|
||||||
|
This feature is still a powerful metaprogramming technique that allows users to map long class template
|
||||||
|
instantiations to nicely named, short, and easy-to-understand user's strong types.
|
||||||
|
|
||||||
|
Such mapping works perfectly fine for 1-to-1 relationships. However, we often deal with N-to-1 connections in the quantities and units domain. Here are only a few such examples:
|
||||||
|
|
||||||
|
- _work_ and _torque_ have the same dimension $L^2MT^{-2}$,
|
||||||
|
- becquerel and hertz have the same definition of $s^{-1}$,
|
||||||
|
- litre and cubic decimetre have the same factor.
|
||||||
|
|
||||||
|
In the above examples, multiple entities "wanted" to register different names for identical class
|
||||||
|
template instantiations, resulting in compile-time errors. We had to invent some hacks and
|
||||||
|
workarounds to make it work, but we were never satisfied with the outcome.
|
||||||
|
|
||||||
|
Additionally, this facility could easily lead to ODR violations or provide different results
|
||||||
|
depending on which header files were included in the translation units. This was too vulnerable
|
||||||
|
to be considered a good practice here.
|
||||||
|
|
||||||
|
*[ODR]: One Definition Rule
|
||||||
|
|
||||||
|
### No UDLs anymore
|
||||||
|
|
||||||
|
Over the years, we have learned that UDLs are not a good solution either. More information on this
|
||||||
|
subject can be found in the
|
||||||
|
[Why don't we use UDLs to create quantities?](../../getting_started/faq.md#why-dont-we-use-udls-to-create-quantities)
|
||||||
|
chapter.
|
||||||
|
|
||||||
|
*[UDL]: User-Defined Literals
|
||||||
|
|
||||||
|
|
||||||
|
## New look and feel
|
||||||
|
|
||||||
|
Here is a concise example showing you the new look and feel of the library:
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
#include <mp-units/format.h>
|
||||||
|
#include <mp-units/systems/isq/isq.h>
|
||||||
|
#include <mp-units/systems/si/si.h>
|
||||||
|
#include <format>
|
||||||
|
|
||||||
|
using namespace mp_units;
|
||||||
|
using namespace mp_units::si::unit_symbols;
|
||||||
|
|
||||||
|
quantity<isq::speed[m / s]> avg_speed(quantity<si::metre> d,
|
||||||
|
quantity<si::second> t)
|
||||||
|
{ return d / t; }
|
||||||
|
|
||||||
|
int main()
|
||||||
|
{
|
||||||
|
auto speed = avg_speed(220 * km, 2 * h);
|
||||||
|
std::println("{}", speed); // 30.5556 m/s
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
All of the changes we provided, although breaking ones, resulted in much better,
|
||||||
|
easier, and safer abstractions. These offer a new quantity on the market and hopefully will be
|
||||||
|
appreciated by our users.
|
||||||
|
|
||||||
|
Please check our new documentation to learn about the latest version of the project and find out
|
||||||
|
how to benefit from all the new cool stuff we have here.
|
10
mkdocs.yml
10
mkdocs.yml
@ -51,6 +51,14 @@ theme:
|
|||||||
|
|
||||||
# Plugins
|
# Plugins
|
||||||
plugins:
|
plugins:
|
||||||
|
- blog
|
||||||
|
- rss:
|
||||||
|
match_path: blog/posts/.*
|
||||||
|
date_from_meta:
|
||||||
|
as_creation: date
|
||||||
|
categories:
|
||||||
|
- categories
|
||||||
|
- tags
|
||||||
- search
|
- search
|
||||||
- tags:
|
- tags:
|
||||||
tags_file: users_guide/examples/tags_index.md
|
tags_file: users_guide/examples/tags_index.md
|
||||||
@ -108,6 +116,8 @@ nav:
|
|||||||
- Quick Start: getting_started/quick_start.md
|
- Quick Start: getting_started/quick_start.md
|
||||||
- Installation and Usage: getting_started/installation_and_usage.md
|
- Installation and Usage: getting_started/installation_and_usage.md
|
||||||
- FAQ: getting_started/faq.md
|
- FAQ: getting_started/faq.md
|
||||||
|
- Blog:
|
||||||
|
- blog/index.md
|
||||||
- User's Guide:
|
- User's Guide:
|
||||||
- Terms and Definitions: users_guide/terms_and_definitions.md
|
- Terms and Definitions: users_guide/terms_and_definitions.md
|
||||||
- Framework Basics:
|
- Framework Basics:
|
||||||
|
@ -2,4 +2,5 @@ conan
|
|||||||
pre-commit
|
pre-commit
|
||||||
identify
|
identify
|
||||||
mkdocs-material
|
mkdocs-material
|
||||||
|
mkdocs-rss-plugin
|
||||||
mike
|
mike
|
||||||
|
Reference in New Issue
Block a user