typst_library/layout/
ratio.rs

1use std::fmt::{self, Debug, Formatter};
2use std::ops::{Add, Div, Mul, Neg};
3
4use ecow::EcoString;
5use typst_utils::{Numeric, Scalar};
6
7use crate::foundations::{Repr, repr, ty};
8
9/// A ratio of a whole.
10///
11/// A ratio is written as a number, followed by a percent sign. Ratios most
12/// often appear as part of a @relative[relative length], to specify the size of
13/// some layout element relative to the page or some container.
14///
15/// ```example
16/// #rect(width: 25%)
17/// ```
18///
19/// However, they can also describe any other property that is relative to some
20/// base, e.g. an amount of @scale.x[horizontal scaling] or the
21/// @math.lr.size[height of parentheses] relative to the height of the content
22/// they enclose.
23///
24/// = Scripting <scripting>
25/// Within your own code, you can use ratios as you like. You can multiply them
26/// with various other types as shown below:
27///
28/// #docs-table(
29///   table.header[Multiply by][Example][Result],
30///
31///   [@ratio],
32///   [`{27% * 10%}`],
33///   [`{2.7%}`],
34///
35///   [@length],
36///   [`{27% * 100pt}`],
37///   [`{27pt}`],
38///
39///   [@relative],
40///   [`{27% * (10% + 100pt)}`],
41///   [`{2.7% + 27pt}`],
42///
43///   [@angle],
44///   [`{27% * 100deg}`],
45///   [`{27deg}`],
46///
47///   [@int],
48///   [`{27% * 2}`],
49///   [`{54%}`],
50///
51///   [@float],
52///   [`{27% * 0.37037}`],
53///   [`{10%}`],
54///
55///   [@fraction],
56///   [`{27% * 3fr}`],
57///   [`{0.81fr}`],
58/// )
59///
60/// When ratios are @repr[displayed] in the document, they are rounded to two
61/// significant digits for readability.
62#[ty(cast)]
63#[derive(Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
64pub struct Ratio(Scalar);
65
66impl Ratio {
67    /// A ratio of `0%` represented as `0.0`.
68    pub const fn zero() -> Self {
69        Self(Scalar::ZERO)
70    }
71
72    /// A ratio of `100%` represented as `1.0`.
73    pub const fn one() -> Self {
74        Self(Scalar::ONE)
75    }
76
77    /// Create a new ratio from a value, where `1.0` means `100%`.
78    pub const fn new(ratio: f64) -> Self {
79        Self(Scalar::new(ratio))
80    }
81
82    /// Get the underlying ratio.
83    pub const fn get(self) -> f64 {
84        (self.0).get()
85    }
86
87    /// Get the underlying ratio.
88    pub const fn scalar(self) -> Scalar {
89        self.0
90    }
91
92    /// Whether the ratio is zero.
93    pub fn is_zero(self) -> bool {
94        self.0 == 0.0
95    }
96
97    /// Whether the ratio is one.
98    pub fn is_one(self) -> bool {
99        self.0 == 1.0
100    }
101
102    /// The absolute value of this ratio.
103    pub fn abs(self) -> Self {
104        Self::new(self.get().abs())
105    }
106
107    /// Return the ratio of the given `whole`.
108    pub fn of<T: Numeric>(self, whole: T) -> T {
109        let resolved = whole * self.get();
110        if resolved.is_finite() { resolved } else { T::zero() }
111    }
112
113    /// The reciprocal (inverse) of this ratio, `1/x`.
114    pub fn recip(self) -> Self {
115        Self::new(self.get().recip())
116    }
117}
118
119impl Numeric for Ratio {
120    fn zero() -> Self {
121        Ratio::zero()
122    }
123
124    fn is_finite(self) -> bool {
125        self.0.is_finite()
126    }
127}
128
129impl Debug for Ratio {
130    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
131        write!(f, "{:?}%", self.get() * 100.0)
132    }
133}
134
135impl Repr for Ratio {
136    fn repr(&self) -> EcoString {
137        repr::format_float_with_unit(self.get() * 100.0, "%")
138    }
139}
140
141impl Neg for Ratio {
142    type Output = Self;
143
144    fn neg(self) -> Self {
145        Self(-self.0)
146    }
147}
148
149impl Add for Ratio {
150    type Output = Self;
151
152    fn add(self, other: Self) -> Self {
153        Self(self.0 + other.0)
154    }
155}
156
157typst_utils::sub_impl!(Ratio - Ratio -> Ratio);
158
159impl Mul for Ratio {
160    type Output = Self;
161
162    fn mul(self, other: Self) -> Self {
163        Self(self.0 * other.0)
164    }
165}
166
167impl Mul<f64> for Ratio {
168    type Output = Self;
169
170    fn mul(self, other: f64) -> Self {
171        Self(self.0 * other)
172    }
173}
174
175impl Mul<Ratio> for f64 {
176    type Output = Ratio;
177
178    fn mul(self, other: Ratio) -> Ratio {
179        other * self
180    }
181}
182
183impl Div for Ratio {
184    type Output = f64;
185
186    fn div(self, other: Self) -> f64 {
187        self.get() / other.get()
188    }
189}
190
191impl Div<f64> for Ratio {
192    type Output = Self;
193
194    fn div(self, other: f64) -> Self {
195        Self(self.0 / other)
196    }
197}
198
199impl Div<Ratio> for f64 {
200    type Output = Self;
201
202    fn div(self, other: Ratio) -> Self {
203        self / other.get()
204    }
205}
206
207typst_utils::assign_impl!(Ratio += Ratio);
208typst_utils::assign_impl!(Ratio -= Ratio);
209typst_utils::assign_impl!(Ratio *= Ratio);
210typst_utils::assign_impl!(Ratio *= f64);
211typst_utils::assign_impl!(Ratio /= f64);
typst_library/layout/ratio.rs

typst_library/layout/
ratio.rs
