kasuari 0.4.12

A rust layout solver for GUIs, based on the Cassowary algorithm. A fork of the unmaintained cassowary-rs crate with improvments and bug fixes. Kasuari is the indonesian name for the cassowary bird.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322

//! Contains useful constants and functions for producing strengths for use in the constraint
//! solver. Each constraint added to the solver has an associated strength specifying the precedence
//! the solver should impose when choosing which constraints to enforce. It will try to enforce all
//! constraints, but if that is impossible the lowest strength constraints are the first to be
//! violated.
//!
//! Strengths are simply real numbers. The strongest legal strength is 1,001,001,000.0. The weakest
//! is 0.0. For convenience constants are declared for commonly used strengths. These are
//! [`REQUIRED`], [`STRONG`], [`MEDIUM`] and [`WEAK`]. Feel free to multiply these by other values
//! to get intermediate strengths. Note that the solver will clip given strengths to the legal
//! range.
//!
//! [`REQUIRED`] signifies a constraint that cannot be violated under any circumstance. Use this
//! special strength sparingly, as the solver will fail completely if it find that not all of the
//! [`REQUIRED`] constraints can be satisfied. The other strengths represent fallible constraints.
//! These should be the most commonly used strenghts for use cases where violating a constraint is
//! acceptable or even desired.
//!
//! The solver will try to get as close to satisfying the constraints it violates as possible,
//! strongest first. This behaviour can be used (for example) to provide a "default" value for a
//! variable should no other stronger constraints be put upon it.

use core::ops;

#[derive(Debug, Copy, Clone, PartialEq)]
pub struct Strength(f64);

impl Strength {
    /// The required strength for a constraint. This is the strongest possible strength.
    pub const REQUIRED: Strength = Strength(1_001_001_000.0);

    /// A strong strength for a constraint. This is weaker than `REQUIRED` but stronger than
    /// `MEDIUM`.
    pub const STRONG: Strength = Strength(1_000_000.0);

    /// A medium strength for a constraint. This is weaker than `STRONG` but stronger than `WEAK`.
    pub const MEDIUM: Strength = Strength(1_000.0);

    /// A weak strength for a constraint. This is weaker than `MEDIUM` but stronger than `0.0`.
    pub const WEAK: Strength = Strength(1.0);

    /// The weakest possible strength for a constraint. This is weaker than `WEAK`.
    pub const ZERO: Strength = Strength(0.0);

    /// Create a new strength with the given value, clipped to the legal range (0.0, REQUIRED)
    #[inline]
    pub const fn new(value: f64) -> Self {
        Self(value.clamp(0.0, Self::REQUIRED.value()))
    }

    /// Create a constraint as a linear combination of STRONG, MEDIUM and WEAK strengths.
    ///
    /// Each weight is multiplied by the multiplier, clamped to the legal range and then multiplied
    /// by the corresponding strength. The resulting strengths are then summed.
    #[inline]
    pub const fn create(strong: f64, medium: f64, weak: f64, multiplier: f64) -> Self {
        let strong = (strong * multiplier).clamp(0.0, 1000.0) * Self::STRONG.value();
        let medium = (medium * multiplier).clamp(0.0, 1000.0) * Self::MEDIUM.value();
        let weak = (weak * multiplier).clamp(0.0, 1000.0) * Self::WEAK.value();
        Self::new(strong + medium + weak)
    }

    /// The value of the strength
    #[inline]
    pub const fn value(&self) -> f64 {
        self.0
    }

    /// Add two strengths together, clamping the result to the legal range
    #[inline]
    pub const fn add(self, rhs: Self) -> Self {
        Self::new(self.0 + rhs.0)
    }

    /// Subtract one strength from another, clipping the result to the legal range
    #[inline]
    pub const fn sub(self, rhs: Self) -> Self {
        Self::new(self.0 - rhs.0)
    }

    /// Multiply a strength by a scalar, clipping the result to the legal range
    #[inline]
    pub const fn mul_f64(self, rhs: f64) -> Self {
        Self::new(self.0 * rhs)
    }

    /// Multiply a strength by a scalar, clipping the result to the legal range
    #[inline]
    pub const fn mul_f32(self, rhs: f32) -> Self {
        Self::new(self.0 * rhs as f64)
    }

    /// Divide a strength by a scalar, clipping the result to the legal range
    #[inline]
    pub const fn div_f64(self, rhs: f64) -> Self {
        Self::new(self.0 / rhs)
    }

    /// Divide a strength by a scalar, clipping the result to the legal range
    #[inline]
    pub const fn div_f32(self, rhs: f32) -> Self {
        Self::new(self.0 / rhs as f64)
    }
}

impl ops::Add<Strength> for Strength {
    type Output = Self;

    /// Add two strengths together, clipping the result to the legal range
    #[inline]
    fn add(self, rhs: Self) -> Self {
        Self::add(self, rhs)
    }
}

impl ops::Sub<Strength> for Strength {
    type Output = Strength;

    /// Subtract one strength from another, clipping the result to the legal range
    #[inline]
    fn sub(self, rhs: Strength) -> Strength {
        Self::sub(self, rhs)
    }
}

