diff --git a/docs/blog/.authors.yml b/docs/blog/.authors.yml new file mode 100644 index 00000000..d8dbd8ca --- /dev/null +++ b/docs/blog/.authors.yml @@ -0,0 +1,6 @@ +authors: + mpusz: + name: Mateusz Pusz + description: Creator + avatar: https://avatars.githubusercontent.com/u/506260 + url: https://github.com/mpusz diff --git a/docs/blog/index.md b/docs/blog/index.md new file mode 100644 index 00000000..05761ac5 --- /dev/null +++ b/docs/blog/index.md @@ -0,0 +1 @@ +# Blog diff --git a/docs/blog/posts/2.0.0-released.md b/docs/blog/posts/2.0.0-released.md new file mode 100644 index 00000000..4176482b --- /dev/null +++ b/docs/blog/posts/2.0.0-released.md @@ -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. + + + +## 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 +#include +#include +#include + +using namespace mp_units; +using namespace mp_units::si::unit_symbols; + +quantity avg_speed(quantity d, + quantity 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. diff --git a/mkdocs.yml b/mkdocs.yml index c4270a59..d7830db5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -51,6 +51,14 @@ theme: # Plugins plugins: + - blog + - rss: + match_path: blog/posts/.* + date_from_meta: + as_creation: date + categories: + - categories + - tags - search - tags: tags_file: users_guide/examples/tags_index.md @@ -108,6 +116,8 @@ nav: - Quick Start: getting_started/quick_start.md - Installation and Usage: getting_started/installation_and_usage.md - FAQ: getting_started/faq.md + - Blog: + - blog/index.md - User's Guide: - Terms and Definitions: users_guide/terms_and_definitions.md - Framework Basics: diff --git a/requirements.txt b/requirements.txt index 8542ef45..3c371fe8 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,4 +2,5 @@ conan pre-commit identify mkdocs-material +mkdocs-rss-plugin mike