fixed_macro/lib.rs
1//! This library provides [`fixed!`][fm-fixed], a proc-macro that allows
2//! easily creating fixed-point constants for all of the fixed-point types provided in
3//! [`fixed`][fixed] crate.
4//!
5//! ```toml
6//! [dependencies]
7//! fixed-macro = "1.1"
8//! ```
9//!
10//! *Compiler support: rustc 1.45+.*
11//!
12//! [fixed]: https://docs.rs/fixed
13//! [fixed-types]: https://docs.rs/fixed/latest/fixed/types/index.html
14//! [fm-fixed]: macro.fixed.html
15//! [fm-types]: types/index.html
16//!
17//! ## Details
18//!
19//! - The syntax of the macro is as follows:
20//!
21//! ```ignore
22//! fixed!(<value>: <type>)
23//! ```
24//!
25//! where `<value>` is an integer literal or a float literal, and `<type>` is either of the
26//! form `I<i>F<f>` or `U<i>F<f>`, matching one of the type aliases provided in
27//! [`fixed::types`][fixed-types]. Note in particular that `<value>` has to be a literal and
28//! not an arbitrary arithmetic expression, and that `<type>` is considered a special identifier,
29//! so that it doesn't have to be imported first.
30//!
31//! - Create a fixed-point constant which is parsed at compile time (the same syntax for int
32//! and float literals is supported as in Rust itself, including underscores and scientific
33//! notation):
34//!
35//! ```rust
36//! use fixed_macro::fixed;
37//! use fixed::types::U8F8;
38//!
39//! let x1 = fixed!(-1.23: I32F32); // float literal (note, the type is not in scope)
40//! const X2: U8F8 = fixed!(1.2: U8F8); // can be used to initialize const values
41//! let x3 = fixed!(123: U8F8); // decimal integers work as well
42//! let x4 = fixed!(0x7B: U8F8); // and hex/oct/bin integers too
43//! let x5 = fixed!(1_234.567_890: I32F32); // underscores are ignored, same as in rustc
44//! let x7 = fixed!(0.12e+01: U8F8); // scientific notation is also supported
45//! ```
46//!
47//! - For each type alias from [`fixed::types`][fixed-types], there is a macro with a matching
48//! name in [`fixed_macro::types`][fm-types] which you can use without specifying the type name:
49//!
50//! ```rust
51//! use fixed_macro::types::I16F48;
52//!
53//! let a1 = I16F48!(-1.23);
54//! ```
55//!
56//! Both the macro and the type can happily coexist in the same scope:
57//!
58//! ```rust
59//! use fixed::types::I16F48;
60//! use fixed_macro::types::I16F48;
61//!
62//! const B1: I16F48 = I16F48!(1.23e-2);
63//! ```
64//!
65//! You can choose to import both under different (or same) user-defined names:
66//!
67//! ```rust
68//! use fixed::types::{I16F48 as Decimal};
69//! use fixed_macro::types::{I16F48 as dec};
70//!
71//! let c1 = dec!(12_345);
72//! const C2: Decimal = dec!(-0.123_456);
73//! ```
74
75#![no_std]
76
77pub use fixed_macro_impl::fixed;
78
79/// Macros allowing to create constants for each available fixed-point type.
80pub mod types {
81 pub use fixed_macro_types::*;
82}
83
84// Not public API. Used by generated code.
85#[doc(hidden)]
86pub use fixed as __fixed;