impl ops::AddAssign<Strength> for Strength {
    /// Perform an in-place addition of two strengths, clipping the result to the legal range
    #[inline]
    fn add_assign(&mut self, rhs: Self) {
        *self = *self + rhs;
    }
}

impl ops::SubAssign<Strength> for Strength {
    /// Perform an in-place subtraction of two strengths, clipping the result to the legal range
    #[inline]
    fn sub_assign(&mut self, rhs: Self) {
        *self = *self - rhs;
    }
}

impl ops::Mul<f64> for Strength {
    type Output = Strength;

    /// Multiply a strength by a scalar, clipping the result to the legal range
    #[inline]
    fn mul(self, rhs: f64) -> Strength {
        self.mul_f64(rhs)
    }
}

impl ops::Mul<Strength> for f64 {
    type Output = Strength;

    /// Multiply a scalar by a strength, clipping the result to the legal range
    #[inline]
    fn mul(self, rhs: Strength) -> Strength {
        rhs.mul_f64(self)
    }
}

impl ops::MulAssign<f64> for Strength {
    /// Perform an in-place multiplication of a strength by a scalar, clipping the result to the
    /// legal range
    #[inline]
    fn mul_assign(&mut self, rhs: f64) {
        *self = *self * rhs;
    }
}

impl core::cmp::Ord for Strength {
    #[inline]
    fn cmp(&self, other: &Self) -> core::cmp::Ordering {
        self.0.partial_cmp(&other.0).unwrap()
    }
}

impl core::cmp::PartialOrd for Strength {
    #[inline]
    fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl core::cmp::Eq for Strength {}

#[cfg(test)]
mod tests {
    use rstest::rstest;

    use super::*;

    #[rstest]
    #[case::under(-1.0, Strength::ZERO)]
    #[case::min(0.0, Strength::ZERO)]
    #[case::weak(1.0, Strength::WEAK)]
    #[case::medium(1_000.0, Strength::MEDIUM)]
    #[case::strong(1_000_000.0, Strength::STRONG)]
    #[case::required(1_001_001_000.0, Strength::REQUIRED)]
    #[case::over(1_001_001_001.0, Strength::REQUIRED)]
    fn new(#[case] value: f64, #[case] expected: Strength) {
        let strength = Strength::new(value);
        assert_eq!(strength, expected);
    }

    #[rstest]
    #[case::all_zeroes(0.0, 0.0, 0.0, 1.0, Strength::ZERO)]
    #[case::weak(0.0, 0.0, 1.0, 1.0, Strength::WEAK)]
    #[case::medium(0.0, 1.0, 0.0, 1.0, Strength::MEDIUM)]
    #[case::strong(1.0, 0.0, 0.0, 1.0, Strength::STRONG)]
    #[case::weak_clip(0.0, 0.0, 1000.0, 2.0, Strength::MEDIUM)]
    #[case::medium_clip(0.0, 1000.0, 0.0, 2.0, Strength::STRONG)]
    #[case::strong_clip(1000.0, 0.0, 0.0, 2.0, 1000.0 * Strength::STRONG)]
    #[case::all_non_zero(1.0, 1.0, 1.0, 1.0, Strength::STRONG + Strength::MEDIUM + Strength::WEAK)]
    #[case::multiplier(1.0, 1.0, 1.0, 2.0, 2.0 * (Strength::STRONG + Strength::MEDIUM + Strength::WEAK))]
    #[case::max(1000.0, 1000.0, 1000.0, 1.0, Strength::REQUIRED)]
    fn create(
        #[case] strong: f64,
        #[case] medium: f64,
        #[case] weak: f64,
        #[case] multiplier: f64,
        #[case] expected: Strength,
    ) {
        let strength = Strength::create(strong, medium, weak, multiplier);
        assert_eq!(strength, expected);
    }

    #[rstest]
    #[case::zero_plus_zero(Strength::ZERO, Strength::ZERO, Strength::ZERO)]
    #[case::zero_plus_weak(Strength::ZERO, Strength::WEAK, Strength::WEAK)]
    #[case::weak_plus_zero(Strength::WEAK, Strength::ZERO, Strength::WEAK)]
    #[case::weak_plus_weak(Strength::WEAK, Strength::WEAK, Strength::new(2.0))]
    #[case::weak_plus_medium(Strength::WEAK, Strength::MEDIUM, Strength::new(1001.0))]
    #[case::medium_plus_strong(Strength::MEDIUM, Strength::STRONG, Strength::new(1_001_000.0))]
    #[case::strong_plus_required(Strength::STRONG, Strength::REQUIRED, Strength::REQUIRED)]
    fn add(#[case] lhs: Strength, #[case] rhs: Strength, #[case] expected: Strength) {
        let result = lhs + rhs;
        assert_eq!(result, expected);
    }

    #[rstest]
    #[case::zero_plus_zero(Strength::ZERO, Strength::ZERO, Strength::ZERO)]
    #[case::zero_plus_weak(Strength::ZERO, Strength::WEAK, Strength::WEAK)]
    #[case::weak_plus_zero(Strength::WEAK, Strength::ZERO, Strength::WEAK)]
    #[case::weak_plus_weak(Strength::WEAK, Strength::WEAK, Strength::new(2.0))]
    #[case::weak_plus_medium(Strength::WEAK, Strength::MEDIUM, Strength::new(1001.0))]
    #[case::medium_plus_strong(Strength::MEDIUM, Strength::STRONG, Strength::new(1_001_000.0))]
    #[case::saturate_high(Strength::STRONG, Strength::REQUIRED, Strength::REQUIRED)]
    fn add_assign(#[case] lhs: Strength, #[case] rhs: Strength, #[case] expected: Strength) {
        let mut result = lhs;
        result += rhs;
        assert_eq!(result, expected);
    }

    #[rstest]
    #[case::saturate_low(Strength::ZERO, Strength::WEAK, Strength::ZERO)]
    #[case::zero_minus_zero(Strength::ZERO, Strength::ZERO, Strength::ZERO)]
    #[case::weak_minus_zero(Strength::WEAK, Strength::ZERO, Strength::WEAK)]
    #[case::weak_minus_weak(Strength::WEAK, Strength::WEAK, Strength::ZERO)]
    #[case::medium_minus_weak(Strength::MEDIUM, Strength::WEAK, Strength::new(999.0))]
    #[case::strong_minus_medium(Strength::STRONG, Strength::MEDIUM, Strength::new(999_000.0))]
    #[case::required_minus_strong(
        Strength::REQUIRED,
        Strength::STRONG,
        Strength::new(1_000_001_000.0)
    )]
    #[case::required_minus_required(Strength::REQUIRED, Strength::REQUIRED, Strength::ZERO)]
    fn sub(#[case] lhs: Strength, #[case] rhs: Strength, #[case] expected: Strength) {
        let result = lhs - rhs;
        assert_eq!(result, expected);
    }

    #[rstest]
    #[case::saturate_low(Strength::ZERO, Strength::WEAK, Strength::ZERO)]
    #[case::zero_minus_zero(Strength::ZERO, Strength::ZERO, Strength::ZERO)]
    #[case::weak_minus_zero(Strength::WEAK, Strength::ZERO, Strength::WEAK)]
    #[case::weak_minus_weak(Strength::WEAK, Strength::WEAK, Strength::ZERO)]
    #[case::medium_minus_weak(Strength::MEDIUM, Strength::WEAK, Strength::new(999.0))]
    #[case::strong_minus_medium(Strength::STRONG, Strength::MEDIUM, Strength::new(999_000.0))]
    #[case::required_minus_strong(
        Strength::REQUIRED,
        Strength::STRONG,
        Strength::new(1_000_001_000.0)
    )]
    #[case::required_minus_required(Strength::REQUIRED, Strength::REQUIRED, Strength::ZERO)]
    fn sub_assign(#[case] lhs: Strength, #[case] rhs: Strength, #[case] expected: Strength) {
        let mut result = lhs;
        result -= rhs;
        assert_eq!(result, expected);
    }

    #[rstest]
    #[case::negative(Strength::WEAK, -1.0, Strength::ZERO)]
    #[case::zero_mul_zero(Strength::ZERO, 0.0, Strength::ZERO)]
    #[case::zero_mul_one(Strength::ZERO, 1.0, Strength::ZERO)]
    #[case::weak_mul_zero(Strength::WEAK, 0.0, Strength::ZERO)]
    #[case::weak_mul_one(Strength::WEAK, 1.0, Strength::WEAK)]
    #[case::weak_mul_two(Strength::WEAK, 2.0, Strength::new(2.0))]
    #[case::medium_mul_half(Strength::MEDIUM, 0.5, Strength::new(500.0))]
    #[case::strong_mul_two(Strength::STRONG, 2.0, Strength::new(2_000_000.0))]
    #[case::required_mul_half(Strength::REQUIRED, 0.5, Strength::new(500_500_500.0))]
    fn mul(#[case] lhs: Strength, #[case] rhs: f64, #[case] expected: Strength) {
        let result = lhs * rhs;
        assert_eq!(result, expected);
    }

    #[rstest]
    #[case::negative(Strength::WEAK, -1.0, Strength::ZERO)]
    #[case::zero_mul_zero(Strength::ZERO, 0.0, Strength::ZERO)]
    #[case::zero_mul_one(Strength::ZERO, 1.0, Strength::ZERO)]
    #[case::weak_mul_zero(Strength::WEAK, 0.0, Strength::ZERO)]
    #[case::weak_mul_one(Strength::WEAK, 1.0, Strength::WEAK)]
    #[case::weak_mul_two(Strength::WEAK, 2.0, Strength::new(2.0))]
    #[case::medium_mul_half(Strength::MEDIUM, 0.5, Strength::new(500.0))]
    #[case::strong_mul_two(Strength::STRONG, 2.0, Strength::new(2_000_000.0))]
    #[case::required_mul_half(Strength::REQUIRED, 0.5, Strength::new(500_500_500.0))]
    fn mul_assign(#[case] lhs: Strength, #[case] rhs: f64, #[case] expected: Strength) {
        let mut result = lhs;
        result *= rhs;
        assert_eq!(result, expected);
    }
}