1 // Copyright © 2016–2020 University of Malta
2
3 // This program is free software: you can redistribute it and/or
4 // modify it under the terms of the GNU Lesser General Public License
5 // as published by the Free Software Foundation, either version 3 of
6 // the License, or (at your option) any later version.
7 //
8 // This program is distributed in the hope that it will be useful, but
9 // WITHOUT ANY WARRANTY; without even the implied warranty of
10 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 // General Public License for more details.
12 //
13 // You should have received a copy of the GNU Lesser General Public
14 // License and a copy of the GNU General Public License along with
15 // this program. If not, see <https://www.gnu.org/licenses/>.
16
17 #[cfg(feature = "rand")]
18 use crate::rand::MutRandState;
19 #[cfg(feature = "rational")]
20 use crate::Rational;
21 use crate::{
22 ext::xmpfr::{self, ordering1, raw_round},
23 float::{
24 self,
25 arith::{AddMulIncomplete, MulAddMulIncomplete, MulSubMulIncomplete, SubMulFromIncomplete},
26 OrdFloat, Round, SmallFloat, Special,
27 },
28 misc::{self, UnwrappedAs, UnwrappedCast},
29 ops::{AddAssignRound, AssignRound, DivRounding, NegAssign},
30 Assign,
31 };
32 use az::{Az, CheckedCast, SaturatingCast, WrappingAs};
33 use core::{
34 cmp::Ordering,
35 fmt::{Display, Formatter, Result as FmtResult},
36 i32,
37 marker::PhantomData,
38 mem::{ManuallyDrop, MaybeUninit},
39 num::FpCategory,
40 ops::{Add, AddAssign, Deref},
41 slice, str, u32,
42 };
43 use gmp_mpfr_sys::{
44 gmp::{self, limb_t},
45 mpfr::{self, exp_t, mpfr_t},
46 };
47 use libc::c_char;
48 use std::{
49 error::Error,
50 ffi::{CStr, CString},
51 };
52 #[cfg(feature = "complex")]
53 use {crate::complex::big::BorrowComplex, gmp_mpfr_sys::mpc::mpc_t};
54 #[cfg(feature = "integer")]
55 use {
56 crate::{integer::big::BorrowInteger, Integer},
57 gmp_mpfr_sys::{gmp::mpz_t, mpfr::prec_t},
58 };
59
60 /**
61 A multi-precision floating-point number with arbitrarily large
62 precision and correct rounding
63
64 The precision has to be set during construction. The rounding method
65 of the required operations can be specified, and the direction of the
66 rounding is returned.
67
68 # Examples
69
70 ```rust
71 use core::cmp::Ordering;
72 use rug::{float::Round, ops::DivAssignRound, Float};
73 // A precision of 32 significant bits is specified here.
74 // (The primitive `f32` has a precision of 24 and
75 // `f64` has a precision of 53.)
76 let mut two_thirds_down = Float::with_val(32, 2.0);
77 let dir = two_thirds_down.div_assign_round(3.0, Round::Down);
78 // since we rounded down, direction is Ordering::Less
79 assert_eq!(dir, Ordering::Less);
80 let mut two_thirds_up = Float::with_val(32, 2.0);
81 let dir = two_thirds_up.div_assign_round(3.0, Round::Up);
82 // since we rounded up, direction is Ordering::Greater
83 assert_eq!(dir, Ordering::Greater);
84 let diff_expected = 2.0_f64.powi(-32);
85 let diff = two_thirds_up - two_thirds_down;
86 assert_eq!(diff, diff_expected);
87 ```
88
89 Operations on two borrowed `Float` numbers result in an
90 [incomplete-computation value][icv] that has to be assigned to a new
91 `Float` value.
92
93 ```rust
94 use rug::Float;
95 let a = Float::with_val(53, 10.5);
96 let b = Float::with_val(53, -1.25);
97 let a_b_ref = &a + &b;
98 let a_b = Float::with_val(53, a_b_ref);
99 assert_eq!(a_b, 9.25);
100 ```
101
102 As a special case, when an [incomplete-computation value][icv] is
103 obtained from multiplying two `Float` references, it can be added to
104 or subtracted from another `Float` (or reference). This will result in
105 a fused multiply-accumulate operation, with only one rounding
106 operation taking place.
107
108 ```rust
109 use rug::Float;
110 // Use only 4 bits of precision for demonstration purposes.
111 // 24 in binary is 11000.
112 let a = Float::with_val(4, 24);
113 // 1.5 in binary is 1.1.
114 let mul1 = Float::with_val(4, 1.5);
115 // −13 in binary is −1101.
116 let mul2 = Float::with_val(4, -13);
117 // 24 + 1.5 × −13 = 4.5
118 let add = Float::with_val(4, &a + &mul1 * &mul2);
119 assert_eq!(add, 4.5);
120 // 24 − 1.5 × −13 = 43.5, rounded to 44 using four bits of precision.
121 let sub = a - &mul1 * &mul2;
122 assert_eq!(sub, 44);
123
124 // With separate addition and multiplication:
125 let a = Float::with_val(4, 24);
126 // No borrows, so multiplication is computed immediately.
127 // 1.5 × −13 = −19.5 (binary −10011.1), rounded to −20.
128 let separate_add = a + mul1 * mul2;
129 assert_eq!(separate_add, 4);
130 ```
131
132 The [incomplete-computation value][icv] obtained from multiplying two
133 `Float` references can also be added to or subtracted from another
134 such [incomplete-computation value][icv], so that two muliplications
135 and an addition are fused with only one rounding operation taking
136 place.
137
138 ```rust
139 use rug::Float;
140 let a = Float::with_val(53, 24);
141 let b = Float::with_val(53, 1.5);
142 let c = Float::with_val(53, 12);
143 let d = Float::with_val(53, 2);
144 // 24 × 1.5 + 12 × 2 = 60
145 let add = Float::with_val(53, &a * &b + &c * &d);
146 assert_eq!(add, 60);
147 // 24 × 1.5 − 12 × 2 = 12
148 let sub = Float::with_val(53, &a * &b - &c * &d);
149 assert_eq!(sub, 12);
150 ```
151
152 The `Float` type supports various functions. Most methods have four
153 versions:
154
155 1. The first method consumes the operand and rounds the returned
156 `Float` to the [nearest][`Nearest`] representable value.
157 2. The second method has a “`_mut`” suffix, mutates the operand and
158 rounds it the nearest representable value.
159 3. The third method has a “`_round`” suffix, mutates the operand,
160 applies the specified [rounding method][`Round`], and returns the
161 rounding direction:
162 * <code>[Ordering][`Ordering`]::[Less][`Less`]</code> if the
163 stored value is less than the exact result,
164 * <code>[Ordering][`Ordering`]::[Equal][`Equal`]</code> if the
165 stored value is equal to the exact result,
166 * <code>[Ordering][`Ordering`]::[Greater][`Greater`]</code> if
167 the stored value is greater than the exact result.
168 4. The fourth method has a “`_ref`” suffix and borrows the operand.
169 The returned item is an [incomplete-computation value][icv] that
170 can be assigned to a `Float`; the rounding method is selected
171 during the assignment.
172
173 ```rust
174 use core::cmp::Ordering;
175 use rug::{float::Round, Float};
176 let expected = 0.9490_f64;
177
178 // 1. consume the operand, round to nearest
179 let a = Float::with_val(53, 1.25);
180 let sin_a = a.sin();
181 assert!((sin_a - expected).abs() < 0.0001);
182
183 // 2. mutate the operand, round to nearest
184 let mut b = Float::with_val(53, 1.25);
185 b.sin_mut();
186 assert!((b - expected).abs() < 0.0001);
187
188 // 3. mutate the operand, apply specified rounding
189 let mut c = Float::with_val(4, 1.25);
190 // using 4 significant bits, 0.9490 is rounded down to 0.9375
191 let dir = c.sin_round(Round::Nearest);
192 assert_eq!(c, 0.9375);
193 assert_eq!(dir, Ordering::Less);
194
195 // 4. borrow the operand
196 let d = Float::with_val(53, 1.25);
197 let r = d.sin_ref();
198 let sin_d = Float::with_val(53, r);
199 assert!((sin_d - expected).abs() < 0.0001);
200 // d was not consumed
201 assert_eq!(d, 1.25);
202 ```
203
204 The following example is a translation of the [MPFR sample] found on
205 the MPFR website. The program computes a lower bound on 1 + 1/1! +
206 1/2! + … + 1/100! using 200-bit precision. The program writes:
207
208 `Sum is 2.7182818284590452353602874713526624977572470936999595749669131`
209
210 ```rust
211 use rug::{
212 float::{self, FreeCache, Round},
213 ops::{AddAssignRound, AssignRound, MulAssignRound},
214 Float,
215 };
216
217 let mut t = Float::with_val(200, 1.0);
218 let mut s = Float::with_val(200, 1.0);
219 let mut u = Float::new(200);
220 for i in 1..=100_u32 {
221 // multiply t by i in place, round towards +∞
222 t.mul_assign_round(i, Round::Up);
223 // set u to 1/t, round towards −∞
224 u.assign_round(t.recip_ref(), Round::Down);
225 // increase s by u in place, round towards −∞
226 s.add_assign_round(&u, Round::Down);
227 }
228 // `None` means the number of printed digits depends on the precision
229 let sr = s.to_string_radix_round(10, None, Round::Down);
230 println!("Sum is {}", sr);
231 # let good = "2.7182818284590452353602874713526624977572470936999595749669131";
232 # assert_eq!(sr, good);
233
234 float::free_cache(FreeCache::All);
235 ```
236
237 [MPFR sample]: https://www.mpfr.org/sample.html
238 [`Equal`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html#variant.Equal
239 [`Greater`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html#variant.Greater
240 [`Less`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html#variant.Less
241 [`Nearest`]: float/enum.Round.html#variant.Nearest
242 [`Ordering`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html
243 [`Round`]: float/enum.Round.html
244 [icv]: index.html#incomplete-computation-values
245 */
246 #[repr(transparent)]
247 pub struct Float {
248 inner: mpfr_t,
249 }
250
251 impl Float {
252 #[inline]
inner(&self) -> &mpfr_t253 pub(crate) fn inner(&self) -> &mpfr_t {
254 &self.inner
255 }
256 #[inline]
inner_mut(&mut self) -> &mut mpfr_t257 pub(crate) unsafe fn inner_mut(&mut self) -> &mut mpfr_t {
258 &mut self.inner
259 }
260 #[inline]
inner_data(&self) -> &[limb_t]261 pub(crate) fn inner_data(&self) -> &[limb_t] {
262 if self.is_normal() {
263 let prec = self.inner.prec.unwrapped_as::<usize>();
264 let limbs = prec.div_ceil(gmp::LIMB_BITS.az::<usize>());
265 unsafe { slice::from_raw_parts(self.inner.d.as_ptr(), limbs) }
266 } else {
267 &[]
268 }
269 }
270 }
271
272 static_assert_same_layout!(Float, mpfr_t);
273 static_assert_same_layout!(BorrowFloat<'_>, mpfr_t);
274
275 static_assert_same_size!(Float, Option<Float>);
276
277 macro_rules! ref_math_op0_float {
278 ($($rest:tt)*) => {
279 ref_math_op0_round! {
280 Float, Round, Round::Nearest, Ordering;
281 $($rest)*
282 }
283 };
284 }
285
286 macro_rules! ref_math_op1_float {
287 ($($rest:tt)*) => {
288 ref_math_op1_round! {
289 Float, Round, Round::Nearest, Ordering;
290 $($rest)*
291 }
292 };
293 }
294
295 macro_rules! ref_math_op1_2_float {
296 ($($rest:tt)*) => {
297 ref_math_op1_2_round! {
298 Float, Round, Round::Nearest, (Ordering, Ordering);
299 $($rest)*
300 }
301 };
302 }
303
304 macro_rules! ref_math_op2_float {
305 ($($rest:tt)*) => {
306 ref_math_op2_round! {
307 Float, Round, Round::Nearest, Ordering;
308 $($rest)*
309 }
310 };
311 }
312
313 impl Float {
314 /// Create a new [`Float`] with the specified precision and with
315 /// value 0.
316 ///
317 /// # Panics
318 ///
319 /// Panics if `prec` is out of the allowed range.
320 ///
321 /// # Examples
322 ///
323 /// ```rust
324 /// use rug::Float;
325 /// let f = Float::new(53);
326 /// assert_eq!(f.prec(), 53);
327 /// assert_eq!(f, 0);
328 /// ```
329 ///
330 /// [`Float`]: struct.Float.html
331 #[inline]
new(prec: u32) -> Self332 pub fn new(prec: u32) -> Self {
333 Self::with_val(prec, Special::Zero)
334 }
335
336 /// Create a new [`Float`] with the specified precision and with
337 /// the given value, rounding to the nearest.
338 ///
339 /// # Panics
340 ///
341 /// Panics if `prec` is out of the allowed range.
342 ///
343 /// # Examples
344 ///
345 /// ```rust
346 /// use rug::Float;
347 /// let f = Float::with_val(53, 1.3);
348 /// assert_eq!(f.prec(), 53);
349 /// assert_eq!(f, 1.3);
350 /// ```
351 ///
352 /// [`Float`]: struct.Float.html
353 #[inline]
with_val<T>(prec: u32, val: T) -> Self where Float: Assign<T>,354 pub fn with_val<T>(prec: u32, val: T) -> Self
355 where
356 Float: Assign<T>,
357 {
358 let mut ret = Float::new_nan(prec);
359 ret.assign(val);
360 ret
361 }
362
363 /// Create a new [`Float`] with the specified precision and with
364 /// the given value, applying the specified rounding method.
365 ///
366 /// # Panics
367 ///
368 /// Panics if `prec` is out of the allowed range.
369 ///
370 /// # Examples
371 ///
372 /// ```rust
373 /// use core::cmp::Ordering;
374 /// use rug::{float::Round, Float};
375 /// let (f1, dir) = Float::with_val_round(4, 3.3, Round::Nearest);
376 /// // 3.3 with precision 4 is rounded down to 3.25
377 /// assert_eq!(f1.prec(), 4);
378 /// assert_eq!(f1, 3.25);
379 /// assert_eq!(dir, Ordering::Less);
380 /// let (f2, dir) = Float::with_val_round(4, 3.3, Round::Up);
381 /// // 3.3 rounded up to 3.5
382 /// assert_eq!(f2.prec(), 4);
383 /// assert_eq!(f2, 3.5);
384 /// assert_eq!(dir, Ordering::Greater);
385 /// ```
386 ///
387 /// [`Float`]: struct.Float.html
388 #[inline]
with_val_round<T>(prec: u32, val: T, round: Round) -> (Self, Ordering) where Self: AssignRound<T, Round = Round, Ordering = Ordering>,389 pub fn with_val_round<T>(prec: u32, val: T, round: Round) -> (Self, Ordering)
390 where
391 Self: AssignRound<T, Round = Round, Ordering = Ordering>,
392 {
393 let mut ret = Float::new_nan(prec);
394 let ord = ret.assign_round(val, round);
395 (ret, ord)
396 }
397
398 #[inline]
new_nan(prec: u32) -> Self399 pub(crate) fn new_nan(prec: u32) -> Self {
400 assert!(
401 prec >= float::prec_min() && prec <= float::prec_max(),
402 "precision out of range"
403 );
404 let mut ret = MaybeUninit::uninit();
405 xmpfr::write_new_nan(&mut ret, prec.unwrapped_cast());
406 // Safety: write_new_nan initializes ret.
407 unsafe { ret.assume_init() }
408 }
409
410 /// Returns the precision.
411 ///
412 /// # Examples
413 ///
414 /// ```rust
415 /// use rug::Float;
416 /// let f = Float::new(53);
417 /// assert_eq!(f.prec(), 53);
418 /// ```
419 #[inline]
prec(&self) -> u32420 pub fn prec(&self) -> u32 {
421 xmpfr::get_prec(self).unwrapped_cast()
422 }
423
424 /// Sets the precision, rounding to the nearest.
425 ///
426 /// # Panics
427 ///
428 /// Panics if `prec` is out of the allowed range.
429 ///
430 /// # Examples
431 ///
432 /// ```rust
433 /// use rug::Float;
434 /// // 16.25 has seven significant bits (binary 10000.01)
435 /// let mut f = Float::with_val(53, 16.25);
436 /// f.set_prec(5);
437 /// assert_eq!(f, 16);
438 /// assert_eq!(f.prec(), 5);
439 /// ```
440 #[inline]
set_prec(&mut self, prec: u32)441 pub fn set_prec(&mut self, prec: u32) {
442 self.set_prec_round(prec, Round::Nearest);
443 }
444
445 /// Sets the precision, applying the specified rounding method.
446 ///
447 /// # Panics
448 ///
449 /// Panics if `prec` is out of the allowed range.
450 ///
451 /// # Examples
452 ///
453 /// ```rust
454 /// use core::cmp::Ordering;
455 /// use rug::{float::Round, Float};
456 /// // 16.25 has seven significant bits (binary 10000.01)
457 /// let mut f = Float::with_val(53, 16.25);
458 /// let dir = f.set_prec_round(5, Round::Up);
459 /// assert_eq!(f, 17);
460 /// assert_eq!(dir, Ordering::Greater);
461 /// assert_eq!(f.prec(), 5);
462 /// ```
463 #[inline]
set_prec_round(&mut self, prec: u32, round: Round) -> Ordering464 pub fn set_prec_round(&mut self, prec: u32, round: Round) -> Ordering {
465 assert!(
466 prec >= float::prec_min() && prec <= float::prec_max(),
467 "precision out of range"
468 );
469 xmpfr::prec_round(self, prec.unwrapped_cast(), round)
470 }
471
472 /// Creates a [`Float`] from an initialized
473 /// [MPFR floating-point number][`mpfr_t`].
474 ///
475 /// # Safety
476 ///
477 /// * The value must be initialized.
478 /// * The [`mpfr_t`] type can be considered as a kind of
479 /// pointer, so there can be multiple copies of it. Since this
480 /// function takes over ownership, no other copies of the
481 /// passed value should exist.
482 ///
483 /// # Examples
484 ///
485 /// ```rust
486 /// use core::mem::MaybeUninit;
487 /// use gmp_mpfr_sys::mpfr::{self, rnd_t};
488 /// use rug::Float;
489 /// let f = unsafe {
490 /// let mut m = MaybeUninit::uninit();
491 /// mpfr::init2(m.as_mut_ptr(), 53);
492 /// let mut m = m.assume_init();
493 /// mpfr::set_d(&mut m, -14.5, rnd_t::RNDN);
494 /// // m is initialized and unique
495 /// Float::from_raw(m)
496 /// };
497 /// assert_eq!(f, -14.5);
498 /// // since f is a Float now, deallocation is automatic
499 /// ```
500 ///
501 /// [`Float`]: struct.Float.html
502 /// [`mpfr_t`]: https://docs.rs/gmp-mpfr-sys/~1.4/gmp_mpfr_sys/mpfr/struct.mpfr_t.html
503 #[inline]
from_raw(raw: mpfr_t) -> Self504 pub unsafe fn from_raw(raw: mpfr_t) -> Self {
505 Float { inner: raw }
506 }
507
508 /// Converts a [`Float`] into an
509 /// [MPFR floating-point number][`mpfr_t`].
510 ///
511 /// The returned object should be freed to avoid memory leaks.
512 ///
513 /// # Examples
514 ///
515 /// ```rust
516 /// use gmp_mpfr_sys::mpfr::{self, rnd_t};
517 /// use rug::Float;
518 /// let f = Float::with_val(53, -14.5);
519 /// let mut m = f.into_raw();
520 /// unsafe {
521 /// let d = mpfr::get_d(&m, rnd_t::RNDN);
522 /// assert_eq!(d, -14.5);
523 /// // free object to prevent memory leak
524 /// mpfr::clear(&mut m);
525 /// }
526 /// ```
527 ///
528 /// [`Float`]: struct.Float.html
529 /// [`mpfr_t`]: https://docs.rs/gmp-mpfr-sys/~1.4/gmp_mpfr_sys/mpfr/struct.mpfr_t.html
530 #[inline]
into_raw(self) -> mpfr_t531 pub fn into_raw(self) -> mpfr_t {
532 let m = ManuallyDrop::new(self);
533 m.inner
534 }
535
536 /// Returns a pointer to the inner
537 /// [MPFR floating-point number][`mpfr_t`].
538 ///
539 /// The returned pointer will be valid for as long as `self` is
540 /// valid.
541 ///
542 /// # Examples
543 ///
544 /// ```rust
545 /// use gmp_mpfr_sys::mpfr::{self, rnd_t};
546 /// use rug::Float;
547 /// let f = Float::with_val(53, -14.5);
548 /// let m_ptr = f.as_raw();
549 /// unsafe {
550 /// let d = mpfr::get_d(m_ptr, rnd_t::RNDN);
551 /// assert_eq!(d, -14.5);
552 /// }
553 /// // f is still valid
554 /// assert_eq!(f, -14.5);
555 /// ```
556 ///
557 /// [`mpfr_t`]: https://docs.rs/gmp-mpfr-sys/~1.4/gmp_mpfr_sys/mpfr/struct.mpfr_t.html
558 #[inline]
as_raw(&self) -> *const mpfr_t559 pub fn as_raw(&self) -> *const mpfr_t {
560 &self.inner
561 }
562
563 /// Returns an unsafe mutable pointer to the inner
564 /// [MPFR floating-point number][`mpfr_t`].
565 ///
566 /// The returned pointer will be valid for as long as `self` is
567 /// valid.
568 ///
569 /// # Examples
570 ///
571 /// ```rust
572 /// use gmp_mpfr_sys::mpfr::{self, rnd_t};
573 /// use rug::Float;
574 /// let mut f = Float::with_val(53, -14.5);
575 /// let m_ptr = f.as_raw_mut();
576 /// unsafe {
577 /// mpfr::add_ui(m_ptr, m_ptr, 10, rnd_t::RNDN);
578 /// }
579 /// assert_eq!(f, -4.5);
580 /// ```
581 ///
582 /// [`mpfr_t`]: https://docs.rs/gmp-mpfr-sys/~1.4/gmp_mpfr_sys/mpfr/struct.mpfr_t.html
583 #[inline]
as_raw_mut(&mut self) -> *mut mpfr_t584 pub fn as_raw_mut(&mut self) -> *mut mpfr_t {
585 &mut self.inner
586 }
587
588 /// Parses a decimal string slice (<code>&[str]</code>) or
589 /// byte slice
590 /// (<code>[&\[][slice][u8][`u8`][\]][slice]</code>) into a
591 /// [`Float`].
592 ///
593 /// <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
594 /// is implemented with the unwrapped returned
595 /// [incomplete-computation value][icv] as `Src`.
596 ///
597 /// The string can start with an optional minus or plus sign and
598 /// must then have one or more significant digits with an optional
599 /// decimal point. This can optionally be followed by an exponent;
600 /// the exponent can start with a separator “`e`”, “`E`” or “`@`”,
601 /// and is followed by an optional minus or plus sign and by one
602 /// or more decimal digits.
603 ///
604 /// Alternatively, the string can indicate the special values
605 /// infinity or NaN. Infinity can be represented as `"inf"`,
606 /// `"infinity"`, `"@inf@"` or `"@infinity@"`,and NaN can be
607 /// represented as `"nan"` or `"@nan@"`. All of these special
608 /// representations are case insensitive. The NaN representation
609 /// may also include a possibly-empty string of ASCII letters,
610 /// digits and underscores enclosed in brackets, for example
611 /// `"nan(char_sequence_1)"`.
612 ///
613 /// ASCII whitespace is ignored everywhere in the string except in
614 /// the substrings specified above for special values; for example
615 /// `" @inf@ "` is accepted but `"@ inf @"` is not. Underscores
616 /// are ignored anywhere in digit strings except before the first
617 /// digit and between the exponent separator and the first digit
618 /// of the exponent.
619 ///
620 /// # Examples
621 ///
622 /// ```rust
623 /// use rug::Float;
624 ///
625 /// let valid = Float::parse("12.25e-4");
626 /// let f = Float::with_val(53, valid.unwrap());
627 /// assert_eq!(f, 12.25e-4);
628 ///
629 /// let invalid = Float::parse(".e-4");
630 /// assert!(invalid.is_err());
631 /// ```
632 ///
633 /// [`AssignRound`]: ops/trait.AssignRound.html
634 /// [`Float`]: struct.Float.html
635 /// [`u8`]: https://doc.rust-lang.org/nightly/std/primitive.u8.html
636 /// [icv]: index.html#incomplete-computation-values
637 /// [slice]: https://doc.rust-lang.org/nightly/std/primitive.slice.html
638 /// [str]: https://doc.rust-lang.org/nightly/std/primitive.str.html
639 #[inline]
parse<S: AsRef<[u8]>>(src: S) -> Result<ParseIncomplete, ParseFloatError>640 pub fn parse<S: AsRef<[u8]>>(src: S) -> Result<ParseIncomplete, ParseFloatError> {
641 parse(src.as_ref(), 10)
642 }
643
644 /// Parses a string slice (<code>&[str]</code>) or byte slice
645 /// (<code>[&\[][slice][u8][`u8`][\]][slice]</code>) into a
646 /// [`Float`].
647 ///
648 /// <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
649 /// is implemented with the unwrapped returned
650 /// [incomplete-computation value][icv] as `Src`.
651 ///
652 /// The string can start with an optional minus or plus sign and
653 /// must then have one or more significant digits with an optional
654 /// point. This can optionally be followed by an exponent; the
655 /// exponent can start with a separator “`e`” or “`E`” if the
656 /// radix ≤ 10, or “`@`” for any radix, and is followed by an
657 /// optional minus or plus sign and by one or more decimal digits.
658 ///
659 /// Alternatively, the string can indicate the special values
660 /// infinity or NaN. If the radix ≤ 10, infinity can be
661 /// represented as `"inf"` or `"infinity"`, and NaN can be
662 /// represented as `"nan"`. For any radix, infinity can also be
663 /// represented as `"@inf@"` or `"@infinity@"`, and NaN can be
664 /// represented as `"@nan@"`. All of these special representations
665 /// are case insensitive. The NaN representation may also include
666 /// a possibly-empty string of ASCII letters, digits and
667 /// underscores enclosed in brackets, for example
668 /// `"nan(char_sequence_1)"`.
669 ///
670 /// ASCII whitespace is ignored everywhere in the string except in
671 /// the substrings specified above for special values; for example
672 /// `" @inf@ "` is accepted but `"@ inf @"` is not. Underscores
673 /// are ignored anywhere in digit strings except before the first
674 /// digit and between the exponent separator and the first digit
675 /// of the exponent.
676 ///
677 /// # Panics
678 ///
679 /// Panics if `radix` is less than 2 or greater than 36.
680 ///
681 /// # Examples
682 ///
683 /// ```rust
684 /// use rug::Float;
685 ///
686 /// let valid1 = Float::parse_radix("12.23e-4", 4);
687 /// let f1 = Float::with_val(53, valid1.unwrap());
688 /// assert_eq!(f1, (2.0 + 4.0 * 1.0 + 0.25 * (2.0 + 0.25 * 3.0)) / 256.0);
689 /// let valid2 = Float::parse_radix("12.yz@2", 36);
690 /// let f2 = Float::with_val(53, valid2.unwrap());
691 /// assert_eq!(f2, 35 + 36 * (34 + 36 * (2 + 36 * 1)));
692 ///
693 /// let invalid = Float::parse_radix("ffe-2", 16);
694 /// assert!(invalid.is_err());
695 /// ```
696 ///
697 /// [`AssignRound`]: ops/trait.AssignRound.html
698 /// [`Float`]: struct.Float.html
699 /// [`u8`]: https://doc.rust-lang.org/nightly/std/primitive.u8.html
700 /// [icv]: index.html#incomplete-computation-values
701 /// [slice]: https://doc.rust-lang.org/nightly/std/primitive.slice.html
702 /// [str]: https://doc.rust-lang.org/nightly/std/primitive.str.html
703 #[inline]
parse_radix<S: AsRef<[u8]>>( src: S, radix: i32, ) -> Result<ParseIncomplete, ParseFloatError>704 pub fn parse_radix<S: AsRef<[u8]>>(
705 src: S,
706 radix: i32,
707 ) -> Result<ParseIncomplete, ParseFloatError> {
708 parse(src.as_ref(), radix)
709 }
710
711 #[cfg(feature = "integer")]
712 /// If the value is a [finite number][`is_finite`], converts it to
713 /// an [`Integer`] rounding to the nearest.
714 ///
715 /// This conversion can also be performed using
716 /// * <code>(&float).[checked\_as][`checked_as`]::<[Integer][`Integer`]>()</code>
717 /// * <code>float.[borrow][`borrow`]().[checked\_as][`checked_as`]::<[Integer][`Integer`]>()</code>
718 ///
719 /// # Examples
720 ///
721 /// ```rust
722 /// use rug::Float;
723 /// let f = Float::with_val(53, 13.7);
724 /// let i = match f.to_integer() {
725 /// Some(i) => i,
726 /// None => unreachable!(),
727 /// };
728 /// assert_eq!(i, 14);
729 /// ```
730 ///
731 /// [`Integer`]: struct.Integer.html
732 /// [`borrow`]: https://doc.rust-lang.org/nightly/core/borrow/trait.Borrow.html#tymethod.borrow
733 /// [`checked_as`]: https://docs.rs/az/1/az/trait.CheckedAs.html#tymethod.checked_as
734 /// [`is_finite`]: #method.is_finite
735 #[inline]
to_integer(&self) -> Option<Integer>736 pub fn to_integer(&self) -> Option<Integer> {
737 self.checked_cast()
738 }
739
740 #[cfg(feature = "integer")]
741 /// If the value is a [finite number][`is_finite`], converts it to
742 /// an [`Integer`] applying the specified rounding method.
743 ///
744 /// # Examples
745 ///
746 /// ```rust
747 /// use core::cmp::Ordering;
748 /// use rug::{float::Round, Float};
749 /// let f = Float::with_val(53, 13.7);
750 /// let (i, dir) = match f.to_integer_round(Round::Down) {
751 /// Some(i_dir) => i_dir,
752 /// None => unreachable!(),
753 /// };
754 /// assert_eq!(i, 13);
755 /// assert_eq!(dir, Ordering::Less);
756 /// ```
757 ///
758 /// [`Integer`]: struct.Integer.html
759 /// [`is_finite`]: #method.is_finite
760 #[inline]
to_integer_round(&self, round: Round) -> Option<(Integer, Ordering)>761 pub fn to_integer_round(&self, round: Round) -> Option<(Integer, Ordering)> {
762 if !self.is_finite() {
763 return None;
764 }
765 let mut i = Integer::new();
766 let ret = unsafe { mpfr::get_z(i.as_raw_mut(), self.as_raw(), raw_round(round)) };
767 Some((i, ordering1(ret)))
768 }
769
770 #[cfg(feature = "integer")]
771 /// If the value is a [finite number][`is_finite`], returns an
772 /// [`Integer`] and exponent such that it is exactly equal to the
773 /// integer multiplied by two raised to the power of the exponent.
774 ///
775 /// # Examples
776 ///
777 /// ```rust
778 /// use rug::{float::Special, Assign, Float};
779 /// let mut float = Float::with_val(16, 6.5);
780 /// // 6.5 in binary is 110.1
781 /// // Since the precision is 16 bits, this becomes
782 /// // 1101_0000_0000_0000 times two to the power of −12
783 /// let (int, exp) = float.to_integer_exp().unwrap();
784 /// assert_eq!(int, 0b1101_0000_0000_0000);
785 /// assert_eq!(exp, -13);
786 ///
787 /// float.assign(0);
788 /// let (zero, _) = float.to_integer_exp().unwrap();
789 /// assert_eq!(zero, 0);
790 ///
791 /// float.assign(Special::Infinity);
792 /// assert!(float.to_integer_exp().is_none());
793 /// ```
794 ///
795 /// [`Integer`]: struct.Integer.html
796 /// [`is_finite`]: #method.is_finite
797 #[inline]
to_integer_exp(&self) -> Option<(Integer, i32)>798 pub fn to_integer_exp(&self) -> Option<(Integer, i32)> {
799 if !self.is_finite() {
800 return None;
801 }
802 let mut i = Integer::new();
803 let exp = unsafe { mpfr::get_z_2exp(i.as_raw_mut(), self.as_raw()) };
804 Some((i, exp.unwrapped_cast()))
805 }
806
807 #[cfg(feature = "rational")]
808 /// If the value is a [finite number][`is_finite`], returns a
809 /// [`Rational`] number preserving all the precision of the value.
810 ///
811 /// This conversion can also be performed using
812 /// * <code>[Rational][`Rational`]::[try_from][`try_from`](&float)</code>
813 /// * <code>[Rational][`Rational`]::[try_from][`try_from`](float)</code>
814 /// * <code>(&float).[checked\_as][`checked_as`]::<[Rational][`Rational`]>()</code>
815 /// * <code>float.[borrow][`borrow`]().[checked\_as][`checked_as`]::<[Rational][`Rational`]>()</code>
816 ///
817 ///
818 /// # Examples
819 ///
820 /// ```rust
821 /// use core::{cmp::Ordering, str::FromStr};
822 /// use rug::{float::Round, Float, Rational};
823 ///
824 /// // Consider the number 123,456,789 / 10,000,000,000.
825 /// let parse = Float::parse("0.0123456789").unwrap();
826 /// let (f, f_rounding) = Float::with_val_round(35, parse, Round::Down);
827 /// assert_eq!(f_rounding, Ordering::Less);
828 /// let r = Rational::from_str("123456789/10000000000").unwrap();
829 /// // Set fr to the value of f exactly.
830 /// let fr = f.to_rational().unwrap();
831 /// // Since f == fr and f was rounded down, r != fr.
832 /// assert_ne!(r, fr);
833 /// let (frf, frf_rounding) = Float::with_val_round(35, &fr, Round::Down);
834 /// assert_eq!(frf_rounding, Ordering::Equal);
835 /// assert_eq!(frf, f);
836 /// assert_eq!(format!("{:.9}", frf), "1.23456789e-2");
837 /// ```
838 ///
839 /// In the following example, the [`Float`] values can be
840 /// represented exactly.
841 ///
842 /// ```rust
843 /// use rug::Float;
844 ///
845 /// let large_f = Float::with_val(16, 6.5);
846 /// let large_r = large_f.to_rational().unwrap();
847 /// let small_f = Float::with_val(16, -0.125);
848 /// let small_r = small_f.to_rational().unwrap();
849 ///
850 /// assert_eq!(*large_r.numer(), 13);
851 /// assert_eq!(*large_r.denom(), 2);
852 /// assert_eq!(*small_r.numer(), -1);
853 /// assert_eq!(*small_r.denom(), 8);
854 /// ```
855 ///
856 /// [`Float`]: struct.Float.html
857 /// [`Rational`]: struct.Rational.html
858 /// [`borrow`]: https://doc.rust-lang.org/nightly/core/borrow/trait.Borrow.html#tymethod.borrow
859 /// [`checked_as`]: https://docs.rs/az/1/az/trait.CheckedAs.html#tymethod.checked_as
860 /// [`is_finite`]: #method.is_finite
861 /// [`try_from`]: https://doc.rust-lang.org/nightly/core/convert/trait.TryFrom.html#tymethod.try_from
862 #[inline]
to_rational(&self) -> Option<Rational>863 pub fn to_rational(&self) -> Option<Rational> {
864 self.checked_cast()
865 }
866
867 /// Converts to an [`i32`], rounding to the nearest.
868 ///
869 /// If the value is too small or too large for the target type,
870 /// the minimum or maximum value allowed is returned.
871 /// If the value is a NaN, [`None`] is returned.
872 ///
873 /// # Examples
874 ///
875 /// ```rust
876 /// use core::{i32, u32};
877 /// use rug::{Assign, Float};
878 /// let mut f = Float::with_val(53, -13.7);
879 /// assert_eq!(f.to_i32_saturating(), Some(-14));
880 /// f.assign(-1e40);
881 /// assert_eq!(f.to_i32_saturating(), Some(i32::MIN));
882 /// f.assign(u32::MAX);
883 /// assert_eq!(f.to_i32_saturating(), Some(i32::MAX));
884 /// ```
885 ///
886 /// [`None`]: https://doc.rust-lang.org/nightly/core/option/enum.Option.html#variant.None
887 /// [`i32`]: https://doc.rust-lang.org/nightly/std/primitive.i32.html
888 #[inline]
to_i32_saturating(&self) -> Option<i32>889 pub fn to_i32_saturating(&self) -> Option<i32> {
890 self.to_i32_saturating_round(Round::Nearest)
891 }
892
893 /// Converts to an [`i32`], applying the specified rounding method.
894 ///
895 /// If the value is too small or too large for the target type,
896 /// the minimum or maximum value allowed is returned.
897 /// If the value is a NaN, [`None`] is returned.
898 ///
899 /// # Examples
900 ///
901 /// ```rust
902 /// use rug::{float::Round, Float};
903 /// let f = Float::with_val(53, -13.7);
904 /// assert_eq!(f.to_i32_saturating_round(Round::Up), Some(-13));
905 /// ```
906 ///
907 /// [`None`]: https://doc.rust-lang.org/nightly/core/option/enum.Option.html#variant.None
908 /// [`i32`]: https://doc.rust-lang.org/nightly/std/primitive.i32.html
909 #[inline]
to_i32_saturating_round(&self, round: Round) -> Option<i32>910 pub fn to_i32_saturating_round(&self, round: Round) -> Option<i32> {
911 if self.is_nan() {
912 None
913 } else {
914 Some(xmpfr::get_si(self, round).saturating_cast())
915 }
916 }
917
918 /// Converts to a [`u32`], rounding to the nearest.
919 ///
920 /// If the value is too small or too large for the target type,
921 /// the minimum or maximum value allowed is returned.
922 /// If the value is a NaN, [`None`] is returned.
923 ///
924 /// # Examples
925 ///
926 /// ```rust
927 /// use core::u32;
928 /// use rug::{Assign, Float};
929 /// let mut f = Float::with_val(53, 13.7);
930 /// assert_eq!(f.to_u32_saturating(), Some(14));
931 /// f.assign(-1);
932 /// assert_eq!(f.to_u32_saturating(), Some(0));
933 /// f.assign(1e40);
934 /// assert_eq!(f.to_u32_saturating(), Some(u32::MAX));
935 /// ```
936 ///
937 /// [`None`]: https://doc.rust-lang.org/nightly/core/option/enum.Option.html#variant.None
938 /// [`u32`]: https://doc.rust-lang.org/nightly/std/primitive.u32.html
939 #[inline]
to_u32_saturating(&self) -> Option<u32>940 pub fn to_u32_saturating(&self) -> Option<u32> {
941 self.to_u32_saturating_round(Round::Nearest)
942 }
943
944 /// Converts to a [`u32`], applying the specified rounding method.
945 ///
946 /// If the value is too small or too large for the target type,
947 /// the minimum or maximum value allowed is returned.
948 /// If the value is a NaN, [`None`] is returned.
949 ///
950 /// # Examples
951 ///
952 /// ```rust
953 /// use rug::{float::Round, Float};
954 /// let f = Float::with_val(53, 13.7);
955 /// assert_eq!(f.to_u32_saturating_round(Round::Down), Some(13));
956 /// ```
957 ///
958 /// [`None`]: https://doc.rust-lang.org/nightly/core/option/enum.Option.html#variant.None
959 /// [`u32`]: https://doc.rust-lang.org/nightly/std/primitive.u32.html
960 #[inline]
to_u32_saturating_round(&self, round: Round) -> Option<u32>961 pub fn to_u32_saturating_round(&self, round: Round) -> Option<u32> {
962 if self.is_nan() {
963 None
964 } else {
965 Some(xmpfr::get_ui(self, round).saturating_cast())
966 }
967 }
968
969 /// Converts to an [`f32`], rounding to the nearest.
970 ///
971 /// If the value is too small or too large for the target type,
972 /// the minimum or maximum value allowed is returned.
973 ///
974 /// # Examples
975 ///
976 /// ```rust
977 /// use core::f32;
978 /// use rug::{Assign, Float};
979 /// let mut f = Float::with_val(53, 13.7);
980 /// assert_eq!(f.to_f32(), 13.7);
981 /// f.assign(1e300);
982 /// assert_eq!(f.to_f32(), f32::INFINITY);
983 /// f.assign(1e-300);
984 /// assert_eq!(f.to_f32(), 0.0);
985 /// ```
986 ///
987 /// [`f32`]: https://doc.rust-lang.org/nightly/std/primitive.f32.html
988 #[inline]
to_f32(&self) -> f32989 pub fn to_f32(&self) -> f32 {
990 self.to_f32_round(Round::Nearest)
991 }
992
993 /// Converts to an [`f32`], applying the specified rounding
994 /// method.
995 ///
996 /// If the value is too small or too large for the target type,
997 /// the minimum or maximum value allowed is returned.
998 ///
999 /// # Examples
1000 ///
1001 /// ```rust
1002 /// use core::f32;
1003 /// use rug::{float::Round, Float};
1004 /// let f = Float::with_val(53, 1.0 + (-50f64).exp2());
1005 /// assert_eq!(f.to_f32_round(Round::Up), 1.0 + f32::EPSILON);
1006 /// ```
1007 ///
1008 /// [`f32`]: https://doc.rust-lang.org/nightly/std/primitive.f32.html
1009 #[inline]
to_f32_round(&self, round: Round) -> f321010 pub fn to_f32_round(&self, round: Round) -> f32 {
1011 xmpfr::get_f32(self, round)
1012 }
1013
1014 /// Converts to an [`f64`], rounding to the nearest.
1015 ///
1016 /// If the value is too small or too large for the target type,
1017 /// the minimum or maximum value allowed is returned.
1018 ///
1019 /// # Examples
1020 ///
1021 /// ```rust
1022 /// use core::f64;
1023 /// use rug::{Assign, Float};
1024 /// let mut f = Float::with_val(53, 13.7);
1025 /// assert_eq!(f.to_f64(), 13.7);
1026 /// f.assign(1e300);
1027 /// f.square_mut();
1028 /// assert_eq!(f.to_f64(), f64::INFINITY);
1029 /// ```
1030 ///
1031 /// [`f64`]: https://doc.rust-lang.org/nightly/std/primitive.f64.html
1032 #[inline]
to_f64(&self) -> f641033 pub fn to_f64(&self) -> f64 {
1034 self.to_f64_round(Round::Nearest)
1035 }
1036
1037 /// Converts to an [`f64`], applying the specified rounding
1038 /// method.
1039 ///
1040 /// If the value is too small or too large for the target type,
1041 /// the minimum or maximum value allowed is returned.
1042 ///
1043 /// # Examples
1044 ///
1045 /// ```rust
1046 /// use core::f64;
1047 /// use rug::{float::Round, Float};
1048 /// // (2.0 ^ −90) + 1
1049 /// let f: Float = Float::with_val(100, -90).exp2() + 1;
1050 /// assert_eq!(f.to_f64_round(Round::Up), 1.0 + f64::EPSILON);
1051 /// ```
1052 ///
1053 /// [`f64`]: https://doc.rust-lang.org/nightly/std/primitive.f64.html
1054 #[inline]
to_f64_round(&self, round: Round) -> f641055 pub fn to_f64_round(&self, round: Round) -> f64 {
1056 xmpfr::get_f64(self, round)
1057 }
1058
1059 /// Converts to an [`f32`] and an exponent, rounding to the
1060 /// nearest.
1061 ///
1062 /// The returned [`f32`] is in the range 0.5 ≤ <i>x</i> < 1.
1063 ///
1064 /// If the value is too small or too large for the target type,
1065 /// the minimum or maximum value allowed is returned.
1066 ///
1067 /// # Examples
1068 ///
1069 /// ```rust
1070 /// use rug::Float;
1071 /// let zero = Float::new(64);
1072 /// let (d0, exp0) = zero.to_f32_exp();
1073 /// assert_eq!((d0, exp0), (0.0, 0));
1074 /// let three_eighths = Float::with_val(64, 0.375);
1075 /// let (d3_8, exp3_8) = three_eighths.to_f32_exp();
1076 /// assert_eq!((d3_8, exp3_8), (0.75, -1));
1077 /// ```
1078 ///
1079 /// [`f32`]: https://doc.rust-lang.org/nightly/std/primitive.f32.html
1080 #[inline]
to_f32_exp(&self) -> (f32, i32)1081 pub fn to_f32_exp(&self) -> (f32, i32) {
1082 self.to_f32_exp_round(Round::Nearest)
1083 }
1084
1085 /// Converts to an [`f32`] and an exponent, applying the specified
1086 /// rounding method.
1087 ///
1088 /// The returned [`f32`] is in the range 0.5 ≤ <i>x</i> < 1.
1089 ///
1090 /// If the value is too small or too large for the target type,
1091 /// the minimum or maximum value allowed is returned.
1092 ///
1093 /// # Examples
1094 ///
1095 /// ```rust
1096 /// use rug::{float::Round, Float};
1097 /// let frac_10_3 = Float::with_val(64, 10) / 3u32;
1098 /// let (f_down, exp_down) = frac_10_3.to_f32_exp_round(Round::Down);
1099 /// assert_eq!((f_down, exp_down), (0.8333333, 2));
1100 /// let (f_up, exp_up) = frac_10_3.to_f32_exp_round(Round::Up);
1101 /// assert_eq!((f_up, exp_up), (0.8333334, 2));
1102 /// ```
1103 ///
1104 /// [`f32`]: https://doc.rust-lang.org/nightly/std/primitive.f32.html
1105 #[inline]
to_f32_exp_round(&self, round: Round) -> (f32, i32)1106 pub fn to_f32_exp_round(&self, round: Round) -> (f32, i32) {
1107 let mut sf = SmallFloat::from(0.0f32);
1108 assert_eq!(sf.prec(), 24);
1109 // Safety: xmpfr::set will not change precision of sf, so we
1110 // can use the unsafe as_nonreallocating_float function.
1111 unsafe {
1112 xmpfr::set(sf.as_nonreallocating_float(), self, round);
1113 }
1114 let (f, exp) = xmpfr::get_f64_2exp(&*sf, Round::Zero);
1115 (f as f32, exp.unwrapped_cast())
1116 }
1117
1118 /// Converts to an [`f64`] and an exponent, rounding to the
1119 /// nearest.
1120 ///
1121 /// The returned [`f64`] is in the range 0.5 ≤ <i>x</i> < 1.
1122 ///
1123 /// If the value is too small or too large for the target type,
1124 /// the minimum or maximum value allowed is returned.
1125 ///
1126 /// # Examples
1127 ///
1128 /// ```rust
1129 /// use rug::Float;
1130 /// let zero = Float::new(64);
1131 /// let (d0, exp0) = zero.to_f64_exp();
1132 /// assert_eq!((d0, exp0), (0.0, 0));
1133 /// let three_eighths = Float::with_val(64, 0.375);
1134 /// let (d3_8, exp3_8) = three_eighths.to_f64_exp();
1135 /// assert_eq!((d3_8, exp3_8), (0.75, -1));
1136 /// ```
1137 ///
1138 /// [`f64`]: https://doc.rust-lang.org/nightly/std/primitive.f64.html
1139 #[inline]
to_f64_exp(&self) -> (f64, i32)1140 pub fn to_f64_exp(&self) -> (f64, i32) {
1141 self.to_f64_exp_round(Round::Nearest)
1142 }
1143
1144 /// Converts to an [`f64`] and an exponent, applying the specified
1145 /// rounding method.
1146 ///
1147 /// The returned [`f64`] is in the range 0.5 ≤ <i>x</i> < 1.
1148 ///
1149 /// If the value is too small or too large for the target type,
1150 /// the minimum or maximum value allowed is returned.
1151 ///
1152 /// # Examples
1153 ///
1154 /// ```rust
1155 /// use rug::{float::Round, Float};
1156 /// let frac_10_3 = Float::with_val(64, 10) / 3u32;
1157 /// let (f_down, exp_down) = frac_10_3.to_f64_exp_round(Round::Down);
1158 /// assert_eq!((f_down, exp_down), (0.8333333333333333, 2));
1159 /// let (f_up, exp_up) = frac_10_3.to_f64_exp_round(Round::Up);
1160 /// assert_eq!((f_up, exp_up), (0.8333333333333334, 2));
1161 /// ```
1162 ///
1163 /// [`f64`]: https://doc.rust-lang.org/nightly/std/primitive.f64.html
1164 #[inline]
to_f64_exp_round(&self, round: Round) -> (f64, i32)1165 pub fn to_f64_exp_round(&self, round: Round) -> (f64, i32) {
1166 let (f, exp) = xmpfr::get_f64_2exp(self, round);
1167 (f, exp.unwrapped_cast())
1168 }
1169
1170 /// Returns a string representation of `self` for the specified
1171 /// `radix` rounding to the nearest.
1172 ///
1173 /// The exponent is encoded in decimal. If the number of digits is
1174 /// not specified, the output string will have enough precision
1175 /// such that reading it again will give the exact same number.
1176 ///
1177 /// # Panics
1178 ///
1179 /// Panics if `radix` is less than 2 or greater than 36.
1180 ///
1181 /// # Examples
1182 ///
1183 /// ```rust
1184 /// use rug::{float::Special, Float};
1185 /// let neg_inf = Float::with_val(53, Special::NegInfinity);
1186 /// assert_eq!(neg_inf.to_string_radix(10, None), "-inf");
1187 /// assert_eq!(neg_inf.to_string_radix(16, None), "-@inf@");
1188 /// let twentythree = Float::with_val(8, 23);
1189 /// assert_eq!(twentythree.to_string_radix(10, None), "23.00");
1190 /// assert_eq!(twentythree.to_string_radix(16, None), "17.0");
1191 /// assert_eq!(twentythree.to_string_radix(10, Some(2)), "23");
1192 /// assert_eq!(twentythree.to_string_radix(16, Some(4)), "17.00");
1193 /// // 2 raised to the power of 80 in hex is 1 followed by 20 zeros
1194 /// let two_to_80 = Float::with_val(53, 80f64.exp2());
1195 /// assert_eq!(two_to_80.to_string_radix(10, Some(3)), "1.21e24");
1196 /// assert_eq!(two_to_80.to_string_radix(16, Some(3)), "1.00@20");
1197 /// ```
1198 #[inline]
to_string_radix(&self, radix: i32, num_digits: Option<usize>) -> String1199 pub fn to_string_radix(&self, radix: i32, num_digits: Option<usize>) -> String {
1200 self.to_string_radix_round(radix, num_digits, Round::Nearest)
1201 }
1202
1203 /// Returns a string representation of `self` for the specified
1204 /// `radix` applying the specified rounding method.
1205 ///
1206 /// The exponent is encoded in decimal. If the number of digits is
1207 /// not specified, the output string will have enough precision
1208 /// such that reading it again will give the exact same number.
1209 ///
1210 /// # Panics
1211 ///
1212 /// Panics if `radix` is less than 2 or greater than 36.
1213 ///
1214 /// # Examples
1215 ///
1216 /// ```rust
1217 /// use rug::{float::Round, Float};
1218 /// let twentythree = Float::with_val(8, 23.3);
1219 /// let down = twentythree.to_string_radix_round(10, Some(2), Round::Down);
1220 /// assert_eq!(down, "23");
1221 /// let up = twentythree.to_string_radix_round(10, Some(2), Round::Up);
1222 /// assert_eq!(up, "24");
1223 /// ```
1224 #[inline]
to_string_radix_round( &self, radix: i32, num_digits: Option<usize>, round: Round, ) -> String1225 pub fn to_string_radix_round(
1226 &self,
1227 radix: i32,
1228 num_digits: Option<usize>,
1229 round: Round,
1230 ) -> String {
1231 let mut s = String::new();
1232 let format = Format {
1233 radix,
1234 precision: num_digits,
1235 round,
1236 ..Format::default()
1237 };
1238 append_to_string(&mut s, self, format);
1239 s
1240 }
1241
1242 /// Returns a string representation of `self` together with a sign
1243 /// and an exponent for the specified `radix`, rounding to the
1244 /// nearest.
1245 ///
1246 /// The returned exponent is [`None`] if the [`Float`] is zero,
1247 /// infinite or NaN, that is if the value is not [normal].
1248 ///
1249 /// For [normal] values, the returned string has an implicit radix
1250 /// point before the first digit. If the number of digits is not
1251 /// specified, the output string will have enough precision such
1252 /// that reading it again will give the exact same number.
1253 ///
1254 /// # Panics
1255 ///
1256 /// Panics if `radix` is less than 2 or greater than 36.
1257 ///
1258 /// # Examples
1259 ///
1260 /// ```rust
1261 /// use rug::{float::Special, Float};
1262 /// let inf = Float::with_val(53, Special::Infinity);
1263 /// let (sign, s, exp) = inf.to_sign_string_exp(10, None);
1264 /// assert_eq!((sign, &*s, exp), (false, "inf", None));
1265 /// let (sign, s, exp) = (-inf).to_sign_string_exp(16, None);
1266 /// assert_eq!((sign, &*s, exp), (true, "@inf@", None));
1267 ///
1268 /// let (sign, s, exp) = Float::with_val(8, -0.0625).to_sign_string_exp(10, None);
1269 /// assert_eq!((sign, &*s, exp), (true, "6250", Some(-1)));
1270 /// let (sign, s, exp) = Float::with_val(8, -0.625).to_sign_string_exp(10, None);
1271 /// assert_eq!((sign, &*s, exp), (true, "6250", Some(0)));
1272 /// let (sign, s, exp) = Float::with_val(8, -6.25).to_sign_string_exp(10, None);
1273 /// assert_eq!((sign, &*s, exp), (true, "6250", Some(1)));
1274 /// // −4.8e4 = 48_000, which is rounded to 48_128 using 8 bits of precision
1275 /// let (sign, s, exp) = Float::with_val(8, -4.8e4).to_sign_string_exp(10, None);
1276 /// assert_eq!((sign, &*s, exp), (true, "4813", Some(5)));
1277 /// ```
1278 ///
1279 /// [`Float`]: struct.Float.html
1280 /// [`None`]: https://doc.rust-lang.org/nightly/core/option/enum.Option.html#variant.None
1281 /// [normal]: #method.is_normal
1282 #[inline]
to_sign_string_exp( &self, radix: i32, num_digits: Option<usize>, ) -> (bool, String, Option<i32>)1283 pub fn to_sign_string_exp(
1284 &self,
1285 radix: i32,
1286 num_digits: Option<usize>,
1287 ) -> (bool, String, Option<i32>) {
1288 self.to_sign_string_exp_round(radix, num_digits, Round::Nearest)
1289 }
1290
1291 /// Returns a string representation of `self` together with a sign
1292 /// and an exponent for the specified `radix`, applying the
1293 /// specified rounding method.
1294 ///
1295 /// The returned exponent is [`None`] if the [`Float`] is zero,
1296 /// infinite or NaN, that is if the value is not [normal].
1297 ///
1298 /// For [normal] values, the returned string has an implicit radix
1299 /// point before the first digit. If the number of digits is not
1300 /// specified, the output string will have enough precision such
1301 /// that reading it again will give the exact same number.
1302 ///
1303 /// # Panics
1304 ///
1305 /// Panics if `radix` is less than 2 or greater than 36.
1306 ///
1307 /// # Examples
1308 ///
1309 /// ```rust
1310 /// use rug::{float::Round, Float};
1311 /// let val = Float::with_val(53, -0.0625);
1312 /// // rounding −0.0625 to two significant digits towards −∞ gives −0.063
1313 /// let (sign, s, exp) = val.to_sign_string_exp_round(10, Some(2), Round::Down);
1314 /// assert_eq!((sign, &*s, exp), (true, "63", Some(-1)));
1315 /// // rounding −0.0625 to two significant digits towards +∞ gives −0.062
1316 /// let (sign, s, exp) = val.to_sign_string_exp_round(10, Some(2), Round::Up);
1317 /// assert_eq!((sign, &*s, exp), (true, "62", Some(-1)));
1318 ///
1319 /// let val = Float::with_val(53, 6.25e4);
1320 /// // rounding 6.25e4 to two significant digits towards −∞ gives 6.2e4
1321 /// let (sign, s, exp) = val.to_sign_string_exp_round(10, Some(2), Round::Down);
1322 /// assert_eq!((sign, &*s, exp), (false, "62", Some(5)));
1323 /// // rounding 6.25e4 to two significant digits towards +∞ gives 6.3e4
1324 /// let (sign, s, exp) = val.to_sign_string_exp_round(10, Some(2), Round::Up);
1325 /// assert_eq!((sign, &*s, exp), (false, "63", Some(5)));
1326 /// ```
1327 ///
1328 /// [`Float`]: struct.Float.html
1329 /// [`None`]: https://doc.rust-lang.org/nightly/core/option/enum.Option.html#variant.None
1330 /// [normal]: #method.is_normal
to_sign_string_exp_round( &self, radix: i32, num_digits: Option<usize>, round: Round, ) -> (bool, String, Option<i32>)1331 pub fn to_sign_string_exp_round(
1332 &self,
1333 radix: i32,
1334 num_digits: Option<usize>,
1335 round: Round,
1336 ) -> (bool, String, Option<i32>) {
1337 assert!(radix >= 2 && radix <= 36, "radix {} out of range", radix);
1338 let sign = self.is_sign_negative();
1339 if self.is_zero() {
1340 return (sign, String::from("0"), None);
1341 }
1342 if self.is_infinite() {
1343 let s = String::from(if radix > 10 { "@inf@" } else { "inf" });
1344 return (sign, s, None);
1345 }
1346 if self.is_nan() {
1347 let s = String::from(if radix > 10 { "@NaN@" } else { "NaN" });
1348 return (sign, s, None);
1349 }
1350 let neg_self;
1351 let (f, round) = if sign {
1352 neg_self = self.as_neg();
1353 let reverse_round = match round {
1354 Round::Up => Round::Down,
1355 Round::Down => Round::Up,
1356 unchanged => unchanged,
1357 };
1358 (&*neg_self, reverse_round)
1359 } else {
1360 (self, round)
1361 };
1362 let format = Format {
1363 radix,
1364 precision: num_digits,
1365 round,
1366 ..Format::default()
1367 };
1368 // add 1 for nul terminator
1369 let size = req_digits(f, format) + 1;
1370 let mut s = String::with_capacity(size);
1371 let digits = format.precision.unwrap_or(0);
1372 let exp: exp_t;
1373 unsafe {
1374 let vec = s.as_mut_vec();
1375 let write_ptr = vec.as_mut_ptr();
1376 let mut maybe_exp = MaybeUninit::uninit();
1377 let c_buf = mpfr::get_str(
1378 write_ptr as *mut c_char,
1379 maybe_exp.as_mut_ptr(),
1380 format.radix.unwrapped_cast(),
1381 digits,
1382 f.as_raw(),
1383 raw_round(format.round),
1384 );
1385 assert_eq!(c_buf, write_ptr as *mut c_char);
1386 exp = maybe_exp.assume_init();
1387 let c_len = CStr::from_ptr(write_ptr as *mut c_char).to_bytes().len();
1388 // there is also 1 byte for nul character, so use < rather than <=
1389 assert!(c_len < size, "buffer overflow");
1390 vec.set_len(c_len);
1391 }
1392 let exp = exp.unwrapped_cast();
1393 (sign, s, Some(exp))
1394 }
1395
1396 /// Borrows a negated copy of the [`Float`].
1397 ///
1398 /// The returned object implements
1399 /// <code>[Deref]<[Target] = [Float][`Float`]></code>.
1400 ///
1401 /// This method performs a shallow copy and negates it, and
1402 /// negation does not change the allocated data.
1403 ///
1404 /// # Examples
1405 ///
1406 /// ```rust
1407 /// use rug::Float;
1408 /// let f = Float::with_val(53, 4.2);
1409 /// let neg_f = f.as_neg();
1410 /// assert_eq!(*neg_f, -4.2);
1411 /// // methods taking &self can be used on the returned object
1412 /// let reneg_f = neg_f.as_neg();
1413 /// assert_eq!(*reneg_f, 4.2);
1414 /// assert_eq!(*reneg_f, f);
1415 /// ```
1416 ///
1417 /// [Deref]: https://doc.rust-lang.org/nightly/core/ops/trait.Deref.html
1418 /// [Target]: https://doc.rust-lang.org/nightly/core/ops/trait.Deref.html#associatedtype.Target
1419 /// [`Float`]: struct.Float.html
as_neg(&self) -> BorrowFloat<'_>1420 pub fn as_neg(&self) -> BorrowFloat<'_> {
1421 let mut raw = self.inner;
1422 raw.sign = -raw.sign;
1423 if self.is_nan() {
1424 xmpfr::set_nanflag();
1425 }
1426 // Safety: the lifetime of the return type is equal to the lifetime of self.
1427 unsafe { BorrowFloat::from_raw(raw) }
1428 }
1429
1430 /// Borrows an absolute copy of the [`Float`].
1431 ///
1432 /// The returned object implements
1433 /// <code>[Deref]<[Target] = [Float][`Float`]></code>.
1434 ///
1435 /// This method performs a shallow copy and possibly negates it,
1436 /// and negation does not change the allocated data.
1437 ///
1438 /// # Examples
1439 ///
1440 /// ```rust
1441 /// use rug::Float;
1442 /// let f = Float::with_val(53, -4.2);
1443 /// let abs_f = f.as_abs();
1444 /// assert_eq!(*abs_f, 4.2);
1445 /// // methods taking &self can be used on the returned object
1446 /// let reabs_f = abs_f.as_abs();
1447 /// assert_eq!(*reabs_f, 4.2);
1448 /// assert_eq!(*reabs_f, *abs_f);
1449 /// ```
1450 ///
1451 /// [Deref]: https://doc.rust-lang.org/nightly/core/ops/trait.Deref.html
1452 /// [Target]: https://doc.rust-lang.org/nightly/core/ops/trait.Deref.html#associatedtype.Target
1453 /// [`Float`]: struct.Float.html
as_abs(&self) -> BorrowFloat<'_>1454 pub fn as_abs(&self) -> BorrowFloat<'_> {
1455 let mut raw = self.inner;
1456 raw.sign = 1;
1457 if self.is_nan() {
1458 xmpfr::set_nanflag();
1459 }
1460 // Safety: the lifetime of the return type is equal to the lifetime of self.
1461 unsafe { BorrowFloat::from_raw(raw) }
1462 }
1463
1464 /// Borrows the [`Float`] as an ordered floating-point number of
1465 /// type [`OrdFloat`].
1466 ///
1467 /// The same result can be obtained using the implementation of
1468 /// <code>[AsRef][`AsRef`]<[OrdFloat][`OrdFloat`]></code>
1469 /// which is provided for [`Float`].
1470 ///
1471 /// # Examples
1472 ///
1473 /// ```rust
1474 /// use core::cmp::Ordering;
1475 /// use rug::{float::Special, Float};
1476 ///
1477 /// let nan_f = Float::with_val(53, Special::Nan);
1478 /// let nan = nan_f.as_ord();
1479 /// assert_eq!(nan.cmp(nan), Ordering::Equal);
1480 ///
1481 /// let neg_inf_f = Float::with_val(53, Special::NegInfinity);
1482 /// let neg_inf = neg_inf_f.as_ord();
1483 /// assert_eq!(nan.cmp(neg_inf), Ordering::Less);
1484 ///
1485 /// let zero_f = Float::with_val(53, Special::Zero);
1486 /// let zero = zero_f.as_ord();
1487 /// let neg_zero_f = Float::with_val(53, Special::NegZero);
1488 /// let neg_zero = neg_zero_f.as_ord();
1489 /// assert_eq!(zero.cmp(neg_zero), Ordering::Greater);
1490 /// ```
1491 ///
1492 /// [`AsRef`]: https://doc.rust-lang.org/nightly/core/convert/trait.AsRef.html
1493 /// [`Float`]: struct.Float.html
1494 /// [`OrdFloat`]: float/struct.OrdFloat.html
1495 #[inline]
as_ord(&self) -> &OrdFloat1496 pub fn as_ord(&self) -> &OrdFloat {
1497 // Safety: OrdFloat is repr(transparent) over Float
1498 unsafe { &*cast_ptr!(self, OrdFloat) }
1499 }
1500
1501 #[cfg(feature = "complex")]
1502 /// Borrows a copy of the [`Float`] as a [`Complex`] number.
1503 ///
1504 /// The returned object implements
1505 /// <code>[Deref]<[Target] = [Complex][`Complex`]></code>.
1506 ///
1507 /// The imaginary part of the return value has the same precision
1508 /// as the real part. While this has no effect for the zero value
1509 /// of the returned complex number, it could have an effect if the
1510 /// return value is cloned.
1511 ///
1512 /// # Examples
1513 ///
1514 /// ```rust
1515 /// use rug::Float;
1516 /// let f = Float::with_val(53, 4.2);
1517 /// let c = f.as_complex();
1518 /// assert_eq!(*c, (4.2, 0.0));
1519 /// // methods taking &self can be used on the returned object
1520 /// let c_mul_i = c.as_mul_i(false);
1521 /// assert_eq!(*c_mul_i, (0.0, 4.2));
1522 /// ```
1523 ///
1524 /// [Deref]: https://doc.rust-lang.org/nightly/core/ops/trait.Deref.html
1525 /// [Target]: https://doc.rust-lang.org/nightly/core/ops/trait.Deref.html#associatedtype.Target
1526 /// [`Complex`]: struct.Complex.html
1527 /// [`Float`]: struct.Float.html
as_complex(&self) -> BorrowComplex<'_>1528 pub fn as_complex(&self) -> BorrowComplex<'_> {
1529 // im.d is set to be the same as re.d since the precision is equal;
1530 // though it will not be read as the imaginary part is 0 (which is singular).
1531 let raw_complex = mpc_t {
1532 re: self.inner,
1533 im: mpfr_t {
1534 prec: self.inner.prec,
1535 sign: 1,
1536 exp: xmpfr::EXP_ZERO,
1537 d: self.inner.d,
1538 },
1539 };
1540 // Safety: the lifetime of the return type is equal to the lifetime of self.
1541 unsafe { BorrowComplex::from_raw(raw_complex) }
1542 }
1543
1544 /// Returns [`true`] if `self` is an integer.
1545 ///
1546 /// # Examples
1547 ///
1548 /// ```rust
1549 /// use rug::Float;
1550 /// let mut f = Float::with_val(53, 13.5);
1551 /// assert!(!f.is_integer());
1552 /// f *= 2;
1553 /// assert!(f.is_integer());
1554 /// ```
1555 ///
1556 /// [`true`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html
1557 #[inline]
is_integer(&self) -> bool1558 pub fn is_integer(&self) -> bool {
1559 xmpfr::integer_p(self)
1560 }
1561
1562 /// Returns [`true`] if `self` is not a number.
1563 ///
1564 /// # Examples
1565 ///
1566 /// ```rust
1567 /// use rug::Float;
1568 /// let mut f = Float::with_val(53, 0);
1569 /// assert!(!f.is_nan());
1570 /// f /= 0;
1571 /// assert!(f.is_nan());
1572 /// ```
1573 ///
1574 /// [`true`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html
1575 #[inline]
is_nan(&self) -> bool1576 pub fn is_nan(&self) -> bool {
1577 xmpfr::nan_p(self)
1578 }
1579
1580 /// Returns [`true`] if `self` is plus or minus infinity.
1581 ///
1582 /// # Examples
1583 ///
1584 /// ```rust
1585 /// use rug::Float;
1586 /// let mut f = Float::with_val(53, 1);
1587 /// assert!(!f.is_infinite());
1588 /// f /= 0;
1589 /// assert!(f.is_infinite());
1590 /// ```
1591 ///
1592 /// [`true`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html
1593 #[inline]
is_infinite(&self) -> bool1594 pub fn is_infinite(&self) -> bool {
1595 xmpfr::inf_p(self)
1596 }
1597
1598 /// Returns [`true`] if `self` is a finite number, that is neither
1599 /// NaN nor infinity.
1600 ///
1601 /// # Examples
1602 ///
1603 /// ```rust
1604 /// use rug::Float;
1605 /// let mut f = Float::with_val(53, 1);
1606 /// assert!(f.is_finite());
1607 /// f /= 0;
1608 /// assert!(!f.is_finite());
1609 /// ```
1610 ///
1611 /// [`true`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html
1612 #[inline]
is_finite(&self) -> bool1613 pub fn is_finite(&self) -> bool {
1614 xmpfr::number_p(self)
1615 }
1616
1617 /// Returns [`true`] if `self` is plus or minus zero.
1618 ///
1619 /// # Examples
1620 ///
1621 /// ```rust
1622 /// use rug::{float::Special, Assign, Float};
1623 /// let mut f = Float::with_val(53, Special::Zero);
1624 /// assert!(f.is_zero());
1625 /// f.assign(Special::NegZero);
1626 /// assert!(f.is_zero());
1627 /// f += 1;
1628 /// assert!(!f.is_zero());
1629 /// ```
1630 ///
1631 /// [`true`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html
1632 #[inline]
is_zero(&self) -> bool1633 pub fn is_zero(&self) -> bool {
1634 xmpfr::zero_p(self)
1635 }
1636
1637 /// Returns [`true`] if `self` is a normal number, that is neither
1638 /// NaN, nor infinity, nor zero. Note that [`Float`] cannot be
1639 /// subnormal.
1640 ///
1641 /// # Examples
1642 ///
1643 /// ```rust
1644 /// use rug::{float::Special, Assign, Float};
1645 /// let mut f = Float::with_val(53, Special::Zero);
1646 /// assert!(!f.is_normal());
1647 /// f += 5.2;
1648 /// assert!(f.is_normal());
1649 /// f.assign(Special::Infinity);
1650 /// assert!(!f.is_normal());
1651 /// f.assign(Special::Nan);
1652 /// assert!(!f.is_normal());
1653 /// ```
1654 ///
1655 /// [`Float`]: struct.Float.html
1656 /// [`true`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html
1657 #[inline]
is_normal(&self) -> bool1658 pub fn is_normal(&self) -> bool {
1659 xmpfr::regular_p(self)
1660 }
1661
1662 /// Returns the floating-point category of the number. Note that
1663 /// [`Float`] cannot be subnormal.
1664 ///
1665 /// # Examples
1666 ///
1667 /// ```rust
1668 /// use core::num::FpCategory;
1669 /// use rug::{float::Special, Float};
1670 /// let nan = Float::with_val(53, Special::Nan);
1671 /// let infinite = Float::with_val(53, Special::Infinity);
1672 /// let zero = Float::with_val(53, Special::Zero);
1673 /// let normal = Float::with_val(53, 2.3);
1674 /// assert_eq!(nan.classify(), FpCategory::Nan);
1675 /// assert_eq!(infinite.classify(), FpCategory::Infinite);
1676 /// assert_eq!(zero.classify(), FpCategory::Zero);
1677 /// assert_eq!(normal.classify(), FpCategory::Normal);
1678 /// ```
1679 ///
1680 /// [`Float`]: struct.Float.html
1681 #[inline]
classify(&self) -> FpCategory1682 pub fn classify(&self) -> FpCategory {
1683 if xmpfr::nan_p(self) {
1684 FpCategory::Nan
1685 } else if xmpfr::inf_p(self) {
1686 FpCategory::Infinite
1687 } else if xmpfr::zero_p(self) {
1688 FpCategory::Zero
1689 } else {
1690 FpCategory::Normal
1691 }
1692 }
1693
1694 /// Returns the same result as
1695 /// <code>self.[partial_cmp][`partial_cmp`](&0)</code>, but is
1696 /// faster.
1697 ///
1698 /// # Examples
1699 ///
1700 /// ```rust
1701 /// use core::cmp::Ordering;
1702 /// use rug::{float::Special, Assign, Float};
1703 /// let mut f = Float::with_val(53, Special::NegZero);
1704 /// assert_eq!(f.cmp0(), Some(Ordering::Equal));
1705 /// f += 5.2;
1706 /// assert_eq!(f.cmp0(), Some(Ordering::Greater));
1707 /// f.assign(Special::NegInfinity);
1708 /// assert_eq!(f.cmp0(), Some(Ordering::Less));
1709 /// f.assign(Special::Nan);
1710 /// assert_eq!(f.cmp0(), None);
1711 /// ```
1712 ///
1713 /// [`partial_cmp`]: https://doc.rust-lang.org/nightly/core/cmp/trait.PartialOrd.html#tymethod.partial_cmp
1714 #[inline]
cmp0(&self) -> Option<Ordering>1715 pub fn cmp0(&self) -> Option<Ordering> {
1716 if self.is_nan() {
1717 None
1718 } else {
1719 Some(xmpfr::sgn(self))
1720 }
1721 }
1722
1723 /// Compares the absolute values of `self` and `other`.
1724 ///
1725 /// # Examples
1726 ///
1727 /// ```rust
1728 /// use core::cmp::Ordering;
1729 /// use rug::Float;
1730 /// let a = Float::with_val(53, -10);
1731 /// let b = Float::with_val(53, 4);
1732 /// assert_eq!(a.partial_cmp(&b), Some(Ordering::Less));
1733 /// assert_eq!(a.cmp_abs(&b), Some(Ordering::Greater));
1734 /// ```
1735 #[inline]
cmp_abs(&self, other: &Self) -> Option<Ordering>1736 pub fn cmp_abs(&self, other: &Self) -> Option<Ordering> {
1737 if xmpfr::unordered_p(self, other) {
1738 None
1739 } else {
1740 Some(xmpfr::cmpabs(self, other))
1741 }
1742 }
1743
1744 /// If the value is a [normal number][`is_normal`], returns its
1745 /// exponent.
1746 ///
1747 /// The significand is assumed to be in the range
1748 /// 0.5 ≤ <i>x</i> < 1.
1749 ///
1750 /// # Examples
1751 ///
1752 /// ```rust
1753 /// use rug::{Assign, Float};
1754 /// // −(2.0 ^ 32) == −(0.5 × 2 ^ 33)
1755 /// let mut f = Float::with_val(53, -32f64.exp2());
1756 /// assert_eq!(f.get_exp(), Some(33));
1757 /// // 0.8 × 2 ^ −39
1758 /// f.assign(0.8 * (-39f64).exp2());
1759 /// assert_eq!(f.get_exp(), Some(-39));
1760 /// f.assign(0);
1761 /// assert_eq!(f.get_exp(), None);
1762 /// ```
1763 ///
1764 /// [`is_normal`]: #method.is_normal
1765 #[inline]
get_exp(&self) -> Option<i32>1766 pub fn get_exp(&self) -> Option<i32> {
1767 if self.is_normal() {
1768 Some(xmpfr::get_exp(self).unwrapped_cast())
1769 } else {
1770 None
1771 }
1772 }
1773
1774 /// Clamps the exponent of a [`Float`] within a specified range if
1775 /// the range is valid.
1776 ///
1777 /// This method returns [`None`] if the specified exponent range
1778 /// is outside the allowed exponent range obtained using
1779 /// [`exp_min`] and [`exp_max`].
1780 ///
1781 /// This method assumes that `self` is the correctly rounded value
1782 /// of some exact result <i>exact</i>, rounded according to
1783 /// `round` in the direction `dir`. If necessary, this function
1784 /// then modifies `self` to be within the specified exponent
1785 /// range. If the exponent of `self` is outside the specified
1786 /// range, an underflow or overflow occurs, and the value of the
1787 /// input parameter `dir` is used to avoid double rounding.
1788 ///
1789 /// Unlike most methods functions, the direction is obtained by
1790 /// comparing the output `self` to the unknown result
1791 /// <i>exact</i>, not to the input value of `self`.
1792 ///
1793 /// # Examples
1794 ///
1795 /// ```rust
1796 /// use core::cmp::Ordering;
1797 /// use rug::{float::Round, ops::DivAssignRound, Float};
1798 /// // use precision 4 for sake of example
1799 /// let mut f = Float::with_val(4, 1.0);
1800 /// // 1/115_000 is 8.696e-6, rounded down to 0.5625 >> 16 = 8.583e-6
1801 /// let dir = f.div_assign_round(115_000, Round::Nearest);
1802 /// assert_eq!(f, 0.5625 / 16f32.exp2());
1803 /// assert_eq!(dir, Ordering::Less);
1804 /// // Limiting exponent range to [-16, 16] leaves f unchanged
1805 /// let dir = f.clamp_exp(dir, Round::Nearest, -16, 16).unwrap();
1806 /// assert_eq!(f, 0.5625 / 16f32.exp2());
1807 /// assert_eq!(dir, Ordering::Less);
1808 /// // Limiting exponent range to [-15, 15] pushes f up to 0.5 >> 15
1809 /// let dir = f.clamp_exp(dir, Round::Nearest, -15, 15).unwrap();
1810 /// assert_eq!(f, 0.5 / 15f32.exp2());
1811 /// assert_eq!(dir, Ordering::Greater);
1812 /// ```
1813 ///
1814 /// The `dir` parameter can be required to avoid double rounding.
1815 /// In the following example, `f` is 1/16, which is a tie between
1816 /// 0 and 1/8. With ties rounding to even, this would be double
1817 /// rounded to 0, but the exact result was actually > 1/16 as
1818 /// indicated by `dir` saying that `f` is less than its exact
1819 /// value. `f` can thus be rounded correctly to 1/8.
1820 ///
1821 /// ```rust
1822 /// use core::cmp::Ordering;
1823 /// use rug::{float::Round, ops::DivAssignRound, Float};
1824 /// let mut f = Float::with_val(4, 1.0);
1825 /// // 1/15.999 is > 1/16, rounded down to 0.5 >> 3 = 1/16
1826 /// let dir = f.div_assign_round(15.999, Round::Nearest);
1827 /// assert_eq!(f, 0.5 / 3f32.exp2());
1828 /// assert_eq!(dir, Ordering::Less);
1829 /// // Limiting exponent range to [-2, 2] pushes f correctly away from zero.
1830 /// let dir = f.clamp_exp(dir, Round::Nearest, -2, 2).unwrap();
1831 /// assert_eq!(f, 0.5 / 2f32.exp2());
1832 /// assert_eq!(dir, Ordering::Greater);
1833 /// ```
1834 ///
1835 /// [`Float`]: struct.Float.html
1836 /// [`None`]: https://doc.rust-lang.org/nightly/core/option/enum.Option.html#variant.None
1837 /// [`exp_max`]: float/fn.exp_max.html
1838 /// [`exp_min`]: float/fn.exp_min.html
clamp_exp( &mut self, dir: Ordering, round: Round, exp_min: i32, exp_max: i32, ) -> Option<Ordering>1839 pub fn clamp_exp(
1840 &mut self,
1841 dir: Ordering,
1842 round: Round,
1843 exp_min: i32,
1844 exp_max: i32,
1845 ) -> Option<Ordering> {
1846 unsafe {
1847 let save_emin = mpfr::get_emin();
1848 if mpfr::set_emin(exp_min.checked_cast()?) != 0 {
1849 return None;
1850 }
1851 let save_emax = mpfr::get_emax();
1852 if exp_max
1853 .checked_cast()
1854 .map(|x| mpfr::set_emax(x) != 0)
1855 .unwrap_or(true)
1856 {
1857 mpfr::set_emin(save_emin);
1858 return None;
1859 }
1860 let dir = xmpfr::check_range(self, dir, round);
1861 mpfr::set_emax(save_emax);
1862 mpfr::set_emin(save_emin);
1863 Some(dir)
1864 }
1865 }
1866
1867 #[cfg(feature = "integer")]
1868 /// If the value is a [normal number][`is_normal`], returns a
1869 /// reference to its significand as an [`Integer`].
1870 ///
1871 /// The unwrapped returned object implements
1872 /// <code>[Deref]<[Target] = [Integer][`Integer`]></code>.
1873 ///
1874 /// The number of [significant bits][`significant_bits`] of a
1875 /// returned significand is at least equal to the
1876 /// [precision][`prec`], but can be larger. It is usually rounded
1877 /// up to a multiple of 32 or 64 depending on the implementation;
1878 /// in this case, the extra least significant bits will be zero.
1879 /// The value of `self` is exactly equal to the returned
1880 /// [`Integer`] divided by two raised to the power of the number
1881 /// of [significant bits][`significant_bits`] and multiplied by
1882 /// two raised to the power of the [exponent][`get_exp`] of
1883 /// `self`.
1884 ///
1885 /// Unlike the [`to_integer_exp`] method which returns an owned
1886 /// [`Integer`], this method only performs a shallow copy and does
1887 /// not allocate any memory.
1888 ///
1889 /// # Examples
1890 ///
1891 /// ```rust
1892 /// use rug::Float;
1893 /// let float = Float::with_val(16, 6.5);
1894 /// // 6.5 in binary is 110.1 = 0.1101 times two to the power of 3
1895 /// let exp = float.get_exp().unwrap();
1896 /// assert_eq!(exp, 3);
1897 /// let significand = float.get_significand().unwrap();
1898 /// let sig_bits = significand.significant_bits();
1899 /// // sig_bits must be greater or equal to precision
1900 /// assert!(sig_bits >= 16);
1901 /// let (check_int, check_exp) = float.to_integer_exp().unwrap();
1902 /// assert_eq!(check_int << sig_bits << (check_exp - exp), *significand);
1903 /// ```
1904 ///
1905 /// [Deref]: https://doc.rust-lang.org/nightly/core/ops/trait.Deref.html
1906 /// [Target]: https://doc.rust-lang.org/nightly/core/ops/trait.Deref.html#associatedtype.Target
1907 /// [`Integer`]: struct.Integer.html
1908 /// [`get_exp`]: #method.get_exp
1909 /// [`is_normal`]: #method.is_normal
1910 /// [`prec`]: #method.prec
1911 /// [`significant_bits`]: struct.Integer.html#method.significant_bits
1912 /// [`to_integer_exp`]: #method.to_integer_exp
1913 #[inline]
get_significand(&self) -> Option<BorrowInteger<'_>>1914 pub fn get_significand(&self) -> Option<BorrowInteger<'_>> {
1915 if self.is_normal() {
1916 let limb_bits = prec_t::from(gmp::LIMB_BITS);
1917 let limbs = (self.inner.prec - 1) / limb_bits + 1;
1918 let raw_int = mpz_t {
1919 alloc: limbs.unwrapped_cast(),
1920 size: limbs.unwrapped_cast(),
1921 d: self.inner.d,
1922 };
1923 // Safety: the lifetime of the return type is equal to the lifetime of self.
1924 Some(unsafe { BorrowInteger::from_raw(raw_int) })
1925 } else {
1926 None
1927 }
1928 }
1929
1930 /// Returns [`true`] if the value is positive, +0 or NaN without a
1931 /// negative sign.
1932 ///
1933 /// # Examples
1934 ///
1935 /// ```rust
1936 /// use rug::Float;
1937 /// let pos = Float::with_val(53, 1.0);
1938 /// let neg = Float::with_val(53, -1.0);
1939 /// assert!(pos.is_sign_positive());
1940 /// assert!(!neg.is_sign_positive());
1941 /// ```
1942 ///
1943 /// [`true`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html
1944 #[inline]
is_sign_positive(&self) -> bool1945 pub fn is_sign_positive(&self) -> bool {
1946 !self.is_sign_negative()
1947 }
1948
1949 /// Returns [`true`] if the value is negative, −0 or NaN with a
1950 /// negative sign.
1951 ///
1952 /// # Examples
1953 ///
1954 /// ```rust
1955 /// use rug::Float;
1956 /// let neg = Float::with_val(53, -1.0);
1957 /// let pos = Float::with_val(53, 1.0);
1958 /// assert!(neg.is_sign_negative());
1959 /// assert!(!pos.is_sign_negative());
1960 /// ```
1961 ///
1962 /// [`true`]: https://doc.rust-lang.org/nightly/std/primitive.bool.html
1963 #[inline]
is_sign_negative(&self) -> bool1964 pub fn is_sign_negative(&self) -> bool {
1965 xmpfr::signbit(self)
1966 }
1967
1968 /// Sets to the next value towards `to`.
1969 ///
1970 /// # Examples
1971 ///
1972 /// ```rust
1973 /// use rug::Float;
1974 /// let to = Float::with_val(8, 100);
1975 /// // 32.5 in binary is 100000.10
1976 /// // 32.75 in binary is 100000.11
1977 /// let mut f = Float::with_val(8, 32.5);
1978 /// f.next_toward(&to);
1979 /// assert_eq!(f, 32.75);
1980 /// ```
1981 #[inline]
next_toward(&mut self, to: &Self)1982 pub fn next_toward(&mut self, to: &Self) {
1983 xmpfr::nexttoward(self, to);
1984 }
1985
1986 /// Sets to the next value towards +∞.
1987 ///
1988 /// # Examples
1989 ///
1990 /// ```rust
1991 /// use rug::Float;
1992 /// // 32.5 in binary is 100000.10
1993 /// // 32.75 in binary is 100000.11
1994 /// let mut f = Float::with_val(8, 32.5);
1995 /// f.next_up();
1996 /// assert_eq!(f, 32.75);
1997 /// ```
1998 #[inline]
next_up(&mut self)1999 pub fn next_up(&mut self) {
2000 xmpfr::nextabove(self);
2001 }
2002
2003 /// Sets to the next value towards −∞.
2004 ///
2005 /// # Examples
2006 ///
2007 /// ```rust
2008 /// use rug::Float;
2009 /// // 32.5 in binary is 100000.10
2010 /// // 32.25 in binary is 100000.01
2011 /// let mut f = Float::with_val(8, 32.5);
2012 /// f.next_down();
2013 /// assert_eq!(f, 32.25);
2014 /// ```
2015 #[inline]
next_down(&mut self)2016 pub fn next_down(&mut self) {
2017 xmpfr::nextbelow(self);
2018 }
2019
2020 /// Emulate subnormal numbers for precisions specified in IEEE
2021 /// 754, rounding to the nearest.
2022 ///
2023 /// Subnormalization is only performed for precisions specified in
2024 /// IEEE 754:
2025 ///
2026 /// * binary16 with 16 storage bits and a precision of 11 bits,
2027 /// * binary32 (single precision) with 32 storage bits and a
2028 /// precision of 24 bits,
2029 /// * binary64 (double precision) with 64 storage bits and a
2030 /// precision of 53 bits,
2031 /// * binary{<i>k</i>} with <i>k</i> storage bits where <i>k</i>
2032 /// is a multiple of 32 and <i>k</i> ≥ 128, and a precision of
2033 /// <i>k</i> − round(4 × log<sub>2</sub> <i>k</i>) + 13 bits.
2034 ///
2035 /// This method has no effect if the value is not in the subnormal
2036 /// range.
2037 ///
2038 /// # Examples
2039 ///
2040 /// ```rust
2041 /// use core::f32;
2042 /// use rug::Float;
2043 /// // minimum single subnormal is 0.5 × 2 ^ −148 = 2 ^ −149
2044 /// let single_min_subnormal = (-149f64).exp2();
2045 /// assert_eq!(single_min_subnormal, single_min_subnormal as f32 as f64);
2046 /// let single_cannot = single_min_subnormal * 1.25;
2047 /// assert_eq!(single_min_subnormal, single_cannot as f32 as f64);
2048 /// let mut f = Float::with_val(24, single_cannot);
2049 /// assert_eq!(f.to_f64(), single_cannot);
2050 /// f.subnormalize_ieee();
2051 /// assert_eq!(f.to_f64(), single_min_subnormal);
2052 /// ```
2053 #[inline]
subnormalize_ieee(&mut self) -> &mut Self2054 pub fn subnormalize_ieee(&mut self) -> &mut Self {
2055 self.subnormalize_ieee_round(Ordering::Equal, Round::Nearest);
2056 self
2057 }
2058
2059 /// Emulate subnormal numbers for precisions specified in IEEE
2060 /// 754, applying the specified rounding method.
2061 ///
2062 /// Subnormalization is only performed for precisions specified in
2063 /// IEEE 754:
2064 ///
2065 /// * binary16 with 16 storage bits and a precision of 11 bits,
2066 /// * binary32 (single precision) with 32 storage bits and a
2067 /// precision of 24 bits,
2068 /// * binary64 (double precision) with 64 storage bits and a
2069 /// precision of 53 bits,
2070 /// * binary{<i>k</i>} with <i>k</i> storage bits where <i>k</i>
2071 /// is a multiple of 32 and <i>k</i> ≥ 128, and a precision of
2072 /// <i>k</i> − round(4 × log<sub>2</sub> <i>k</i>) + 13 bits.
2073 ///
2074 /// This method simply propagates `prev_rounding` if the value is
2075 /// not in the subnormal range.
2076 ///
2077 /// # Examples
2078 ///
2079 /// ```rust
2080 /// use core::cmp::Ordering;
2081 /// use rug::{float::Round, Float};
2082 /// // minimum single subnormal is 0.5 × 2 ^ −148 = 2 ^ −149
2083 /// let single_min_subnormal = (-149f64).exp2();
2084 /// assert_eq!(single_min_subnormal, single_min_subnormal as f32 as f64);
2085 /// let single_cannot = single_min_subnormal * 1.25;
2086 /// assert_eq!(single_min_subnormal, single_cannot as f32 as f64);
2087 /// let mut f = Float::with_val(24, single_cannot);
2088 /// assert_eq!(f.to_f64(), single_cannot);
2089 /// let dir = f.subnormalize_ieee_round(Ordering::Equal, Round::Up);
2090 /// assert_eq!(f.to_f64(), single_min_subnormal * 2.0);
2091 /// assert_eq!(dir, Ordering::Greater);
2092 /// ```
subnormalize_ieee_round(&mut self, prev_rounding: Ordering, round: Round) -> Ordering2093 pub fn subnormalize_ieee_round(&mut self, prev_rounding: Ordering, round: Round) -> Ordering {
2094 let prec = self.prec();
2095 let exp_bits = match ieee_storage_bits_for_prec(prec) {
2096 Some(storage_bits) => storage_bits - prec,
2097 None => return prev_rounding,
2098 };
2099 let normal_exp_min = (-1i32 << (exp_bits - 1)) + 3;
2100 self.subnormalize_round(normal_exp_min, prev_rounding, round)
2101 }
2102
2103 /// Emulate subnormal numbers, rounding to the nearest.
2104 ///
2105 /// Subnormalization is only performed when the exponent lies
2106 /// within the subnormal range, that is when
2107 ///
2108 /// `normal_exp_min` − <i>precision</i> + 1 ≤ <i>exponent</i> < `normal_exp_min`
2109 ///
2110 /// For example, for IEEE 754 single precision, the precision is
2111 /// 24 and `normal_exp_min` is −125, so the subnormal range would
2112 /// be −148 ≤ <i>exponent</i> < −125.
2113 ///
2114 /// This method has no effect if the value is not in the subnormal
2115 /// range.
2116 ///
2117 /// # Examples
2118 ///
2119 /// ```rust
2120 /// use rug::Float;
2121 /// // minimum single subnormal is 0.5 × 2 ^ −148 = 2 ^ −149
2122 /// let single_min_subnormal = (-149f64).exp2();
2123 /// assert_eq!(single_min_subnormal, single_min_subnormal as f32 as f64);
2124 /// let single_cannot = single_min_subnormal * 1.25;
2125 /// assert_eq!(single_min_subnormal, single_cannot as f32 as f64);
2126 /// let mut f = Float::with_val(24, single_cannot);
2127 /// assert_eq!(f.to_f64(), single_cannot);
2128 /// f.subnormalize(-125);
2129 /// assert_eq!(f.to_f64(), single_min_subnormal);
2130 /// ```
2131 #[inline]
subnormalize(&mut self, normal_exp_min: i32) -> &mut Self2132 pub fn subnormalize(&mut self, normal_exp_min: i32) -> &mut Self {
2133 self.subnormalize_round(normal_exp_min, Ordering::Equal, Round::Nearest);
2134 self
2135 }
2136
2137 /// Emulate subnormal numbers, applying the specified rounding
2138 /// method.
2139 ///
2140 /// Subnormalization is only performed when the exponent lies
2141 /// within the subnormal range, that is when
2142 ///
2143 /// `normal_exp_min` − <i>precision</i> + 1 ≤ <i>exponent</i> < `normal_exp_min`
2144 ///
2145 /// For example, for IEEE 754 single precision, the precision is
2146 /// 24 and `normal_exp_min` is −125, so the subnormal range would
2147 /// be −148 ≤ <i>exponent</i> < −125.
2148 ///
2149 /// This method simply propagates `prev_rounding` if the value is
2150 /// not in the subnormal range.
2151 ///
2152 /// # Examples
2153 ///
2154 /// ```rust
2155 /// use core::cmp::Ordering;
2156 /// use rug::{float::Round, Float};
2157 /// // minimum single subnormal is 0.5 × 2 ^ −148 = 2 ^ −149
2158 /// let single_min_subnormal = (-149f64).exp2();
2159 /// assert_eq!(single_min_subnormal, single_min_subnormal as f32 as f64);
2160 /// let single_cannot = single_min_subnormal * 1.25;
2161 /// assert_eq!(single_min_subnormal, single_cannot as f32 as f64);
2162 /// let mut f = Float::with_val(24, single_cannot);
2163 /// assert_eq!(f.to_f64(), single_cannot);
2164 /// let dir = f.subnormalize_round(-125, Ordering::Equal, Round::Up);
2165 /// assert_eq!(f.to_f64(), single_min_subnormal * 2.0);
2166 /// assert_eq!(dir, Ordering::Greater);
2167 /// ```
subnormalize_round( &mut self, normal_exp_min: i32, prev_rounding: Ordering, round: Round, ) -> Ordering2168 pub fn subnormalize_round(
2169 &mut self,
2170 normal_exp_min: i32,
2171 prev_rounding: Ordering,
2172 round: Round,
2173 ) -> Ordering {
2174 if !self.is_normal() {
2175 return prev_rounding;
2176 }
2177 let exp_min = exp_t::from(normal_exp_min);
2178 let sub_exp_min = exp_min
2179 .checked_sub((self.prec() - 1).unwrapped_as::<exp_t>())
2180 .expect("overflow");
2181 let exp = xmpfr::get_exp(self);
2182 if exp < sub_exp_min || exp >= exp_min {
2183 return prev_rounding;
2184 }
2185 let prev = match prev_rounding {
2186 Ordering::Less => -1,
2187 Ordering::Equal => 0,
2188 Ordering::Greater => 1,
2189 };
2190 unsafe {
2191 let save_emin = mpfr::get_emin();
2192 let save_emax = mpfr::get_emax();
2193 assert!(save_emax >= exp_min, "`normal_exp_min` too large");
2194 mpfr::set_emin(sub_exp_min);
2195 mpfr::set_emax(exp_min);
2196 let ret = mpfr::subnormalize(self.as_raw_mut(), prev, raw_round(round));
2197 mpfr::set_emin(save_emin);
2198 mpfr::set_emax(save_emax);
2199 ordering1(ret)
2200 }
2201 }
2202
2203 /// Adds a list of [`Float`] values with correct rounding.
2204 ///
2205 /// The following are implemented with the returned
2206 /// [incomplete-computation value][icv] as `Src`:
2207 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
2208 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
2209 /// * <code>[AddAssign][`AddAssign`]<Src> for [Float][`Float`]</code>
2210 /// * <code>[AddAssignRound][`AddAssignRound`]<Src> for [Float][`Float`]</code>
2211 /// * <code>[Add][`Add`]<Src> for [Float][`Float`]</code>
2212 ///
2213 /// # Examples
2214 ///
2215 /// ```rust
2216 /// use core::cmp::Ordering;
2217 /// use rug::{float::Round, ops::AddAssignRound, Float};
2218 ///
2219 /// // Give each value only 4 bits of precision for example purposes.
2220 /// let values = [
2221 /// Float::with_val(4, 5.0),
2222 /// Float::with_val(4, 1024.0),
2223 /// Float::with_val(4, -1024.0),
2224 /// Float::with_val(4, -4.5),
2225 /// ];
2226 ///
2227 /// // The result should still be exact if it fits.
2228 /// let r = Float::sum(values.iter());
2229 /// let sum = Float::with_val(4, r);
2230 /// assert_eq!(sum, 0.5);
2231 ///
2232 /// let mut f = Float::with_val(4, 15.0);
2233 /// // 15.5 using 4 bits of precision becomes 16.0
2234 /// let r = Float::sum(values.iter());
2235 /// let dir = f.add_assign_round(r, Round::Nearest);
2236 /// assert_eq!(f, 16.0);
2237 /// assert_eq!(dir, Ordering::Greater);
2238 /// ```
2239 ///
2240 /// [`AddAssignRound`]: ops/trait.AddAssignRound.html
2241 /// [`AddAssign`]: https://doc.rust-lang.org/nightly/core/ops/trait.AddAssign.html
2242 /// [`Add`]: https://doc.rust-lang.org/nightly/core/ops/trait.Add.html
2243 /// [`AssignRound`]: ops/trait.AssignRound.html
2244 /// [`Assign`]: trait.Assign.html
2245 /// [`Float`]: struct.Float.html
2246 /// [icv]: index.html#incomplete-computation-values
2247 #[inline]
sum<'a, I>(values: I) -> SumIncomplete<'a, I> where I: Iterator<Item = &'a Self>,2248 pub fn sum<'a, I>(values: I) -> SumIncomplete<'a, I>
2249 where
2250 I: Iterator<Item = &'a Self>,
2251 {
2252 SumIncomplete { values }
2253 }
2254
2255 /// Finds the dot product of a list of [`Float`] value pairs with
2256 /// correct rounding.
2257 ///
2258 /// The following are implemented with the returned
2259 /// [incomplete-computation value][icv] as `Src`:
2260 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
2261 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
2262 /// * <code>[AddAssign][`AddAssign`]<Src> for [Float][`Float`]</code>
2263 /// * <code>[AddAssignRound][`AddAssignRound`]<Src> for [Float][`Float`]</code>
2264 /// * <code>[Add][`Add`]<Src> for [Float][`Float`]</code>
2265 ///
2266 /// This method will produce a result with correct rounding,
2267 /// except for some cases where underflow or overflow occurs in
2268 /// intermediate products.
2269 ///
2270 /// # Examples
2271 ///
2272 /// ```rust
2273 /// use rug::Float;
2274 ///
2275 /// let a = [Float::with_val(53, 2.75), Float::with_val(53, -1.25)];
2276 /// let b = [Float::with_val(53, 10.5), Float::with_val(53, 0.5)];
2277 ///
2278 /// let r = Float::dot(a.iter().zip(b.iter()));
2279 /// let dot = Float::with_val(53, r);
2280 /// let expected = 2.75 * 10.5 - 1.25 * 0.5;
2281 /// assert_eq!(dot, expected);
2282 /// let r = Float::dot(b.iter().zip(a.iter()));
2283 /// let twice = dot + r;
2284 /// assert_eq!(twice, expected * 2.0);
2285 /// ```
2286 ///
2287 /// [`AddAssignRound`]: ops/trait.AddAssignRound.html
2288 /// [`AddAssign`]: https://doc.rust-lang.org/nightly/core/ops/trait.AddAssign.html
2289 /// [`Add`]: https://doc.rust-lang.org/nightly/core/ops/trait.Add.html
2290 /// [`AssignRound`]: ops/trait.AssignRound.html
2291 /// [`Assign`]: trait.Assign.html
2292 /// [`Float`]: struct.Float.html
2293 /// [icv]: index.html#incomplete-computation-values
2294 #[inline]
dot<'a, I>(values: I) -> DotIncomplete<'a, I> where I: Iterator<Item = (&'a Self, &'a Self)>,2295 pub fn dot<'a, I>(values: I) -> DotIncomplete<'a, I>
2296 where
2297 I: Iterator<Item = (&'a Self, &'a Self)>,
2298 {
2299 DotIncomplete { values }
2300 }
2301
2302 /// Computes the remainder, rounding to the nearest.
2303 ///
2304 /// The remainder is the value of `self` − <i>n</i> × `divisor`,
2305 /// where <i>n</i> is the integer quotient of `self` / `divisor`
2306 /// rounded to the nearest integer (ties rounded to even). This is
2307 /// different from the remainder obtained using the `%` operator
2308 /// or the [`Rem`] trait, where <i>n</i> is truncated instead of
2309 /// rounded to the nearest.
2310 ///
2311 /// # Examples
2312 ///
2313 /// ```rust
2314 /// use rug::Float;
2315 /// let num = Float::with_val(53, 589.4);
2316 /// let den = Float::with_val(53, 100);
2317 /// let remainder = num.remainder(&den);
2318 /// let expected = -10.6_f64;
2319 /// assert!((remainder - expected).abs() < 0.0001);
2320 ///
2321 /// // compare to % operator
2322 /// let num = Float::with_val(53, 589.4);
2323 /// let den = Float::with_val(53, 100);
2324 /// let rem_op = num % &den;
2325 /// let expected = 89.4_f64;
2326 /// assert!((rem_op - expected).abs() < 0.0001);
2327 /// ```
2328 ///
2329 /// [`Rem`]: https://doc.rust-lang.org/nightly/core/ops/trait.Rem.html
2330 #[inline]
remainder(mut self, divisor: &Self) -> Self2331 pub fn remainder(mut self, divisor: &Self) -> Self {
2332 self.remainder_round(divisor, Round::Nearest);
2333 self
2334 }
2335
2336 /// Computes the remainder, rounding to the nearest.
2337 ///
2338 /// The remainder is the value of `self` − <i>n</i> × `divisor`,
2339 /// where <i>n</i> is the integer quotient of `self` / `divisor`
2340 /// rounded to the nearest integer (ties rounded to even). This is
2341 /// different from the remainder obtained using the `%=` operator
2342 /// or the [`RemAssign`] trait, where <i>n</i> is truncated instead of
2343 /// rounded to the nearest.
2344 ///
2345 /// # Examples
2346 ///
2347 /// ```rust
2348 /// use rug::Float;
2349 /// let mut f = Float::with_val(53, 589.4);
2350 /// let g = Float::with_val(53, 100);
2351 /// f.remainder_mut(&g);
2352 /// let expected = -10.6_f64;
2353 /// assert!((f - expected).abs() < 0.0001);
2354 ///
2355 /// // compare to %= operator
2356 /// let mut f = Float::with_val(53, 589.4);
2357 /// let g = Float::with_val(53, 100);
2358 /// f %= &g;
2359 /// let expected = 89.4_f64;
2360 /// assert!((f - expected).abs() < 0.0001);
2361 /// ```
2362 ///
2363 /// [`RemAssign`]: https://doc.rust-lang.org/nightly/core/ops/trait.RemAssign.html
2364 #[inline]
remainder_mut(&mut self, divisor: &Self)2365 pub fn remainder_mut(&mut self, divisor: &Self) {
2366 self.remainder_round(divisor, Round::Nearest);
2367 }
2368
2369 /// Computes the remainder, applying the specified rounding
2370 /// method.
2371 ///
2372 /// The remainder is the value of `self` − <i>n</i> × `divisor`,
2373 /// where <i>n</i> is the integer quotient of `self` / `divisor`
2374 /// rounded to the nearest integer (ties rounded to even). This is
2375 /// different from the remainder obtained using the
2376 /// [`RemAssignRound`] trait, where <i>n</i> is truncated instead
2377 /// of rounded to the nearest.
2378 ///
2379 /// # Examples
2380 ///
2381 /// ```rust
2382 /// use core::cmp::Ordering;
2383 /// use rug::{float::Round, ops::RemAssignRound, Float};
2384 /// // Use only 4 bits of precision to show rounding.
2385 /// let mut f = Float::with_val(4, 128);
2386 /// let g = Float::with_val(6, 49);
2387 /// // remainder of 128 / 49 is 128 − 3 × 49 = −19
2388 /// // using 4 significant bits: −20
2389 /// let dir = f.remainder_round(&g, Round::Nearest);
2390 /// assert_eq!(f, -20.0);
2391 /// assert_eq!(dir, Ordering::Less);
2392 ///
2393 /// // compare to RemAssignRound::rem_assign_round
2394 /// let mut f = Float::with_val(4, 128);
2395 /// let g = Float::with_val(6, 49);
2396 /// // with RemAssignRound, remainder of 128 / 49 is 128 − 2 × 49 = 30
2397 /// // using 4 significant bits: 30
2398 /// let dir = f.rem_assign_round(&g, Round::Nearest);
2399 /// assert_eq!(f, 30.0);
2400 /// assert_eq!(dir, Ordering::Equal);
2401 /// ```
2402 ///
2403 /// [`RemAssignRound`]: ops/trait.RemAssignRound.html
2404 #[inline]
remainder_round(&mut self, divisor: &Self, round: Round) -> Ordering2405 pub fn remainder_round(&mut self, divisor: &Self, round: Round) -> Ordering {
2406 xmpfr::remainder(self, (), divisor, round)
2407 }
2408
2409 /// Computes the remainder, rounding to the nearest.
2410 ///
2411 /// The remainder is the value of `dividend` − <i>n</i> × `self`,
2412 /// where <i>n</i> is the integer quotient of `dividend` / `self`
2413 /// rounded to the nearest integer (ties rounded to even). This is
2414 /// different from the remainder obtained using the [`RemFrom`]
2415 /// trait, where <i>n</i> is truncated instead of rounded to the
2416 /// nearest.
2417 ///
2418 /// # Examples
2419 ///
2420 /// ```rust
2421 /// use rug::{ops::RemFrom, Float};
2422 /// let f = Float::with_val(53, 589.4);
2423 /// let mut g = Float::with_val(53, 100);
2424 /// g.remainder_from(&f);
2425 /// let expected = -10.6_f64;
2426 /// assert!((g - expected).abs() < 0.0001);
2427 ///
2428 /// // compare to RemFrom::rem_from
2429 /// let f = Float::with_val(53, 589.4);
2430 /// let mut g = Float::with_val(53, 100);
2431 /// g.rem_from(&f);
2432 /// let expected = 89.4_f64;
2433 /// assert!((g - expected).abs() < 0.0001);
2434 /// ```
2435 ///
2436 /// [`RemFrom`]: ops/trait.RemFrom.html
2437 #[inline]
remainder_from(&mut self, dividend: &Self)2438 pub fn remainder_from(&mut self, dividend: &Self) {
2439 self.remainder_from_round(dividend, Round::Nearest);
2440 }
2441
2442 /// Computes the remainder, applying the specified rounding
2443 /// method.
2444 ///
2445 /// The remainder is the value of `dividend` − <i>n</i> × `self`,
2446 /// where <i>n</i> is the integer quotient of `dividend` / `self`
2447 /// rounded to the nearest integer (ties rounded to even). This is
2448 /// different from the remainder obtained using the
2449 /// [`RemFromRound`] trait, where <i>n</i> is truncated instead of
2450 /// rounded to the nearest.
2451 ///
2452 /// # Examples
2453 ///
2454 /// ```rust
2455 /// use core::cmp::Ordering;
2456 /// use rug::{float::Round, ops::RemFromRound, Float};
2457 /// // Use only 4 bits of precision to show rounding.
2458 /// let f = Float::with_val(8, 171);
2459 /// let mut g = Float::with_val(4, 64);
2460 /// // remainder of 171 / 64 is 171 − 3 × 64 = −21
2461 /// // using 4 significant bits: −20
2462 /// let dir = g.remainder_from_round(&f, Round::Nearest);
2463 /// assert_eq!(g, -20.0);
2464 /// assert_eq!(dir, Ordering::Greater);
2465 ///
2466 /// // compare to RemFromRound::rem_from_round
2467 /// let f = Float::with_val(8, 171);
2468 /// let mut g = Float::with_val(4, 64);
2469 /// // with RemFromRound, remainder of 171 / 64 is 171 − 2 × 64 = 43
2470 /// // using 4 significant bits: 44
2471 /// let dir = g.rem_from_round(&f, Round::Nearest);
2472 /// assert_eq!(g, 44.0);
2473 /// assert_eq!(dir, Ordering::Greater);
2474 /// ```
2475 ///
2476 /// [`RemFromRound`]: ops/trait.RemFromRound.html
2477 #[inline]
remainder_from_round(&mut self, dividend: &Self, round: Round) -> Ordering2478 pub fn remainder_from_round(&mut self, dividend: &Self, round: Round) -> Ordering {
2479 xmpfr::remainder(self, dividend, (), round)
2480 }
2481
2482 /// Computes the remainder.
2483 ///
2484 /// The remainder is the value of `self` − <i>n</i> × `divisor`,
2485 /// where <i>n</i> is the integer quotient of `self` / `divisor`
2486 /// rounded to the nearest integer (ties rounded to even). This is
2487 /// different from the remainder obtained using the `%` operator
2488 /// or the [`Rem`] trait, where <i>n</i> is truncated instead of
2489 /// rounded to the nearest.
2490 ///
2491 /// The following are implemented with the returned
2492 /// [incomplete-computation value][icv] as `Src`:
2493 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
2494 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
2495 ///
2496 /// # Examples
2497 ///
2498 /// ```rust
2499 /// use rug::Float;
2500 /// let f = Float::with_val(53, 589.4);
2501 /// let g = Float::with_val(53, 100);
2502 /// let remainder = Float::with_val(53, f.remainder_ref(&g));
2503 /// let expected = -10.6_f64;
2504 /// assert!((remainder - expected).abs() < 0.0001);
2505 ///
2506 /// // compare to % operator
2507 /// let f = Float::with_val(53, 589.4);
2508 /// let g = Float::with_val(53, 100);
2509 /// let rem_op = Float::with_val(53, &f % &g);
2510 /// let expected = 89.4_f64;
2511 /// assert!((rem_op - expected).abs() < 0.0001);
2512 /// ```
2513 ///
2514 /// [`AssignRound`]: ops/trait.AssignRound.html
2515 /// [`Assign`]: trait.Assign.html
2516 /// [`Float`]: struct.Float.html
2517 /// [`Rem`]: https://doc.rust-lang.org/nightly/core/ops/trait.Rem.html
2518 /// [icv]: index.html#incomplete-computation-values
2519 #[inline]
remainder_ref<'a>(&'a self, divisor: &'a Self) -> RemainderIncomplete<'_>2520 pub fn remainder_ref<'a>(&'a self, divisor: &'a Self) -> RemainderIncomplete<'_> {
2521 RemainderIncomplete {
2522 ref_self: self,
2523 divisor,
2524 }
2525 }
2526
2527 /// Multiplies and adds in one fused operation, rounding to the
2528 /// nearest with only one rounding error.
2529 ///
2530 /// `a.mul_add(&b, &c)` produces a result like `&a * &b + &c`, but
2531 /// `a` is consumed and the result produced uses its precision.
2532 ///
2533 /// # Examples
2534 ///
2535 /// ```rust
2536 /// use rug::Float;
2537 /// // Use only 4 bits of precision for demonstration purposes.
2538 /// // 1.5 in binary is 1.1.
2539 /// let mul1 = Float::with_val(4, 1.5);
2540 /// // −13 in binary is −1101.
2541 /// let mul2 = Float::with_val(4, -13);
2542 /// // 24 in binary is 11000.
2543 /// let add = Float::with_val(4, 24);
2544 ///
2545 /// // 1.5 × −13 + 24 = 4.5
2546 /// let mul_add = mul1.mul_add(&mul2, &add);
2547 /// assert_eq!(mul_add, 4.5);
2548 /// ```
2549 #[inline]
mul_add(mut self, mul: &Self, add: &Self) -> Self2550 pub fn mul_add(mut self, mul: &Self, add: &Self) -> Self {
2551 self.mul_add_round(mul, add, Round::Nearest);
2552 self
2553 }
2554
2555 /// Multiplies and adds in one fused operation, rounding to the
2556 /// nearest with only one rounding error.
2557 ///
2558 /// `a.mul_add_mut(&b, &c)` produces a result like `&a * &b + &c`,
2559 /// but stores the result in `a` using its precision.
2560 ///
2561 /// # Examples
2562 ///
2563 /// ```rust
2564 /// use rug::Float;
2565 /// // Use only 4 bits of precision for demonstration purposes.
2566 /// // 1.5 in binary is 1.1.
2567 /// let mut mul1 = Float::with_val(4, 1.5);
2568 /// // −13 in binary is −1101.
2569 /// let mul2 = Float::with_val(4, -13);
2570 /// // 24 in binary is 11000.
2571 /// let add = Float::with_val(4, 24);
2572 ///
2573 /// // 1.5 × −13 + 24 = 4.5
2574 /// mul1.mul_add_mut(&mul2, &add);
2575 /// assert_eq!(mul1, 4.5);
2576 /// ```
2577 #[inline]
mul_add_mut(&mut self, mul: &Self, add: &Self)2578 pub fn mul_add_mut(&mut self, mul: &Self, add: &Self) {
2579 self.mul_add_round(mul, add, Round::Nearest);
2580 }
2581
2582 /// Multiplies and adds in one fused operation, applying the
2583 /// specified rounding method with only one rounding error.
2584 ///
2585 /// `a.mul_add_round(&b, &c, round)` produces a result like
2586 /// `ans.assign_round(&a * &b + &c, round)`, but stores the result
2587 /// in `a` using its precision rather than in another [`Float`]
2588 /// like `ans`.
2589 ///
2590 /// # Examples
2591 ///
2592 /// ```rust
2593 /// use core::cmp::Ordering;
2594 /// use rug::{float::Round, Float};
2595 /// // Use only 4 bits of precision for demonstration purposes.
2596 /// // 1.5 in binary is 1.1.
2597 /// let mut mul1 = Float::with_val(4, 1.5);
2598 /// // −13 in binary is −1101.
2599 /// let mul2 = Float::with_val(4, -13);
2600 /// // 24 in binary is 11000.
2601 /// let add = Float::with_val(4, 24);
2602 ///
2603 /// // 1.5 × −13 + 24 = 4.5
2604 /// let dir = mul1.mul_add_round(&mul2, &add, Round::Nearest);
2605 /// assert_eq!(mul1, 4.5);
2606 /// assert_eq!(dir, Ordering::Equal);
2607 /// ```
2608 ///
2609 /// [`Float`]: struct.Float.html
2610 #[inline]
mul_add_round(&mut self, mul: &Self, add: &Self, round: Round) -> Ordering2611 pub fn mul_add_round(&mut self, mul: &Self, add: &Self, round: Round) -> Ordering {
2612 xmpfr::fma(self, (), mul, add, round)
2613 }
2614
2615 /// Multiplies and adds in one fused operation.
2616 ///
2617 /// The following are implemented with the returned
2618 /// [incomplete-computation value][icv] as `Src`:
2619 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
2620 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
2621 ///
2622 /// `a.mul_add_ref(&b, &c)` produces the exact same result as
2623 /// `&a * &b + &c`.
2624 ///
2625 /// # Examples
2626 ///
2627 /// ```rust
2628 /// use rug::Float;
2629 /// // Use only 4 bits of precision for demonstration purposes.
2630 /// // 1.5 in binary is 1.1.
2631 /// let mul1 = Float::with_val(4, 1.5);
2632 /// // −13 in binary is −1101.
2633 /// let mul2 = Float::with_val(4, -13);
2634 /// // 24 in binary is 11000.
2635 /// let add = Float::with_val(4, 24);
2636 ///
2637 /// // 1.5 × −13 + 24 = 4.5
2638 /// let ans = Float::with_val(4, mul1.mul_add_ref(&mul2, &add));
2639 /// assert_eq!(ans, 4.5);
2640 /// ```
2641 ///
2642 /// [`AssignRound`]: ops/trait.AssignRound.html
2643 /// [`Assign`]: trait.Assign.html
2644 /// [`Float`]: struct.Float.html
2645 /// [icv]: index.html#incomplete-computation-values
2646 #[inline]
mul_add_ref<'a>(&'a self, mul: &'a Self, add: &'a Self) -> AddMulIncomplete<'a>2647 pub fn mul_add_ref<'a>(&'a self, mul: &'a Self, add: &'a Self) -> AddMulIncomplete<'a> {
2648 self * mul + add
2649 }
2650
2651 /// Multiplies and subtracts in one fused operation, rounding to
2652 /// the nearest with only one rounding error.
2653 ///
2654 /// `a.mul_sub(&b, &c)` produces a result like `&a * &b - &c`, but
2655 /// `a` is consumed and the result produced uses its precision.
2656 ///
2657 /// # Examples
2658 ///
2659 /// ```rust
2660 /// use rug::Float;
2661 /// // Use only 4 bits of precision for demonstration purposes.
2662 /// // 1.5 in binary is 1.1.
2663 /// let mul1 = Float::with_val(4, 1.5);
2664 /// // −13 in binary is −1101.
2665 /// let mul2 = Float::with_val(4, -13);
2666 /// // 24 in binary is 11000.
2667 /// let sub = Float::with_val(4, 24);
2668 ///
2669 /// // 1.5 × −13 − 24 = −43.5, rounded to 44 using four bits of precision.
2670 /// let mul_sub = mul1.mul_sub(&mul2, &sub);
2671 /// assert_eq!(mul_sub, -44);
2672 /// ```
2673 #[inline]
mul_sub(mut self, mul: &Self, sub: &Self) -> Self2674 pub fn mul_sub(mut self, mul: &Self, sub: &Self) -> Self {
2675 self.mul_sub_round(mul, sub, Round::Nearest);
2676 self
2677 }
2678
2679 /// Multiplies and subtracts in one fused operation, rounding to
2680 /// the nearest with only one rounding error.
2681 ///
2682 /// `a.mul_sub_mut(&b, &c)` produces a result like `&a * &b - &c`,
2683 /// but stores the result in `a` using its precision.
2684 ///
2685 /// # Examples
2686 ///
2687 /// ```rust
2688 /// use rug::Float;
2689 /// // Use only 4 bits of precision for demonstration purposes.
2690 /// // 1.5 in binary is 1.1.
2691 /// let mut mul1 = Float::with_val(4, 1.5);
2692 /// // −13 in binary is −1101.
2693 /// let mul2 = Float::with_val(4, -13);
2694 /// // 24 in binary is 11000.
2695 /// let sub = Float::with_val(4, 24);
2696 ///
2697 /// // 1.5 × −13 − 24 = −43.5, rounded to 44 using four bits of precision.
2698 /// mul1.mul_sub_mut(&mul2, &sub);
2699 /// assert_eq!(mul1, -44);
2700 /// ```
2701 #[inline]
mul_sub_mut(&mut self, mul: &Self, sub: &Self)2702 pub fn mul_sub_mut(&mut self, mul: &Self, sub: &Self) {
2703 self.mul_sub_round(mul, sub, Round::Nearest);
2704 }
2705
2706 /// Multiplies and subtracts in one fused operation, applying the
2707 /// specified rounding method with only one rounding error.
2708 ///
2709 /// `a.mul_sub_round(&b, &c, round)` produces a result like
2710 /// `ans.assign_round(&a * &b - &c, round)`, but stores the result
2711 /// in `a` using its precision rather than in another [`Float`]
2712 /// like `ans`.
2713 ///
2714 /// # Examples
2715 ///
2716 /// ```rust
2717 /// use core::cmp::Ordering;
2718 /// use rug::{float::Round, Float};
2719 /// // Use only 4 bits of precision for demonstration purposes.
2720 /// // 1.5 in binary is 1.1.
2721 /// let mut mul1 = Float::with_val(4, 1.5);
2722 /// // −13 in binary is −1101.
2723 /// let mul2 = Float::with_val(4, -13);
2724 /// // 24 in binary is 11000.
2725 /// let sub = Float::with_val(4, 24);
2726 ///
2727 /// // 1.5 × −13 − 24 = −43.5, rounded to 44 using four bits of precision.
2728 /// let dir = mul1.mul_sub_round(&mul2, &sub, Round::Nearest);
2729 /// assert_eq!(mul1, -44);
2730 /// assert_eq!(dir, Ordering::Less);
2731 /// ```
2732 ///
2733 /// [`Float`]: struct.Float.html
2734 #[inline]
mul_sub_round(&mut self, mul: &Self, sub: &Self, round: Round) -> Ordering2735 pub fn mul_sub_round(&mut self, mul: &Self, sub: &Self, round: Round) -> Ordering {
2736 xmpfr::fms(self, (), mul, sub, round)
2737 }
2738
2739 /// Multiplies and subtracts in one fused operation.
2740 ///
2741 /// The following are implemented with the returned
2742 /// [incomplete-computation value][icv] as `Src`:
2743 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
2744 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
2745 ///
2746 /// `a.mul_sub_ref(&b, &c)` produces the exact same result as
2747 /// `&a * &b - &c`.
2748 ///
2749 /// # Examples
2750 ///
2751 /// ```rust
2752 /// use rug::Float;
2753 /// // Use only 4 bits of precision for demonstration purposes.
2754 /// // 1.5 in binary is 1.1.
2755 /// let mul1 = Float::with_val(4, 1.5);
2756 /// // −13 in binary is −1101.
2757 /// let mul2 = Float::with_val(4, -13);
2758 /// // 24 in binary is 11000.
2759 /// let sub = Float::with_val(4, 24);
2760 ///
2761 /// // 1.5 × −13 − 24 = −43.5, rounded to 44 using four bits of precision.
2762 /// let ans = Float::with_val(4, mul1.mul_sub_ref(&mul2, &sub));
2763 /// assert_eq!(ans, -44);
2764 /// ```
2765 ///
2766 /// [`AssignRound`]: ops/trait.AssignRound.html
2767 /// [`Assign`]: trait.Assign.html
2768 /// [`Float`]: struct.Float.html
2769 /// [icv]: index.html#incomplete-computation-values
2770 #[inline]
mul_sub_ref<'a>(&'a self, mul: &'a Self, sub: &'a Self) -> SubMulFromIncomplete<'a>2771 pub fn mul_sub_ref<'a>(&'a self, mul: &'a Self, sub: &'a Self) -> SubMulFromIncomplete<'a> {
2772 self * mul - sub
2773 }
2774
2775 /// Multiplies two products and adds them in one fused operation,
2776 /// rounding to the nearest with only one rounding error.
2777 ///
2778 /// `a.mul_add_mul(&b, &c, &d)` produces a result like
2779 /// `&a * &b + &c * &d`, but `a` is consumed and the result
2780 /// produced uses its precision.
2781 ///
2782 /// # Examples
2783 ///
2784 /// ```rust
2785 /// use rug::Float;
2786 /// let a = Float::with_val(53, 24);
2787 /// let b = Float::with_val(53, 1.5);
2788 /// let c = Float::with_val(53, 12);
2789 /// let d = Float::with_val(53, 2);
2790 /// // 24 × 1.5 + 12 × 2 = 60
2791 /// let mul_add_mul = a.mul_add_mul(&b, &c, &d);
2792 /// assert_eq!(mul_add_mul, 60);
2793 /// ```
2794 #[inline]
mul_add_mul(mut self, mul: &Self, add_mul1: &Self, add_mul2: &Self) -> Self2795 pub fn mul_add_mul(mut self, mul: &Self, add_mul1: &Self, add_mul2: &Self) -> Self {
2796 self.mul_add_mul_round(mul, add_mul1, add_mul2, Round::Nearest);
2797 self
2798 }
2799
2800 /// Multiplies two products and adds them in one fused operation,
2801 /// rounding to the nearest with only one rounding error.
2802 ///
2803 /// `a.mul_add_mul_mut(&b, &c, &d)` produces a result like
2804 /// `&a * &b + &c * &d`, but stores the result in `a` using its
2805 /// precision.
2806 ///
2807 /// # Examples
2808 ///
2809 /// ```rust
2810 /// use rug::Float;
2811 /// let mut a = Float::with_val(53, 24);
2812 /// let b = Float::with_val(53, 1.5);
2813 /// let c = Float::with_val(53, 12);
2814 /// let d = Float::with_val(53, 2);
2815 /// // 24 × 1.5 + 12 × 2 = 60
2816 /// a.mul_add_mul_mut(&b, &c, &d);
2817 /// assert_eq!(a, 60);
2818 /// ```
2819 #[inline]
mul_add_mul_mut(&mut self, mul: &Self, add_mul1: &Self, add_mul2: &Self)2820 pub fn mul_add_mul_mut(&mut self, mul: &Self, add_mul1: &Self, add_mul2: &Self) {
2821 self.mul_add_mul_round(mul, add_mul1, add_mul2, Round::Nearest);
2822 }
2823
2824 /// Multiplies two produces and adds them in one fused operation,
2825 /// applying the specified rounding method with only one rounding
2826 /// error.
2827 ///
2828 /// `a.mul_add_mul_round(&b, &c, &d, round)` produces a result
2829 /// like `ans.assign_round(&a * &b + &c * &d, round)`, but stores
2830 /// the result in `a` using its precision rather than in another
2831 /// [`Float`] like `ans`.
2832 ///
2833 /// # Examples
2834 ///
2835 /// ```rust
2836 /// use core::cmp::Ordering;
2837 /// use rug::{float::Round, Float};
2838 /// let mut a = Float::with_val(53, 24);
2839 /// let b = Float::with_val(53, 1.5);
2840 /// let c = Float::with_val(53, 12);
2841 /// let d = Float::with_val(53, 2);
2842 /// // 24 × 1.5 + 12 × 2 = 60
2843 /// let dir = a.mul_add_mul_round(&b, &c, &d, Round::Nearest);
2844 /// assert_eq!(a, 60);
2845 /// assert_eq!(dir, Ordering::Equal);
2846 /// ```
2847 ///
2848 /// [`Float`]: struct.Float.html
2849 #[inline]
mul_add_mul_round( &mut self, mul: &Self, add_mul1: &Self, add_mul2: &Self, round: Round, ) -> Ordering2850 pub fn mul_add_mul_round(
2851 &mut self,
2852 mul: &Self,
2853 add_mul1: &Self,
2854 add_mul2: &Self,
2855 round: Round,
2856 ) -> Ordering {
2857 xmpfr::fmma(self, (), mul, add_mul1, add_mul2, round)
2858 }
2859
2860 /// Multiplies two products and adds them in one fused operation.
2861 ///
2862 /// The following are implemented with the returned
2863 /// [incomplete-computation value][icv] as `Src`:
2864 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
2865 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
2866 ///
2867 /// `a.mul_add_mul_ref(&b, &c, &d)` produces the exact same result
2868 /// as `&a * &b + &c * &d`.
2869 ///
2870 /// # Examples
2871 ///
2872 /// ```rust
2873 /// use rug::Float;
2874 /// let a = Float::with_val(53, 24);
2875 /// let b = Float::with_val(53, 1.5);
2876 /// let c = Float::with_val(53, 12);
2877 /// let d = Float::with_val(53, 2);
2878 /// // 24 × 1.5 + 12 × 2 = 60
2879 /// let ans = Float::with_val(53, a.mul_add_mul_ref(&b, &c, &d));
2880 /// assert_eq!(ans, 60);
2881 /// ```
2882 ///
2883 /// [`AssignRound`]: ops/trait.AssignRound.html
2884 /// [`Assign`]: trait.Assign.html
2885 /// [`Float`]: struct.Float.html
2886 /// [icv]: index.html#incomplete-computation-values
2887 #[inline]
mul_add_mul_ref<'a>( &'a self, mul: &'a Self, add_mul1: &'a Self, add_mul2: &'a Self, ) -> MulAddMulIncomplete<'a>2888 pub fn mul_add_mul_ref<'a>(
2889 &'a self,
2890 mul: &'a Self,
2891 add_mul1: &'a Self,
2892 add_mul2: &'a Self,
2893 ) -> MulAddMulIncomplete<'a> {
2894 self * mul + add_mul1 * add_mul2
2895 }
2896
2897 /// Multiplies two products and subtracts them in one fused
2898 /// operation, rounding to the nearest with only one rounding
2899 /// error.
2900 ///
2901 /// `a.mul_sub_mul(&b, &c, &d)` produces a result like
2902 /// `&a * &b - &c * &d`, but `a` is consumed and the result
2903 /// produced uses its precision.
2904 ///
2905 /// # Examples
2906 ///
2907 /// ```rust
2908 /// use rug::Float;
2909 /// let a = Float::with_val(53, 24);
2910 /// let b = Float::with_val(53, 1.5);
2911 /// let c = Float::with_val(53, 12);
2912 /// let d = Float::with_val(53, 2);
2913 /// // 24 × 1.5 − 12 × 2 = 12
2914 /// let mul_sub_mul = a.mul_sub_mul(&b, &c, &d);
2915 /// assert_eq!(mul_sub_mul, 12);
2916 /// ```
2917 #[inline]
mul_sub_mul(mut self, mul: &Self, sub_mul1: &Self, sub_mul2: &Self) -> Self2918 pub fn mul_sub_mul(mut self, mul: &Self, sub_mul1: &Self, sub_mul2: &Self) -> Self {
2919 self.mul_sub_mul_round(mul, sub_mul1, sub_mul2, Round::Nearest);
2920 self
2921 }
2922
2923 /// Multiplies two products and subtracts them in one fused
2924 /// operation, rounding to the nearest with only one rounding
2925 /// error.
2926 ///
2927 /// `a.mul_sub_mul_mut(&b, &c, &d)` produces a result like
2928 /// `&a * &b - &c * &d`, but stores the result in `a` using its
2929 /// precision.
2930 ///
2931 /// # Examples
2932 ///
2933 /// ```rust
2934 /// use rug::Float;
2935 /// let mut a = Float::with_val(53, 24);
2936 /// let b = Float::with_val(53, 1.5);
2937 /// let c = Float::with_val(53, 12);
2938 /// let d = Float::with_val(53, 2);
2939 /// // 24 × 1.5 − 12 × 2 = 12
2940 /// a.mul_sub_mul_mut(&b, &c, &d);
2941 /// assert_eq!(a, 12);
2942 /// ```
2943 #[inline]
mul_sub_mul_mut(&mut self, mul: &Self, sub_mul1: &Self, sub_mul2: &Self)2944 pub fn mul_sub_mul_mut(&mut self, mul: &Self, sub_mul1: &Self, sub_mul2: &Self) {
2945 self.mul_sub_mul_round(mul, sub_mul1, sub_mul2, Round::Nearest);
2946 }
2947
2948 /// Multiplies two produces and subtracts them in one fused
2949 /// operation, applying the specified rounding method with only
2950 /// one rounding error.
2951 ///
2952 /// `a.mul_sub_mul_round(&b, &c, &d, round)` produces a result
2953 /// like `ans.assign_round(&a * &b - &c * &d, round)`, but stores
2954 /// the result in `a` using its precision rather than in another
2955 /// [`Float`] like `ans`.
2956 ///
2957 /// # Examples
2958 ///
2959 /// ```rust
2960 /// use core::cmp::Ordering;
2961 /// use rug::{float::Round, Float};
2962 /// let mut a = Float::with_val(53, 24);
2963 /// let b = Float::with_val(53, 1.5);
2964 /// let c = Float::with_val(53, 12);
2965 /// let d = Float::with_val(53, 2);
2966 /// // 24 × 1.5 − 12 × 2 = 12
2967 /// let dir = a.mul_sub_mul_round(&b, &c, &d, Round::Nearest);
2968 /// assert_eq!(a, 12);
2969 /// assert_eq!(dir, Ordering::Equal);
2970 /// ```
2971 ///
2972 /// [`Float`]: struct.Float.html
2973 #[inline]
mul_sub_mul_round( &mut self, mul: &Self, sub_mul1: &Self, sub_mul2: &Self, round: Round, ) -> Ordering2974 pub fn mul_sub_mul_round(
2975 &mut self,
2976 mul: &Self,
2977 sub_mul1: &Self,
2978 sub_mul2: &Self,
2979 round: Round,
2980 ) -> Ordering {
2981 xmpfr::fmms(self, (), mul, sub_mul1, sub_mul2, round)
2982 }
2983
2984 /// Multiplies two products and subtracts them in one fused
2985 /// operation.
2986 ///
2987 /// The following are implemented with the returned
2988 /// [incomplete-computation value][icv] as `Src`:
2989 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
2990 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
2991 ///
2992 /// `a.mul_sub_mul_ref(&b, &c, &d)` produces the exact same result
2993 /// as `&a * &b - &c * &d`.
2994 ///
2995 /// # Examples
2996 ///
2997 /// ```rust
2998 /// use rug::Float;
2999 /// let a = Float::with_val(53, 24);
3000 /// let b = Float::with_val(53, 1.5);
3001 /// let c = Float::with_val(53, 12);
3002 /// let d = Float::with_val(53, 2);
3003 /// // 24 × 1.5 − 12 × 2 = 12
3004 /// let ans = Float::with_val(53, a.mul_sub_mul_ref(&b, &c, &d));
3005 /// assert_eq!(ans, 12);
3006 /// ```
3007 ///
3008 /// [`AssignRound`]: ops/trait.AssignRound.html
3009 /// [`Assign`]: trait.Assign.html
3010 /// [`Float`]: struct.Float.html
3011 /// [icv]: index.html#incomplete-computation-values
3012 #[inline]
mul_sub_mul_ref<'a>( &'a self, mul: &'a Self, sub_mul1: &'a Self, sub_mul2: &'a Self, ) -> MulSubMulIncomplete<'a>3013 pub fn mul_sub_mul_ref<'a>(
3014 &'a self,
3015 mul: &'a Self,
3016 sub_mul1: &'a Self,
3017 sub_mul2: &'a Self,
3018 ) -> MulSubMulIncomplete<'a> {
3019 self * mul - sub_mul1 * sub_mul2
3020 }
3021
3022 /// Multiplies `u` by 2<sup>`exp`</sup>.
3023 ///
3024 /// The following are implemented with the returned
3025 /// [incomplete-computation value][icv] as `Src`:
3026 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
3027 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
3028 ///
3029 /// You can also compare the returned value to a [`Float`];
3030 /// the following are also implemented with the returned
3031 /// [incomplete-computation value][icv] as `Src`:
3032 /// * <code>[PartialEq][`PartialEq`]<Src> for [Float][`Float`]</code>
3033 /// * <code>[PartialEq][`PartialEq`]<[Float][`Float`]> for Src</code>
3034 /// * <code>[PartialOrd][`PartialOrd`]<Src> for [Float][`Float`]</code>
3035 /// * <code>[PartialOrd][`PartialOrd`]<[Float][`Float`]> for Src</code>
3036 ///
3037 /// # Examples
3038 ///
3039 /// ```rust
3040 /// use rug::Float;
3041 /// let v = Float::u_exp(120, -100);
3042 /// let f = Float::with_val(53, v);
3043 /// assert_eq!(f, 120.0 * (-100f64).exp2());
3044 /// let same = Float::u_exp(120 << 2, -100 - 2);
3045 /// assert_eq!(f, same);
3046 /// ```
3047 ///
3048 /// [`AssignRound`]: ops/trait.AssignRound.html
3049 /// [`Assign`]: trait.Assign.html
3050 /// [`Float`]: struct.Float.html
3051 /// [`PartialEq`]: https://doc.rust-lang.org/nightly/core/cmp/trait.PartialEq.html
3052 /// [`PartialOrd`]: https://doc.rust-lang.org/nightly/core/cmp/trait.PartialOrd.html
3053 /// [icv]: index.html#incomplete-computation-values
3054 #[inline]
u_exp(u: u32, exp: i32) -> UExpIncomplete3055 pub fn u_exp(u: u32, exp: i32) -> UExpIncomplete {
3056 UExpIncomplete { u, exp }
3057 }
3058
3059 /// Multiplies `i` by 2<sup>`exp`</sup>.
3060 ///
3061 /// The following are implemented with the returned
3062 /// [incomplete-computation value][icv] as `Src`:
3063 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
3064 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
3065 ///
3066 /// You can also compare the returned value to a [`Float`];
3067 /// the following are also implemented with the returned
3068 /// [incomplete-computation value][icv] as `Src`:
3069 /// * <code>[PartialEq][`PartialEq`]<Src> for [Float][`Float`]</code>
3070 /// * <code>[PartialEq][`PartialEq`]<[Float][`Float`]> for Src</code>
3071 /// * <code>[PartialOrd][`PartialOrd`]<Src> for [Float][`Float`]</code>
3072 /// * <code>[PartialOrd][`PartialOrd`]<[Float][`Float`]> for Src</code>
3073 ///
3074 /// # Examples
3075 ///
3076 /// ```rust
3077 /// use rug::Float;
3078 /// let v = Float::i_exp(-120, -100);
3079 /// let f = Float::with_val(53, v);
3080 /// assert_eq!(f, -120.0 * (-100f64).exp2());
3081 /// let same = Float::i_exp(-120 << 2, -100 - 2);
3082 /// assert_eq!(f, same);
3083 /// ```
3084 ///
3085 /// [`AssignRound`]: ops/trait.AssignRound.html
3086 /// [`Assign`]: trait.Assign.html
3087 /// [`Float`]: struct.Float.html
3088 /// [`PartialEq`]: https://doc.rust-lang.org/nightly/core/cmp/trait.PartialEq.html
3089 /// [`PartialOrd`]: https://doc.rust-lang.org/nightly/core/cmp/trait.PartialOrd.html
3090 /// [icv]: index.html#incomplete-computation-values
3091 #[inline]
i_exp(i: i32, exp: i32) -> IExpIncomplete3092 pub fn i_exp(i: i32, exp: i32) -> IExpIncomplete {
3093 IExpIncomplete { i, exp }
3094 }
3095
3096 /// Raises `base` to the power of `exponent`.
3097 ///
3098 /// The following are implemented with the returned
3099 /// [incomplete-computation value][icv] as `Src`:
3100 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
3101 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
3102 ///
3103 /// # Examples
3104 ///
3105 /// ```rust
3106 /// use rug::Float;
3107 /// let p = Float::u_pow_u(13, 6);
3108 /// let f = Float::with_val(53, p);
3109 /// assert_eq!(f, 13u32.pow(6));
3110 /// ```
3111 ///
3112 /// [`AssignRound`]: ops/trait.AssignRound.html
3113 /// [`Assign`]: trait.Assign.html
3114 /// [`Float`]: struct.Float.html
3115 /// [icv]: index.html#incomplete-computation-values
3116 #[inline]
u_pow_u(base: u32, exponent: u32) -> UPowUIncomplete3117 pub fn u_pow_u(base: u32, exponent: u32) -> UPowUIncomplete {
3118 UPowUIncomplete { base, exponent }
3119 }
3120
3121 /// Raises `base` to the power of `exponent`.
3122 ///
3123 /// The following are implemented with the returned
3124 /// [incomplete-computation value][icv] as `Src`:
3125 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
3126 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
3127 ///
3128 /// # Examples
3129 ///
3130 /// ```rust
3131 /// use rug::Float;
3132 /// let p = Float::i_pow_u(-13, 5);
3133 /// let f = Float::with_val(53, p);
3134 /// assert_eq!(f, -13i32.pow(5));
3135 /// ```
3136 ///
3137 /// [`AssignRound`]: ops/trait.AssignRound.html
3138 /// [`Assign`]: trait.Assign.html
3139 /// [`Float`]: struct.Float.html
3140 /// [icv]: index.html#incomplete-computation-values
3141 #[inline]
i_pow_u(base: i32, exponent: u32) -> IPowUIncomplete3142 pub fn i_pow_u(base: i32, exponent: u32) -> IPowUIncomplete {
3143 IPowUIncomplete { base, exponent }
3144 }
3145
3146 /// Computes the square, rounding to the nearest.
3147 ///
3148 /// # Examples
3149 ///
3150 /// ```rust
3151 /// use rug::Float;
3152 /// let f = Float::with_val(53, 5.0);
3153 /// let square = f.square();
3154 /// assert_eq!(square, 25.0);
3155 /// ```
3156 #[inline]
square(mut self) -> Self3157 pub fn square(mut self) -> Self {
3158 self.square_round(Round::Nearest);
3159 self
3160 }
3161
3162 /// Computes the square, rounding to the nearest.
3163 ///
3164 /// # Examples
3165 ///
3166 /// ```rust
3167 /// use rug::Float;
3168 /// let mut f = Float::with_val(53, 5.0);
3169 /// f.square_mut();
3170 /// assert_eq!(f, 25.0);
3171 /// ```
3172 #[inline]
square_mut(&mut self)3173 pub fn square_mut(&mut self) {
3174 self.square_round(Round::Nearest);
3175 }
3176
3177 /// Computes the square, applying the specified rounding method.
3178 ///
3179 /// # Examples
3180 ///
3181 /// ```rust
3182 /// use core::cmp::Ordering;
3183 /// use rug::{float::Round, Float};
3184 /// // 5 in binary is 101
3185 /// let mut f = Float::with_val(3, 5.0);
3186 /// // 25 in binary is 11001 (more than 3 bits of precision).
3187 /// // 25 (11001) is rounded up to 28 (11100).
3188 /// let dir = f.square_round(Round::Up);
3189 /// assert_eq!(f, 28.0);
3190 /// assert_eq!(dir, Ordering::Greater);
3191 /// ```
3192 #[inline]
square_round(&mut self, round: Round) -> Ordering3193 pub fn square_round(&mut self, round: Round) -> Ordering {
3194 xmpfr::sqr(self, (), round)
3195 }
3196
3197 /// Computes the square.
3198 ///
3199 /// The following are implemented with the returned
3200 /// [incomplete-computation value][icv] as `Src`:
3201 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
3202 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
3203 ///
3204 /// # Examples
3205 ///
3206 /// ```rust
3207 /// use rug::Float;
3208 /// let f = Float::with_val(53, 5.0);
3209 /// let r = f.square_ref();
3210 /// let square = Float::with_val(53, r);
3211 /// assert_eq!(square, 25.0);
3212 /// ```
3213 ///
3214 /// [`AssignRound`]: ops/trait.AssignRound.html
3215 /// [`Assign`]: trait.Assign.html
3216 /// [`Float`]: struct.Float.html
3217 /// [icv]: index.html#incomplete-computation-values
3218 #[inline]
square_ref(&self) -> SquareIncomplete<'_>3219 pub fn square_ref(&self) -> SquareIncomplete<'_> {
3220 SquareIncomplete { ref_self: self }
3221 }
3222
3223 /// Computes the square root, rounding to the nearest.
3224 ///
3225 /// # Examples
3226 ///
3227 /// ```rust
3228 /// use rug::Float;
3229 /// let f = Float::with_val(53, 25.0);
3230 /// let sqrt = f.sqrt();
3231 /// assert_eq!(sqrt, 5.0);
3232 /// ```
3233 #[inline]
sqrt(mut self) -> Self3234 pub fn sqrt(mut self) -> Self {
3235 self.sqrt_round(Round::Nearest);
3236 self
3237 }
3238
3239 /// Computes the square root, rounding to the nearest.
3240 ///
3241 /// # Examples
3242 ///
3243 /// ```rust
3244 /// use rug::Float;
3245 /// let mut f = Float::with_val(53, 25.0);
3246 /// f.sqrt_mut();
3247 /// assert_eq!(f, 5.0);
3248 /// ```
3249 #[inline]
sqrt_mut(&mut self)3250 pub fn sqrt_mut(&mut self) {
3251 self.sqrt_round(Round::Nearest);
3252 }
3253
3254 /// Computes the square root, applying the specified rounding
3255 /// method.
3256 ///
3257 /// # Examples
3258 ///
3259 /// ```rust
3260 /// use core::cmp::Ordering;
3261 /// use rug::{float::Round, Float};
3262 /// // 5 in binary is 101
3263 /// let mut f = Float::with_val(4, 5.0);
3264 /// // sqrt(5) in binary is 10.00111100...
3265 /// // sqrt(5) is rounded to 2.25 (10.01).
3266 /// let dir = f.sqrt_round(Round::Nearest);
3267 /// assert_eq!(f, 2.25);
3268 /// assert_eq!(dir, Ordering::Greater);
3269 /// ```
3270 #[inline]
sqrt_round(&mut self, round: Round) -> Ordering3271 pub fn sqrt_round(&mut self, round: Round) -> Ordering {
3272 xmpfr::sqrt(self, (), round)
3273 }
3274
3275 /// Computes the square root.
3276 ///
3277 /// The following are implemented with the returned
3278 /// [incomplete-computation value][icv] as `Src`:
3279 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
3280 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
3281 ///
3282 /// # Examples
3283 ///
3284 /// ```rust
3285 /// use rug::Float;
3286 /// let f = Float::with_val(53, 25.0);
3287 /// let r = f.sqrt_ref();
3288 /// let sqrt = Float::with_val(53, r);
3289 /// assert_eq!(sqrt, 5.0);
3290 /// ```
3291 ///
3292 /// [`AssignRound`]: ops/trait.AssignRound.html
3293 /// [`Assign`]: trait.Assign.html
3294 /// [`Float`]: struct.Float.html
3295 /// [icv]: index.html#incomplete-computation-values
3296 #[inline]
sqrt_ref(&self) -> SqrtIncomplete<'_>3297 pub fn sqrt_ref(&self) -> SqrtIncomplete<'_> {
3298 SqrtIncomplete { ref_self: self }
3299 }
3300
3301 /// Computes the square root of `u`.
3302 ///
3303 /// The following are implemented with the returned
3304 /// [incomplete-computation value][icv] as `Src`:
3305 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
3306 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
3307 ///
3308 /// # Examples
3309 ///
3310 /// ```rust
3311 /// use rug::Float;
3312 /// let s = Float::sqrt_u(25);
3313 /// let f = Float::with_val(53, s);
3314 /// assert_eq!(f, 5.0);
3315 /// ```
3316 ///
3317 /// [`AssignRound`]: ops/trait.AssignRound.html
3318 /// [`Assign`]: trait.Assign.html
3319 /// [`Float`]: struct.Float.html
3320 /// [icv]: index.html#incomplete-computation-values
3321 #[inline]
sqrt_u(u: u32) -> SqrtUIncomplete3322 pub fn sqrt_u(u: u32) -> SqrtUIncomplete {
3323 SqrtUIncomplete { u }
3324 }
3325
3326 /// Computes the reciprocal square root, rounding to the nearest.
3327 ///
3328 /// # Examples
3329 ///
3330 /// ```rust
3331 /// use rug::Float;
3332 /// let f = Float::with_val(53, 16.0);
3333 /// let recip_sqrt = f.recip_sqrt();
3334 /// assert_eq!(recip_sqrt, 0.25);
3335 /// ```
3336 #[inline]
recip_sqrt(mut self) -> Self3337 pub fn recip_sqrt(mut self) -> Self {
3338 self.recip_sqrt_round(Round::Nearest);
3339 self
3340 }
3341
3342 /// Computes the reciprocal square root, rounding to the nearest.
3343 ///
3344 /// # Examples
3345 ///
3346 /// ```rust
3347 /// use rug::Float;
3348 /// let mut f = Float::with_val(53, 16.0);
3349 /// f.recip_sqrt_mut();
3350 /// assert_eq!(f, 0.25);
3351 /// ```
3352 #[inline]
recip_sqrt_mut(&mut self)3353 pub fn recip_sqrt_mut(&mut self) {
3354 self.recip_sqrt_round(Round::Nearest);
3355 }
3356
3357 /// Computes the reciprocal square root, applying the specified
3358 /// rounding method.
3359 ///
3360 /// # Examples
3361 ///
3362 /// ```rust
3363 /// use core::cmp::Ordering;
3364 /// use rug::{float::Round, Float};
3365 /// // 5 in binary is 101
3366 /// let mut f = Float::with_val(4, 5.0);
3367 /// // 1 / √5 in binary is 0.01110010...
3368 /// // 1 / √5 is rounded to 0.4375 (0.01110).
3369 /// let dir = f.recip_sqrt_round(Round::Nearest);
3370 /// assert_eq!(f, 0.4375);
3371 /// assert_eq!(dir, Ordering::Less);
3372 /// ```
3373 #[inline]
recip_sqrt_round(&mut self, round: Round) -> Ordering3374 pub fn recip_sqrt_round(&mut self, round: Round) -> Ordering {
3375 xmpfr::rec_sqrt(self, (), round)
3376 }
3377
3378 /// Computes the reciprocal square root.
3379 ///
3380 /// The following are implemented with the returned
3381 /// [incomplete-computation value][icv] as `Src`:
3382 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
3383 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
3384 ///
3385 /// # Examples
3386 ///
3387 /// ```rust
3388 /// use rug::Float;
3389 /// let f = Float::with_val(53, 16.0);
3390 /// let r = f.recip_sqrt_ref();
3391 /// let recip_sqrt = Float::with_val(53, r);
3392 /// assert_eq!(recip_sqrt, 0.25);
3393 /// ```
3394 ///
3395 /// [`AssignRound`]: ops/trait.AssignRound.html
3396 /// [`Assign`]: trait.Assign.html
3397 /// [`Float`]: struct.Float.html
3398 /// [icv]: index.html#incomplete-computation-values
3399 #[inline]
recip_sqrt_ref(&self) -> RecipSqrtIncomplete<'_>3400 pub fn recip_sqrt_ref(&self) -> RecipSqrtIncomplete<'_> {
3401 RecipSqrtIncomplete { ref_self: self }
3402 }
3403
3404 /// Computes the cube root, rounding to the nearest.
3405 ///
3406 /// # Examples
3407 ///
3408 /// ```rust
3409 /// use rug::Float;
3410 /// let f = Float::with_val(53, 125.0);
3411 /// let cbrt = f.cbrt();
3412 /// assert_eq!(cbrt, 5.0);
3413 /// ```
3414 #[inline]
cbrt(mut self) -> Self3415 pub fn cbrt(mut self) -> Self {
3416 self.cbrt_round(Round::Nearest);
3417 self
3418 }
3419
3420 /// Computes the cube root, rounding to the nearest.
3421 ///
3422 /// # Examples
3423 ///
3424 /// ```rust
3425 /// use rug::Float;
3426 /// let mut f = Float::with_val(53, 125.0);
3427 /// f.cbrt_mut();
3428 /// assert_eq!(f, 5.0);
3429 /// ```
3430 #[inline]
cbrt_mut(&mut self)3431 pub fn cbrt_mut(&mut self) {
3432 self.cbrt_round(Round::Nearest);
3433 }
3434
3435 /// Computes the cube root, applying the specified rounding
3436 /// method.
3437 ///
3438 /// # Examples
3439 ///
3440 /// ```rust
3441 /// use core::cmp::Ordering;
3442 /// use rug::{float::Round, Float};
3443 /// // 5 in binary is 101
3444 /// let mut f = Float::with_val(4, 5.0);
3445 /// // cbrt(5) in binary is 1.101101...
3446 /// // cbrt(5) is rounded to 1.75 (1.110).
3447 /// let dir = f.cbrt_round(Round::Nearest);
3448 /// assert_eq!(f, 1.75);
3449 /// assert_eq!(dir, Ordering::Greater);
3450 /// ```
3451 #[inline]
cbrt_round(&mut self, round: Round) -> Ordering3452 pub fn cbrt_round(&mut self, round: Round) -> Ordering {
3453 xmpfr::cbrt(self, (), round)
3454 }
3455
3456 /// Computes the cube root.
3457 ///
3458 /// The following are implemented with the returned
3459 /// [incomplete-computation value][icv] as `Src`:
3460 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
3461 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
3462 ///
3463 /// # Examples
3464 ///
3465 /// ```rust
3466 /// use rug::Float;
3467 /// let f = Float::with_val(53, 125.0);
3468 /// let r = f.cbrt_ref();
3469 /// let cbrt = Float::with_val(53, r);
3470 /// assert_eq!(cbrt, 5.0);
3471 /// ```
3472 ///
3473 /// [`AssignRound`]: ops/trait.AssignRound.html
3474 /// [`Assign`]: trait.Assign.html
3475 /// [`Float`]: struct.Float.html
3476 /// [icv]: index.html#incomplete-computation-values
3477 #[inline]
cbrt_ref(&self) -> CbrtIncomplete<'_>3478 pub fn cbrt_ref(&self) -> CbrtIncomplete<'_> {
3479 CbrtIncomplete { ref_self: self }
3480 }
3481
3482 /// Computes the <i>k</i>th root, rounding to the nearest.
3483 ///
3484 /// # Examples
3485 ///
3486 /// ```rust
3487 /// use rug::Float;
3488 /// let f = Float::with_val(53, 625.0);
3489 /// let root = f.root(4);
3490 /// assert_eq!(root, 5.0);
3491 /// ```
3492 #[inline]
root(mut self, k: u32) -> Self3493 pub fn root(mut self, k: u32) -> Self {
3494 self.root_round(k, Round::Nearest);
3495 self
3496 }
3497
3498 /// Computes the <i>k</i>th root, rounding to the nearest.
3499 ///
3500 /// # Examples
3501 ///
3502 /// ```rust
3503 /// use rug::Float;
3504 /// let mut f = Float::with_val(53, 625.0);
3505 /// f.root_mut(4);
3506 /// assert_eq!(f, 5.0);
3507 /// ```
3508 #[inline]
root_mut(&mut self, k: u32)3509 pub fn root_mut(&mut self, k: u32) {
3510 self.root_round(k, Round::Nearest);
3511 }
3512
3513 /// Computes the <i>k</i>th root, applying the specified
3514 /// rounding method.
3515 ///
3516 /// # Examples
3517 ///
3518 /// ```rust
3519 /// use core::cmp::Ordering;
3520 /// use rug::{float::Round, Float};
3521 /// // 5 in binary is 101
3522 /// let mut f = Float::with_val(4, 5.0);
3523 /// // fourth root of 5 in binary is 1.01111...
3524 /// // fourth root of 5 is rounded to 1.5 (1.100).
3525 /// let dir = f.root_round(4, Round::Nearest);
3526 /// assert_eq!(f, 1.5);
3527 /// assert_eq!(dir, Ordering::Greater);
3528 /// ```
3529 #[inline]
root_round(&mut self, k: u32, round: Round) -> Ordering3530 pub fn root_round(&mut self, k: u32, round: Round) -> Ordering {
3531 xmpfr::rootn_ui(self, (), k, round)
3532 }
3533
3534 /// Computes the <i>k</i>th root.
3535 ///
3536 /// The following are implemented with the returned
3537 /// [incomplete-computation value][icv] as `Src`:
3538 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
3539 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
3540 ///
3541 /// # Examples
3542 ///
3543 /// ```rust
3544 /// use rug::Float;
3545 /// let f = Float::with_val(53, 625.0);
3546 /// let r = f.root_ref(4);
3547 /// let root = Float::with_val(53, r);
3548 /// assert_eq!(root, 5.0);
3549 /// ```
3550 ///
3551 /// [`AssignRound`]: ops/trait.AssignRound.html
3552 /// [`Assign`]: trait.Assign.html
3553 /// [`Float`]: struct.Float.html
3554 /// [icv]: index.html#incomplete-computation-values
3555 #[inline]
root_ref(&self, k: u32) -> RootIncomplete<'_>3556 pub fn root_ref(&self, k: u32) -> RootIncomplete<'_> {
3557 RootIncomplete { ref_self: self, k }
3558 }
3559
3560 /// Computes the absolute value.
3561 ///
3562 /// # Examples
3563 ///
3564 /// ```rust
3565 /// use rug::Float;
3566 /// let f = Float::with_val(53, -23.5);
3567 /// let abs = f.abs();
3568 /// assert_eq!(abs, 23.5);
3569 /// ```
3570 #[inline]
abs(mut self) -> Self3571 pub fn abs(mut self) -> Self {
3572 self.abs_mut();
3573 self
3574 }
3575
3576 /// Computes the absolute value.
3577 ///
3578 /// # Examples
3579 ///
3580 /// ```rust
3581 /// use rug::Float;
3582 /// let mut f = Float::with_val(53, -23.5);
3583 /// f.abs_mut();
3584 /// assert_eq!(f, 23.5);
3585 /// ```
3586 #[inline]
abs_mut(&mut self)3587 pub fn abs_mut(&mut self) {
3588 xmpfr::abs(self, (), Round::Nearest);
3589 }
3590
3591 /// Computes the absolute value.
3592 ///
3593 /// The following are implemented with the returned
3594 /// [incomplete-computation value][icv] as `Src`:
3595 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
3596 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
3597 ///
3598 /// # Examples
3599 ///
3600 /// ```rust
3601 /// use rug::Float;
3602 /// let f = Float::with_val(53, -23.5);
3603 /// let r = f.abs_ref();
3604 /// let abs = Float::with_val(53, r);
3605 /// assert_eq!(abs, 23.5);
3606 /// ```
3607 ///
3608 /// [`AssignRound`]: ops/trait.AssignRound.html
3609 /// [`Assign`]: trait.Assign.html
3610 /// [`Float`]: struct.Float.html
3611 /// [icv]: index.html#incomplete-computation-values
3612 #[inline]
abs_ref(&self) -> AbsIncomplete<'_>3613 pub fn abs_ref(&self) -> AbsIncomplete<'_> {
3614 AbsIncomplete { ref_self: self }
3615 }
3616
3617 /// Computes the signum.
3618 ///
3619 /// * 1.0 if the value is positive, +0.0 or +∞
3620 /// * −1.0 if the value is negative, −0.0 or −∞
3621 /// * NaN if the value is NaN
3622 ///
3623 /// # Examples
3624 ///
3625 /// ```rust
3626 /// use rug::Float;
3627 /// assert_eq!(Float::with_val(53, -23.5).signum(), -1);
3628 /// assert_eq!(Float::with_val(53, -0.0).signum(), -1);
3629 /// assert_eq!(Float::with_val(53, 0.0).signum(), 1);
3630 /// assert_eq!(Float::with_val(53, 23.5).signum(), 1);
3631 /// ```
3632 #[inline]
signum(mut self) -> Self3633 pub fn signum(mut self) -> Self {
3634 self.signum_mut();
3635 self
3636 }
3637
3638 /// Computes the signum.
3639 ///
3640 /// * 1.0 if the value is positive, +0.0 or +∞
3641 /// * −1.0 if the value is negative, −0.0 or −∞
3642 /// * NaN if the value is NaN
3643 ///
3644 /// # Examples
3645 ///
3646 /// ```rust
3647 /// use rug::Float;
3648 /// let mut f = Float::with_val(53, -23.5);
3649 /// f.signum_mut();
3650 /// assert_eq!(f, -1);
3651 /// ```
3652 #[inline]
signum_mut(&mut self)3653 pub fn signum_mut(&mut self) {
3654 xmpfr::signum(self, (), Round::Nearest);
3655 }
3656
3657 /// Computes the signum.
3658 ///
3659 /// * 1.0 if the value is positive, +0.0 or +∞
3660 /// * −1.0 if the value is negative, −0.0 or −∞
3661 /// * NaN if the value is NaN
3662 ///
3663 /// The following are implemented with the returned
3664 /// [incomplete-computation value][icv] as `Src`:
3665 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
3666 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
3667 ///
3668 /// # Examples
3669 ///
3670 /// ```rust
3671 /// use rug::Float;
3672 /// let f = Float::with_val(53, -23.5);
3673 /// let r = f.signum_ref();
3674 /// let signum = Float::with_val(53, r);
3675 /// assert_eq!(signum, -1);
3676 /// ```
3677 ///
3678 /// [`AssignRound`]: ops/trait.AssignRound.html
3679 /// [`Assign`]: trait.Assign.html
3680 /// [`Float`]: struct.Float.html
3681 /// [icv]: index.html#incomplete-computation-values
3682 #[inline]
signum_ref(&self) -> SignumIncomplete<'_>3683 pub fn signum_ref(&self) -> SignumIncomplete<'_> {
3684 SignumIncomplete { ref_self: self }
3685 }
3686
3687 /// Returns a number with the magnitude of `self` and the sign
3688 /// of `y`.
3689 ///
3690 /// # Examples
3691 ///
3692 /// ```rust
3693 /// use rug::Float;
3694 /// let x = Float::with_val(53, 23.0);
3695 /// let y = Float::with_val(53, -1.0);
3696 /// let copysign = x.copysign(&y);
3697 /// assert_eq!(copysign, -23.0);
3698 /// ```
3699 #[inline]
copysign(mut self, y: &Self) -> Self3700 pub fn copysign(mut self, y: &Self) -> Self {
3701 self.copysign_mut(y);
3702 self
3703 }
3704
3705 /// Retains the magnitude of `self` and copies the sign of
3706 /// `y`.
3707 ///
3708 /// # Examples
3709 ///
3710 /// ```rust
3711 /// use rug::Float;
3712 /// let mut x = Float::with_val(53, 23.0);
3713 /// let y = Float::with_val(53, -1.0);
3714 /// x.copysign_mut(&y);
3715 /// assert_eq!(x, -23.0);
3716 /// ```
3717 #[inline]
copysign_mut(&mut self, y: &Self)3718 pub fn copysign_mut(&mut self, y: &Self) {
3719 xmpfr::copysign(self, (), y, Round::Nearest);
3720 }
3721
3722 /// Computes a number with the magnitude of `self` and the
3723 /// sign of `y`.
3724 ///
3725 /// The following are implemented with the returned
3726 /// [incomplete-computation value][icv] as `Src`:
3727 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
3728 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
3729 ///
3730 /// # Examples
3731 ///
3732 /// ```rust
3733 /// use rug::Float;
3734 /// let x = Float::with_val(53, 23.0);
3735 /// let y = Float::with_val(53, -1.0);
3736 /// let r = x.copysign_ref(&y);
3737 /// let copysign = Float::with_val(53, r);
3738 /// assert_eq!(copysign, -23.0);
3739 /// ```
3740 ///
3741 /// [`AssignRound`]: ops/trait.AssignRound.html
3742 /// [`Assign`]: trait.Assign.html
3743 /// [`Float`]: struct.Float.html
3744 /// [icv]: index.html#incomplete-computation-values
3745 #[inline]
copysign_ref<'a>(&'a self, y: &'a Self) -> CopysignIncomplete<'_>3746 pub fn copysign_ref<'a>(&'a self, y: &'a Self) -> CopysignIncomplete<'_> {
3747 CopysignIncomplete { ref_self: self, y }
3748 }
3749
3750 /// Clamps the value within the specified bounds, rounding to the
3751 /// nearest.
3752 ///
3753 /// # Panics
3754 ///
3755 /// Panics if the maximum value is less than the minimum value,
3756 /// unless assigning any of them to `self` produces the same value
3757 /// with the same rounding direction.
3758 ///
3759 /// # Examples
3760 ///
3761 /// ```rust
3762 /// use rug::Float;
3763 /// let min = -1.5;
3764 /// let max = 1.5;
3765 /// let too_small = Float::with_val(53, -2.5);
3766 /// let clamped1 = too_small.clamp(&min, &max);
3767 /// assert_eq!(clamped1, -1.5);
3768 /// let in_range = Float::with_val(53, 0.5);
3769 /// let clamped2 = in_range.clamp(&min, &max);
3770 /// assert_eq!(clamped2, 0.5);
3771 /// ```
3772 #[inline]
clamp<Min, Max>(mut self, min: &Min, max: &Max) -> Self where Self: PartialOrd<Min> + PartialOrd<Max> + for<'a> AssignRound<&'a Min, Round = Round, Ordering = Ordering> + for<'a> AssignRound<&'a Max, Round = Round, Ordering = Ordering>,3773 pub fn clamp<Min, Max>(mut self, min: &Min, max: &Max) -> Self
3774 where
3775 Self: PartialOrd<Min>
3776 + PartialOrd<Max>
3777 + for<'a> AssignRound<&'a Min, Round = Round, Ordering = Ordering>
3778 + for<'a> AssignRound<&'a Max, Round = Round, Ordering = Ordering>,
3779 {
3780 self.clamp_round(min, max, Round::Nearest);
3781 self
3782 }
3783
3784 /// Clamps the value within the specified bounds, rounding to the
3785 /// nearest.
3786 ///
3787 /// # Panics
3788 ///
3789 /// Panics if the maximum value is less than the minimum value,
3790 /// unless assigning any of them to `self` produces the same value
3791 /// with the same rounding direction.
3792 ///
3793 /// # Examples
3794 ///
3795 /// ```rust
3796 /// use rug::Float;
3797 /// let min = -1.5;
3798 /// let max = 1.5;
3799 /// let mut too_small = Float::with_val(53, -2.5);
3800 /// too_small.clamp_mut(&min, &max);
3801 /// assert_eq!(too_small, -1.5);
3802 /// let mut in_range = Float::with_val(53, 0.5);
3803 /// in_range.clamp_mut(&min, &max);
3804 /// assert_eq!(in_range, 0.5);
3805 /// ```
3806 #[inline]
clamp_mut<Min, Max>(&mut self, min: &Min, max: &Max) where Self: PartialOrd<Min> + PartialOrd<Max> + for<'a> AssignRound<&'a Min, Round = Round, Ordering = Ordering> + for<'a> AssignRound<&'a Max, Round = Round, Ordering = Ordering>,3807 pub fn clamp_mut<Min, Max>(&mut self, min: &Min, max: &Max)
3808 where
3809 Self: PartialOrd<Min>
3810 + PartialOrd<Max>
3811 + for<'a> AssignRound<&'a Min, Round = Round, Ordering = Ordering>
3812 + for<'a> AssignRound<&'a Max, Round = Round, Ordering = Ordering>,
3813 {
3814 self.clamp_round(min, max, Round::Nearest);
3815 }
3816
3817 /// Clamps the value within the specified bounds, applying the
3818 /// specified rounding method.
3819 ///
3820 /// # Panics
3821 ///
3822 /// Panics if the maximum value is less than the minimum value,
3823 /// unless assigning any of them to `self` produces the same value
3824 /// with the same rounding direction.
3825 ///
3826 /// # Examples
3827 ///
3828 /// ```rust
3829 /// use core::cmp::Ordering;
3830 /// use rug::{float::Round, Float};
3831 /// let min = Float::with_val(53, -1.5);
3832 /// let max = Float::with_val(53, 1.5);
3833 /// let mut too_small = Float::with_val(53, -2.5);
3834 /// let dir1 = too_small.clamp_round(&min, &max, Round::Nearest);
3835 /// assert_eq!(too_small, -1.5);
3836 /// assert_eq!(dir1, Ordering::Equal);
3837 /// let mut in_range = Float::with_val(53, 0.5);
3838 /// let dir2 = in_range.clamp_round(&min, &max, Round::Nearest);
3839 /// assert_eq!(in_range, 0.5);
3840 /// assert_eq!(dir2, Ordering::Equal);
3841 /// ```
clamp_round<Min, Max>(&mut self, min: &Min, max: &Max, round: Round) -> Ordering where Self: PartialOrd<Min> + PartialOrd<Max> + for<'a> AssignRound<&'a Min, Round = Round, Ordering = Ordering> + for<'a> AssignRound<&'a Max, Round = Round, Ordering = Ordering>,3842 pub fn clamp_round<Min, Max>(&mut self, min: &Min, max: &Max, round: Round) -> Ordering
3843 where
3844 Self: PartialOrd<Min>
3845 + PartialOrd<Max>
3846 + for<'a> AssignRound<&'a Min, Round = Round, Ordering = Ordering>
3847 + for<'a> AssignRound<&'a Max, Round = Round, Ordering = Ordering>,
3848 {
3849 if (*self).lt(min) {
3850 let dir = self.assign_round(min, round);
3851 if (*self).gt(max) {
3852 let dir2 = self.assign_round(max, round);
3853 assert!(
3854 dir == dir2 && !(*self).lt(min),
3855 "minimum larger than maximum"
3856 );
3857 dir
3858 } else {
3859 dir
3860 }
3861 } else if (*self).gt(max) {
3862 let dir = self.assign_round(max, round);
3863 if (*self).lt(min) {
3864 let dir2 = self.assign_round(min, round);
3865 assert!(
3866 dir == dir2 && !(*self).gt(max),
3867 "minimum larger than maximum"
3868 );
3869 dir
3870 } else {
3871 dir
3872 }
3873 } else {
3874 if self.is_nan() {
3875 xmpfr::set_nanflag();
3876 }
3877 Ordering::Equal
3878 }
3879 }
3880
3881 /// Clamps the value within the specified bounds.
3882 ///
3883 /// The following are implemented with the returned
3884 /// [incomplete-computation value][icv] as `Src`:
3885 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
3886 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
3887 ///
3888 /// # Panics
3889 ///
3890 /// Panics if the maximum value is less than the minimum value,
3891 /// unless assigning any of them to the target produces the same
3892 /// value with the same rounding direction.
3893 ///
3894 /// # Examples
3895 ///
3896 /// ```rust
3897 /// use rug::Float;
3898 /// let min = -1.5;
3899 /// let max = 1.5;
3900 /// let too_small = Float::with_val(53, -2.5);
3901 /// let r1 = too_small.clamp_ref(&min, &max);
3902 /// let clamped1 = Float::with_val(53, r1);
3903 /// assert_eq!(clamped1, -1.5);
3904 /// let in_range = Float::with_val(53, 0.5);
3905 /// let r2 = in_range.clamp_ref(&min, &max);
3906 /// let clamped2 = Float::with_val(53, r2);
3907 /// assert_eq!(clamped2, 0.5);
3908 /// ```
3909 ///
3910 /// [`AssignRound`]: ops/trait.AssignRound.html
3911 /// [`Assign`]: trait.Assign.html
3912 /// [`Float`]: struct.Float.html
3913 /// [icv]: index.html#incomplete-computation-values
3914 #[inline]
clamp_ref<'min, 'max, Min, Max>( &self, min: &'min Min, max: &'max Max, ) -> ClampIncomplete<'_, 'min, 'max, Min, Max> where Self: PartialOrd<Min> + PartialOrd<Max> + for<'a> AssignRound<&'a Min, Round = Round, Ordering = Ordering> + for<'a> AssignRound<&'a Max, Round = Round, Ordering = Ordering>,3915 pub fn clamp_ref<'min, 'max, Min, Max>(
3916 &self,
3917 min: &'min Min,
3918 max: &'max Max,
3919 ) -> ClampIncomplete<'_, 'min, 'max, Min, Max>
3920 where
3921 Self: PartialOrd<Min>
3922 + PartialOrd<Max>
3923 + for<'a> AssignRound<&'a Min, Round = Round, Ordering = Ordering>
3924 + for<'a> AssignRound<&'a Max, Round = Round, Ordering = Ordering>,
3925 {
3926 ClampIncomplete {
3927 ref_self: self,
3928 min,
3929 max,
3930 }
3931 }
3932
3933 /// Computes the reciprocal, rounding to the nearest.
3934 ///
3935 /// # Examples
3936 ///
3937 /// ```rust
3938 /// use rug::Float;
3939 /// let f = Float::with_val(53, -0.25);
3940 /// let recip = f.recip();
3941 /// assert_eq!(recip, -4.0);
3942 /// ```
3943 #[inline]
recip(mut self) -> Self3944 pub fn recip(mut self) -> Self {
3945 self.recip_round(Round::Nearest);
3946 self
3947 }
3948
3949 /// Computes the reciprocal, rounding to the nearest.
3950 ///
3951 /// # Examples
3952 ///
3953 /// ```rust
3954 /// use rug::Float;
3955 /// let mut f = Float::with_val(53, -0.25);
3956 /// f.recip_mut();
3957 /// assert_eq!(f, -4.0);
3958 /// ```
3959 #[inline]
recip_mut(&mut self)3960 pub fn recip_mut(&mut self) {
3961 self.recip_round(Round::Nearest);
3962 }
3963
3964 /// Computes the reciprocal, applying the specified rounding
3965 /// method.
3966 ///
3967 /// # Examples
3968 ///
3969 /// ```rust
3970 /// use core::cmp::Ordering;
3971 /// use rug::{float::Round, Float};
3972 /// // 5 in binary is 101
3973 /// let mut f = Float::with_val(4, -5.0);
3974 /// // 1/5 in binary is 0.00110011...
3975 /// // 1/5 is rounded to 0.203125 (0.001101).
3976 /// let dir = f.recip_round(Round::Nearest);
3977 /// assert_eq!(f, -0.203125);
3978 /// assert_eq!(dir, Ordering::Less);
3979 /// ```
3980 #[inline]
recip_round(&mut self, round: Round) -> Ordering3981 pub fn recip_round(&mut self, round: Round) -> Ordering {
3982 xmpfr::recip(self, (), round)
3983 }
3984
3985 /// Computes the reciprocal.
3986 ///
3987 /// The following are implemented with the returned
3988 /// [incomplete-computation value][icv] as `Src`:
3989 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
3990 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
3991 ///
3992 /// # Examples
3993 ///
3994 /// ```rust
3995 /// use rug::Float;
3996 /// let f = Float::with_val(53, -0.25);
3997 /// let r = f.recip_ref();
3998 /// let recip = Float::with_val(53, r);
3999 /// assert_eq!(recip, -4.0);
4000 /// ```
4001 ///
4002 /// [`AssignRound`]: ops/trait.AssignRound.html
4003 /// [`Assign`]: trait.Assign.html
4004 /// [`Float`]: struct.Float.html
4005 /// [icv]: index.html#incomplete-computation-values
4006 #[inline]
recip_ref(&self) -> RecipIncomplete<'_>4007 pub fn recip_ref(&self) -> RecipIncomplete<'_> {
4008 RecipIncomplete { ref_self: self }
4009 }
4010
4011 /// Finds the minimum, rounding to the nearest.
4012 ///
4013 /// # Examples
4014 ///
4015 /// ```rust
4016 /// use rug::Float;
4017 /// let a = Float::with_val(53, 5.2);
4018 /// let b = Float::with_val(53, -2);
4019 /// let min = a.min(&b);
4020 /// assert_eq!(min, -2);
4021 /// ```
4022 #[inline]
min(mut self, other: &Self) -> Self4023 pub fn min(mut self, other: &Self) -> Self {
4024 self.min_round(other, Round::Nearest);
4025 self
4026 }
4027
4028 /// Finds the minimum, rounding to the nearest.
4029 ///
4030 /// # Examples
4031 ///
4032 /// ```rust
4033 /// use rug::Float;
4034 /// let mut a = Float::with_val(53, 5.2);
4035 /// let b = Float::with_val(53, -2);
4036 /// a.min_mut(&b);
4037 /// assert_eq!(a, -2);
4038 /// ```
4039 #[inline]
min_mut(&mut self, other: &Self)4040 pub fn min_mut(&mut self, other: &Self) {
4041 self.min_round(other, Round::Nearest);
4042 }
4043
4044 /// Finds the minimum, applying the specified rounding method.
4045 ///
4046 /// # Examples
4047 ///
4048 /// ```rust
4049 /// use core::cmp::Ordering;
4050 /// use rug::{float::Round, Float};
4051 /// let mut a = Float::with_val(53, 5.2);
4052 /// let b = Float::with_val(53, -2);
4053 /// let dir = a.min_round(&b, Round::Nearest);
4054 /// assert_eq!(a, -2);
4055 /// assert_eq!(dir, Ordering::Equal);
4056 /// ```
4057 #[inline]
min_round(&mut self, other: &Self, round: Round) -> Ordering4058 pub fn min_round(&mut self, other: &Self, round: Round) -> Ordering {
4059 xmpfr::min(self, (), other, round)
4060 }
4061
4062 /// Finds the minimum.
4063 ///
4064 /// The following are implemented with the returned
4065 /// [incomplete-computation value][icv] as `Src`:
4066 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
4067 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
4068 ///
4069 /// # Examples
4070 ///
4071 /// ```rust
4072 /// use rug::Float;
4073 /// let a = Float::with_val(53, 5.2);
4074 /// let b = Float::with_val(53, -2);
4075 /// let r = a.min_ref(&b);
4076 /// let min = Float::with_val(53, r);
4077 /// assert_eq!(min, -2);
4078 /// ```
4079 ///
4080 /// [`AssignRound`]: ops/trait.AssignRound.html
4081 /// [`Assign`]: trait.Assign.html
4082 /// [`Float`]: struct.Float.html
4083 /// [icv]: index.html#incomplete-computation-values
4084 #[inline]
min_ref<'a>(&'a self, other: &'a Self) -> MinIncomplete<'_>4085 pub fn min_ref<'a>(&'a self, other: &'a Self) -> MinIncomplete<'_> {
4086 MinIncomplete {
4087 ref_self: self,
4088 other,
4089 }
4090 }
4091
4092 /// Finds the maximum, rounding to the nearest.
4093 ///
4094 /// # Examples
4095 ///
4096 /// ```rust
4097 /// use rug::Float;
4098 /// let a = Float::with_val(53, 5.2);
4099 /// let b = Float::with_val(53, 12.5);
4100 /// let max = a.max(&b);
4101 /// assert_eq!(max, 12.5);
4102 /// ```
4103 #[inline]
max(mut self, other: &Self) -> Self4104 pub fn max(mut self, other: &Self) -> Self {
4105 self.max_round(other, Round::Nearest);
4106 self
4107 }
4108
4109 /// Finds the maximum, rounding to the nearest.
4110 ///
4111 /// # Examples
4112 ///
4113 /// ```rust
4114 /// use rug::Float;
4115 /// let mut a = Float::with_val(53, 5.2);
4116 /// let b = Float::with_val(53, 12.5);
4117 /// a.max_mut(&b);
4118 /// assert_eq!(a, 12.5);
4119 /// ```
4120 #[inline]
max_mut(&mut self, other: &Self)4121 pub fn max_mut(&mut self, other: &Self) {
4122 self.max_round(other, Round::Nearest);
4123 }
4124
4125 /// Finds the maximum, applying the specified rounding method.
4126 ///
4127 /// # Examples
4128 ///
4129 /// ```rust
4130 /// use core::cmp::Ordering;
4131 /// use rug::{float::Round, Float};
4132 /// let mut a = Float::with_val(53, 5.2);
4133 /// let b = Float::with_val(53, 12.5);
4134 /// let dir = a.max_round(&b, Round::Nearest);
4135 /// assert_eq!(a, 12.5);
4136 /// assert_eq!(dir, Ordering::Equal);
4137 /// ```
4138 #[inline]
max_round(&mut self, other: &Self, round: Round) -> Ordering4139 pub fn max_round(&mut self, other: &Self, round: Round) -> Ordering {
4140 xmpfr::max(self, (), other, round)
4141 }
4142
4143 /// Finds the maximum.
4144 ///
4145 /// The following are implemented with the returned
4146 /// [incomplete-computation value][icv] as `Src`:
4147 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
4148 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
4149 ///
4150 /// # Examples
4151 ///
4152 /// ```rust
4153 /// use rug::Float;
4154 /// let a = Float::with_val(53, 5.2);
4155 /// let b = Float::with_val(53, 12.5);
4156 /// let r = a.max_ref(&b);
4157 /// let max = Float::with_val(53, r);
4158 /// assert_eq!(max, 12.5);
4159 /// ```
4160 ///
4161 /// [`AssignRound`]: ops/trait.AssignRound.html
4162 /// [`Assign`]: trait.Assign.html
4163 /// [`Float`]: struct.Float.html
4164 /// [icv]: index.html#incomplete-computation-values
4165 #[inline]
max_ref<'a>(&'a self, other: &'a Self) -> MaxIncomplete<'_>4166 pub fn max_ref<'a>(&'a self, other: &'a Self) -> MaxIncomplete<'_> {
4167 MaxIncomplete {
4168 ref_self: self,
4169 other,
4170 }
4171 }
4172
4173 /// Computes the positive difference between `self` and
4174 /// `other`, rounding to the nearest.
4175 ///
4176 /// The positive difference is `self` − `other` if `self` >
4177 /// `other`, zero if `self` ≤ `other`, or NaN if any operand
4178 /// is NaN.
4179 ///
4180 /// # Examples
4181 ///
4182 /// ```rust
4183 /// use rug::Float;
4184 /// let a = Float::with_val(53, 12.5);
4185 /// let b = Float::with_val(53, 7.3);
4186 /// let diff1 = a.positive_diff(&b);
4187 /// assert_eq!(diff1, 5.2);
4188 /// let diff2 = diff1.positive_diff(&b);
4189 /// assert_eq!(diff2, 0);
4190 /// ```
4191 #[inline]
positive_diff(mut self, other: &Self) -> Self4192 pub fn positive_diff(mut self, other: &Self) -> Self {
4193 self.positive_diff_round(other, Round::Nearest);
4194 self
4195 }
4196
4197 /// Computes the positive difference between `self` and
4198 /// `other`, rounding to the nearest.
4199 ///
4200 /// The positive difference is `self` − `other` if `self` >
4201 /// `other`, zero if `self` ≤ `other`, or NaN if any operand
4202 /// is NaN.
4203 ///
4204 /// # Examples
4205 ///
4206 /// ```rust
4207 /// use rug::Float;
4208 /// let mut a = Float::with_val(53, 12.5);
4209 /// let b = Float::with_val(53, 7.3);
4210 /// a.positive_diff_mut(&b);
4211 /// assert_eq!(a, 5.2);
4212 /// a.positive_diff_mut(&b);
4213 /// assert_eq!(a, 0);
4214 /// ```
4215 #[inline]
positive_diff_mut(&mut self, other: &Self)4216 pub fn positive_diff_mut(&mut self, other: &Self) {
4217 self.positive_diff_round(other, Round::Nearest);
4218 }
4219
4220 /// Computes the positive difference between `self` and
4221 /// `other`, applying the specified rounding method.
4222 ///
4223 /// The positive difference is `self` − `other` if `self` >
4224 /// `other`, zero if `self` ≤ `other`, or NaN if any operand
4225 /// is NaN.
4226 ///
4227 /// # Examples
4228 ///
4229 /// ```rust
4230 /// use core::cmp::Ordering;
4231 /// use rug::{float::Round, Float};
4232 /// let mut a = Float::with_val(53, 12.5);
4233 /// let b = Float::with_val(53, 7.3);
4234 /// let dir = a.positive_diff_round(&b, Round::Nearest);
4235 /// assert_eq!(a, 5.2);
4236 /// assert_eq!(dir, Ordering::Equal);
4237 /// let dir = a.positive_diff_round(&b, Round::Nearest);
4238 /// assert_eq!(a, 0);
4239 /// assert_eq!(dir, Ordering::Equal);
4240 /// ```
4241 #[inline]
positive_diff_round(&mut self, other: &Self, round: Round) -> Ordering4242 pub fn positive_diff_round(&mut self, other: &Self, round: Round) -> Ordering {
4243 xmpfr::dim(self, (), other, round)
4244 }
4245
4246 /// Computes the positive difference.
4247 ///
4248 /// The positive difference is `self` − `other` if `self` >
4249 /// `other`, zero if `self` ≤ `other`, or NaN if any operand
4250 /// is NaN.
4251 ///
4252 /// The following are implemented with the returned
4253 /// [incomplete-computation value][icv] as `Src`:
4254 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
4255 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
4256 ///
4257 /// # Examples
4258 ///
4259 /// ```rust
4260 /// use rug::Float;
4261 /// let a = Float::with_val(53, 12.5);
4262 /// let b = Float::with_val(53, 7.3);
4263 /// let rab = a.positive_diff_ref(&b);
4264 /// let ab = Float::with_val(53, rab);
4265 /// assert_eq!(ab, 5.2);
4266 /// let rba = b.positive_diff_ref(&a);
4267 /// let ba = Float::with_val(53, rba);
4268 /// assert_eq!(ba, 0);
4269 /// ```
4270 ///
4271 /// [`AssignRound`]: ops/trait.AssignRound.html
4272 /// [`Assign`]: trait.Assign.html
4273 /// [`Float`]: struct.Float.html
4274 /// [icv]: index.html#incomplete-computation-values
4275 #[inline]
positive_diff_ref<'a>(&'a self, other: &'a Self) -> PositiveDiffIncomplete<'_>4276 pub fn positive_diff_ref<'a>(&'a self, other: &'a Self) -> PositiveDiffIncomplete<'_> {
4277 PositiveDiffIncomplete {
4278 ref_self: self,
4279 other,
4280 }
4281 }
4282
4283 /// Computes the natural logarithm, rounding to the nearest.
4284 ///
4285 /// # Examples
4286 ///
4287 /// ```rust
4288 /// use rug::Float;
4289 /// let f = Float::with_val(53, 1.5);
4290 /// let ln = f.ln();
4291 /// let expected = 0.4055_f64;
4292 /// assert!((ln - expected).abs() < 0.0001);
4293 /// ```
4294 #[inline]
ln(mut self) -> Self4295 pub fn ln(mut self) -> Self {
4296 self.ln_round(Round::Nearest);
4297 self
4298 }
4299
4300 /// Computes the natural logarithm, rounding to the nearest.
4301 ///
4302 /// # Examples
4303 ///
4304 /// ```rust
4305 /// use rug::Float;
4306 /// let mut f = Float::with_val(53, 1.5);
4307 /// f.ln_mut();
4308 /// let expected = 0.4055_f64;
4309 /// assert!((f - expected).abs() < 0.0001);
4310 /// ```
4311 #[inline]
ln_mut(&mut self)4312 pub fn ln_mut(&mut self) {
4313 self.ln_round(Round::Nearest);
4314 }
4315
4316 /// Computes the natural logarithm, applying the specified
4317 /// rounding method.
4318 ///
4319 /// # Examples
4320 ///
4321 /// ```rust
4322 /// use core::cmp::Ordering;
4323 /// use rug::{float::Round, Float};
4324 /// // Use only 4 bits of precision to show rounding.
4325 /// let mut f = Float::with_val(4, 1.5);
4326 /// // ln(1.5) = 0.4055
4327 /// // using 4 significant bits: 0.40625
4328 /// let dir = f.ln_round(Round::Nearest);
4329 /// assert_eq!(f, 0.40625);
4330 /// assert_eq!(dir, Ordering::Greater);
4331 /// ```
4332 #[inline]
ln_round(&mut self, round: Round) -> Ordering4333 pub fn ln_round(&mut self, round: Round) -> Ordering {
4334 xmpfr::log(self, (), round)
4335 }
4336
4337 /// Computes the natural logarithm.
4338 ///
4339 /// The following are implemented with the returned
4340 /// [incomplete-computation value][icv] as `Src`:
4341 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
4342 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
4343 ///
4344 /// # Examples
4345 ///
4346 /// ```rust
4347 /// use rug::Float;
4348 /// let f = Float::with_val(53, 1.5);
4349 /// let ln = Float::with_val(53, f.ln_ref());
4350 /// let expected = 0.4055_f64;
4351 /// assert!((ln - expected).abs() < 0.0001);
4352 /// ```
4353 ///
4354 /// [`AssignRound`]: ops/trait.AssignRound.html
4355 /// [`Assign`]: trait.Assign.html
4356 /// [`Float`]: struct.Float.html
4357 /// [icv]: index.html#incomplete-computation-values
4358 #[inline]
ln_ref(&self) -> LnIncomplete<'_>4359 pub fn ln_ref(&self) -> LnIncomplete<'_> {
4360 LnIncomplete { ref_self: self }
4361 }
4362
4363 /// Computes the natural logarithm of `u`.
4364 ///
4365 /// The following are implemented with the returned
4366 /// [incomplete-computation value][icv] as `Src`:
4367 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
4368 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
4369 ///
4370 /// # Examples
4371 ///
4372 /// ```rust
4373 /// use rug::Float;
4374 /// let l = Float::ln_u(3);
4375 /// let f = Float::with_val(53, l);
4376 /// let expected = 1.0986f64;
4377 /// assert!((f - expected).abs() < 0.0001);
4378 /// ```
4379 ///
4380 /// [`AssignRound`]: ops/trait.AssignRound.html
4381 /// [`Assign`]: trait.Assign.html
4382 /// [`Float`]: struct.Float.html
4383 /// [icv]: index.html#incomplete-computation-values
4384 #[inline]
ln_u(u: u32) -> LnUIncomplete4385 pub fn ln_u(u: u32) -> LnUIncomplete {
4386 LnUIncomplete { u }
4387 }
4388
4389 /// Computes the logarithm to base 2, rounding to the nearest.
4390 ///
4391 /// # Examples
4392 ///
4393 /// ```rust
4394 /// use rug::Float;
4395 /// let f = Float::with_val(53, 1.5);
4396 /// let log2 = f.log2();
4397 /// let expected = 0.5850_f64;
4398 /// assert!((log2 - expected).abs() < 0.0001);
4399 /// ```
4400 #[inline]
log2(mut self) -> Self4401 pub fn log2(mut self) -> Self {
4402 self.log2_round(Round::Nearest);
4403 self
4404 }
4405
4406 /// Computes the logarithm to base 2, rounding to the nearest.
4407 ///
4408 /// # Examples
4409 ///
4410 /// ```rust
4411 /// use rug::Float;
4412 /// let mut f = Float::with_val(53, 1.5);
4413 /// f.log2_mut();
4414 /// let expected = 0.5850_f64;
4415 /// assert!((f - expected).abs() < 0.0001);
4416 /// ```
4417 #[inline]
log2_mut(&mut self)4418 pub fn log2_mut(&mut self) {
4419 self.log2_round(Round::Nearest);
4420 }
4421
4422 /// Computes the logarithm to base 2, applying the specified
4423 /// rounding method.
4424 ///
4425 /// # Examples
4426 ///
4427 /// ```rust
4428 /// use core::cmp::Ordering;
4429 /// use rug::{float::Round, Float};
4430 /// // Use only 4 bits of precision to show rounding.
4431 /// let mut f = Float::with_val(4, 1.5);
4432 /// // log2(1.5) = 0.5850
4433 /// // using 4 significant bits: 0.5625
4434 /// let dir = f.log2_round(Round::Nearest);
4435 /// assert_eq!(f, 0.5625);
4436 /// assert_eq!(dir, Ordering::Less);
4437 /// ```
4438 #[inline]
log2_round(&mut self, round: Round) -> Ordering4439 pub fn log2_round(&mut self, round: Round) -> Ordering {
4440 xmpfr::log2(self, (), round)
4441 }
4442
4443 /// Computes the logarithm to base 2.
4444 ///
4445 /// The following are implemented with the returned
4446 /// [incomplete-computation value][icv] as `Src`:
4447 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
4448 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
4449 ///
4450 /// # Examples
4451 ///
4452 /// ```rust
4453 /// use rug::Float;
4454 /// let f = Float::with_val(53, 1.5);
4455 /// let log2 = Float::with_val(53, f.log2_ref());
4456 /// let expected = 0.5850_f64;
4457 /// assert!((log2 - expected).abs() < 0.0001);
4458 /// ```
4459 ///
4460 /// [`AssignRound`]: ops/trait.AssignRound.html
4461 /// [`Assign`]: trait.Assign.html
4462 /// [`Float`]: struct.Float.html
4463 /// [icv]: index.html#incomplete-computation-values
4464 #[inline]
log2_ref(&self) -> Log2Incomplete<'_>4465 pub fn log2_ref(&self) -> Log2Incomplete<'_> {
4466 Log2Incomplete { ref_self: self }
4467 }
4468
4469 /// Computes the logarithm to base 10, rounding to the nearest.
4470 ///
4471 /// # Examples
4472 ///
4473 /// ```rust
4474 /// use rug::Float;
4475 /// let f = Float::with_val(53, 1.5);
4476 /// let log10 = f.log10();
4477 /// let expected = 0.1761_f64;
4478 /// assert!((log10 - expected).abs() < 0.0001);
4479 /// ```
4480 #[inline]
log10(mut self) -> Self4481 pub fn log10(mut self) -> Self {
4482 self.log10_round(Round::Nearest);
4483 self
4484 }
4485
4486 /// Computes the logarithm to base 10, rounding to the nearest.
4487 ///
4488 /// # Examples
4489 ///
4490 /// ```rust
4491 /// use rug::Float;
4492 /// let mut f = Float::with_val(53, 1.5);
4493 /// f.log10_mut();
4494 /// let expected = 0.1761_f64;
4495 /// assert!((f - expected).abs() < 0.0001);
4496 /// ```
4497 #[inline]
log10_mut(&mut self)4498 pub fn log10_mut(&mut self) {
4499 self.log10_round(Round::Nearest);
4500 }
4501
4502 /// Computes the logarithm to base 10, applying the specified
4503 /// rounding method.
4504 ///
4505 /// # Examples
4506 ///
4507 /// ```rust
4508 /// use core::cmp::Ordering;
4509 /// use rug::{float::Round, Float};
4510 /// // Use only 4 bits of precision to show rounding.
4511 /// let mut f = Float::with_val(4, 1.5);
4512 /// // log10(1.5) = 0.1761
4513 /// // using 4 significant bits: 0.171875
4514 /// let dir = f.log10_round(Round::Nearest);
4515 /// assert_eq!(f, 0.171875);
4516 /// assert_eq!(dir, Ordering::Less);
4517 /// ```
4518 #[inline]
log10_round(&mut self, round: Round) -> Ordering4519 pub fn log10_round(&mut self, round: Round) -> Ordering {
4520 xmpfr::log10(self, (), round)
4521 }
4522
4523 /// Computes the logarithm to base 10.
4524 ///
4525 /// The following are implemented with the returned
4526 /// [incomplete-computation value][icv] as `Src`:
4527 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
4528 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
4529 ///
4530 /// # Examples
4531 ///
4532 /// ```rust
4533 /// use rug::Float;
4534 /// let f = Float::with_val(53, 1.5);
4535 /// let log10 = Float::with_val(53, f.log10_ref());
4536 /// let expected = 0.1761_f64;
4537 /// assert!((log10 - expected).abs() < 0.0001);
4538 /// ```
4539 ///
4540 /// [`AssignRound`]: ops/trait.AssignRound.html
4541 /// [`Assign`]: trait.Assign.html
4542 /// [`Float`]: struct.Float.html
4543 /// [icv]: index.html#incomplete-computation-values
4544 #[inline]
log10_ref(&self) -> Log10Incomplete<'_>4545 pub fn log10_ref(&self) -> Log10Incomplete<'_> {
4546 Log10Incomplete { ref_self: self }
4547 }
4548
4549 /// Computes the exponential, rounding to the nearest.
4550 ///
4551 /// # Examples
4552 ///
4553 /// ```rust
4554 /// use rug::Float;
4555 /// let f = Float::with_val(53, 1.5);
4556 /// let exp = f.exp();
4557 /// let expected = 4.4817_f64;
4558 /// assert!((exp - expected).abs() < 0.0001);
4559 /// ```
4560 #[inline]
exp(mut self) -> Self4561 pub fn exp(mut self) -> Self {
4562 self.exp_round(Round::Nearest);
4563 self
4564 }
4565
4566 /// Computes the exponential, rounding to the nearest.
4567 ///
4568 /// # Examples
4569 ///
4570 /// ```rust
4571 /// use rug::Float;
4572 /// let mut f = Float::with_val(53, 1.5);
4573 /// f.exp_mut();
4574 /// let expected = 4.4817_f64;
4575 /// assert!((f - expected).abs() < 0.0001);
4576 /// ```
4577 #[inline]
exp_mut(&mut self)4578 pub fn exp_mut(&mut self) {
4579 self.exp_round(Round::Nearest);
4580 }
4581
4582 /// Computes the exponential, applying the specified rounding
4583 /// method.
4584 ///
4585 /// # Examples
4586 ///
4587 /// ```rust
4588 /// use core::cmp::Ordering;
4589 /// use rug::{float::Round, Float};
4590 /// // Use only 4 bits of precision to show rounding.
4591 /// let mut f = Float::with_val(4, 1.5);
4592 /// // exp(1.5) = 4.4817
4593 /// // using 4 significant bits: 4.5
4594 /// let dir = f.exp_round(Round::Nearest);
4595 /// assert_eq!(f, 4.5);
4596 /// assert_eq!(dir, Ordering::Greater);
4597 /// ```
4598 #[inline]
exp_round(&mut self, round: Round) -> Ordering4599 pub fn exp_round(&mut self, round: Round) -> Ordering {
4600 xmpfr::exp(self, (), round)
4601 }
4602
4603 /// Computes the exponential.
4604 ///
4605 /// The following are implemented with the returned
4606 /// [incomplete-computation value][icv] as `Src`:
4607 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
4608 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
4609 ///
4610 /// # Examples
4611 ///
4612 /// ```rust
4613 /// use rug::Float;
4614 /// let f = Float::with_val(53, 1.5);
4615 /// let exp = Float::with_val(53, f.exp_ref());
4616 /// let expected = 4.4817_f64;
4617 /// assert!((exp - expected).abs() < 0.0001);
4618 /// ```
4619 ///
4620 /// [`AssignRound`]: ops/trait.AssignRound.html
4621 /// [`Assign`]: trait.Assign.html
4622 /// [`Float`]: struct.Float.html
4623 /// [icv]: index.html#incomplete-computation-values
4624 #[inline]
exp_ref(&self) -> ExpIncomplete<'_>4625 pub fn exp_ref(&self) -> ExpIncomplete<'_> {
4626 ExpIncomplete { ref_self: self }
4627 }
4628
4629 /// Computes 2 to the power of `self`, rounding to the nearest.
4630 ///
4631 /// # Examples
4632 ///
4633 /// ```rust
4634 /// use rug::Float;
4635 /// let f = Float::with_val(53, 1.5);
4636 /// let exp2 = f.exp2();
4637 /// let expected = 2.8284_f64;
4638 /// assert!((exp2 - expected).abs() < 0.0001);
4639 /// ```
4640 #[inline]
exp2(mut self) -> Self4641 pub fn exp2(mut self) -> Self {
4642 self.exp2_round(Round::Nearest);
4643 self
4644 }
4645
4646 /// Computes 2 to the power of `self`, rounding to the nearest.
4647 ///
4648 /// # Examples
4649 ///
4650 /// ```rust
4651 /// use rug::Float;
4652 /// let mut f = Float::with_val(53, 1.5);
4653 /// f.exp2_mut();
4654 /// let expected = 2.8284_f64;
4655 /// assert!((f - expected).abs() < 0.0001);
4656 /// ```
4657 #[inline]
exp2_mut(&mut self)4658 pub fn exp2_mut(&mut self) {
4659 self.exp2_round(Round::Nearest);
4660 }
4661
4662 /// Computes 2 to the power of `self`, applying the specified
4663 /// rounding method.
4664 ///
4665 /// # Examples
4666 ///
4667 /// ```rust
4668 /// use core::cmp::Ordering;
4669 /// use rug::{float::Round, Float};
4670 /// // Use only 4 bits of precision to show rounding.
4671 /// let mut f = Float::with_val(4, 1.5);
4672 /// // exp2(1.5) = 2.8284
4673 /// // using 4 significant bits: 2.75
4674 /// let dir = f.exp2_round(Round::Nearest);
4675 /// assert_eq!(f, 2.75);
4676 /// assert_eq!(dir, Ordering::Less);
4677 /// ```
4678 #[inline]
exp2_round(&mut self, round: Round) -> Ordering4679 pub fn exp2_round(&mut self, round: Round) -> Ordering {
4680 xmpfr::exp2(self, (), round)
4681 }
4682
4683 /// Computes 2 to the power of the value.
4684 ///
4685 /// The following are implemented with the returned
4686 /// [incomplete-computation value][icv] as `Src`:
4687 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
4688 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
4689 ///
4690 /// # Examples
4691 ///
4692 /// ```rust
4693 /// use rug::Float;
4694 /// let f = Float::with_val(53, 1.5);
4695 /// let exp2 = Float::with_val(53, f.exp2_ref());
4696 /// let expected = 2.8284_f64;
4697 /// assert!((exp2 - expected).abs() < 0.0001);
4698 /// ```
4699 ///
4700 /// [`AssignRound`]: ops/trait.AssignRound.html
4701 /// [`Assign`]: trait.Assign.html
4702 /// [`Float`]: struct.Float.html
4703 /// [icv]: index.html#incomplete-computation-values
4704 #[inline]
exp2_ref(&self) -> Exp2Incomplete<'_>4705 pub fn exp2_ref(&self) -> Exp2Incomplete<'_> {
4706 Exp2Incomplete { ref_self: self }
4707 }
4708
4709 /// Computes 10 to the power of `self`, rounding to the nearest.
4710 ///
4711 /// # Examples
4712 ///
4713 /// ```rust
4714 /// use rug::Float;
4715 /// let f = Float::with_val(53, 1.5);
4716 /// let exp10 = f.exp10();
4717 /// let expected = 31.6228_f64;
4718 /// assert!((exp10 - expected).abs() < 0.0001);
4719 /// ```
4720 #[inline]
exp10(mut self) -> Self4721 pub fn exp10(mut self) -> Self {
4722 self.exp10_round(Round::Nearest);
4723 self
4724 }
4725
4726 /// Computes 10 to the power of `self`, rounding to the nearest.
4727 ///
4728 /// # Examples
4729 ///
4730 /// ```rust
4731 /// use rug::Float;
4732 /// let mut f = Float::with_val(53, 1.5);
4733 /// f.exp10_mut();
4734 /// let expected = 31.6228_f64;
4735 /// assert!((f - expected).abs() < 0.0001);
4736 /// ```
4737 #[inline]
exp10_mut(&mut self)4738 pub fn exp10_mut(&mut self) {
4739 self.exp10_round(Round::Nearest);
4740 }
4741
4742 /// Computes 10 to the power of `self`, applying the specified
4743 /// rounding method.
4744 ///
4745 /// # Examples
4746 ///
4747 /// ```rust
4748 /// use core::cmp::Ordering;
4749 /// use rug::{float::Round, Float};
4750 /// // Use only 4 bits of precision to show rounding.
4751 /// let mut f = Float::with_val(4, 1.5);
4752 /// // exp10(1.5) = 31.6228
4753 /// // using 4 significant bits: 32
4754 /// let dir = f.exp10_round(Round::Nearest);
4755 /// assert_eq!(f, 32);
4756 /// assert_eq!(dir, Ordering::Greater);
4757 /// ```
4758 #[inline]
exp10_round(&mut self, round: Round) -> Ordering4759 pub fn exp10_round(&mut self, round: Round) -> Ordering {
4760 xmpfr::exp10(self, (), round)
4761 }
4762
4763 /// Computes 10 to the power of the value.
4764 ///
4765 /// The following are implemented with the returned
4766 /// [incomplete-computation value][icv] as `Src`:
4767 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
4768 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
4769 ///
4770 /// # Examples
4771 ///
4772 /// ```rust
4773 /// use rug::Float;
4774 /// let f = Float::with_val(53, 1.5);
4775 /// let exp10 = Float::with_val(53, f.exp10_ref());
4776 /// let expected = 31.6228_f64;
4777 /// assert!((exp10 - expected).abs() < 0.0001);
4778 /// ```
4779 ///
4780 /// [`AssignRound`]: ops/trait.AssignRound.html
4781 /// [`Assign`]: trait.Assign.html
4782 /// [`Float`]: struct.Float.html
4783 /// [icv]: index.html#incomplete-computation-values
4784 #[inline]
exp10_ref(&self) -> Exp10Incomplete<'_>4785 pub fn exp10_ref(&self) -> Exp10Incomplete<'_> {
4786 Exp10Incomplete { ref_self: self }
4787 }
4788
4789 /// Computes the sine, rounding to the nearest.
4790 ///
4791 /// # Examples
4792 ///
4793 /// ```rust
4794 /// use rug::Float;
4795 /// let f = Float::with_val(53, 1.25);
4796 /// let sin = f.sin();
4797 /// let expected = 0.9490_f64;
4798 /// assert!((sin - expected).abs() < 0.0001);
4799 /// ```
4800 #[inline]
sin(mut self) -> Self4801 pub fn sin(mut self) -> Self {
4802 self.sin_round(Round::Nearest);
4803 self
4804 }
4805
4806 /// Computes the sine, rounding to the nearest.
4807 ///
4808 /// # Examples
4809 ///
4810 /// ```rust
4811 /// use rug::Float;
4812 /// let mut f = Float::with_val(53, 1.25);
4813 /// f.sin_mut();
4814 /// let expected = 0.9490_f64;
4815 /// assert!((f - expected).abs() < 0.0001);
4816 /// ```
4817 #[inline]
sin_mut(&mut self)4818 pub fn sin_mut(&mut self) {
4819 self.sin_round(Round::Nearest);
4820 }
4821
4822 /// Computes the sine, applying the specified rounding method.
4823 ///
4824 /// # Examples
4825 ///
4826 /// ```rust
4827 /// use core::cmp::Ordering;
4828 /// use rug::{float::Round, Float};
4829 /// // Use only 4 bits of precision to show rounding.
4830 /// let mut f = Float::with_val(4, 1.25);
4831 /// // sin(1.25) = 0.9490
4832 /// // using 4 significant bits: 0.9375
4833 /// let dir = f.sin_round(Round::Nearest);
4834 /// assert_eq!(f, 0.9375);
4835 /// assert_eq!(dir, Ordering::Less);
4836 /// ```
4837 #[inline]
sin_round(&mut self, round: Round) -> Ordering4838 pub fn sin_round(&mut self, round: Round) -> Ordering {
4839 xmpfr::sin(self, (), round)
4840 }
4841
4842 /// Computes the sine.
4843 ///
4844 /// The following are implemented with the returned
4845 /// [incomplete-computation value][icv] as `Src`:
4846 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
4847 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
4848 ///
4849 /// # Examples
4850 ///
4851 /// ```rust
4852 /// use rug::Float;
4853 /// let f = Float::with_val(53, 1.25);
4854 /// let sin = Float::with_val(53, f.sin_ref());
4855 /// let expected = 0.9490_f64;
4856 /// assert!((sin - expected).abs() < 0.0001);
4857 /// ```
4858 ///
4859 /// [`AssignRound`]: ops/trait.AssignRound.html
4860 /// [`Assign`]: trait.Assign.html
4861 /// [`Float`]: struct.Float.html
4862 /// [icv]: index.html#incomplete-computation-values
4863 #[inline]
sin_ref(&self) -> SinIncomplete<'_>4864 pub fn sin_ref(&self) -> SinIncomplete<'_> {
4865 SinIncomplete { ref_self: self }
4866 }
4867
4868 /// Computes the cosine, rounding to the nearest.
4869 ///
4870 /// # Examples
4871 ///
4872 /// ```rust
4873 /// use rug::Float;
4874 /// let f = Float::with_val(53, 1.25);
4875 /// let cos = f.cos();
4876 /// let expected = 0.3153_f64;
4877 /// assert!((cos - expected).abs() < 0.0001);
4878 /// ```
4879 #[inline]
cos(mut self) -> Self4880 pub fn cos(mut self) -> Self {
4881 self.cos_round(Round::Nearest);
4882 self
4883 }
4884
4885 /// Computes the cosine, rounding to the nearest.
4886 ///
4887 /// # Examples
4888 ///
4889 /// ```rust
4890 /// use rug::Float;
4891 /// let mut f = Float::with_val(53, 1.25);
4892 /// f.cos_mut();
4893 /// let expected = 0.3153_f64;
4894 /// assert!((f - expected).abs() < 0.0001);
4895 /// ```
4896 #[inline]
cos_mut(&mut self)4897 pub fn cos_mut(&mut self) {
4898 self.cos_round(Round::Nearest);
4899 }
4900
4901 /// Computes the cosine, applying the specified rounding method.
4902 ///
4903 /// # Examples
4904 ///
4905 /// ```rust
4906 /// use core::cmp::Ordering;
4907 /// use rug::{float::Round, Float};
4908 /// // Use only 4 bits of precision to show rounding.
4909 /// let mut f = Float::with_val(4, 1.25);
4910 /// // cos(1.25) = 0.3153
4911 /// // using 4 significant bits: 0.3125
4912 /// let dir = f.cos_round(Round::Nearest);
4913 /// assert_eq!(f, 0.3125);
4914 /// assert_eq!(dir, Ordering::Less);
4915 /// ```
4916 #[inline]
cos_round(&mut self, round: Round) -> Ordering4917 pub fn cos_round(&mut self, round: Round) -> Ordering {
4918 xmpfr::cos(self, (), round)
4919 }
4920
4921 /// Computes the cosine.
4922 ///
4923 /// The following are implemented with the returned
4924 /// [incomplete-computation value][icv] as `Src`:
4925 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
4926 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
4927 ///
4928 /// # Examples
4929 ///
4930 /// ```rust
4931 /// use rug::Float;
4932 /// let f = Float::with_val(53, 1.25);
4933 /// let cos = Float::with_val(53, f.cos_ref());
4934 /// let expected = 0.3153_f64;
4935 /// assert!((cos - expected).abs() < 0.0001);
4936 /// ```
4937 ///
4938 /// [`AssignRound`]: ops/trait.AssignRound.html
4939 /// [`Assign`]: trait.Assign.html
4940 /// [`Float`]: struct.Float.html
4941 /// [icv]: index.html#incomplete-computation-values
4942 #[inline]
cos_ref(&self) -> CosIncomplete<'_>4943 pub fn cos_ref(&self) -> CosIncomplete<'_> {
4944 CosIncomplete { ref_self: self }
4945 }
4946
4947 /// Computes the tangent, rounding to the nearest.
4948 ///
4949 /// # Examples
4950 ///
4951 /// ```rust
4952 /// use rug::Float;
4953 /// let f = Float::with_val(53, 1.25);
4954 /// let tan = f.tan();
4955 /// let expected = 3.0096_f64;
4956 /// assert!((tan - expected).abs() < 0.0001);
4957 /// ```
4958 #[inline]
tan(mut self) -> Self4959 pub fn tan(mut self) -> Self {
4960 self.tan_round(Round::Nearest);
4961 self
4962 }
4963
4964 /// Computes the tangent, rounding to the nearest.
4965 ///
4966 /// # Examples
4967 ///
4968 /// ```rust
4969 /// use rug::Float;
4970 /// let mut f = Float::with_val(53, 1.25);
4971 /// f.tan_mut();
4972 /// let expected = 3.0096_f64;
4973 /// assert!((f - expected).abs() < 0.0001);
4974 /// ```
4975 #[inline]
tan_mut(&mut self)4976 pub fn tan_mut(&mut self) {
4977 self.tan_round(Round::Nearest);
4978 }
4979
4980 /// Computes the tangent, applying the specified rounding method.
4981 ///
4982 /// # Examples
4983 ///
4984 /// ```rust
4985 /// use core::cmp::Ordering;
4986 /// use rug::{float::Round, Float};
4987 /// // Use only 4 bits of precision to show rounding.
4988 /// let mut f = Float::with_val(4, 1.25);
4989 /// // tan(1.25) = 3.0096
4990 /// // using 4 significant bits: 3.0
4991 /// let dir = f.tan_round(Round::Nearest);
4992 /// assert_eq!(f, 3.0);
4993 /// assert_eq!(dir, Ordering::Less);
4994 /// ```
4995 #[inline]
tan_round(&mut self, round: Round) -> Ordering4996 pub fn tan_round(&mut self, round: Round) -> Ordering {
4997 xmpfr::tan(self, (), round)
4998 }
4999
5000 /// Computes the tangent.
5001 ///
5002 /// The following are implemented with the returned
5003 /// [incomplete-computation value][icv] as `Src`:
5004 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
5005 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
5006 ///
5007 /// # Examples
5008 ///
5009 /// ```rust
5010 /// use rug::Float;
5011 /// let f = Float::with_val(53, 1.25);
5012 /// let tan = Float::with_val(53, f.tan_ref());
5013 /// let expected = 3.0096_f64;
5014 /// assert!((tan - expected).abs() < 0.0001);
5015 /// ```
5016 ///
5017 /// [`AssignRound`]: ops/trait.AssignRound.html
5018 /// [`Assign`]: trait.Assign.html
5019 /// [`Float`]: struct.Float.html
5020 /// [icv]: index.html#incomplete-computation-values
5021 #[inline]
tan_ref(&self) -> TanIncomplete<'_>5022 pub fn tan_ref(&self) -> TanIncomplete<'_> {
5023 TanIncomplete { ref_self: self }
5024 }
5025
5026 /// Computes the sine and cosine of `self`, rounding to the
5027 /// nearest.
5028 ///
5029 /// The sine is stored in `self` and keeps its precision,
5030 /// while the cosine is stored in `cos` keeping its precision.
5031 ///
5032 /// The initial value of `cos` is ignored.
5033 ///
5034 /// # Examples
5035 ///
5036 /// ```rust
5037 /// use rug::Float;
5038 /// let f = Float::with_val(53, 1.25);
5039 /// let (sin, cos) = f.sin_cos(Float::new(53));
5040 /// let expected_sin = 0.9490_f64;
5041 /// let expected_cos = 0.3153_f64;
5042 /// assert!((sin - expected_sin).abs() < 0.0001);
5043 /// assert!((cos - expected_cos).abs() < 0.0001);
5044 /// ```
5045 #[inline]
sin_cos(mut self, mut cos: Self) -> (Self, Self)5046 pub fn sin_cos(mut self, mut cos: Self) -> (Self, Self) {
5047 self.sin_cos_round(&mut cos, Round::Nearest);
5048 (self, cos)
5049 }
5050
5051 /// Computes the sine and cosine of `self`, rounding to the
5052 /// nearest.
5053 ///
5054 /// The sine is stored in `self` and keeps its precision,
5055 /// while the cosine is stored in `cos` keeping its precision.
5056 ///
5057 /// The initial value of `cos` is ignored.
5058 ///
5059 /// # Examples
5060 ///
5061 /// ```rust
5062 /// use rug::Float;
5063 /// let mut sin = Float::with_val(53, 1.25);
5064 /// let mut cos = Float::new(53);
5065 /// sin.sin_cos_mut(&mut cos);
5066 /// let expected_sin = 0.9490_f64;
5067 /// let expected_cos = 0.3153_f64;
5068 /// assert!((sin - expected_sin).abs() < 0.0001);
5069 /// assert!((cos - expected_cos).abs() < 0.0001);
5070 /// ```
5071 #[inline]
sin_cos_mut(&mut self, cos: &mut Self)5072 pub fn sin_cos_mut(&mut self, cos: &mut Self) {
5073 self.sin_cos_round(cos, Round::Nearest);
5074 }
5075
5076 /// Computes the sine and cosine of `self`, applying the specified
5077 /// rounding method.
5078 ///
5079 /// The sine is stored in `self` and keeps its precision,
5080 /// while the cosine is stored in `cos` keeping its precision.
5081 ///
5082 /// The initial value of `cos` is ignored.
5083 ///
5084 /// # Examples
5085 ///
5086 /// ```rust
5087 /// use core::cmp::Ordering;
5088 /// use rug::{float::Round, Float};
5089 /// // Use only 4 bits of precision to show rounding.
5090 /// let mut sin = Float::with_val(4, 1.25);
5091 /// let mut cos = Float::new(4);
5092 /// // sin(1.25) = 0.9490, using 4 significant bits: 0.9375
5093 /// // cos(1.25) = 0.3153, using 4 significant bits: 0.3125
5094 /// let (dir_sin, dir_cos) =
5095 /// sin.sin_cos_round(&mut cos, Round::Nearest);
5096 /// assert_eq!(sin, 0.9375);
5097 /// assert_eq!(dir_sin, Ordering::Less);
5098 /// assert_eq!(cos, 0.3125);
5099 /// assert_eq!(dir_cos, Ordering::Less);
5100 /// ```
5101 #[inline]
sin_cos_round(&mut self, cos: &mut Self, round: Round) -> (Ordering, Ordering)5102 pub fn sin_cos_round(&mut self, cos: &mut Self, round: Round) -> (Ordering, Ordering) {
5103 xmpfr::sin_cos(self, cos, (), round)
5104 }
5105
5106 /// Computes the sine and cosine.
5107 ///
5108 /// The following are implemented with the returned
5109 /// [incomplete-computation value][icv] as `Src`:
5110 /// * <code>[Assign][`Assign`]<Src> for
5111 /// [(][tuple][Float][`Float`],
5112 /// [Float][`Float`][)][tuple]</code>
5113 /// * <code>[Assign][`Assign`]<Src> for
5114 /// [(][tuple]&mut [Float][`Float`],
5115 /// &mut [Float][`Float`][)][tuple]</code>
5116 /// * <code>[AssignRound][`AssignRound`]<Src> for
5117 /// [(][tuple][Float][`Float`],
5118 /// [Float][`Float`][)][tuple]</code>
5119 /// * <code>[AssignRound][`AssignRound`]<Src> for
5120 /// [(][tuple]&mut [Float][`Float`],
5121 /// &mut [Float][`Float`][)][tuple]</code>
5122 ///
5123 /// # Examples
5124 ///
5125 /// ```rust
5126 /// use core::cmp::Ordering;
5127 /// use rug::{float::Round, ops::AssignRound, Assign, Float};
5128 /// let phase = Float::with_val(53, 1.25);
5129 ///
5130 /// let (mut sin, mut cos) = (Float::new(53), Float::new(53));
5131 /// let sin_cos = phase.sin_cos_ref();
5132 /// (&mut sin, &mut cos).assign(sin_cos);
5133 /// let expected_sin = 0.9490_f64;
5134 /// let expected_cos = 0.3153_f64;
5135 /// assert!((sin - expected_sin).abs() < 0.0001);
5136 /// assert!((cos - expected_cos).abs() < 0.0001);
5137 ///
5138 /// // using 4 significant bits: sin = 0.9375
5139 /// // using 4 significant bits: cos = 0.3125
5140 /// let (mut sin_4, mut cos_4) = (Float::new(4), Float::new(4));
5141 /// let sin_cos = phase.sin_cos_ref();
5142 /// let (dir_sin, dir_cos) = (&mut sin_4, &mut cos_4)
5143 /// .assign_round(sin_cos, Round::Nearest);
5144 /// assert_eq!(sin_4, 0.9375);
5145 /// assert_eq!(dir_sin, Ordering::Less);
5146 /// assert_eq!(cos_4, 0.3125);
5147 /// assert_eq!(dir_cos, Ordering::Less);
5148 /// ```
5149 ///
5150 /// [`AssignRound`]: ops/trait.AssignRound.html
5151 /// [`Assign`]: trait.Assign.html
5152 /// [`Float`]: struct.Float.html
5153 /// [icv]: index.html#incomplete-computation-values
5154 /// [tuple]: https://doc.rust-lang.org/nightly/std/primitive.tuple.html
5155 #[inline]
sin_cos_ref(&self) -> SinCosIncomplete<'_>5156 pub fn sin_cos_ref(&self) -> SinCosIncomplete<'_> {
5157 SinCosIncomplete { ref_self: self }
5158 }
5159
5160 /// Computes the secant, rounding to the nearest.
5161 ///
5162 /// # Examples
5163 ///
5164 /// ```rust
5165 /// use rug::Float;
5166 /// let f = Float::with_val(53, 1.25);
5167 /// let sec = f.sec();
5168 /// let expected = 3.1714_f64;
5169 /// assert!((sec - expected).abs() < 0.0001);
5170 /// ```
5171 #[inline]
sec(mut self) -> Self5172 pub fn sec(mut self) -> Self {
5173 self.sec_round(Round::Nearest);
5174 self
5175 }
5176
5177 /// Computes the secant, rounding to the nearest.
5178 ///
5179 /// # Examples
5180 ///
5181 /// ```rust
5182 /// use rug::Float;
5183 /// let mut f = Float::with_val(53, 1.25);
5184 /// f.sec_mut();
5185 /// let expected = 3.1714_f64;
5186 /// assert!((f - expected).abs() < 0.0001);
5187 /// ```
5188 #[inline]
sec_mut(&mut self)5189 pub fn sec_mut(&mut self) {
5190 self.sec_round(Round::Nearest);
5191 }
5192
5193 /// Computes the secant, applying the specified rounding method.
5194 ///
5195 /// # Examples
5196 ///
5197 /// ```rust
5198 /// use core::cmp::Ordering;
5199 /// use rug::{float::Round, Float};
5200 /// // Use only 4 bits of precision to show rounding.
5201 /// let mut f = Float::with_val(4, 1.25);
5202 /// // sec(1.25) = 3.1714
5203 /// // using 4 significant bits: 3.25
5204 /// let dir = f.sec_round(Round::Nearest);
5205 /// assert_eq!(f, 3.25);
5206 /// assert_eq!(dir, Ordering::Greater);
5207 /// ```
5208 #[inline]
sec_round(&mut self, round: Round) -> Ordering5209 pub fn sec_round(&mut self, round: Round) -> Ordering {
5210 xmpfr::sec(self, (), round)
5211 }
5212
5213 /// Computes the secant.
5214 ///
5215 /// The following are implemented with the returned
5216 /// [incomplete-computation value][icv] as `Src`:
5217 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
5218 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
5219 ///
5220 /// # Examples
5221 ///
5222 /// ```rust
5223 /// use rug::Float;
5224 /// let f = Float::with_val(53, 1.25);
5225 /// let sec = Float::with_val(53, f.sec_ref());
5226 /// let expected = 3.1714_f64;
5227 /// assert!((sec - expected).abs() < 0.0001);
5228 /// ```
5229 ///
5230 /// [`AssignRound`]: ops/trait.AssignRound.html
5231 /// [`Assign`]: trait.Assign.html
5232 /// [`Float`]: struct.Float.html
5233 /// [icv]: index.html#incomplete-computation-values
5234 #[inline]
sec_ref(&self) -> SecIncomplete<'_>5235 pub fn sec_ref(&self) -> SecIncomplete<'_> {
5236 SecIncomplete { ref_self: self }
5237 }
5238
5239 /// Computes the cosecant, rounding to the nearest.
5240 ///
5241 /// # Examples
5242 ///
5243 /// ```rust
5244 /// use rug::Float;
5245 /// let f = Float::with_val(53, 1.25);
5246 /// let csc = f.csc();
5247 /// let expected = 1.0538_f64;
5248 /// assert!((csc - expected).abs() < 0.0001);
5249 /// ```
5250 #[inline]
csc(mut self) -> Self5251 pub fn csc(mut self) -> Self {
5252 self.csc_round(Round::Nearest);
5253 self
5254 }
5255
5256 /// Computes the cosecant, rounding to the nearest.
5257 ///
5258 /// # Examples
5259 ///
5260 /// ```rust
5261 /// use rug::Float;
5262 /// let mut f = Float::with_val(53, 1.25);
5263 /// f.csc_mut();
5264 /// let expected = 1.0538_f64;
5265 /// assert!((f - expected).abs() < 0.0001);
5266 /// ```
5267 #[inline]
csc_mut(&mut self)5268 pub fn csc_mut(&mut self) {
5269 self.csc_round(Round::Nearest);
5270 }
5271
5272 /// Computes the cosecant, applying the specified rounding method.
5273 ///
5274 /// # Examples
5275 ///
5276 /// ```rust
5277 /// use core::cmp::Ordering;
5278 /// use rug::{float::Round, Float};
5279 /// // Use only 4 bits of precision to show rounding.
5280 /// let mut f = Float::with_val(4, 1.25);
5281 /// // csc(1.25) = 1.0538
5282 /// // using 4 significant bits: 1.0
5283 /// let dir = f.csc_round(Round::Nearest);
5284 /// assert_eq!(f, 1.0);
5285 /// assert_eq!(dir, Ordering::Less);
5286 /// ```
5287 #[inline]
csc_round(&mut self, round: Round) -> Ordering5288 pub fn csc_round(&mut self, round: Round) -> Ordering {
5289 xmpfr::csc(self, (), round)
5290 }
5291
5292 /// Computes the cosecant.
5293 ///
5294 /// The following are implemented with the returned
5295 /// [incomplete-computation value][icv] as `Src`:
5296 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
5297 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
5298 ///
5299 /// # Examples
5300 ///
5301 /// ```rust
5302 /// use rug::Float;
5303 /// let f = Float::with_val(53, 1.25);
5304 /// let csc = Float::with_val(53, f.csc_ref());
5305 /// let expected = 1.0538_f64;
5306 /// assert!((csc - expected).abs() < 0.0001);
5307 /// ```
5308 ///
5309 /// [`AssignRound`]: ops/trait.AssignRound.html
5310 /// [`Assign`]: trait.Assign.html
5311 /// [`Float`]: struct.Float.html
5312 /// [icv]: index.html#incomplete-computation-values
5313 #[inline]
csc_ref(&self) -> CscIncomplete<'_>5314 pub fn csc_ref(&self) -> CscIncomplete<'_> {
5315 CscIncomplete { ref_self: self }
5316 }
5317
5318 /// Computes the cotangent, rounding to the nearest.
5319 ///
5320 /// # Examples
5321 ///
5322 /// ```rust
5323 /// use rug::Float;
5324 /// let f = Float::with_val(53, 1.25);
5325 /// let cot = f.cot();
5326 /// let expected = 0.3323_f64;
5327 /// assert!((cot - expected).abs() < 0.0001);
5328 /// ```
5329 #[inline]
cot(mut self) -> Self5330 pub fn cot(mut self) -> Self {
5331 self.cot_round(Round::Nearest);
5332 self
5333 }
5334
5335 /// Computes the cotangent, rounding to the nearest.
5336 ///
5337 /// # Examples
5338 ///
5339 /// ```rust
5340 /// use rug::Float;
5341 /// let mut f = Float::with_val(53, 1.25);
5342 /// f.cot_mut();
5343 /// let expected = 0.3323_f64;
5344 /// assert!((f - expected).abs() < 0.0001);
5345 /// ```
5346 #[inline]
cot_mut(&mut self)5347 pub fn cot_mut(&mut self) {
5348 self.cot_round(Round::Nearest);
5349 }
5350
5351 /// Computes the cotangent, applying the specified rounding
5352 /// method.
5353 ///
5354 /// # Examples
5355 ///
5356 /// ```rust
5357 /// use core::cmp::Ordering;
5358 /// use rug::{float::Round, Float};
5359 /// // Use only 4 bits of precision to show rounding.
5360 /// let mut f = Float::with_val(4, 1.25);
5361 /// // cot(1.25) = 0.3323
5362 /// // using 4 significant bits: 0.34375
5363 /// let dir = f.cot_round(Round::Nearest);
5364 /// assert_eq!(f, 0.34375);
5365 /// assert_eq!(dir, Ordering::Greater);
5366 /// ```
5367 #[inline]
cot_round(&mut self, round: Round) -> Ordering5368 pub fn cot_round(&mut self, round: Round) -> Ordering {
5369 xmpfr::cot(self, (), round)
5370 }
5371
5372 /// Computes the cotangent.
5373 ///
5374 /// The following are implemented with the returned
5375 /// [incomplete-computation value][icv] as `Src`:
5376 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
5377 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
5378 ///
5379 /// # Examples
5380 ///
5381 /// ```rust
5382 /// use rug::Float;
5383 /// let f = Float::with_val(53, 1.25);
5384 /// let cot = Float::with_val(53, f.cot_ref());
5385 /// let expected = 0.3323_f64;
5386 /// assert!((cot - expected).abs() < 0.0001);
5387 /// ```
5388 ///
5389 /// [`AssignRound`]: ops/trait.AssignRound.html
5390 /// [`Assign`]: trait.Assign.html
5391 /// [`Float`]: struct.Float.html
5392 /// [icv]: index.html#incomplete-computation-values
5393 #[inline]
cot_ref(&self) -> CotIncomplete<'_>5394 pub fn cot_ref(&self) -> CotIncomplete<'_> {
5395 CotIncomplete { ref_self: self }
5396 }
5397
5398 /// Computes the arc-sine, rounding to the nearest.
5399 ///
5400 /// # Examples
5401 ///
5402 /// ```rust
5403 /// use rug::Float;
5404 /// let f = Float::with_val(53, -0.75);
5405 /// let asin = f.asin();
5406 /// let expected = -0.8481_f64;
5407 /// assert!((asin - expected).abs() < 0.0001);
5408 /// ```
5409 #[inline]
asin(mut self) -> Self5410 pub fn asin(mut self) -> Self {
5411 self.asin_round(Round::Nearest);
5412 self
5413 }
5414
5415 /// Computes the arc-sine, rounding to the nearest.
5416 ///
5417 /// # Examples
5418 ///
5419 /// ```rust
5420 /// use rug::Float;
5421 /// let mut f = Float::with_val(53, -0.75);
5422 /// f.asin_mut();
5423 /// let expected = -0.8481_f64;
5424 /// assert!((f - expected).abs() < 0.0001);
5425 /// ```
5426 #[inline]
asin_mut(&mut self)5427 pub fn asin_mut(&mut self) {
5428 self.asin_round(Round::Nearest);
5429 }
5430
5431 /// Computes the arc-sine, applying the specified rounding method.
5432 ///
5433 /// # Examples
5434 ///
5435 /// ```rust
5436 /// use core::cmp::Ordering;
5437 /// use rug::{float::Round, Float};
5438 /// // Use only 4 bits of precision to show rounding.
5439 /// let mut f = Float::with_val(4, -0.75);
5440 /// // asin(−0.75) = −0.8481
5441 /// // using 4 significant bits: −0.875
5442 /// let dir = f.asin_round(Round::Nearest);
5443 /// assert_eq!(f, -0.875);
5444 /// assert_eq!(dir, Ordering::Less);
5445 /// ```
5446 #[inline]
asin_round(&mut self, round: Round) -> Ordering5447 pub fn asin_round(&mut self, round: Round) -> Ordering {
5448 xmpfr::asin(self, (), round)
5449 }
5450
5451 /// Computes the arc-sine.
5452 ///
5453 /// The following are implemented with the returned
5454 /// [incomplete-computation value][icv] as `Src`:
5455 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
5456 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
5457 ///
5458 /// # Examples
5459 ///
5460 /// ```rust
5461 /// use rug::Float;
5462 /// let f = Float::with_val(53, -0.75);
5463 /// let asin = Float::with_val(53, f.asin_ref());
5464 /// let expected = -0.8481_f64;
5465 /// assert!((asin - expected).abs() < 0.0001);
5466 /// ```
5467 ///
5468 /// [`AssignRound`]: ops/trait.AssignRound.html
5469 /// [`Assign`]: trait.Assign.html
5470 /// [`Float`]: struct.Float.html
5471 /// [icv]: index.html#incomplete-computation-values
5472 #[inline]
asin_ref(&self) -> AsinIncomplete<'_>5473 pub fn asin_ref(&self) -> AsinIncomplete<'_> {
5474 AsinIncomplete { ref_self: self }
5475 }
5476
5477 /// Computes the arc-cosine, rounding to the nearest.
5478 ///
5479 /// # Examples
5480 ///
5481 /// ```rust
5482 /// use rug::Float;
5483 /// let f = Float::with_val(53, -0.75);
5484 /// let acos = f.acos();
5485 /// let expected = 2.4189_f64;
5486 /// assert!((acos - expected).abs() < 0.0001);
5487 /// ```
5488 #[inline]
acos(mut self) -> Self5489 pub fn acos(mut self) -> Self {
5490 self.acos_round(Round::Nearest);
5491 self
5492 }
5493
5494 /// Computes the arc-cosine, rounding to the nearest.
5495 ///
5496 /// # Examples
5497 ///
5498 /// ```rust
5499 /// use rug::Float;
5500 /// let mut f = Float::with_val(53, -0.75);
5501 /// f.acos_mut();
5502 /// let expected = 2.4189_f64;
5503 /// assert!((f - expected).abs() < 0.0001);
5504 /// ```
5505 #[inline]
acos_mut(&mut self)5506 pub fn acos_mut(&mut self) {
5507 self.acos_round(Round::Nearest);
5508 }
5509
5510 /// Computes the arc-cosine, applying the specified rounding
5511 /// method.
5512 ///
5513 /// # Examples
5514 ///
5515 /// ```rust
5516 /// use core::cmp::Ordering;
5517 /// use rug::{float::Round, Float};
5518 /// // Use only 4 bits of precision to show rounding.
5519 /// let mut f = Float::with_val(4, -0.75);
5520 /// // acos(−0.75) = 2.4189
5521 /// // using 4 significant bits: 2.5
5522 /// let dir = f.acos_round(Round::Nearest);
5523 /// assert_eq!(f, 2.5);
5524 /// assert_eq!(dir, Ordering::Greater);
5525 /// ```
5526 #[inline]
acos_round(&mut self, round: Round) -> Ordering5527 pub fn acos_round(&mut self, round: Round) -> Ordering {
5528 xmpfr::acos(self, (), round)
5529 }
5530
5531 /// Computes the arc-cosine.
5532 ///
5533 /// The following are implemented with the returned
5534 /// [incomplete-computation value][icv] as `Src`:
5535 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
5536 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
5537 ///
5538 /// # Examples
5539 ///
5540 /// ```rust
5541 /// use rug::Float;
5542 /// let f = Float::with_val(53, -0.75);
5543 /// let acos = Float::with_val(53, f.acos_ref());
5544 /// let expected = 2.4189_f64;
5545 /// assert!((acos - expected).abs() < 0.0001);
5546 /// ```
5547 ///
5548 /// [`AssignRound`]: ops/trait.AssignRound.html
5549 /// [`Assign`]: trait.Assign.html
5550 /// [`Float`]: struct.Float.html
5551 /// [icv]: index.html#incomplete-computation-values
5552 #[inline]
acos_ref(&self) -> AcosIncomplete<'_>5553 pub fn acos_ref(&self) -> AcosIncomplete<'_> {
5554 AcosIncomplete { ref_self: self }
5555 }
5556
5557 /// Computes the arc-tangent, rounding to the nearest.
5558 ///
5559 /// # Examples
5560 ///
5561 /// ```rust
5562 /// use rug::Float;
5563 /// let f = Float::with_val(53, -0.75);
5564 /// let atan = f.atan();
5565 /// let expected = -0.6435_f64;
5566 /// assert!((atan - expected).abs() < 0.0001);
5567 /// ```
5568 #[inline]
atan(mut self) -> Self5569 pub fn atan(mut self) -> Self {
5570 self.atan_round(Round::Nearest);
5571 self
5572 }
5573
5574 /// Computes the arc-tangent, rounding to the nearest.
5575 ///
5576 /// # Examples
5577 ///
5578 /// ```rust
5579 /// use rug::Float;
5580 /// let mut f = Float::with_val(53, -0.75);
5581 /// f.atan_mut();
5582 /// let expected = -0.6435_f64;
5583 /// assert!((f - expected).abs() < 0.0001);
5584 /// ```
5585 #[inline]
atan_mut(&mut self)5586 pub fn atan_mut(&mut self) {
5587 self.atan_round(Round::Nearest);
5588 }
5589
5590 /// Computes the arc-tangent, applying the specified rounding
5591 /// method.
5592 ///
5593 /// # Examples
5594 ///
5595 /// ```rust
5596 /// use core::cmp::Ordering;
5597 /// use rug::{float::Round, Float};
5598 /// // Use only 4 bits of precision to show rounding.
5599 /// let mut f = Float::with_val(4, -0.75);
5600 /// // atan(−0.75) = −0.6435
5601 /// // using 4 significant bits: −0.625
5602 /// let dir = f.atan_round(Round::Nearest);
5603 /// assert_eq!(f, -0.625);
5604 /// assert_eq!(dir, Ordering::Greater);
5605 /// ```
5606 #[inline]
atan_round(&mut self, round: Round) -> Ordering5607 pub fn atan_round(&mut self, round: Round) -> Ordering {
5608 xmpfr::atan(self, (), round)
5609 }
5610
5611 /// Computes the arc-tangent.
5612 ///
5613 /// The following are implemented with the returned
5614 /// [incomplete-computation value][icv] as `Src`:
5615 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
5616 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
5617 ///
5618 /// # Examples
5619 ///
5620 /// ```rust
5621 /// use rug::Float;
5622 /// let f = Float::with_val(53, -0.75);
5623 /// let atan = Float::with_val(53, f.atan_ref());
5624 /// let expected = -0.6435_f64;
5625 /// assert!((atan - expected).abs() < 0.0001);
5626 /// ```
5627 ///
5628 /// [`AssignRound`]: ops/trait.AssignRound.html
5629 /// [`Assign`]: trait.Assign.html
5630 /// [`Float`]: struct.Float.html
5631 /// [icv]: index.html#incomplete-computation-values
5632 #[inline]
atan_ref(&self) -> AtanIncomplete<'_>5633 pub fn atan_ref(&self) -> AtanIncomplete<'_> {
5634 AtanIncomplete { ref_self: self }
5635 }
5636
5637 /// Computes the arc-tangent2 of `self` and `x`, rounding to
5638 /// the nearest.
5639 ///
5640 /// This is similar to the arc-tangent of `self / x`, but
5641 /// has an output range of 2π rather than π.
5642 ///
5643 /// # Examples
5644 ///
5645 /// ```rust
5646 /// use rug::Float;
5647 /// let y = Float::with_val(53, 3.0);
5648 /// let x = Float::with_val(53, -4.0);
5649 /// let atan2 = y.atan2(&x);
5650 /// let expected = 2.4981_f64;
5651 /// assert!((atan2 - expected).abs() < 0.0001);
5652 /// ```
5653 #[inline]
atan2(mut self, x: &Self) -> Self5654 pub fn atan2(mut self, x: &Self) -> Self {
5655 self.atan2_round(x, Round::Nearest);
5656 self
5657 }
5658
5659 /// Computes the arc-tangent2 of `self` and `x`, rounding to
5660 /// the nearest.
5661 ///
5662 /// This is similar to the arc-tangent of `self / x`, but
5663 /// has an output range of 2π rather than π.
5664 ///
5665 /// # Examples
5666 ///
5667 /// ```rust
5668 /// use rug::Float;
5669 /// let mut y = Float::with_val(53, 3.0);
5670 /// let x = Float::with_val(53, -4.0);
5671 /// y.atan2_mut(&x);
5672 /// let expected = 2.4981_f64;
5673 /// assert!((y - expected).abs() < 0.0001);
5674 /// ```
5675 #[inline]
atan2_mut(&mut self, x: &Self)5676 pub fn atan2_mut(&mut self, x: &Self) {
5677 self.atan2_round(x, Round::Nearest);
5678 }
5679
5680 /// Computes the arc-tangent2 of `self` and `x`, applying the
5681 /// specified rounding method.
5682 ///
5683 /// This is similar to the arc-tangent of `self / x`, but
5684 /// has an output range of 2π rather than π.
5685 ///
5686 /// # Examples
5687 ///
5688 /// ```rust
5689 /// use core::cmp::Ordering;
5690 /// use rug::{float::Round, Float};
5691 /// // Use only 4 bits of precision to show rounding.
5692 /// let mut y = Float::with_val(4, 3.0);
5693 /// let x = Float::with_val(4, -4.0);
5694 /// // atan2(3.0, −4.0) = 2.4981
5695 /// // using 4 significant bits: 2.5
5696 /// let dir = y.atan2_round(&x, Round::Nearest);
5697 /// assert_eq!(y, 2.5);
5698 /// assert_eq!(dir, Ordering::Greater);
5699 /// ```
5700 #[inline]
atan2_round(&mut self, x: &Self, round: Round) -> Ordering5701 pub fn atan2_round(&mut self, x: &Self, round: Round) -> Ordering {
5702 xmpfr::atan2(self, (), x, round)
5703 }
5704
5705 /// Computes the arc-tangent.
5706 ///
5707 /// This is similar to the arc-tangent of `self / x`, but
5708 /// has an output range of 2π rather than π.
5709 ///
5710 /// The following are implemented with the returned
5711 /// [incomplete-computation value][icv] as `Src`:
5712 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
5713 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
5714 ///
5715 /// # Examples
5716 ///
5717 /// ```rust
5718 /// use rug::Float;
5719 /// let y = Float::with_val(53, 3.0);
5720 /// let x = Float::with_val(53, -4.0);
5721 /// let r = y.atan2_ref(&x);
5722 /// let atan2 = Float::with_val(53, r);
5723 /// let expected = 2.4981_f64;
5724 /// assert!((atan2 - expected).abs() < 0.0001);
5725 /// ```
5726 ///
5727 /// [`AssignRound`]: ops/trait.AssignRound.html
5728 /// [`Assign`]: trait.Assign.html
5729 /// [`Float`]: struct.Float.html
5730 /// [icv]: index.html#incomplete-computation-values
5731 #[inline]
atan2_ref<'a>(&'a self, x: &'a Self) -> Atan2Incomplete<'_>5732 pub fn atan2_ref<'a>(&'a self, x: &'a Self) -> Atan2Incomplete<'_> {
5733 Atan2Incomplete { ref_self: self, x }
5734 }
5735
5736 /// Computes the hyperbolic sine, rounding to the nearest.
5737 ///
5738 /// # Examples
5739 ///
5740 /// ```rust
5741 /// use rug::Float;
5742 /// let f = Float::with_val(53, 1.25);
5743 /// let sinh = f.sinh();
5744 /// let expected = 1.6019_f64;
5745 /// assert!((sinh - expected).abs() < 0.0001);
5746 /// ```
5747 #[inline]
sinh(mut self) -> Self5748 pub fn sinh(mut self) -> Self {
5749 self.sinh_round(Round::Nearest);
5750 self
5751 }
5752
5753 /// Computes the hyperbolic sine, rounding to the nearest.
5754 ///
5755 /// # Examples
5756 ///
5757 /// ```rust
5758 /// use rug::Float;
5759 /// let mut f = Float::with_val(53, 1.25);
5760 /// f.sinh_mut();
5761 /// let expected = 1.6019_f64;
5762 /// assert!((f - expected).abs() < 0.0001);
5763 /// ```
5764 #[inline]
sinh_mut(&mut self)5765 pub fn sinh_mut(&mut self) {
5766 self.sinh_round(Round::Nearest);
5767 }
5768
5769 /// Computes the hyperbolic sine, applying the specified rounding
5770 /// method.
5771 ///
5772 /// # Examples
5773 ///
5774 /// ```rust
5775 /// use core::cmp::Ordering;
5776 /// use rug::{float::Round, Float};
5777 /// // Use only 4 bits of precision to show rounding.
5778 /// let mut f = Float::with_val(4, 1.25);
5779 /// // sinh(1.25) = 1.6019
5780 /// // using 4 significant bits: 1.625
5781 /// let dir = f.sinh_round(Round::Nearest);
5782 /// assert_eq!(f, 1.625);
5783 /// assert_eq!(dir, Ordering::Greater);
5784 /// ```
5785 #[inline]
sinh_round(&mut self, round: Round) -> Ordering5786 pub fn sinh_round(&mut self, round: Round) -> Ordering {
5787 xmpfr::sinh(self, (), round)
5788 }
5789
5790 /// Computes the hyperbolic sine.
5791 ///
5792 /// The following are implemented with the returned
5793 /// [incomplete-computation value][icv] as `Src`:
5794 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
5795 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
5796 ///
5797 /// # Examples
5798 ///
5799 /// ```rust
5800 /// use rug::Float;
5801 /// let f = Float::with_val(53, 1.25);
5802 /// let sinh = Float::with_val(53, f.sinh_ref());
5803 /// let expected = 1.6019_f64;
5804 /// assert!((sinh - expected).abs() < 0.0001);
5805 /// ```
5806 ///
5807 /// [`AssignRound`]: ops/trait.AssignRound.html
5808 /// [`Assign`]: trait.Assign.html
5809 /// [`Float`]: struct.Float.html
5810 /// [icv]: index.html#incomplete-computation-values
5811 #[inline]
sinh_ref(&self) -> SinhIncomplete<'_>5812 pub fn sinh_ref(&self) -> SinhIncomplete<'_> {
5813 SinhIncomplete { ref_self: self }
5814 }
5815
5816 /// Computes the hyperbolic cosine, rounding to the nearest.
5817 ///
5818 /// # Examples
5819 ///
5820 /// ```rust
5821 /// use rug::Float;
5822 /// let f = Float::with_val(53, 1.25);
5823 /// let cosh = f.cosh();
5824 /// let expected = 1.8884_f64;
5825 /// assert!((cosh - expected).abs() < 0.0001);
5826 /// ```
5827 #[inline]
cosh(mut self) -> Self5828 pub fn cosh(mut self) -> Self {
5829 self.cosh_round(Round::Nearest);
5830 self
5831 }
5832
5833 /// Computes the hyperbolic cosine, rounding to the nearest.
5834 ///
5835 /// # Examples
5836 ///
5837 /// ```rust
5838 /// use rug::Float;
5839 /// let mut f = Float::with_val(53, 1.25);
5840 /// f.cosh_mut();
5841 /// let expected = 1.8884_f64;
5842 /// assert!((f - expected).abs() < 0.0001);
5843 /// ```
5844 #[inline]
cosh_mut(&mut self)5845 pub fn cosh_mut(&mut self) {
5846 self.cosh_round(Round::Nearest);
5847 }
5848
5849 /// Computes the hyperbolic cosine, applying the specified
5850 /// rounding method.
5851 ///
5852 /// # Examples
5853 ///
5854 /// ```rust
5855 /// use core::cmp::Ordering;
5856 /// use rug::{float::Round, Float};
5857 /// // Use only 4 bits of precision to show rounding.
5858 /// let mut f = Float::with_val(4, 1.25);
5859 /// // cosh(1.25) = 1.8884
5860 /// // using 4 significant bits: 1.875
5861 /// let dir = f.cosh_round(Round::Nearest);
5862 /// assert_eq!(f, 1.875);
5863 /// assert_eq!(dir, Ordering::Less);
5864 /// ```
5865 #[inline]
cosh_round(&mut self, round: Round) -> Ordering5866 pub fn cosh_round(&mut self, round: Round) -> Ordering {
5867 xmpfr::cosh(self, (), round)
5868 }
5869
5870 /// Computes the hyperbolic cosine.
5871 ///
5872 /// The following are implemented with the returned
5873 /// [incomplete-computation value][icv] as `Src`:
5874 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
5875 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
5876 ///
5877 /// # Examples
5878 ///
5879 /// ```rust
5880 /// use rug::Float;
5881 /// let f = Float::with_val(53, 1.25);
5882 /// let cosh = Float::with_val(53, f.cosh_ref());
5883 /// let expected = 1.8884_f64;
5884 /// assert!((cosh - expected).abs() < 0.0001);
5885 /// ```
5886 ///
5887 /// [`AssignRound`]: ops/trait.AssignRound.html
5888 /// [`Assign`]: trait.Assign.html
5889 /// [`Float`]: struct.Float.html
5890 /// [icv]: index.html#incomplete-computation-values
5891 #[inline]
cosh_ref(&self) -> CoshIncomplete<'_>5892 pub fn cosh_ref(&self) -> CoshIncomplete<'_> {
5893 CoshIncomplete { ref_self: self }
5894 }
5895
5896 /// Computes the hyperbolic tangent, rounding to the nearest.
5897 ///
5898 /// # Examples
5899 ///
5900 /// ```rust
5901 /// use rug::Float;
5902 /// let f = Float::with_val(53, 1.25);
5903 /// let tanh = f.tanh();
5904 /// let expected = 0.8483_f64;
5905 /// assert!((tanh - expected).abs() < 0.0001);
5906 /// ```
5907 #[inline]
tanh(mut self) -> Self5908 pub fn tanh(mut self) -> Self {
5909 self.tanh_round(Round::Nearest);
5910 self
5911 }
5912
5913 /// Computes the hyperbolic tangent, rounding to the nearest.
5914 ///
5915 /// # Examples
5916 ///
5917 /// ```rust
5918 /// use rug::Float;
5919 /// let mut f = Float::with_val(53, 1.25);
5920 /// f.tanh_mut();
5921 /// let expected = 0.8483_f64;
5922 /// assert!((f - expected).abs() < 0.0001);
5923 /// ```
5924 #[inline]
tanh_mut(&mut self)5925 pub fn tanh_mut(&mut self) {
5926 self.tanh_round(Round::Nearest);
5927 }
5928
5929 /// Computes the hyperbolic tangent, applying the specified
5930 /// rounding method.
5931 ///
5932 /// # Examples
5933 ///
5934 /// ```rust
5935 /// use core::cmp::Ordering;
5936 /// use rug::{float::Round, Float};
5937 /// // Use only 4 bits of precision to show rounding.
5938 /// let mut f = Float::with_val(4, 1.25);
5939 /// // tanh(1.25) = 0.8483
5940 /// // using 4 significant bits: 0.875
5941 /// let dir = f.tanh_round(Round::Nearest);
5942 /// assert_eq!(f, 0.875);
5943 /// assert_eq!(dir, Ordering::Greater);
5944 /// ```
5945 #[inline]
tanh_round(&mut self, round: Round) -> Ordering5946 pub fn tanh_round(&mut self, round: Round) -> Ordering {
5947 xmpfr::tanh(self, (), round)
5948 }
5949
5950 /// Computes the hyperbolic tangent.
5951 ///
5952 /// The following are implemented with the returned
5953 /// [incomplete-computation value][icv] as `Src`:
5954 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
5955 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
5956 ///
5957 /// # Examples
5958 ///
5959 /// ```rust
5960 /// use rug::Float;
5961 /// let f = Float::with_val(53, 1.25);
5962 /// let tanh = Float::with_val(53, f.tanh_ref());
5963 /// let expected = 0.8483_f64;
5964 /// assert!((tanh - expected).abs() < 0.0001);
5965 /// ```
5966 ///
5967 /// [`AssignRound`]: ops/trait.AssignRound.html
5968 /// [`Assign`]: trait.Assign.html
5969 /// [`Float`]: struct.Float.html
5970 /// [icv]: index.html#incomplete-computation-values
5971 #[inline]
tanh_ref(&self) -> TanhIncomplete<'_>5972 pub fn tanh_ref(&self) -> TanhIncomplete<'_> {
5973 TanhIncomplete { ref_self: self }
5974 }
5975
5976 /// Computes the hyperbolic sine and cosine of `self`,
5977 /// rounding to the nearest.
5978 ///
5979 /// The sine is stored in `self` and keeps its precision,
5980 /// while the cosine is stored in `cos` keeping its precision.
5981 ///
5982 /// The initial value of `cos` is ignored.
5983 ///
5984 /// # Examples
5985 ///
5986 /// ```rust
5987 /// use rug::Float;
5988 /// let f = Float::with_val(53, 1.25);
5989 /// let (sinh, cosh) = f.sinh_cosh(Float::new(53));
5990 /// let expected_sinh = 1.6019_f64;
5991 /// let expected_cosh = 1.8884_f64;
5992 /// assert!((sinh - expected_sinh).abs() < 0.0001);
5993 /// assert!((cosh - expected_cosh).abs() < 0.0001);
5994 /// ```
5995 #[inline]
sinh_cosh(mut self, mut cos: Self) -> (Self, Self)5996 pub fn sinh_cosh(mut self, mut cos: Self) -> (Self, Self) {
5997 self.sinh_cosh_round(&mut cos, Round::Nearest);
5998 (self, cos)
5999 }
6000
6001 /// Computes the hyperbolic sine and cosine of `self`,
6002 /// rounding to the nearest.
6003 ///
6004 /// The sine is stored in `self` and keeps its precision,
6005 /// while the cosine is stored in `cos` keeping its precision.
6006 ///
6007 /// The initial value of `cos` is ignored.
6008 ///
6009 /// # Examples
6010 ///
6011 /// ```rust
6012 /// use rug::Float;
6013 /// let mut sinh = Float::with_val(53, 1.25);
6014 /// let mut cosh = Float::new(53);
6015 /// sinh.sinh_cosh_mut(&mut cosh);
6016 /// let expected_sinh = 1.6019_f64;
6017 /// let expected_cosh = 1.8884_f64;
6018 /// assert!((sinh - expected_sinh).abs() < 0.0001);
6019 /// assert!((cosh - expected_cosh).abs() < 0.0001);
6020 /// ```
6021 #[inline]
sinh_cosh_mut(&mut self, cos: &mut Self)6022 pub fn sinh_cosh_mut(&mut self, cos: &mut Self) {
6023 self.sinh_cosh_round(cos, Round::Nearest);
6024 }
6025
6026 /// Computes the hyperbolic sine and cosine of `self`,
6027 /// applying the specified rounding method.
6028 ///
6029 /// The sine is stored in `self` and keeps its precision,
6030 /// while the cosine is stored in `cos` keeping its precision.
6031 ///
6032 /// The initial value of `cos` is ignored.
6033 ///
6034 /// # Examples
6035 ///
6036 /// ```rust
6037 /// use core::cmp::Ordering;
6038 /// use rug::{float::Round, Float};
6039 /// // Use only 4 bits of precision to show rounding.
6040 /// let mut sinh = Float::with_val(4, 1.25);
6041 /// let mut cosh = Float::new(4);
6042 /// // sinh(1.25) = 1.6019, using 4 significant bits: 1.625
6043 /// // cosh(1.25) = 1.8884, using 4 significant bits: 1.875
6044 /// let (dir_sinh, dir_cosh) =
6045 /// sinh.sinh_cosh_round(&mut cosh, Round::Nearest);
6046 /// assert_eq!(sinh, 1.625);
6047 /// assert_eq!(dir_sinh, Ordering::Greater);
6048 /// assert_eq!(cosh, 1.875);
6049 /// assert_eq!(dir_cosh, Ordering::Less);
6050 /// ```
6051 #[inline]
sinh_cosh_round(&mut self, cos: &mut Self, round: Round) -> (Ordering, Ordering)6052 pub fn sinh_cosh_round(&mut self, cos: &mut Self, round: Round) -> (Ordering, Ordering) {
6053 xmpfr::sinh_cosh(self, cos, (), round)
6054 }
6055
6056 /// Computes the hyperbolic sine and cosine.
6057 ///
6058 /// The following are implemented with the returned
6059 /// [incomplete-computation value][icv] as `Src`:
6060 /// * <code>[Assign][`Assign`]<Src> for
6061 /// [(][tuple][Float][`Float`],
6062 /// [Float][`Float`][)][tuple]</code>
6063 /// * <code>[Assign][`Assign`]<Src> for
6064 /// [(][tuple]&mut [Float][`Float`],
6065 /// &mut [Float][`Float`][)][tuple]</code>
6066 /// * <code>[AssignRound][`AssignRound`]<Src> for
6067 /// [(][tuple][Float][`Float`],
6068 /// [Float][`Float`][)][tuple]</code>
6069 /// * <code>[AssignRound][`AssignRound`]<Src> for
6070 /// [(][tuple]&mut [Float][`Float`],
6071 /// &mut [Float][`Float`][)][tuple]</code>
6072 ///
6073 /// # Examples
6074 ///
6075 /// ```rust
6076 /// use core::cmp::Ordering;
6077 /// use rug::{float::Round, ops::AssignRound, Assign, Float};
6078 /// let phase = Float::with_val(53, 1.25);
6079 ///
6080 /// let (mut sinh, mut cosh) = (Float::new(53), Float::new(53));
6081 /// let sinh_cosh = phase.sinh_cosh_ref();
6082 /// (&mut sinh, &mut cosh).assign(sinh_cosh);
6083 /// let expected_sinh = 1.6019_f64;
6084 /// let expected_cosh = 1.8884_f64;
6085 /// assert!((sinh - expected_sinh).abs() < 0.0001);
6086 /// assert!((cosh - expected_cosh).abs() < 0.0001);
6087 ///
6088 /// // using 4 significant bits: sin = 1.625
6089 /// // using 4 significant bits: cos = 1.875
6090 /// let (mut sinh_4, mut cosh_4) = (Float::new(4), Float::new(4));
6091 /// let sinh_cosh = phase.sinh_cosh_ref();
6092 /// let (dir_sinh, dir_cosh) = (&mut sinh_4, &mut cosh_4)
6093 /// .assign_round(sinh_cosh, Round::Nearest);
6094 /// assert_eq!(sinh_4, 1.625);
6095 /// assert_eq!(dir_sinh, Ordering::Greater);
6096 /// assert_eq!(cosh_4, 1.875);
6097 /// assert_eq!(dir_cosh, Ordering::Less);
6098 /// ```
6099 ///
6100 /// [`AssignRound`]: ops/trait.AssignRound.html
6101 /// [`Assign`]: trait.Assign.html
6102 /// [`Float`]: struct.Float.html
6103 /// [icv]: index.html#incomplete-computation-values
6104 /// [tuple]: https://doc.rust-lang.org/nightly/std/primitive.tuple.html
6105 #[inline]
sinh_cosh_ref(&self) -> SinhCoshIncomplete<'_>6106 pub fn sinh_cosh_ref(&self) -> SinhCoshIncomplete<'_> {
6107 SinhCoshIncomplete { ref_self: self }
6108 }
6109
6110 /// Computes the hyperbolic secant, rounding to the nearest.
6111 ///
6112 /// # Examples
6113 ///
6114 /// ```rust
6115 /// use rug::Float;
6116 /// let f = Float::with_val(53, 1.25);
6117 /// let sech = f.sech();
6118 /// let expected = 0.5295_f64;
6119 /// assert!((sech - expected).abs() < 0.0001);
6120 /// ```
6121 #[inline]
sech(mut self) -> Self6122 pub fn sech(mut self) -> Self {
6123 self.sech_round(Round::Nearest);
6124 self
6125 }
6126
6127 /// Computes the hyperbolic secant, rounding to the nearest.
6128 ///
6129 /// # Examples
6130 ///
6131 /// ```rust
6132 /// use rug::Float;
6133 /// let mut f = Float::with_val(53, 1.25);
6134 /// f.sech_mut();
6135 /// let expected = 0.5295_f64;
6136 /// assert!((f - expected).abs() < 0.0001);
6137 /// ```
6138 #[inline]
sech_mut(&mut self)6139 pub fn sech_mut(&mut self) {
6140 self.sech_round(Round::Nearest);
6141 }
6142
6143 /// Computes the hyperbolic secant, applying the specified
6144 /// rounding method.
6145 ///
6146 /// # Examples
6147 ///
6148 /// ```rust
6149 /// use core::cmp::Ordering;
6150 /// use rug::{float::Round, Float};
6151 /// // Use only 4 bits of precision to show rounding.
6152 /// let mut f = Float::with_val(4, 1.25);
6153 /// // sech(1.25) = 0.5295
6154 /// // using 4 significant bits: 0.5
6155 /// let dir = f.sech_round(Round::Nearest);
6156 /// assert_eq!(f, 0.5);
6157 /// assert_eq!(dir, Ordering::Less);
6158 /// ```
6159 #[inline]
sech_round(&mut self, round: Round) -> Ordering6160 pub fn sech_round(&mut self, round: Round) -> Ordering {
6161 xmpfr::sech(self, (), round)
6162 }
6163
6164 /// Computes the hyperbolic secant.
6165 ///
6166 /// The following are implemented with the returned
6167 /// [incomplete-computation value][icv] as `Src`:
6168 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
6169 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
6170 ///
6171 /// # Examples
6172 ///
6173 /// ```rust
6174 /// use rug::Float;
6175 /// let f = Float::with_val(53, 1.25);
6176 /// let sech = Float::with_val(53, f.sech_ref());
6177 /// let expected = 0.5295_f64;
6178 /// assert!((sech - expected).abs() < 0.0001);
6179 /// ```
6180 ///
6181 /// [`AssignRound`]: ops/trait.AssignRound.html
6182 /// [`Assign`]: trait.Assign.html
6183 /// [`Float`]: struct.Float.html
6184 /// [icv]: index.html#incomplete-computation-values
6185 #[inline]
sech_ref(&self) -> SechIncomplete<'_>6186 pub fn sech_ref(&self) -> SechIncomplete<'_> {
6187 SechIncomplete { ref_self: self }
6188 }
6189
6190 /// Computes the hyperbolic cosecant, rounding to the nearest.
6191 ///
6192 /// # Examples
6193 ///
6194 /// ```rust
6195 /// use rug::Float;
6196 /// let f = Float::with_val(53, 1.25);
6197 /// let csch = f.csch();
6198 /// let expected = 0.6243_f64;
6199 /// assert!((csch - expected).abs() < 0.0001);
6200 /// ```
6201 #[inline]
csch(mut self) -> Self6202 pub fn csch(mut self) -> Self {
6203 self.csch_round(Round::Nearest);
6204 self
6205 }
6206
6207 /// Computes the hyperbolic cosecant, rounding to the nearest.
6208 ///
6209 /// # Examples
6210 ///
6211 /// ```rust
6212 /// use rug::Float;
6213 /// let mut f = Float::with_val(53, 1.25);
6214 /// f.csch_mut();
6215 /// let expected = 0.6243_f64;
6216 /// assert!((f - expected).abs() < 0.0001);
6217 /// ```
6218 #[inline]
csch_mut(&mut self)6219 pub fn csch_mut(&mut self) {
6220 self.csch_round(Round::Nearest);
6221 }
6222
6223 /// Computes the hyperbolic cosecant, applying the specified
6224 /// rounding method.
6225 ///
6226 /// # Examples
6227 ///
6228 /// ```rust
6229 /// use core::cmp::Ordering;
6230 /// use rug::{float::Round, Float};
6231 /// // Use only 4 bits of precision to show rounding.
6232 /// let mut f = Float::with_val(4, 1.25);
6233 /// // csch(1.25) = 0.6243
6234 /// // using 4 significant bits: 0.625
6235 /// let dir = f.csch_round(Round::Nearest);
6236 /// assert_eq!(f, 0.625);
6237 /// assert_eq!(dir, Ordering::Greater);
6238 /// ```
6239 #[inline]
csch_round(&mut self, round: Round) -> Ordering6240 pub fn csch_round(&mut self, round: Round) -> Ordering {
6241 xmpfr::csch(self, (), round)
6242 }
6243
6244 /// Computes the hyperbolic cosecant.
6245 ///
6246 /// The following are implemented with the returned
6247 /// [incomplete-computation value][icv] as `Src`:
6248 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
6249 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
6250 ///
6251 /// # Examples
6252 ///
6253 /// ```rust
6254 /// use rug::Float;
6255 /// let f = Float::with_val(53, 1.25);
6256 /// let csch = Float::with_val(53, f.csch_ref());
6257 /// let expected = 0.6243_f64;
6258 /// assert!((csch - expected).abs() < 0.0001);
6259 /// ```
6260 ///
6261 /// [`AssignRound`]: ops/trait.AssignRound.html
6262 /// [`Assign`]: trait.Assign.html
6263 /// [`Float`]: struct.Float.html
6264 /// [icv]: index.html#incomplete-computation-values
6265 #[inline]
csch_ref(&self) -> CschIncomplete<'_>6266 pub fn csch_ref(&self) -> CschIncomplete<'_> {
6267 CschIncomplete { ref_self: self }
6268 }
6269
6270 /// Computes the hyperbolic cotangent, rounding to the nearest.
6271 ///
6272 /// # Examples
6273 ///
6274 /// ```rust
6275 /// use rug::Float;
6276 /// let f = Float::with_val(53, 1.25);
6277 /// let coth = f.coth();
6278 /// let expected = 1.1789_f64;
6279 /// assert!((coth - expected).abs() < 0.0001);
6280 /// ```
6281 #[inline]
coth(mut self) -> Self6282 pub fn coth(mut self) -> Self {
6283 self.coth_round(Round::Nearest);
6284 self
6285 }
6286
6287 /// Computes the hyperbolic cotangent, rounding to the nearest.
6288 ///
6289 /// # Examples
6290 ///
6291 /// ```rust
6292 /// use rug::Float;
6293 /// let mut f = Float::with_val(53, 1.25);
6294 /// f.coth_mut();
6295 /// let expected = 1.1789_f64;
6296 /// assert!((f - expected).abs() < 0.0001);
6297 /// ```
6298 #[inline]
coth_mut(&mut self)6299 pub fn coth_mut(&mut self) {
6300 self.coth_round(Round::Nearest);
6301 }
6302
6303 /// Computes the hyperbolic cotangent, applying the specified
6304 /// rounding method.
6305 ///
6306 /// # Examples
6307 ///
6308 /// ```rust
6309 /// use core::cmp::Ordering;
6310 /// use rug::{float::Round, Float};
6311 /// // Use only 4 bits of precision to show rounding.
6312 /// let mut f = Float::with_val(4, 1.25);
6313 /// // coth(1.25) = 1.1789
6314 /// // using 4 significant bits: 1.125
6315 /// let dir = f.coth_round(Round::Nearest);
6316 /// assert_eq!(f, 1.125);
6317 /// assert_eq!(dir, Ordering::Less);
6318 /// ```
6319 #[inline]
coth_round(&mut self, round: Round) -> Ordering6320 pub fn coth_round(&mut self, round: Round) -> Ordering {
6321 xmpfr::coth(self, (), round)
6322 }
6323
6324 /// Computes the hyperbolic cotangent.
6325 ///
6326 /// The following are implemented with the returned
6327 /// [incomplete-computation value][icv] as `Src`:
6328 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
6329 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
6330 ///
6331 /// # Examples
6332 ///
6333 /// ```rust
6334 /// use rug::Float;
6335 /// let f = Float::with_val(53, 1.25);
6336 /// let coth = Float::with_val(53, f.coth_ref());
6337 /// let expected = 1.1789_f64;
6338 /// assert!((coth - expected).abs() < 0.0001);
6339 /// ```
6340 ///
6341 /// [`AssignRound`]: ops/trait.AssignRound.html
6342 /// [`Assign`]: trait.Assign.html
6343 /// [`Float`]: struct.Float.html
6344 /// [icv]: index.html#incomplete-computation-values
6345 #[inline]
coth_ref(&self) -> CothIncomplete<'_>6346 pub fn coth_ref(&self) -> CothIncomplete<'_> {
6347 CothIncomplete { ref_self: self }
6348 }
6349
6350 /// Computes the inverse hyperbolic sine, rounding to the nearest.
6351 ///
6352 /// # Examples
6353 ///
6354 /// ```rust
6355 /// use rug::Float;
6356 /// let f = Float::with_val(53, 1.25);
6357 /// let asinh = f.asinh();
6358 /// let expected = 1.0476_f64;
6359 /// assert!((asinh - expected).abs() < 0.0001);
6360 /// ```
6361 #[inline]
asinh(mut self) -> Self6362 pub fn asinh(mut self) -> Self {
6363 self.asinh_round(Round::Nearest);
6364 self
6365 }
6366
6367 /// Computes the inverse hyperbolic sine, rounding to the nearest.
6368 ///
6369 /// # Examples
6370 ///
6371 /// ```rust
6372 /// use rug::Float;
6373 /// let mut f = Float::with_val(53, 1.25);
6374 /// f.asinh_mut();
6375 /// let expected = 1.0476_f64;
6376 /// assert!((f - expected).abs() < 0.0001);
6377 /// ```
6378 #[inline]
asinh_mut(&mut self)6379 pub fn asinh_mut(&mut self) {
6380 self.asinh_round(Round::Nearest);
6381 }
6382
6383 /// Computes the inverse hyperbolic sine, applying the specified
6384 /// rounding method.
6385 ///
6386 /// # Examples
6387 ///
6388 /// ```rust
6389 /// use core::cmp::Ordering;
6390 /// use rug::{float::Round, Float};
6391 /// // Use only 4 bits of precision to show rounding.
6392 /// let mut f = Float::with_val(4, 1.25);
6393 /// // asinh(1.25) = 1.0476
6394 /// // using 4 significant bits: 1.0
6395 /// let dir = f.asinh_round(Round::Nearest);
6396 /// assert_eq!(f, 1.0);
6397 /// assert_eq!(dir, Ordering::Less);
6398 /// ```
6399 #[inline]
asinh_round(&mut self, round: Round) -> Ordering6400 pub fn asinh_round(&mut self, round: Round) -> Ordering {
6401 xmpfr::asinh(self, (), round)
6402 }
6403
6404 /// Computes the inverse hyperbolic sine.
6405 ///
6406 /// The following are implemented with the returned
6407 /// [incomplete-computation value][icv] as `Src`:
6408 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
6409 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
6410 ///
6411 /// # Examples
6412 ///
6413 /// ```rust
6414 /// use rug::Float;
6415 /// let f = Float::with_val(53, 1.25);
6416 /// let asinh = Float::with_val(53, f.asinh_ref());
6417 /// let expected = 1.0476_f64;
6418 /// assert!((asinh - expected).abs() < 0.0001);
6419 /// ```
6420 ///
6421 /// [`AssignRound`]: ops/trait.AssignRound.html
6422 /// [`Assign`]: trait.Assign.html
6423 /// [`Float`]: struct.Float.html
6424 /// [icv]: index.html#incomplete-computation-values
6425 #[inline]
asinh_ref(&self) -> AsinhIncomplete<'_>6426 pub fn asinh_ref(&self) -> AsinhIncomplete<'_> {
6427 AsinhIncomplete { ref_self: self }
6428 }
6429
6430 /// Computes the inverse hyperbolic cosine, rounding to the
6431 /// nearest.
6432 ///
6433 /// # Examples
6434 ///
6435 /// ```rust
6436 /// use rug::Float;
6437 /// let f = Float::with_val(53, 1.25);
6438 /// let acosh = f.acosh();
6439 /// let expected = 0.6931_f64;
6440 /// assert!((acosh - expected).abs() < 0.0001);
6441 /// ```
6442 #[inline]
acosh(mut self) -> Self6443 pub fn acosh(mut self) -> Self {
6444 self.acosh_round(Round::Nearest);
6445 self
6446 }
6447
6448 /// Computes the inverse hyperbolic cosine, rounding to the
6449 /// nearest.
6450 ///
6451 /// # Examples
6452 ///
6453 /// ```rust
6454 /// use rug::Float;
6455 /// let mut f = Float::with_val(53, 1.25);
6456 /// f.acosh_mut();
6457 /// let expected = 0.6931_f64;
6458 /// assert!((f - expected).abs() < 0.0001);
6459 /// ```
6460 #[inline]
acosh_mut(&mut self)6461 pub fn acosh_mut(&mut self) {
6462 self.acosh_round(Round::Nearest);
6463 }
6464
6465 /// Computes the inverse hyperbolic cosine, applying the specified
6466 /// rounding method.
6467 ///
6468 /// # Examples
6469 ///
6470 /// ```rust
6471 /// use core::cmp::Ordering;
6472 /// use rug::{float::Round, Float};
6473 /// // Use only 4 bits of precision to show rounding.
6474 /// let mut f = Float::with_val(4, 1.25);
6475 /// // acosh(1.25) = 0.6931
6476 /// // using 4 significant bits: 0.6875
6477 /// let dir = f.acosh_round(Round::Nearest);
6478 /// assert_eq!(f, 0.6875);
6479 /// assert_eq!(dir, Ordering::Less);
6480 /// ```
6481 #[inline]
acosh_round(&mut self, round: Round) -> Ordering6482 pub fn acosh_round(&mut self, round: Round) -> Ordering {
6483 xmpfr::acosh(self, (), round)
6484 }
6485
6486 /// Computes the inverse hyperbolic cosine
6487 ///
6488 /// The following are implemented with the returned
6489 /// [incomplete-computation value][icv] as `Src`:
6490 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
6491 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
6492 ///
6493 /// # Examples
6494 ///
6495 /// ```rust
6496 /// use rug::Float;
6497 /// let f = Float::with_val(53, 1.25);
6498 /// let acosh = Float::with_val(53, f.acosh_ref());
6499 /// let expected = 0.6931_f64;
6500 /// assert!((acosh - expected).abs() < 0.0001);
6501 /// ```
6502 ///
6503 /// [`AssignRound`]: ops/trait.AssignRound.html
6504 /// [`Assign`]: trait.Assign.html
6505 /// [`Float`]: struct.Float.html
6506 /// [icv]: index.html#incomplete-computation-values
6507 #[inline]
acosh_ref(&self) -> AcoshIncomplete<'_>6508 pub fn acosh_ref(&self) -> AcoshIncomplete<'_> {
6509 AcoshIncomplete { ref_self: self }
6510 }
6511
6512 /// Computes the inverse hyperbolic tangent, rounding to the
6513 /// nearest.
6514 ///
6515 /// # Examples
6516 ///
6517 /// ```rust
6518 /// use rug::Float;
6519 /// let f = Float::with_val(53, 0.75);
6520 /// let atanh = f.atanh();
6521 /// let expected = 0.9730_f64;
6522 /// assert!((atanh - expected).abs() < 0.0001);
6523 /// ```
6524 #[inline]
atanh(mut self) -> Self6525 pub fn atanh(mut self) -> Self {
6526 self.atanh_round(Round::Nearest);
6527 self
6528 }
6529
6530 /// Computes the inverse hyperbolic tangent, rounding to the
6531 /// nearest.
6532 ///
6533 /// # Examples
6534 ///
6535 /// ```rust
6536 /// use rug::Float;
6537 /// let mut f = Float::with_val(53, 0.75);
6538 /// f.atanh_mut();
6539 /// let expected = 0.9730_f64;
6540 /// assert!((f - expected).abs() < 0.0001);
6541 /// ```
6542 #[inline]
atanh_mut(&mut self)6543 pub fn atanh_mut(&mut self) {
6544 self.atanh_round(Round::Nearest);
6545 }
6546
6547 /// Computes the inverse hyperbolic tangent, applying the
6548 /// specified rounding method.
6549 ///
6550 /// # Examples
6551 ///
6552 /// ```rust
6553 /// use core::cmp::Ordering;
6554 /// use rug::{float::Round, Float};
6555 /// // Use only 4 bits of precision to show rounding.
6556 /// let mut f = Float::with_val(4, 0.75);
6557 /// // atanh(0.75) = 0.9730
6558 /// // using 4 significant bits: 1.0
6559 /// let dir = f.atanh_round(Round::Nearest);
6560 /// assert_eq!(f, 1.0);
6561 /// assert_eq!(dir, Ordering::Greater);
6562 /// ```
6563 #[inline]
atanh_round(&mut self, round: Round) -> Ordering6564 pub fn atanh_round(&mut self, round: Round) -> Ordering {
6565 xmpfr::atanh(self, (), round)
6566 }
6567
6568 /// Computes the inverse hyperbolic tangent.
6569 ///
6570 /// The following are implemented with the returned
6571 /// [incomplete-computation value][icv] as `Src`:
6572 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
6573 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
6574 ///
6575 /// # Examples
6576 ///
6577 /// ```rust
6578 /// use rug::Float;
6579 /// let f = Float::with_val(53, 0.75);
6580 /// let atanh = Float::with_val(53, f.atanh_ref());
6581 /// let expected = 0.9730_f64;
6582 /// assert!((atanh - expected).abs() < 0.0001);
6583 /// ```
6584 ///
6585 /// [`AssignRound`]: ops/trait.AssignRound.html
6586 /// [`Assign`]: trait.Assign.html
6587 /// [`Float`]: struct.Float.html
6588 /// [icv]: index.html#incomplete-computation-values
6589 #[inline]
atanh_ref(&self) -> AtanhIncomplete<'_>6590 pub fn atanh_ref(&self) -> AtanhIncomplete<'_> {
6591 AtanhIncomplete { ref_self: self }
6592 }
6593
6594 /// Computes the factorial of <i>n</i>.
6595 ///
6596 /// The following are implemented with the returned
6597 /// [incomplete-computation value][icv] as `Src`:
6598 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
6599 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
6600 ///
6601 /// # Examples
6602 ///
6603 /// ```rust
6604 /// use rug::Float;
6605 /// // 10 × 9 × 8 × 7 × 6 × 5 × 4 × 3 × 2 × 1
6606 /// let n = Float::factorial(10);
6607 /// let f = Float::with_val(53, n);
6608 /// assert_eq!(f, 3628800.0);
6609 /// ```
6610 ///
6611 /// [`AssignRound`]: ops/trait.AssignRound.html
6612 /// [`Assign`]: trait.Assign.html
6613 /// [`Float`]: struct.Float.html
6614 /// [icv]: index.html#incomplete-computation-values
6615 #[inline]
factorial(n: u32) -> FactorialIncomplete6616 pub fn factorial(n: u32) -> FactorialIncomplete {
6617 FactorialIncomplete { n }
6618 }
6619
6620 /// Computes the natural logarithm of one plus `self`, rounding to
6621 /// the nearest.
6622 ///
6623 /// # Examples
6624 ///
6625 /// ```rust
6626 /// use rug::Float;
6627 /// let two_to_m10 = (-10f64).exp2();
6628 /// let f = Float::with_val(53, 1.5 * two_to_m10);
6629 /// let ln_1p = f.ln_1p();
6630 /// let expected = 1.4989_f64 * two_to_m10;
6631 /// assert!((ln_1p - expected).abs() < 0.0001 * two_to_m10);
6632 /// ```
6633 #[inline]
ln_1p(mut self) -> Self6634 pub fn ln_1p(mut self) -> Self {
6635 self.ln_1p_round(Round::Nearest);
6636 self
6637 }
6638
6639 /// Computes the natural logarithm of one plus `self`, rounding to
6640 /// the nearest.
6641 ///
6642 /// # Examples
6643 ///
6644 /// ```rust
6645 /// use rug::Float;
6646 /// let two_to_m10 = (-10f64).exp2();
6647 /// let mut f = Float::with_val(53, 1.5 * two_to_m10);
6648 /// f.ln_1p_mut();
6649 /// let expected = 1.4989_f64 * two_to_m10;
6650 /// assert!((f - expected).abs() < 0.0001 * two_to_m10);
6651 /// ```
6652 #[inline]
ln_1p_mut(&mut self)6653 pub fn ln_1p_mut(&mut self) {
6654 self.ln_1p_round(Round::Nearest);
6655 }
6656
6657 /// Computes the natural logarithm of one plus `self`, applying
6658 /// the specified rounding method.
6659 ///
6660 /// # Examples
6661 ///
6662 /// ```rust
6663 /// use core::cmp::Ordering;
6664 /// use rug::{float::Round, Float};
6665 /// let two_to_m10 = (-10f64).exp2();
6666 /// // Use only 4 bits of precision to show rounding.
6667 /// let mut f = Float::with_val(4, 1.5 * two_to_m10);
6668 /// // ln_1p(1.5 × 2 ^ −10) = 1.4989 × 2 ^ −10
6669 /// // using 4 significant bits: 1.5 × 2 ^ −10
6670 /// let dir = f.ln_1p_round(Round::Nearest);
6671 /// assert_eq!(f, 1.5 * two_to_m10);
6672 /// assert_eq!(dir, Ordering::Greater);
6673 /// ```
6674 #[inline]
ln_1p_round(&mut self, round: Round) -> Ordering6675 pub fn ln_1p_round(&mut self, round: Round) -> Ordering {
6676 xmpfr::log1p(self, (), round)
6677 }
6678
6679 /// Computes the natural logorithm of one plus the value.
6680 ///
6681 /// The following are implemented with the returned
6682 /// [incomplete-computation value][icv] as `Src`:
6683 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
6684 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
6685 ///
6686 /// # Examples
6687 ///
6688 /// ```rust
6689 /// use rug::Float;
6690 /// let two_to_m10 = (-10f64).exp2();
6691 /// let f = Float::with_val(53, 1.5 * two_to_m10);
6692 /// let ln_1p = Float::with_val(53, f.ln_1p_ref());
6693 /// let expected = 1.4989_f64 * two_to_m10;
6694 /// assert!((ln_1p - expected).abs() < 0.0001 * two_to_m10);
6695 /// ```
6696 ///
6697 /// [`AssignRound`]: ops/trait.AssignRound.html
6698 /// [`Assign`]: trait.Assign.html
6699 /// [`Float`]: struct.Float.html
6700 /// [icv]: index.html#incomplete-computation-values
6701 #[inline]
ln_1p_ref(&self) -> Ln1pIncomplete<'_>6702 pub fn ln_1p_ref(&self) -> Ln1pIncomplete<'_> {
6703 Ln1pIncomplete { ref_self: self }
6704 }
6705
6706 /// Subtracts one from the exponential of `self`, rounding to the
6707 /// nearest.
6708 ///
6709 /// # Examples
6710 ///
6711 /// ```rust
6712 /// use rug::Float;
6713 /// let two_to_m10 = (-10f64).exp2();
6714 /// let f = Float::with_val(53, 1.5 * two_to_m10);
6715 /// let exp_m1 = f.exp_m1();
6716 /// let expected = 1.5011_f64 * two_to_m10;
6717 /// assert!((exp_m1 - expected).abs() < 0.0001 * two_to_m10);
6718 /// ```
6719 #[inline]
exp_m1(mut self) -> Self6720 pub fn exp_m1(mut self) -> Self {
6721 self.exp_m1_round(Round::Nearest);
6722 self
6723 }
6724
6725 /// Subtracts one from the exponential of `self`, rounding to the
6726 /// nearest.
6727 ///
6728 /// # Examples
6729 ///
6730 /// ```rust
6731 /// use rug::Float;
6732 /// let two_to_m10 = (-10f64).exp2();
6733 /// let mut f = Float::with_val(53, 1.5 * two_to_m10);
6734 /// f.exp_m1_mut();
6735 /// let expected = 1.5011_f64 * two_to_m10;
6736 /// assert!((f - expected).abs() < 0.0001 * two_to_m10);
6737 /// ```
6738 #[inline]
exp_m1_mut(&mut self)6739 pub fn exp_m1_mut(&mut self) {
6740 self.exp_m1_round(Round::Nearest);
6741 }
6742
6743 /// Subtracts one from the exponential of `self`, applying the
6744 /// specified rounding method.
6745 ///
6746 /// # Examples
6747 ///
6748 /// ```rust
6749 /// use core::cmp::Ordering;
6750 /// use rug::{float::Round, Float};
6751 /// let two_to_m10 = (-10f64).exp2();
6752 /// // Use only 4 bits of precision to show rounding.
6753 /// let mut f = Float::with_val(4, 1.5 * two_to_m10);
6754 /// // exp_m1(1.5 × 2 ^ −10) = 1.5011 × 2 ^ −10
6755 /// // using 4 significant bits: 1.5 × 2 ^ −10
6756 /// let dir = f.exp_m1_round(Round::Nearest);
6757 /// assert_eq!(f, 1.5 * two_to_m10);
6758 /// assert_eq!(dir, Ordering::Less);
6759 /// ```
6760 #[inline]
exp_m1_round(&mut self, round: Round) -> Ordering6761 pub fn exp_m1_round(&mut self, round: Round) -> Ordering {
6762 xmpfr::expm1(self, (), round)
6763 }
6764
6765 /// Computes one less than the exponential of the
6766 /// value.
6767 ///
6768 /// The following are implemented with the returned
6769 /// [incomplete-computation value][icv] as `Src`:
6770 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
6771 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
6772 ///
6773 /// # Examples
6774 ///
6775 /// ```rust
6776 /// use rug::Float;
6777 /// let two_to_m10 = (-10f64).exp2();
6778 /// let f = Float::with_val(53, 1.5 * two_to_m10);
6779 /// let exp_m1 = Float::with_val(53, f.exp_m1_ref());
6780 /// let expected = 1.5011_f64 * two_to_m10;
6781 /// assert!((exp_m1 - expected).abs() < 0.0001 * two_to_m10);
6782 /// ```
6783 ///
6784 /// [`AssignRound`]: ops/trait.AssignRound.html
6785 /// [`Assign`]: trait.Assign.html
6786 /// [`Float`]: struct.Float.html
6787 /// [icv]: index.html#incomplete-computation-values
6788 #[inline]
exp_m1_ref(&self) -> ExpM1Incomplete<'_>6789 pub fn exp_m1_ref(&self) -> ExpM1Incomplete<'_> {
6790 ExpM1Incomplete { ref_self: self }
6791 }
6792
6793 /// Computes the exponential integral, rounding to the nearest.
6794 ///
6795 /// # Examples
6796 ///
6797 /// ```rust
6798 /// use rug::Float;
6799 /// let f = Float::with_val(53, 1.25);
6800 /// let eint = f.eint();
6801 /// let expected = 2.5810_f64;
6802 /// assert!((eint - expected).abs() < 0.0001);
6803 /// ```
6804 #[inline]
eint(mut self) -> Self6805 pub fn eint(mut self) -> Self {
6806 self.eint_round(Round::Nearest);
6807 self
6808 }
6809
6810 /// Computes the exponential integral, rounding to the nearest.
6811 ///
6812 /// # Examples
6813 ///
6814 /// ```rust
6815 /// use rug::Float;
6816 /// let mut f = Float::with_val(53, 1.25);
6817 /// f.eint_mut();
6818 /// let expected = 2.5810_f64;
6819 /// assert!((f - expected).abs() < 0.0001);
6820 /// ```
6821 #[inline]
eint_mut(&mut self)6822 pub fn eint_mut(&mut self) {
6823 self.eint_round(Round::Nearest);
6824 }
6825
6826 /// Computes the exponential integral, applying the specified
6827 /// rounding method.
6828 ///
6829 /// # Examples
6830 ///
6831 /// ```rust
6832 /// use core::cmp::Ordering;
6833 /// use rug::{float::Round, Float};
6834 /// // Use only 4 bits of precision to show rounding.
6835 /// let mut f = Float::with_val(4, 1.25);
6836 /// // eint(1.25) = 2.5810
6837 /// // using 4 significant bits: 2.5
6838 /// let dir = f.eint_round(Round::Nearest);
6839 /// assert_eq!(f, 2.5);
6840 /// assert_eq!(dir, Ordering::Less);
6841 /// ```
6842 #[inline]
eint_round(&mut self, round: Round) -> Ordering6843 pub fn eint_round(&mut self, round: Round) -> Ordering {
6844 xmpfr::eint(self, (), round)
6845 }
6846
6847 /// Computes the exponential integral.
6848 ///
6849 /// The following are implemented with the returned
6850 /// [incomplete-computation value][icv] as `Src`:
6851 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
6852 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
6853 ///
6854 /// # Examples
6855 ///
6856 /// ```rust
6857 /// use rug::Float;
6858 /// let f = Float::with_val(53, 1.25);
6859 /// let eint = Float::with_val(53, f.eint_ref());
6860 /// let expected = 2.5810_f64;
6861 /// assert!((eint - expected).abs() < 0.0001);
6862 /// ```
6863 ///
6864 /// [`AssignRound`]: ops/trait.AssignRound.html
6865 /// [`Assign`]: trait.Assign.html
6866 /// [`Float`]: struct.Float.html
6867 /// [icv]: index.html#incomplete-computation-values
6868 #[inline]
eint_ref(&self) -> EintIncomplete<'_>6869 pub fn eint_ref(&self) -> EintIncomplete<'_> {
6870 EintIncomplete { ref_self: self }
6871 }
6872
6873 /// Computes the real part of the dilogarithm of `self`, rounding
6874 /// to the nearest.
6875 ///
6876 /// # Examples
6877 ///
6878 /// ```rust
6879 /// use rug::Float;
6880 /// let f = Float::with_val(53, 1.25);
6881 /// let li2 = f.li2();
6882 /// let expected = 2.1902_f64;
6883 /// assert!((li2 - expected).abs() < 0.0001);
6884 /// ```
6885 #[inline]
li2(mut self) -> Self6886 pub fn li2(mut self) -> Self {
6887 self.li2_round(Round::Nearest);
6888 self
6889 }
6890
6891 /// Computes the real part of the dilogarithm of `self`, rounding
6892 /// to the nearest.
6893 ///
6894 /// # Examples
6895 ///
6896 /// ```rust
6897 /// use rug::Float;
6898 /// let mut f = Float::with_val(53, 1.25);
6899 /// f.li2_mut();
6900 /// let expected = 2.1902_f64;
6901 /// assert!((f - expected).abs() < 0.0001);
6902 /// ```
6903 #[inline]
li2_mut(&mut self)6904 pub fn li2_mut(&mut self) {
6905 self.li2_round(Round::Nearest);
6906 }
6907
6908 /// Computes the real part of the dilogarithm of `self`, applying
6909 /// the specified rounding method.
6910 ///
6911 /// # Examples
6912 ///
6913 /// ```rust
6914 /// use core::cmp::Ordering;
6915 /// use rug::{float::Round, Float};
6916 /// // Use only 4 bits of precision to show rounding.
6917 /// let mut f = Float::with_val(4, 1.25);
6918 /// // li2(1.25) = 2.1902
6919 /// // using 4 significant bits: 2.25
6920 /// let dir = f.li2_round(Round::Nearest);
6921 /// assert_eq!(f, 2.25);
6922 /// assert_eq!(dir, Ordering::Greater);
6923 /// ```
6924 #[inline]
li2_round(&mut self, round: Round) -> Ordering6925 pub fn li2_round(&mut self, round: Round) -> Ordering {
6926 xmpfr::li2(self, (), round)
6927 }
6928
6929 /// Computes the real part of the dilogarithm of the
6930 /// value.
6931 ///
6932 /// The following are implemented with the returned
6933 /// [incomplete-computation value][icv] as `Src`:
6934 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
6935 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
6936 ///
6937 /// # Examples
6938 ///
6939 /// ```rust
6940 /// use rug::Float;
6941 /// let f = Float::with_val(53, 1.25);
6942 /// let li2 = Float::with_val(53, f.li2_ref());
6943 /// let expected = 2.1902_f64;
6944 /// assert!((li2 - expected).abs() < 0.0001);
6945 /// ```
6946 ///
6947 /// [`AssignRound`]: ops/trait.AssignRound.html
6948 /// [`Assign`]: trait.Assign.html
6949 /// [`Float`]: struct.Float.html
6950 /// [icv]: index.html#incomplete-computation-values
6951 #[inline]
li2_ref(&self) -> Li2Incomplete<'_>6952 pub fn li2_ref(&self) -> Li2Incomplete<'_> {
6953 Li2Incomplete { ref_self: self }
6954 }
6955
6956 /// Computes the value of the gamma function on `self`, rounding
6957 /// to the nearest.
6958 ///
6959 /// # Examples
6960 ///
6961 /// ```rust
6962 /// use rug::Float;
6963 /// let f = Float::with_val(53, 1.25);
6964 /// let gamma = f.gamma();
6965 /// let expected = 0.9064_f64;
6966 /// assert!((gamma - expected).abs() < 0.0001);
6967 /// ```
6968 #[inline]
gamma(mut self) -> Self6969 pub fn gamma(mut self) -> Self {
6970 self.gamma_round(Round::Nearest);
6971 self
6972 }
6973
6974 /// Computes the value of the gamma function on `self`, rounding
6975 /// to the nearest.
6976 ///
6977 /// # Examples
6978 ///
6979 /// ```rust
6980 /// use rug::Float;
6981 /// let mut f = Float::with_val(53, 1.25);
6982 /// f.gamma_mut();
6983 /// let expected = 0.9064_f64;
6984 /// assert!((f - expected).abs() < 0.0001);
6985 /// ```
6986 #[inline]
gamma_mut(&mut self)6987 pub fn gamma_mut(&mut self) {
6988 self.gamma_round(Round::Nearest);
6989 }
6990
6991 /// Computes the value of the gamma function on `self`, applying
6992 /// the specified rounding method.
6993 ///
6994 /// # Examples
6995 ///
6996 /// ```rust
6997 /// use core::cmp::Ordering;
6998 /// use rug::{float::Round, Float};
6999 /// // Use only 4 bits of precision to show rounding.
7000 /// let mut f = Float::with_val(4, 1.25);
7001 /// // gamma(1.25) = 0.9064
7002 /// // using 4 significant bits: 0.9375
7003 /// let dir = f.gamma_round(Round::Nearest);
7004 /// assert_eq!(f, 0.9375);
7005 /// assert_eq!(dir, Ordering::Greater);
7006 /// ```
7007 #[inline]
gamma_round(&mut self, round: Round) -> Ordering7008 pub fn gamma_round(&mut self, round: Round) -> Ordering {
7009 xmpfr::gamma(self, (), round)
7010 }
7011
7012 /// Computes the gamma function on the value.
7013 ///
7014 /// The following are implemented with the returned
7015 /// [incomplete-computation value][icv] as `Src`:
7016 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
7017 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
7018 ///
7019 /// # Examples
7020 ///
7021 /// ```rust
7022 /// use rug::Float;
7023 /// let f = Float::with_val(53, 1.25);
7024 /// let gamma = Float::with_val(53, f.gamma_ref());
7025 /// let expected = 0.9064_f64;
7026 /// assert!((gamma - expected).abs() < 0.0001);
7027 /// ```
7028 ///
7029 /// [`AssignRound`]: ops/trait.AssignRound.html
7030 /// [`Assign`]: trait.Assign.html
7031 /// [`Float`]: struct.Float.html
7032 /// [icv]: index.html#incomplete-computation-values
7033 #[inline]
gamma_ref(&self) -> GammaIncomplete<'_>7034 pub fn gamma_ref(&self) -> GammaIncomplete<'_> {
7035 GammaIncomplete { ref_self: self }
7036 }
7037
7038 /// Computes the value of the upper incomplete gamma function
7039 /// on `self` and `x`, rounding to the nearest.
7040 ///
7041 /// # Examples
7042 ///
7043 /// ```rust
7044 /// use rug::Float;
7045 /// let f = Float::with_val(53, 1.25);
7046 /// let x = Float::with_val(53, 2.5);
7047 /// let gamma_inc = f.gamma_inc(&x);
7048 /// let expected = 0.1116_f64;
7049 /// assert!((gamma_inc - expected).abs() < 0.0001);
7050 /// ```
7051 #[inline]
gamma_inc(mut self, x: &Self) -> Self7052 pub fn gamma_inc(mut self, x: &Self) -> Self {
7053 self.gamma_inc_round(x, Round::Nearest);
7054 self
7055 }
7056
7057 /// Computes the value of the upper incomplete gamma function
7058 /// on `self`, rounding to the nearest.
7059 ///
7060 /// # Examples
7061 ///
7062 /// ```rust
7063 /// use rug::Float;
7064 /// let mut f = Float::with_val(53, 1.25);
7065 /// let x = Float::with_val(53, 2.5);
7066 /// f.gamma_inc_mut(&x);
7067 /// let expected = 0.1116_f64;
7068 /// assert!((f - expected).abs() < 0.0001);
7069 /// ```
7070 #[inline]
gamma_inc_mut(&mut self, x: &Self)7071 pub fn gamma_inc_mut(&mut self, x: &Self) {
7072 self.gamma_inc_round(x, Round::Nearest);
7073 }
7074
7075 /// Computes the value of the upper incomplete gamma function
7076 /// on `self`, applying the specified rounding method.
7077 ///
7078 /// # Examples
7079 ///
7080 /// ```rust
7081 /// use core::cmp::Ordering;
7082 /// use rug::{float::Round, Float};
7083 /// // Use only 4 bits of precision to show rounding.
7084 /// let mut f = Float::with_val(4, 1.25);
7085 /// let x = Float::with_val(53, 2.5);
7086 /// // gamma_inc(1.25, 2.5) = 0.1116
7087 /// // using 4 significant bits: 0.109375
7088 /// let dir = f.gamma_inc_round(&x, Round::Nearest);
7089 /// assert_eq!(f, 0.109375);
7090 /// assert_eq!(dir, Ordering::Less);
7091 /// ```
7092 #[inline]
gamma_inc_round(&mut self, x: &Self, round: Round) -> Ordering7093 pub fn gamma_inc_round(&mut self, x: &Self, round: Round) -> Ordering {
7094 xmpfr::gamma_inc(self, (), x, round)
7095 }
7096
7097 /// Computes the upper incomplete gamma function on the value.
7098 ///
7099 /// The following are implemented with the returned
7100 /// [incomplete-computation value][icv] as `Src`:
7101 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
7102 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
7103 ///
7104 /// # Examples
7105 ///
7106 /// ```rust
7107 /// use rug::Float;
7108 /// let f = Float::with_val(53, 1.25);
7109 /// let x = Float::with_val(53, 2.5);
7110 /// let gamma_inc = Float::with_val(53, f.gamma_inc_ref(&x));
7111 /// let expected = 0.1116_f64;
7112 /// assert!((gamma_inc - expected).abs() < 0.0001);
7113 /// ```
7114 ///
7115 /// [`AssignRound`]: ops/trait.AssignRound.html
7116 /// [`Assign`]: trait.Assign.html
7117 /// [`Float`]: struct.Float.html
7118 /// [icv]: index.html#incomplete-computation-values
7119 #[inline]
gamma_inc_ref<'a>(&'a self, x: &'a Self) -> GammaIncIncomplete<'_>7120 pub fn gamma_inc_ref<'a>(&'a self, x: &'a Self) -> GammaIncIncomplete<'_> {
7121 GammaIncIncomplete { ref_self: self, x }
7122 }
7123
7124 /// Computes the logarithm of the gamma function on `self`,
7125 /// rounding to the nearest.
7126 ///
7127 /// # Examples
7128 ///
7129 /// ```rust
7130 /// use rug::Float;
7131 /// let f = Float::with_val(53, 1.25);
7132 /// let ln_gamma = f.ln_gamma();
7133 /// let expected = -0.0983_f64;
7134 /// assert!((ln_gamma - expected).abs() < 0.0001);
7135 /// ```
7136 #[inline]
ln_gamma(mut self) -> Self7137 pub fn ln_gamma(mut self) -> Self {
7138 self.ln_gamma_round(Round::Nearest);
7139 self
7140 }
7141
7142 /// Computes the logarithm of the gamma function on `self`,
7143 /// rounding to the nearest.
7144 ///
7145 /// # Examples
7146 ///
7147 /// ```rust
7148 /// use rug::Float;
7149 /// let mut f = Float::with_val(53, 1.25);
7150 /// f.ln_gamma_mut();
7151 /// let expected = -0.0983_f64;
7152 /// assert!((f - expected).abs() < 0.0001);
7153 /// ```
7154 #[inline]
ln_gamma_mut(&mut self)7155 pub fn ln_gamma_mut(&mut self) {
7156 self.ln_gamma_round(Round::Nearest);
7157 }
7158
7159 /// Computes the logarithm of the gamma function on `self`,
7160 /// applying the specified rounding method.
7161 ///
7162 /// # Examples
7163 ///
7164 /// ```rust
7165 /// use core::cmp::Ordering;
7166 /// use rug::{float::Round, Float};
7167 /// // Use only 4 bits of precision to show rounding.
7168 /// let mut f = Float::with_val(4, 1.25);
7169 /// // ln_gamma(1.25) = −0.0983
7170 /// // using 4 significant bits: −0.1015625
7171 /// let dir = f.ln_gamma_round(Round::Nearest);
7172 /// assert_eq!(f, -0.1015625);
7173 /// assert_eq!(dir, Ordering::Less);
7174 /// ```
7175 #[inline]
ln_gamma_round(&mut self, round: Round) -> Ordering7176 pub fn ln_gamma_round(&mut self, round: Round) -> Ordering {
7177 xmpfr::lngamma(self, (), round)
7178 }
7179
7180 /// Computes the logarithm of the gamma function on
7181 /// the value.
7182 ///
7183 /// The following are implemented with the returned
7184 /// [incomplete-computation value][icv] as `Src`:
7185 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
7186 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
7187 ///
7188 /// # Examples
7189 ///
7190 /// ```rust
7191 /// use rug::Float;
7192 /// let f = Float::with_val(53, 1.25);
7193 /// let ln_gamma = Float::with_val(53, f.ln_gamma_ref());
7194 /// let expected = -0.0983_f64;
7195 /// assert!((ln_gamma - expected).abs() < 0.0001);
7196 /// ```
7197 ///
7198 /// [`AssignRound`]: ops/trait.AssignRound.html
7199 /// [`Assign`]: trait.Assign.html
7200 /// [`Float`]: struct.Float.html
7201 /// [icv]: index.html#incomplete-computation-values
7202 #[inline]
ln_gamma_ref(&self) -> LnGammaIncomplete<'_>7203 pub fn ln_gamma_ref(&self) -> LnGammaIncomplete<'_> {
7204 LnGammaIncomplete { ref_self: self }
7205 }
7206
7207 /// Computes the logarithm of the absolute value of the gamma
7208 /// function on `self`, rounding to the nearest.
7209 ///
7210 /// Returns <code>[Ordering][`Ordering`]::[Less][`Less`]</code> if
7211 /// the gamma function is negative, or
7212 /// <code>[Ordering][`Ordering`]::[Greater][`Greater`]</code> if
7213 /// the gamma function is positive.
7214 ///
7215 /// # Examples
7216 ///
7217 /// ```rust
7218 /// use core::cmp::Ordering;
7219 /// use rug::{float::Constant, Float};
7220 ///
7221 /// // gamma of 1/2 is √π
7222 /// let ln_gamma_64 = Float::with_val(64, Constant::Pi).sqrt().ln();
7223 ///
7224 /// let f = Float::with_val(53, 0.5);
7225 /// let (ln_gamma, sign) = f.ln_abs_gamma();
7226 /// // gamma of 1/2 is positive
7227 /// assert_eq!(sign, Ordering::Greater);
7228 /// // check to 53 significant bits
7229 /// assert_eq!(ln_gamma, Float::with_val(53, &ln_gamma_64));
7230 /// ```
7231 ///
7232 /// If the gamma function is negative, the sign returned is
7233 /// <code>[Ordering][`Ordering`]::[Less][`Less`]</code>.
7234 ///
7235 /// ```rust
7236 /// use core::cmp::Ordering;
7237 /// use rug::{float::Constant, Float};
7238 ///
7239 /// // gamma of −1/2 is −2√π
7240 /// let abs_gamma_64 = Float::with_val(64, Constant::Pi).sqrt() * 2u32;
7241 /// let ln_gamma_64 = abs_gamma_64.ln();
7242 ///
7243 /// let f = Float::with_val(53, -0.5);
7244 /// let (ln_gamma, sign) = f.ln_abs_gamma();
7245 /// // gamma of −1/2 is negative
7246 /// assert_eq!(sign, Ordering::Less);
7247 /// // check to 53 significant bits
7248 /// assert_eq!(ln_gamma, Float::with_val(53, &ln_gamma_64));
7249 /// ```
7250 ///
7251 /// [`Greater`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html#variant.Greater
7252 /// [`Less`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html#variant.Less
7253 /// [`Ordering`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html
7254 #[inline]
ln_abs_gamma(mut self) -> (Self, Ordering)7255 pub fn ln_abs_gamma(mut self) -> (Self, Ordering) {
7256 let sign = self.ln_abs_gamma_round(Round::Nearest).0;
7257 (self, sign)
7258 }
7259
7260 /// Computes the logarithm of the absolute value of the gamma
7261 /// function on `self`, rounding to the nearest.
7262 ///
7263 /// Returns <code>[Ordering][`Ordering`]::[Less][`Less`]</code> if
7264 /// the gamma function is negative, or
7265 /// <code>[Ordering][`Ordering`]::[Greater][`Greater`]</code> if
7266 /// the gamma function is positive.
7267 ///
7268 /// # Examples
7269 ///
7270 /// ```rust
7271 /// use core::cmp::Ordering;
7272 /// use rug::{float::Constant, Float};
7273 ///
7274 /// // gamma of −1/2 is −2√π
7275 /// let abs_gamma_64 = Float::with_val(64, Constant::Pi).sqrt() * 2u32;
7276 /// let ln_gamma_64 = abs_gamma_64.ln();
7277 ///
7278 /// let mut f = Float::with_val(53, -0.5);
7279 /// let sign = f.ln_abs_gamma_mut();
7280 /// // gamma of −1/2 is negative
7281 /// assert_eq!(sign, Ordering::Less);
7282 /// // check to 53 significant bits
7283 /// assert_eq!(f, Float::with_val(53, &ln_gamma_64));
7284 /// ```
7285 ///
7286 /// [`Greater`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html#variant.Greater
7287 /// [`Less`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html#variant.Less
7288 /// [`Ordering`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html
7289 #[inline]
ln_abs_gamma_mut(&mut self) -> Ordering7290 pub fn ln_abs_gamma_mut(&mut self) -> Ordering {
7291 self.ln_abs_gamma_round(Round::Nearest).0
7292 }
7293
7294 /// Computes the logarithm of the absolute value of the gamma
7295 /// function on `self`, applying the specified rounding method.
7296 ///
7297 /// The returned tuple contains:
7298 ///
7299 /// 1. The logarithm of the absolute value of the gamma function.
7300 /// 2. The rounding direction.
7301 ///
7302 /// # Examples
7303 ///
7304 /// ```rust
7305 /// use core::cmp::Ordering;
7306 /// use rug::{
7307 /// float::{Constant, Round},
7308 /// Float,
7309 /// };
7310 ///
7311 /// // gamma of −1/2 is −2√π
7312 /// let abs_gamma_64 = Float::with_val(64, Constant::Pi).sqrt() * 2u32;
7313 /// let ln_gamma_64 = abs_gamma_64.ln();
7314 ///
7315 /// let mut f = Float::with_val(53, -0.5);
7316 /// let (sign, dir) = f.ln_abs_gamma_round(Round::Nearest);
7317 /// // gamma of −1/2 is negative
7318 /// assert_eq!(sign, Ordering::Less);
7319 /// // check is correct to 53 significant bits
7320 /// let (check, check_dir) =
7321 /// Float::with_val_round(53, &ln_gamma_64, Round::Nearest);
7322 /// assert_eq!(f, check);
7323 /// assert_eq!(dir, check_dir);
7324 /// ```
7325 #[inline]
ln_abs_gamma_round(&mut self, round: Round) -> (Ordering, Ordering)7326 pub fn ln_abs_gamma_round(&mut self, round: Round) -> (Ordering, Ordering) {
7327 xmpfr::lgamma(self, (), round)
7328 }
7329
7330 /// Computes the logarithm of the absolute value of the gamma
7331 /// function on `val`.
7332 ///
7333 /// The following are implemented with the returned
7334 /// [incomplete-computation value][icv] as `Src`:
7335 /// * <code>[Assign][`Assign`]<Src> for
7336 /// [(][tuple][Float][`Float`],
7337 /// [Ordering][`Ordering`][)][tuple]</code>
7338 /// * <code>[Assign][`Assign`]<Src> for
7339 /// [(][tuple]&mut [Float][`Float`],
7340 /// &mut [Ordering][`Ordering`][)][tuple]</code>
7341 /// * <code>[AssignRound][`AssignRound`]<Src> for
7342 /// [(][tuple][Float][`Float`],
7343 /// [Ordering][`Ordering`][)][tuple]</code>
7344 /// * <code>[AssignRound][`AssignRound`]<Src> for
7345 /// [(][tuple]&mut [Float][`Float`],
7346 /// &mut [Ordering][`Ordering`][)][tuple]</code>
7347 ///
7348 /// # Examples
7349 ///
7350 /// ```rust
7351 /// use core::cmp::Ordering;
7352 /// use rug::{float::Constant, Assign, Float};
7353 ///
7354 /// let neg1_2 = Float::with_val(53, -0.5);
7355 /// // gamma of −1/2 is −2√π
7356 /// let abs_gamma_64 = Float::with_val(64, Constant::Pi).sqrt() * 2u32;
7357 /// let ln_gamma_64 = abs_gamma_64.ln();
7358 ///
7359 /// // Assign rounds to the nearest
7360 /// let r = neg1_2.ln_abs_gamma_ref();
7361 /// let (mut f, mut sign) = (Float::new(53), Ordering::Equal);
7362 /// (&mut f, &mut sign).assign(r);
7363 /// // gamma of −1/2 is negative
7364 /// assert_eq!(sign, Ordering::Less);
7365 /// // check to 53 significant bits
7366 /// assert_eq!(f, Float::with_val(53, &ln_gamma_64));
7367 /// ```
7368 ///
7369 /// [`AssignRound`]: ops/trait.AssignRound.html
7370 /// [`Assign`]: trait.Assign.html
7371 /// [`Float`]: struct.Float.html
7372 /// [`Ordering`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html
7373 /// [icv]: index.html#incomplete-computation-values
7374 /// [tuple]: https://doc.rust-lang.org/nightly/std/primitive.tuple.html
7375 #[inline]
ln_abs_gamma_ref(&self) -> LnAbsGammaIncomplete<'_>7376 pub fn ln_abs_gamma_ref(&self) -> LnAbsGammaIncomplete<'_> {
7377 LnAbsGammaIncomplete { ref_self: self }
7378 }
7379
7380 /// Computes the value of the Digamma function on `self`, rounding
7381 /// to the nearest.
7382 ///
7383 /// # Examples
7384 ///
7385 /// ```rust
7386 /// use rug::Float;
7387 /// let f = Float::with_val(53, 1.25);
7388 /// let digamma = f.digamma();
7389 /// let expected = -0.2275_f64;
7390 /// assert!((digamma - expected).abs() < 0.0001);
7391 /// ```
7392 #[inline]
digamma(mut self) -> Self7393 pub fn digamma(mut self) -> Self {
7394 self.digamma_round(Round::Nearest);
7395 self
7396 }
7397
7398 /// Computes the value of the Digamma function on `self`, rounding
7399 /// to the nearest.
7400 ///
7401 /// # Examples
7402 ///
7403 /// ```rust
7404 /// use rug::Float;
7405 /// let mut f = Float::with_val(53, 1.25);
7406 /// f.digamma_mut();
7407 /// let expected = -0.2275_f64;
7408 /// assert!((f - expected).abs() < 0.0001);
7409 /// ```
7410 #[inline]
digamma_mut(&mut self)7411 pub fn digamma_mut(&mut self) {
7412 self.digamma_round(Round::Nearest);
7413 }
7414
7415 /// Computes the value of the Digamma function on `self`, applying
7416 /// the specified rounding method.
7417 ///
7418 /// # Examples
7419 ///
7420 /// ```rust
7421 /// use core::cmp::Ordering;
7422 /// use rug::{float::Round, Float};
7423 /// // Use only 4 bits of precision to show rounding.
7424 /// let mut f = Float::with_val(4, 1.25);
7425 /// // digamma(1.25) = −0.2275
7426 /// // using 4 significant bits: −0.234375
7427 /// let dir = f.digamma_round(Round::Nearest);
7428 /// assert_eq!(f, -0.234375);
7429 /// assert_eq!(dir, Ordering::Less);
7430 /// ```
7431 #[inline]
digamma_round(&mut self, round: Round) -> Ordering7432 pub fn digamma_round(&mut self, round: Round) -> Ordering {
7433 xmpfr::digamma(self, (), round)
7434 }
7435
7436 /// Computes the Digamma function on the value.
7437 ///
7438 /// The following are implemented with the returned
7439 /// [incomplete-computation value][icv] as `Src`:
7440 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
7441 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
7442 ///
7443 /// # Examples
7444 ///
7445 /// ```rust
7446 /// use rug::Float;
7447 /// let f = Float::with_val(53, 1.25);
7448 /// let digamma = Float::with_val(53, f.digamma_ref());
7449 /// let expected = -0.2275_f64;
7450 /// assert!((digamma - expected).abs() < 0.0001);
7451 /// ```
7452 ///
7453 /// [`AssignRound`]: ops/trait.AssignRound.html
7454 /// [`Assign`]: trait.Assign.html
7455 /// [`Float`]: struct.Float.html
7456 /// [icv]: index.html#incomplete-computation-values
7457 #[inline]
digamma_ref(&self) -> DigammaIncomplete<'_>7458 pub fn digamma_ref(&self) -> DigammaIncomplete<'_> {
7459 DigammaIncomplete { ref_self: self }
7460 }
7461
7462 /// Computes the value of the Riemann Zeta function on `self`,
7463 /// rounding to the nearest.
7464 ///
7465 /// # Examples
7466 ///
7467 /// ```rust
7468 /// use rug::Float;
7469 /// let f = Float::with_val(53, 1.25);
7470 /// let zeta = f.zeta();
7471 /// let expected = 4.5951_f64;
7472 /// assert!((zeta - expected).abs() < 0.0001);
7473 /// ```
7474 #[inline]
zeta(mut self) -> Self7475 pub fn zeta(mut self) -> Self {
7476 self.zeta_round(Round::Nearest);
7477 self
7478 }
7479
7480 /// Computes the value of the Riemann Zeta function on `self`,
7481 /// rounding to the nearest.
7482 ///
7483 /// # Examples
7484 ///
7485 /// ```rust
7486 /// use rug::Float;
7487 /// let mut f = Float::with_val(53, 1.25);
7488 /// f.zeta_mut();
7489 /// let expected = 4.5951_f64;
7490 /// assert!((f - expected).abs() < 0.0001);
7491 /// ```
7492 #[inline]
zeta_mut(&mut self)7493 pub fn zeta_mut(&mut self) {
7494 self.zeta_round(Round::Nearest);
7495 }
7496
7497 /// Computes the value of the Riemann Zeta function on `self`,
7498 /// applying the specified rounding method.
7499 ///
7500 /// # Examples
7501 ///
7502 /// ```rust
7503 /// use core::cmp::Ordering;
7504 /// use rug::{float::Round, Float};
7505 /// // Use only 4 bits of precision to show rounding.
7506 /// let mut f = Float::with_val(4, 1.25);
7507 /// // zeta(1.25) = 4.5951
7508 /// // using 4 significant bits: 4.5
7509 /// let dir = f.zeta_round(Round::Nearest);
7510 /// assert_eq!(f, 4.5);
7511 /// assert_eq!(dir, Ordering::Less);
7512 /// ```
7513 #[inline]
zeta_round(&mut self, round: Round) -> Ordering7514 pub fn zeta_round(&mut self, round: Round) -> Ordering {
7515 xmpfr::zeta(self, (), round)
7516 }
7517
7518 /// Computes the Riemann Zeta function on the value.
7519 ///
7520 /// The following are implemented with the returned
7521 /// [incomplete-computation value][icv] as `Src`:
7522 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
7523 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
7524 ///
7525 /// # Examples
7526 ///
7527 /// ```rust
7528 /// use rug::Float;
7529 /// let f = Float::with_val(53, 1.25);
7530 /// let zeta = Float::with_val(53, f.zeta_ref());
7531 /// let expected = 4.5951_f64;
7532 /// assert!((zeta - expected).abs() < 0.0001);
7533 /// ```
7534 ///
7535 /// [`AssignRound`]: ops/trait.AssignRound.html
7536 /// [`Assign`]: trait.Assign.html
7537 /// [`Float`]: struct.Float.html
7538 /// [icv]: index.html#incomplete-computation-values
7539 #[inline]
zeta_ref(&self) -> ZetaIncomplete<'_>7540 pub fn zeta_ref(&self) -> ZetaIncomplete<'_> {
7541 ZetaIncomplete { ref_self: self }
7542 }
7543
7544 /// Computes the Riemann Zeta function on <i>u</i>.
7545 ///
7546 /// The following are implemented with the returned
7547 /// [incomplete-computation value][icv] as `Src`:
7548 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
7549 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
7550 ///
7551 /// # Examples
7552 ///
7553 /// ```rust
7554 /// use rug::Float;
7555 /// let z = Float::zeta_u(3);
7556 /// let f = Float::with_val(53, z);
7557 /// let expected = 1.2021_f64;
7558 /// assert!((f - expected).abs() < 0.0001);
7559 /// ```
7560 ///
7561 /// [`AssignRound`]: ops/trait.AssignRound.html
7562 /// [`Assign`]: trait.Assign.html
7563 /// [`Float`]: struct.Float.html
7564 /// [icv]: index.html#incomplete-computation-values
7565 #[inline]
zeta_u(u: u32) -> ZetaUIncomplete7566 pub fn zeta_u(u: u32) -> ZetaUIncomplete {
7567 ZetaUIncomplete { u }
7568 }
7569
7570 /// Computes the value of the error function, rounding to the
7571 /// nearest.
7572 ///
7573 /// # Examples
7574 ///
7575 /// ```rust
7576 /// use rug::Float;
7577 /// let f = Float::with_val(53, 1.25);
7578 /// let erf = f.erf();
7579 /// let expected = 0.9229_f64;
7580 /// assert!((erf - expected).abs() < 0.0001);
7581 /// ```
7582 #[inline]
erf(mut self) -> Self7583 pub fn erf(mut self) -> Self {
7584 self.erf_round(Round::Nearest);
7585 self
7586 }
7587
7588 /// Computes the value of the error function, rounding to the
7589 /// nearest.
7590 ///
7591 /// # Examples
7592 ///
7593 /// ```rust
7594 /// use rug::Float;
7595 /// let mut f = Float::with_val(53, 1.25);
7596 /// f.erf_mut();
7597 /// let expected = 0.9229_f64;
7598 /// assert!((f - expected).abs() < 0.0001);
7599 /// ```
7600 #[inline]
erf_mut(&mut self)7601 pub fn erf_mut(&mut self) {
7602 self.erf_round(Round::Nearest);
7603 }
7604
7605 /// Computes the value of the error function, applying the
7606 /// specified rounding method.
7607 ///
7608 /// # Examples
7609 ///
7610 /// ```rust
7611 /// use core::cmp::Ordering;
7612 /// use rug::{float::Round, Float};
7613 /// // Use only 4 bits of precision to show rounding.
7614 /// let mut f = Float::with_val(4, 1.25);
7615 /// // erf(1.25) = 0.9229
7616 /// // using 4 significant bits: 0.9375
7617 /// let dir = f.erf_round(Round::Nearest);
7618 /// assert_eq!(f, 0.9375);
7619 /// assert_eq!(dir, Ordering::Greater);
7620 /// ```
7621 #[inline]
erf_round(&mut self, round: Round) -> Ordering7622 pub fn erf_round(&mut self, round: Round) -> Ordering {
7623 xmpfr::erf(self, (), round)
7624 }
7625
7626 /// Computes the error function.
7627 ///
7628 /// The following are implemented with the returned
7629 /// [incomplete-computation value][icv] as `Src`:
7630 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
7631 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
7632 ///
7633 /// # Examples
7634 ///
7635 /// ```rust
7636 /// use rug::Float;
7637 /// let f = Float::with_val(53, 1.25);
7638 /// let erf = Float::with_val(53, f.erf_ref());
7639 /// let expected = 0.9229_f64;
7640 /// assert!((erf - expected).abs() < 0.0001);
7641 /// ```
7642 ///
7643 /// [`AssignRound`]: ops/trait.AssignRound.html
7644 /// [`Assign`]: trait.Assign.html
7645 /// [`Float`]: struct.Float.html
7646 /// [icv]: index.html#incomplete-computation-values
7647 #[inline]
erf_ref(&self) -> ErfIncomplete<'_>7648 pub fn erf_ref(&self) -> ErfIncomplete<'_> {
7649 ErfIncomplete { ref_self: self }
7650 }
7651
7652 /// Computes the value of the complementary error function,
7653 /// rounding to the nearest.
7654 ///
7655 /// # Examples
7656 ///
7657 /// ```rust
7658 /// use rug::Float;
7659 /// let f = Float::with_val(53, 1.25);
7660 /// let erfc = f.erfc();
7661 /// let expected = 0.0771_f64;
7662 /// assert!((erfc - expected).abs() < 0.0001);
7663 /// ```
7664 #[inline]
erfc(mut self) -> Self7665 pub fn erfc(mut self) -> Self {
7666 self.erfc_round(Round::Nearest);
7667 self
7668 }
7669
7670 /// Computes the value of the complementary error function,
7671 /// rounding to the nearest.
7672 ///
7673 /// # Examples
7674 ///
7675 /// ```rust
7676 /// use rug::Float;
7677 /// let mut f = Float::with_val(53, 1.25);
7678 /// f.erfc_mut();
7679 /// let expected = 0.0771_f64;
7680 /// assert!((f - expected).abs() < 0.0001);
7681 /// ```
7682 #[inline]
erfc_mut(&mut self)7683 pub fn erfc_mut(&mut self) {
7684 self.erfc_round(Round::Nearest);
7685 }
7686
7687 /// Computes the value of the complementary error function,
7688 /// applying the specified rounding method.
7689 ///
7690 /// # Examples
7691 ///
7692 /// ```rust
7693 /// use core::cmp::Ordering;
7694 /// use rug::{float::Round, Float};
7695 /// // Use only 4 bits of precision to show rounding.
7696 /// let mut f = Float::with_val(4, 1.25);
7697 /// // erfc(1.25) = 0.0771
7698 /// // using 4 significant bits: 0.078125
7699 /// let dir = f.erfc_round(Round::Nearest);
7700 /// assert_eq!(f, 0.078125);
7701 /// assert_eq!(dir, Ordering::Greater);
7702 /// ```
7703 #[inline]
erfc_round(&mut self, round: Round) -> Ordering7704 pub fn erfc_round(&mut self, round: Round) -> Ordering {
7705 xmpfr::erfc(self, (), round)
7706 }
7707
7708 /// Computes the complementary error function.
7709 ///
7710 /// The following are implemented with the returned
7711 /// [incomplete-computation value][icv] as `Src`:
7712 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
7713 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
7714 ///
7715 /// # Examples
7716 ///
7717 /// ```rust
7718 /// use rug::Float;
7719 /// let f = Float::with_val(53, 1.25);
7720 /// let erfc = Float::with_val(53, f.erfc_ref());
7721 /// let expected = 0.0771_f64;
7722 /// assert!((erfc - expected).abs() < 0.0001);
7723 /// ```
7724 ///
7725 /// [`AssignRound`]: ops/trait.AssignRound.html
7726 /// [`Assign`]: trait.Assign.html
7727 /// [`Float`]: struct.Float.html
7728 /// [icv]: index.html#incomplete-computation-values
7729 #[inline]
erfc_ref(&self) -> ErfcIncomplete<'_>7730 pub fn erfc_ref(&self) -> ErfcIncomplete<'_> {
7731 ErfcIncomplete { ref_self: self }
7732 }
7733
7734 /// Computes the value of the first kind Bessel function of
7735 /// order 0, rounding to the nearest.
7736 ///
7737 /// # Examples
7738 ///
7739 /// ```rust
7740 /// use rug::Float;
7741 /// let f = Float::with_val(53, 1.25);
7742 /// let j0 = f.j0();
7743 /// let expected = 0.6459_f64;
7744 /// assert!((j0 - expected).abs() < 0.0001);
7745 /// ```
7746 #[inline]
j0(mut self) -> Self7747 pub fn j0(mut self) -> Self {
7748 self.j0_round(Round::Nearest);
7749 self
7750 }
7751
7752 /// Computes the value of the first kind Bessel function of
7753 /// order 0, rounding to the nearest.
7754 ///
7755 /// # Examples
7756 ///
7757 /// ```rust
7758 /// use rug::Float;
7759 /// let mut f = Float::with_val(53, 1.25);
7760 /// f.j0_mut();
7761 /// let expected = 0.6459_f64;
7762 /// assert!((f - expected).abs() < 0.0001);
7763 /// ```
7764 #[inline]
j0_mut(&mut self)7765 pub fn j0_mut(&mut self) {
7766 self.j0_round(Round::Nearest);
7767 }
7768
7769 /// Computes the value of the first kind Bessel function of
7770 /// order 0, applying the specified rounding method.
7771 ///
7772 /// # Examples
7773 ///
7774 /// ```rust
7775 /// use core::cmp::Ordering;
7776 /// use rug::{float::Round, Float};
7777 /// // Use only 4 bits of precision to show rounding.
7778 /// let mut f = Float::with_val(4, 1.25);
7779 /// // j0(1.25) = 0.6459
7780 /// // using 4 significant bits: 0.625
7781 /// let dir = f.j0_round(Round::Nearest);
7782 /// assert_eq!(f, 0.625);
7783 /// assert_eq!(dir, Ordering::Less);
7784 /// ```
7785 #[inline]
j0_round(&mut self, round: Round) -> Ordering7786 pub fn j0_round(&mut self, round: Round) -> Ordering {
7787 xmpfr::j0(self, (), round)
7788 }
7789
7790 /// Computes the first kind Bessel function of order 0.
7791 ///
7792 /// The following are implemented with the returned
7793 /// [incomplete-computation value][icv] as `Src`:
7794 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
7795 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
7796 ///
7797 /// # Examples
7798 ///
7799 /// ```rust
7800 /// use rug::Float;
7801 /// let f = Float::with_val(53, 1.25);
7802 /// let j0 = Float::with_val(53, f.j0_ref());
7803 /// let expected = 0.6459_f64;
7804 /// assert!((j0 - expected).abs() < 0.0001);
7805 /// ```
7806 ///
7807 /// [`AssignRound`]: ops/trait.AssignRound.html
7808 /// [`Assign`]: trait.Assign.html
7809 /// [`Float`]: struct.Float.html
7810 /// [icv]: index.html#incomplete-computation-values
7811 #[inline]
j0_ref(&self) -> J0Incomplete<'_>7812 pub fn j0_ref(&self) -> J0Incomplete<'_> {
7813 J0Incomplete { ref_self: self }
7814 }
7815
7816 /// Computes the value of the first kind Bessel function of
7817 /// order 1, rounding to the nearest.
7818 ///
7819 /// # Examples
7820 ///
7821 /// ```rust
7822 /// use rug::Float;
7823 /// let f = Float::with_val(53, 1.25);
7824 /// let j1 = f.j1();
7825 /// let expected = 0.5106_f64;
7826 /// assert!((j1 - expected).abs() < 0.0001);
7827 /// ```
7828 #[inline]
j1(mut self) -> Self7829 pub fn j1(mut self) -> Self {
7830 self.j1_round(Round::Nearest);
7831 self
7832 }
7833
7834 /// Computes the value of the first kind Bessel function of
7835 /// order 1, rounding to the nearest.
7836 ///
7837 /// # Examples
7838 ///
7839 /// ```rust
7840 /// use rug::Float;
7841 /// let mut f = Float::with_val(53, 1.25);
7842 /// f.j1_mut();
7843 /// let expected = 0.5106_f64;
7844 /// assert!((f - expected).abs() < 0.0001);
7845 /// ```
7846 #[inline]
j1_mut(&mut self)7847 pub fn j1_mut(&mut self) {
7848 self.j1_round(Round::Nearest);
7849 }
7850
7851 /// Computes the value of the first kind Bessel function of
7852 /// order 1, applying the specified rounding method.
7853 ///
7854 /// # Examples
7855 ///
7856 /// ```rust
7857 /// use core::cmp::Ordering;
7858 /// use rug::{float::Round, Float};
7859 /// // Use only 4 bits of precision to show rounding.
7860 /// let mut f = Float::with_val(4, 1.25);
7861 /// // j1(1.25) = 0.5106
7862 /// // using 4 significant bits: 0.5
7863 /// let dir = f.j1_round(Round::Nearest);
7864 /// assert_eq!(f, 0.5);
7865 /// assert_eq!(dir, Ordering::Less);
7866 /// ```
7867 #[inline]
j1_round(&mut self, round: Round) -> Ordering7868 pub fn j1_round(&mut self, round: Round) -> Ordering {
7869 xmpfr::j1(self, (), round)
7870 }
7871
7872 /// Computes the first kind Bessel function of order 1.
7873 ///
7874 /// The following are implemented with the returned
7875 /// [incomplete-computation value][icv] as `Src`:
7876 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
7877 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
7878 ///
7879 /// # Examples
7880 ///
7881 /// ```rust
7882 /// use rug::Float;
7883 /// let f = Float::with_val(53, 1.25);
7884 /// let j1 = Float::with_val(53, f.j1_ref());
7885 /// let expected = 0.5106_f64;
7886 /// assert!((j1 - expected).abs() < 0.0001);
7887 /// ```
7888 ///
7889 /// [`AssignRound`]: ops/trait.AssignRound.html
7890 /// [`Assign`]: trait.Assign.html
7891 /// [`Float`]: struct.Float.html
7892 /// [icv]: index.html#incomplete-computation-values
7893 #[inline]
j1_ref(&self) -> J1Incomplete<'_>7894 pub fn j1_ref(&self) -> J1Incomplete<'_> {
7895 J1Incomplete { ref_self: self }
7896 }
7897
7898 /// Computes the value of the first kind Bessel function of
7899 /// order <i>n</i>, rounding to the nearest.
7900 ///
7901 /// # Examples
7902 ///
7903 /// ```rust
7904 /// use rug::Float;
7905 /// let f = Float::with_val(53, 1.25);
7906 /// let j2 = f.jn(2);
7907 /// let expected = 0.1711_f64;
7908 /// assert!((j2 - expected).abs() < 0.0001);
7909 /// ```
7910 #[inline]
jn(mut self, n: i32) -> Self7911 pub fn jn(mut self, n: i32) -> Self {
7912 self.jn_round(n, Round::Nearest);
7913 self
7914 }
7915
7916 /// Computes the value of the first kind Bessel function of
7917 /// order <i>n</i>, rounding to the nearest.
7918 ///
7919 /// # Examples
7920 ///
7921 /// ```rust
7922 /// use rug::Float;
7923 /// let mut f = Float::with_val(53, 1.25);
7924 /// f.jn_mut(2);
7925 /// let expected = 0.1711_f64;
7926 /// assert!((f - expected).abs() < 0.0001);
7927 /// ```
7928 #[inline]
jn_mut(&mut self, n: i32)7929 pub fn jn_mut(&mut self, n: i32) {
7930 self.jn_round(n, Round::Nearest);
7931 }
7932
7933 /// Computes the value of the first kind Bessel function of
7934 /// order <i>n</i>, applying the specified rounding method.
7935 ///
7936 /// # Examples
7937 ///
7938 /// ```rust
7939 /// use core::cmp::Ordering;
7940 /// use rug::{float::Round, Float};
7941 /// // Use only 4 bits of precision to show rounding.
7942 /// let mut f = Float::with_val(4, 1.25);
7943 /// // j2(1.25) = 0.1711
7944 /// // using 4 significant bits: 0.171875
7945 /// let dir = f.jn_round(2, Round::Nearest);
7946 /// assert_eq!(f, 0.171875);
7947 /// assert_eq!(dir, Ordering::Greater);
7948 /// ```
7949 #[inline]
jn_round(&mut self, n: i32, round: Round) -> Ordering7950 pub fn jn_round(&mut self, n: i32, round: Round) -> Ordering {
7951 xmpfr::jn(self, (), n, round)
7952 }
7953
7954 /// Computes the first kind Bessel function of order <i>n</i>.
7955 ///
7956 /// The following are implemented with the returned
7957 /// [incomplete-computation value][icv] as `Src`:
7958 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
7959 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
7960 ///
7961 /// # Examples
7962 ///
7963 /// ```rust
7964 /// use rug::Float;
7965 /// let f = Float::with_val(53, 1.25);
7966 /// let j2 = Float::with_val(53, f.jn_ref(2));
7967 /// let expected = 0.1711_f64;
7968 /// assert!((j2 - expected).abs() < 0.0001);
7969 /// ```
7970 ///
7971 /// [`AssignRound`]: ops/trait.AssignRound.html
7972 /// [`Assign`]: trait.Assign.html
7973 /// [`Float`]: struct.Float.html
7974 /// [icv]: index.html#incomplete-computation-values
7975 #[inline]
jn_ref(&self, n: i32) -> JnIncomplete<'_>7976 pub fn jn_ref(&self, n: i32) -> JnIncomplete<'_> {
7977 JnIncomplete { ref_self: self, n }
7978 }
7979
7980 /// Computes the value of the second kind Bessel function of
7981 /// order 0, rounding to the nearest.
7982 ///
7983 /// # Examples
7984 ///
7985 /// ```rust
7986 /// use rug::Float;
7987 /// let f = Float::with_val(53, 1.25);
7988 /// let y0 = f.y0();
7989 /// let expected = 0.2582_f64;
7990 /// assert!((y0 - expected).abs() < 0.0001);
7991 /// ```
7992 #[inline]
y0(mut self) -> Self7993 pub fn y0(mut self) -> Self {
7994 self.y0_round(Round::Nearest);
7995 self
7996 }
7997
7998 /// Computes the value of the second kind Bessel function of
7999 /// order 0, rounding to the nearest.
8000 ///
8001 /// # Examples
8002 ///
8003 /// ```rust
8004 /// use rug::Float;
8005 /// let mut f = Float::with_val(53, 1.25);
8006 /// f.y0_mut();
8007 /// let expected = 0.2582_f64;
8008 /// assert!((f - expected).abs() < 0.0001);
8009 /// ```
8010 #[inline]
y0_mut(&mut self)8011 pub fn y0_mut(&mut self) {
8012 self.y0_round(Round::Nearest);
8013 }
8014
8015 /// Computes the value of the second kind Bessel function of
8016 /// order 0, applying the specified rounding method.
8017 ///
8018 /// # Examples
8019 ///
8020 /// ```rust
8021 /// use core::cmp::Ordering;
8022 /// use rug::{float::Round, Float};
8023 /// // Use only 4 bits of precision to show rounding.
8024 /// let mut f = Float::with_val(4, 1.25);
8025 /// // y0(1.25) = 0.2582
8026 /// // using 4 significant bits: 0.25
8027 /// let dir = f.y0_round(Round::Nearest);
8028 /// assert_eq!(f, 0.25);
8029 /// assert_eq!(dir, Ordering::Less);
8030 /// ```
8031 #[inline]
y0_round(&mut self, round: Round) -> Ordering8032 pub fn y0_round(&mut self, round: Round) -> Ordering {
8033 xmpfr::y0(self, (), round)
8034 }
8035
8036 /// Computes the second kind Bessel function of order 0.
8037 ///
8038 /// The following are implemented with the returned
8039 /// [incomplete-computation value][icv] as `Src`:
8040 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
8041 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
8042 ///
8043 /// # Examples
8044 ///
8045 /// ```rust
8046 /// use rug::Float;
8047 /// let f = Float::with_val(53, 1.25);
8048 /// let y0 = Float::with_val(53, f.y0_ref());
8049 /// let expected = 0.2582_f64;
8050 /// assert!((y0 - expected).abs() < 0.0001);
8051 /// ```
8052 ///
8053 /// [`AssignRound`]: ops/trait.AssignRound.html
8054 /// [`Assign`]: trait.Assign.html
8055 /// [`Float`]: struct.Float.html
8056 /// [icv]: index.html#incomplete-computation-values
8057 #[inline]
y0_ref(&self) -> Y0Incomplete<'_>8058 pub fn y0_ref(&self) -> Y0Incomplete<'_> {
8059 Y0Incomplete { ref_self: self }
8060 }
8061
8062 /// Computes the value of the second kind Bessel function of
8063 /// order 1, rounding to the nearest.
8064 ///
8065 /// # Examples
8066 ///
8067 /// ```rust
8068 /// use rug::Float;
8069 /// let f = Float::with_val(53, 1.25);
8070 /// let y1 = f.y1();
8071 /// let expected = -0.5844_f64;
8072 /// assert!((y1 - expected).abs() < 0.0001);
8073 /// ```
8074 #[inline]
y1(mut self) -> Self8075 pub fn y1(mut self) -> Self {
8076 self.y1_round(Round::Nearest);
8077 self
8078 }
8079
8080 /// Computes the value of the second kind Bessel function of
8081 /// order 1, rounding to the nearest.
8082 ///
8083 /// # Examples
8084 ///
8085 /// ```rust
8086 /// use rug::Float;
8087 /// let mut f = Float::with_val(53, 1.25);
8088 /// f.y1_mut();
8089 /// let expected = -0.5844_f64;
8090 /// assert!((f - expected).abs() < 0.0001);
8091 /// ```
8092 #[inline]
y1_mut(&mut self)8093 pub fn y1_mut(&mut self) {
8094 self.y1_round(Round::Nearest);
8095 }
8096
8097 /// Computes the value of the second kind Bessel function of
8098 /// order 1, applying the specified rounding method.
8099 ///
8100 /// # Examples
8101 ///
8102 /// ```rust
8103 /// use core::cmp::Ordering;
8104 /// use rug::{float::Round, Float};
8105 /// // Use only 4 bits of precision to show rounding.
8106 /// let mut f = Float::with_val(4, 1.25);
8107 /// // y1(1.25) = −0.5844
8108 /// // using 4 significant bits: −0.5625
8109 /// let dir = f.y1_round(Round::Nearest);
8110 /// assert_eq!(f, -0.5625);
8111 /// assert_eq!(dir, Ordering::Greater);
8112 /// ```
8113 #[inline]
y1_round(&mut self, round: Round) -> Ordering8114 pub fn y1_round(&mut self, round: Round) -> Ordering {
8115 xmpfr::y1(self, (), round)
8116 }
8117
8118 /// Computes the second kind Bessel function of order 1.
8119 ///
8120 /// The following are implemented with the returned
8121 /// [incomplete-computation value][icv] as `Src`:
8122 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
8123 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
8124 ///
8125 /// # Examples
8126 ///
8127 /// ```rust
8128 /// use rug::Float;
8129 /// let f = Float::with_val(53, 1.25);
8130 /// let y1 = Float::with_val(53, f.y1_ref());
8131 /// let expected = -0.5844_f64;
8132 /// assert!((y1 - expected).abs() < 0.0001);
8133 /// ```
8134 ///
8135 /// [`AssignRound`]: ops/trait.AssignRound.html
8136 /// [`Assign`]: trait.Assign.html
8137 /// [`Float`]: struct.Float.html
8138 /// [icv]: index.html#incomplete-computation-values
8139 #[inline]
y1_ref(&self) -> Y1Incomplete<'_>8140 pub fn y1_ref(&self) -> Y1Incomplete<'_> {
8141 Y1Incomplete { ref_self: self }
8142 }
8143
8144 /// Computes the value of the second kind Bessel function of
8145 /// order <i>n</i>, rounding to the nearest.
8146 ///
8147 /// # Examples
8148 ///
8149 /// ```rust
8150 /// use rug::Float;
8151 /// let f = Float::with_val(53, 1.25);
8152 /// let y2 = f.yn(2);
8153 /// let expected = -1.1932_f64;
8154 /// assert!((y2 - expected).abs() < 0.0001);
8155 /// ```
8156 #[inline]
yn(mut self, n: i32) -> Self8157 pub fn yn(mut self, n: i32) -> Self {
8158 self.yn_round(n, Round::Nearest);
8159 self
8160 }
8161
8162 /// Computes the value of the second kind Bessel function of
8163 /// order <i>n</i>, rounding to the nearest.
8164 ///
8165 /// # Examples
8166 ///
8167 /// ```rust
8168 /// use rug::Float;
8169 /// let mut f = Float::with_val(53, 1.25);
8170 /// f.yn_mut(2);
8171 /// let expected = -1.1932_f64;
8172 /// assert!((f - expected).abs() < 0.0001);
8173 /// ```
8174 #[inline]
yn_mut(&mut self, n: i32)8175 pub fn yn_mut(&mut self, n: i32) {
8176 self.yn_round(n, Round::Nearest);
8177 }
8178
8179 /// Computes the value of the second kind Bessel function of
8180 /// order <i>n</i>, applying the specified rounding method.
8181 ///
8182 /// # Examples
8183 ///
8184 /// ```rust
8185 /// use core::cmp::Ordering;
8186 /// use rug::{float::Round, Float};
8187 /// // Use only 4 bits of precision to show rounding.
8188 /// let mut f = Float::with_val(4, 1.25);
8189 /// // y2(1.25) = −1.1932
8190 /// // using 4 significant bits: −1.25
8191 /// let dir = f.yn_round(2, Round::Nearest);
8192 /// assert_eq!(f, -1.25);
8193 /// assert_eq!(dir, Ordering::Less);
8194 /// ```
8195 #[inline]
yn_round(&mut self, n: i32, round: Round) -> Ordering8196 pub fn yn_round(&mut self, n: i32, round: Round) -> Ordering {
8197 xmpfr::yn(self, (), n, round)
8198 }
8199
8200 /// Computes the second kind Bessel function of order <i>n</i>.
8201 ///
8202 /// The following are implemented with the returned
8203 /// [incomplete-computation value][icv] as `Src`:
8204 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
8205 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
8206 ///
8207 /// # Examples
8208 ///
8209 /// ```rust
8210 /// use rug::Float;
8211 /// let f = Float::with_val(53, 1.25);
8212 /// let y2 = Float::with_val(53, f.yn_ref(2));
8213 /// let expected = -1.1932_f64;
8214 /// assert!((y2 - expected).abs() < 0.0001);
8215 /// ```
8216 ///
8217 /// [`AssignRound`]: ops/trait.AssignRound.html
8218 /// [`Assign`]: trait.Assign.html
8219 /// [`Float`]: struct.Float.html
8220 /// [icv]: index.html#incomplete-computation-values
8221 #[inline]
yn_ref(&self, n: i32) -> YnIncomplete<'_>8222 pub fn yn_ref(&self, n: i32) -> YnIncomplete<'_> {
8223 YnIncomplete { ref_self: self, n }
8224 }
8225
8226 /// Computes the arithmetic-geometric mean of `self` and `other`,
8227 /// rounding to the nearest.
8228 ///
8229 /// # Examples
8230 ///
8231 /// ```rust
8232 /// use rug::Float;
8233 /// let f = Float::with_val(53, 1.25);
8234 /// let g = Float::with_val(53, 3.75);
8235 /// let agm = f.agm(&g);
8236 /// let expected = 2.3295_f64;
8237 /// assert!((agm - expected).abs() < 0.0001);
8238 /// ```
8239 #[inline]
agm(mut self, other: &Self) -> Self8240 pub fn agm(mut self, other: &Self) -> Self {
8241 self.agm_round(other, Round::Nearest);
8242 self
8243 }
8244
8245 /// Computes the arithmetic-geometric mean of `self` and `other`,
8246 /// rounding to the nearest.
8247 ///
8248 /// # Examples
8249 ///
8250 /// ```rust
8251 /// use rug::Float;
8252 /// let mut f = Float::with_val(53, 1.25);
8253 /// let g = Float::with_val(53, 3.75);
8254 /// f.agm_mut(&g);
8255 /// let expected = 2.3295_f64;
8256 /// assert!((f - expected).abs() < 0.0001);
8257 /// ```
8258 #[inline]
agm_mut(&mut self, other: &Self)8259 pub fn agm_mut(&mut self, other: &Self) {
8260 self.agm_round(other, Round::Nearest);
8261 }
8262
8263 /// Computes the arithmetic-geometric mean of `self` and `other`,
8264 /// applying the specified rounding method.
8265 ///
8266 /// # Examples
8267 ///
8268 /// ```rust
8269 /// use core::cmp::Ordering;
8270 /// use rug::{float::Round, Float};
8271 /// // Use only 4 bits of precision to show rounding.
8272 /// let mut f = Float::with_val(4, 1.25);
8273 /// let g = Float::with_val(4, 3.75);
8274 /// // agm(1.25, 3.75) = 2.3295
8275 /// // using 4 significant bits: 2.25
8276 /// let dir = f.agm_round(&g, Round::Nearest);
8277 /// assert_eq!(f, 2.25);
8278 /// assert_eq!(dir, Ordering::Less);
8279 /// ```
8280 #[inline]
agm_round(&mut self, other: &Self, round: Round) -> Ordering8281 pub fn agm_round(&mut self, other: &Self, round: Round) -> Ordering {
8282 xmpfr::agm(self, (), other, round)
8283 }
8284
8285 /// Computes the arithmetic-geometric mean.
8286 ///
8287 /// The following are implemented with the returned
8288 /// [incomplete-computation value][icv] as `Src`:
8289 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
8290 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
8291 ///
8292 /// # Examples
8293 ///
8294 /// ```rust
8295 /// use rug::Float;
8296 /// let f = Float::with_val(53, 1.25);
8297 /// let g = Float::with_val(53, 3.75);
8298 /// let agm = Float::with_val(53, f.agm_ref(&g));
8299 /// let expected = 2.3295_f64;
8300 /// assert!((agm - expected).abs() < 0.0001);
8301 /// ```
8302 ///
8303 /// [`AssignRound`]: ops/trait.AssignRound.html
8304 /// [`Assign`]: trait.Assign.html
8305 /// [`Float`]: struct.Float.html
8306 /// [icv]: index.html#incomplete-computation-values
8307 #[inline]
agm_ref<'a>(&'a self, other: &'a Self) -> AgmIncomplete<'_>8308 pub fn agm_ref<'a>(&'a self, other: &'a Self) -> AgmIncomplete<'_> {
8309 AgmIncomplete {
8310 ref_self: self,
8311 other,
8312 }
8313 }
8314
8315 /// Computes the Euclidean norm of `self` and `other`, rounding to
8316 /// the nearest.
8317 ///
8318 /// # Examples
8319 ///
8320 /// ```rust
8321 /// use rug::Float;
8322 /// let f = Float::with_val(53, 1.25);
8323 /// let g = Float::with_val(53, 3.75);
8324 /// let hypot = f.hypot(&g);
8325 /// let expected = 3.9528_f64;
8326 /// assert!((hypot - expected).abs() < 0.0001);
8327 /// ```
8328 #[inline]
hypot(mut self, other: &Self) -> Self8329 pub fn hypot(mut self, other: &Self) -> Self {
8330 self.hypot_round(other, Round::Nearest);
8331 self
8332 }
8333
8334 /// Computes the Euclidean norm of `self` and `other`, rounding to
8335 /// the nearest.
8336 ///
8337 /// # Examples
8338 ///
8339 /// ```rust
8340 /// use rug::Float;
8341 /// let mut f = Float::with_val(53, 1.25);
8342 /// let g = Float::with_val(53, 3.75);
8343 /// f.hypot_mut(&g);
8344 /// let expected = 3.9528_f64;
8345 /// assert!((f - expected).abs() < 0.0001);
8346 /// ```
8347 #[inline]
hypot_mut(&mut self, other: &Self)8348 pub fn hypot_mut(&mut self, other: &Self) {
8349 self.hypot_round(other, Round::Nearest);
8350 }
8351
8352 /// Computes the Euclidean norm of `self` and `other`, applying
8353 /// the specified rounding method.
8354 ///
8355 /// # Examples
8356 ///
8357 /// ```rust
8358 /// use core::cmp::Ordering;
8359 /// use rug::{float::Round, Float};
8360 /// // Use only 4 bits of precision to show rounding.
8361 /// let mut f = Float::with_val(4, 1.25);
8362 /// let g = Float::with_val(4, 3.75);
8363 /// // hypot(1.25) = 3.9528
8364 /// // using 4 significant bits: 4.0
8365 /// let dir = f.hypot_round(&g, Round::Nearest);
8366 /// assert_eq!(f, 4.0);
8367 /// assert_eq!(dir, Ordering::Greater);
8368 /// ```
8369 #[inline]
hypot_round(&mut self, other: &Self, round: Round) -> Ordering8370 pub fn hypot_round(&mut self, other: &Self, round: Round) -> Ordering {
8371 xmpfr::hypot(self, (), other, round)
8372 }
8373
8374 /// Computes the Euclidean norm.
8375 ///
8376 /// The following are implemented with the returned
8377 /// [incomplete-computation value][icv] as `Src`:
8378 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
8379 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
8380 ///
8381 /// # Examples
8382 ///
8383 /// ```rust
8384 /// use rug::Float;
8385 /// let f = Float::with_val(53, 1.25);
8386 /// let g = Float::with_val(53, 3.75);
8387 /// let hypot = Float::with_val(53, f.hypot_ref(&g));
8388 /// let expected = 3.9528_f64;
8389 /// assert!((hypot - expected).abs() < 0.0001);
8390 /// ```
8391 ///
8392 /// [`AssignRound`]: ops/trait.AssignRound.html
8393 /// [`Assign`]: trait.Assign.html
8394 /// [`Float`]: struct.Float.html
8395 /// [icv]: index.html#incomplete-computation-values
8396 #[inline]
hypot_ref<'a>(&'a self, other: &'a Self) -> HypotIncomplete<'_>8397 pub fn hypot_ref<'a>(&'a self, other: &'a Self) -> HypotIncomplete<'_> {
8398 HypotIncomplete {
8399 ref_self: self,
8400 other,
8401 }
8402 }
8403
8404 /// Computes the value of the Airy function Ai on `self`, rounding
8405 /// to the nearest.
8406 ///
8407 /// # Examples
8408 ///
8409 /// ```rust
8410 /// use rug::Float;
8411 /// let f = Float::with_val(53, 1.25);
8412 /// let ai = f.ai();
8413 /// let expected = 0.0996_f64;
8414 /// assert!((ai - expected).abs() < 0.0001);
8415 /// ```
8416 #[inline]
ai(mut self) -> Self8417 pub fn ai(mut self) -> Self {
8418 self.ai_round(Round::Nearest);
8419 self
8420 }
8421
8422 /// Computes the value of the Airy function Ai on `self`, rounding
8423 /// to the nearest.
8424 ///
8425 /// # Examples
8426 ///
8427 /// ```rust
8428 /// use rug::Float;
8429 /// let mut f = Float::with_val(53, 1.25);
8430 /// f.ai_mut();
8431 /// let expected = 0.0996_f64;
8432 /// assert!((f - expected).abs() < 0.0001);
8433 /// ```
8434 #[inline]
ai_mut(&mut self)8435 pub fn ai_mut(&mut self) {
8436 self.ai_round(Round::Nearest);
8437 }
8438
8439 /// Computes the value of the Airy function Ai on `self`, applying
8440 /// the specified rounding method.
8441 ///
8442 /// # Examples
8443 ///
8444 /// ```rust
8445 /// use core::cmp::Ordering;
8446 /// use rug::{float::Round, Float};
8447 /// // Use only 4 bits of precision to show rounding.
8448 /// let mut f = Float::with_val(4, 1.25);
8449 /// // ai(1.25) = 0.0996
8450 /// // using 4 significant bits: 0.1015625
8451 /// let dir = f.ai_round(Round::Nearest);
8452 /// assert_eq!(f, 0.1015625);
8453 /// assert_eq!(dir, Ordering::Greater);
8454 /// ```
8455 #[inline]
ai_round(&mut self, round: Round) -> Ordering8456 pub fn ai_round(&mut self, round: Round) -> Ordering {
8457 xmpfr::ai(self, (), round)
8458 }
8459
8460 /// Computes the Airy function Ai on the value.
8461 ///
8462 /// The following are implemented with the returned
8463 /// [incomplete-computation value][icv] as `Src`:
8464 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
8465 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
8466 ///
8467 /// # Examples
8468 ///
8469 /// ```rust
8470 /// use rug::Float;
8471 /// let f = Float::with_val(53, 1.25);
8472 /// let ai = Float::with_val(53, f.ai_ref());
8473 /// let expected = 0.0996_f64;
8474 /// assert!((ai - expected).abs() < 0.0001);
8475 /// ```
8476 ///
8477 /// [`AssignRound`]: ops/trait.AssignRound.html
8478 /// [`Assign`]: trait.Assign.html
8479 /// [`Float`]: struct.Float.html
8480 /// [icv]: index.html#incomplete-computation-values
8481 #[inline]
ai_ref(&self) -> AiIncomplete<'_>8482 pub fn ai_ref(&self) -> AiIncomplete<'_> {
8483 AiIncomplete { ref_self: self }
8484 }
8485
8486 /// Rounds up to the next higher integer.
8487 ///
8488 /// # Examples
8489 ///
8490 /// ```rust
8491 /// use rug::Float;
8492 /// let f1 = Float::with_val(53, -23.75);
8493 /// let ceil1 = f1.ceil();
8494 /// assert_eq!(ceil1, -23);
8495 /// let f2 = Float::with_val(53, 23.75);
8496 /// let ceil2 = f2.ceil();
8497 /// assert_eq!(ceil2, 24);
8498 /// ```
8499 #[inline]
ceil(mut self) -> Self8500 pub fn ceil(mut self) -> Self {
8501 self.ceil_mut();
8502 self
8503 }
8504
8505 /// Rounds up to the next higher integer.
8506 ///
8507 /// # Examples
8508 ///
8509 /// ```rust
8510 /// use rug::Float;
8511 /// let mut f1 = Float::with_val(53, -23.75);
8512 /// f1.ceil_mut();
8513 /// assert_eq!(f1, -23);
8514 /// let mut f2 = Float::with_val(53, 23.75);
8515 /// f2.ceil_mut();
8516 /// assert_eq!(f2, 24);
8517 /// ```
8518 #[inline]
ceil_mut(&mut self)8519 pub fn ceil_mut(&mut self) {
8520 xmpfr::rint_ceil(self, (), Round::Nearest);
8521 }
8522
8523 /// Rounds up to the next higher integer. The result may be
8524 /// rounded again when assigned to the target.
8525 ///
8526 /// The following are implemented with the returned
8527 /// [incomplete-computation value][icv] as `Src`:
8528 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
8529 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
8530 ///
8531 /// # Examples
8532 ///
8533 /// ```rust
8534 /// use rug::Float;
8535 /// let f1 = Float::with_val(53, -23.75);
8536 /// let ceil1 = Float::with_val(53, f1.ceil_ref());
8537 /// assert_eq!(ceil1, -23);
8538 /// let f2 = Float::with_val(53, 23.75);
8539 /// let ceil2 = Float::with_val(53, f2.ceil_ref());
8540 /// assert_eq!(ceil2, 24);
8541 /// ```
8542 ///
8543 /// [`AssignRound`]: ops/trait.AssignRound.html
8544 /// [`Assign`]: trait.Assign.html
8545 /// [`Float`]: struct.Float.html
8546 /// [icv]: index.html#incomplete-computation-values
8547 #[inline]
ceil_ref(&self) -> CeilIncomplete<'_>8548 pub fn ceil_ref(&self) -> CeilIncomplete<'_> {
8549 CeilIncomplete { ref_self: self }
8550 }
8551
8552 /// Rounds down to the next lower integer.
8553 ///
8554 /// # Examples
8555 ///
8556 /// ```rust
8557 /// use rug::Float;
8558 /// let f1 = Float::with_val(53, -23.75);
8559 /// let floor1 = f1.floor();
8560 /// assert_eq!(floor1, -24);
8561 /// let f2 = Float::with_val(53, 23.75);
8562 /// let floor2 = f2.floor();
8563 /// assert_eq!(floor2, 23);
8564 /// ```
8565 #[inline]
floor(mut self) -> Self8566 pub fn floor(mut self) -> Self {
8567 self.floor_mut();
8568 self
8569 }
8570
8571 /// Rounds down to the next lower integer.
8572 ///
8573 /// # Examples
8574 ///
8575 /// ```rust
8576 /// use rug::Float;
8577 /// let mut f1 = Float::with_val(53, -23.75);
8578 /// f1.floor_mut();
8579 /// assert_eq!(f1, -24);
8580 /// let mut f2 = Float::with_val(53, 23.75);
8581 /// f2.floor_mut();
8582 /// assert_eq!(f2, 23);
8583 /// ```
8584 #[inline]
floor_mut(&mut self)8585 pub fn floor_mut(&mut self) {
8586 xmpfr::rint_floor(self, (), Round::Nearest);
8587 }
8588
8589 /// Rounds down to the next lower integer. The result may be
8590 /// rounded again when assigned to the target.
8591 ///
8592 /// The following are implemented with the returned
8593 /// [incomplete-computation value][icv] as `Src`:
8594 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
8595 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
8596 ///
8597 /// # Examples
8598 ///
8599 /// ```rust
8600 /// use rug::Float;
8601 /// let f1 = Float::with_val(53, -23.75);
8602 /// let floor1 = Float::with_val(53, f1.floor_ref());
8603 /// assert_eq!(floor1, -24);
8604 /// let f2 = Float::with_val(53, 23.75);
8605 /// let floor2 = Float::with_val(53, f2.floor_ref());
8606 /// assert_eq!(floor2, 23);
8607 /// ```
8608 ///
8609 /// [`AssignRound`]: ops/trait.AssignRound.html
8610 /// [`Assign`]: trait.Assign.html
8611 /// [`Float`]: struct.Float.html
8612 /// [icv]: index.html#incomplete-computation-values
8613 #[inline]
floor_ref(&self) -> FloorIncomplete<'_>8614 pub fn floor_ref(&self) -> FloorIncomplete<'_> {
8615 FloorIncomplete { ref_self: self }
8616 }
8617
8618 /// Rounds to the nearest integer, rounding half-way cases
8619 /// away from zero.
8620 ///
8621 /// # Examples
8622 ///
8623 /// ```rust
8624 /// use rug::Float;
8625 /// let f1 = Float::with_val(53, -23.75);
8626 /// let round1 = f1.round();
8627 /// assert_eq!(round1, -24);
8628 /// let f2 = Float::with_val(53, 23.75);
8629 /// let round2 = f2.round();
8630 /// assert_eq!(round2, 24);
8631 /// ```
8632 #[inline]
round(mut self) -> Self8633 pub fn round(mut self) -> Self {
8634 self.round_mut();
8635 self
8636 }
8637
8638 /// Rounds to the nearest integer, rounding half-way cases
8639 /// away from zero.
8640 ///
8641 /// # Examples
8642 ///
8643 /// ```rust
8644 /// use rug::Float;
8645 /// let mut f1 = Float::with_val(53, -23.75);
8646 /// f1.round_mut();
8647 /// assert_eq!(f1, -24);
8648 /// let mut f2 = Float::with_val(53, 23.75);
8649 /// f2.round_mut();
8650 /// assert_eq!(f2, 24);
8651 /// ```
8652 #[inline]
round_mut(&mut self)8653 pub fn round_mut(&mut self) {
8654 xmpfr::rint_round(self, (), Round::Nearest);
8655 }
8656
8657 /// Rounds to the nearest integer, rounding half-way cases
8658 /// away from zero. The result may be rounded again when
8659 /// assigned to the target.
8660 ///
8661 /// The following are implemented with the returned
8662 /// [incomplete-computation value][icv] as `Src`:
8663 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
8664 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
8665 ///
8666 /// # Examples
8667 ///
8668 /// ```rust
8669 /// use rug::Float;
8670 /// let f1 = Float::with_val(53, -23.75);
8671 /// let round1 = Float::with_val(53, f1.round_ref());
8672 /// assert_eq!(round1, -24);
8673 /// let f2 = Float::with_val(53, 23.75);
8674 /// let round2 = Float::with_val(53, f2.round_ref());
8675 /// assert_eq!(round2, 24);
8676 /// ```
8677 ///
8678 /// Double rounding may happen when assigning to a target with
8679 /// a precision less than the number of significant bits for
8680 /// the truncated integer.
8681 ///
8682 /// ```rust
8683 /// use rug::{float::Round, Float};
8684 /// use rug::ops::AssignRound;
8685 /// let f = Float::with_val(53, 6.5);
8686 /// // 6.5 (binary 110.1) is rounded to 7 (binary 111)
8687 /// let r = f.round_ref();
8688 /// // use only 2 bits of precision in destination
8689 /// let mut dst = Float::new(2);
8690 /// // 7 (binary 111) is rounded to 8 (binary 1000) by
8691 /// // round-even rule in order to store in 2-bit Float, even
8692 /// // though 6 (binary 110) is closer to original 6.5).
8693 /// dst.assign_round(r, Round::Nearest);
8694 /// assert_eq!(dst, 8);
8695 /// ```
8696 ///
8697 /// [`AssignRound`]: ops/trait.AssignRound.html
8698 /// [`Assign`]: trait.Assign.html
8699 /// [`Float`]: struct.Float.html
8700 /// [icv]: index.html#incomplete-computation-values
8701 #[inline]
round_ref(&self) -> RoundIncomplete<'_>8702 pub fn round_ref(&self) -> RoundIncomplete<'_> {
8703 RoundIncomplete { ref_self: self }
8704 }
8705
8706 /// Rounds to the nearest integer, rounding half-way cases to
8707 /// even.
8708 ///
8709 /// # Examples
8710 ///
8711 /// ```rust
8712 /// use rug::Float;
8713 /// let f1 = Float::with_val(53, 23.5);
8714 /// let round1 = f1.round_even();
8715 /// assert_eq!(round1, 24);
8716 /// let f2 = Float::with_val(53, 24.5);
8717 /// let round2 = f2.round_even();
8718 /// assert_eq!(round2, 24);
8719 /// ```
8720 #[inline]
round_even(mut self) -> Self8721 pub fn round_even(mut self) -> Self {
8722 self.round_even_mut();
8723 self
8724 }
8725
8726 /// Rounds to the nearest integer, rounding half-way cases to
8727 /// even.
8728 ///
8729 /// # Examples
8730 ///
8731 /// ```rust
8732 /// use rug::Float;
8733 /// let mut f1 = Float::with_val(53, 23.5);
8734 /// f1.round_even_mut();
8735 /// assert_eq!(f1, 24);
8736 /// let mut f2 = Float::with_val(53, 24.5);
8737 /// f2.round_even_mut();
8738 /// assert_eq!(f2, 24);
8739 /// ```
8740 #[inline]
round_even_mut(&mut self)8741 pub fn round_even_mut(&mut self) {
8742 xmpfr::rint_roundeven(self, (), Round::Nearest);
8743 }
8744
8745 /// Rounds to the nearest integer, rounding half-way cases to
8746 /// even. The result may be rounded again when assigned to the
8747 /// target.
8748 ///
8749 /// The following are implemented with the returned
8750 /// [incomplete-computation value][icv] as `Src`:
8751 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
8752 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
8753 ///
8754 /// # Examples
8755 ///
8756 /// ```rust
8757 /// use rug::Float;
8758 /// let f1 = Float::with_val(53, 23.5);
8759 /// let round1 = Float::with_val(53, f1.round_even_ref());
8760 /// assert_eq!(round1, 24);
8761 /// let f2 = Float::with_val(53, 24.5);
8762 /// let round2 = Float::with_val(53, f2.round_even_ref());
8763 /// assert_eq!(round2, 24);
8764 /// ```
8765 ///
8766 /// [`AssignRound`]: ops/trait.AssignRound.html
8767 /// [`Assign`]: trait.Assign.html
8768 /// [`Float`]: struct.Float.html
8769 /// [icv]: index.html#incomplete-computation-values
8770 #[inline]
round_even_ref(&self) -> RoundEvenIncomplete<'_>8771 pub fn round_even_ref(&self) -> RoundEvenIncomplete<'_> {
8772 RoundEvenIncomplete { ref_self: self }
8773 }
8774
8775 /// Rounds to the next integer towards zero.
8776 ///
8777 /// # Examples
8778 ///
8779 /// ```rust
8780 /// use rug::Float;
8781 /// let f1 = Float::with_val(53, -23.75);
8782 /// let trunc1 = f1.trunc();
8783 /// assert_eq!(trunc1, -23);
8784 /// let f2 = Float::with_val(53, 23.75);
8785 /// let trunc2 = f2.trunc();
8786 /// assert_eq!(trunc2, 23);
8787 /// ```
8788 #[inline]
trunc(mut self) -> Self8789 pub fn trunc(mut self) -> Self {
8790 self.trunc_mut();
8791 self
8792 }
8793
8794 /// Rounds to the next integer towards zero.
8795 ///
8796 /// # Examples
8797 ///
8798 /// ```rust
8799 /// use rug::Float;
8800 /// let mut f1 = Float::with_val(53, -23.75);
8801 /// f1.trunc_mut();
8802 /// assert_eq!(f1, -23);
8803 /// let mut f2 = Float::with_val(53, 23.75);
8804 /// f2.trunc_mut();
8805 /// assert_eq!(f2, 23);
8806 /// ```
8807 #[inline]
trunc_mut(&mut self)8808 pub fn trunc_mut(&mut self) {
8809 xmpfr::rint_trunc(self, (), Round::Nearest);
8810 }
8811
8812 /// Rounds to the next integer towards zero. The result may be
8813 /// rounded again when assigned to the target.
8814 ///
8815 /// The following are implemented with the returned
8816 /// [incomplete-computation value][icv] as `Src`:
8817 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
8818 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
8819 ///
8820 /// # Examples
8821 ///
8822 /// ```rust
8823 /// use rug::Float;
8824 /// let f1 = Float::with_val(53, -23.75);
8825 /// let trunc1 = Float::with_val(53, f1.trunc_ref());
8826 /// assert_eq!(trunc1, -23);
8827 /// let f2 = Float::with_val(53, 23.75);
8828 /// let trunc2 = Float::with_val(53, f2.trunc_ref());
8829 /// assert_eq!(trunc2, 23);
8830 /// ```
8831 ///
8832 /// [`AssignRound`]: ops/trait.AssignRound.html
8833 /// [`Assign`]: trait.Assign.html
8834 /// [`Float`]: struct.Float.html
8835 /// [icv]: index.html#incomplete-computation-values
8836 #[inline]
trunc_ref(&self) -> TruncIncomplete<'_>8837 pub fn trunc_ref(&self) -> TruncIncomplete<'_> {
8838 TruncIncomplete { ref_self: self }
8839 }
8840
8841 /// Gets the fractional part of the number.
8842 ///
8843 /// # Examples
8844 ///
8845 /// ```rust
8846 /// use rug::Float;
8847 /// let f1 = Float::with_val(53, -23.75);
8848 /// let fract1 = f1.fract();
8849 /// assert_eq!(fract1, -0.75);
8850 /// let f2 = Float::with_val(53, 23.75);
8851 /// let fract2 = f2.fract();
8852 /// assert_eq!(fract2, 0.75);
8853 /// ```
8854 #[inline]
fract(mut self) -> Self8855 pub fn fract(mut self) -> Self {
8856 self.fract_mut();
8857 self
8858 }
8859
8860 /// Gets the fractional part of the number.
8861 ///
8862 /// # Examples
8863 ///
8864 /// ```rust
8865 /// use rug::Float;
8866 /// let mut f1 = Float::with_val(53, -23.75);
8867 /// f1.fract_mut();
8868 /// assert_eq!(f1, -0.75);
8869 /// let mut f2 = Float::with_val(53, 23.75);
8870 /// f2.fract_mut();
8871 /// assert_eq!(f2, 0.75);
8872 /// ```
8873 #[inline]
fract_mut(&mut self)8874 pub fn fract_mut(&mut self) {
8875 xmpfr::frac(self, (), Round::Nearest);
8876 }
8877
8878 /// Gets the fractional part of the number.
8879 ///
8880 /// The following are implemented with the returned
8881 /// [incomplete-computation value][icv] as `Src`:
8882 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
8883 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
8884 ///
8885 /// # Examples
8886 ///
8887 /// ```rust
8888 /// use rug::Float;
8889 /// let f1 = Float::with_val(53, -23.75);
8890 /// let fract1 = Float::with_val(53, f1.fract_ref());
8891 /// assert_eq!(fract1, -0.75);
8892 /// let f2 = Float::with_val(53, 23.75);
8893 /// let fract2 = Float::with_val(53, f2.fract_ref());
8894 /// assert_eq!(fract2, 0.75);
8895 /// ```
8896 ///
8897 /// [`AssignRound`]: ops/trait.AssignRound.html
8898 /// [`Assign`]: trait.Assign.html
8899 /// [`Float`]: struct.Float.html
8900 /// [icv]: index.html#incomplete-computation-values
8901 #[inline]
fract_ref(&self) -> FractIncomplete<'_>8902 pub fn fract_ref(&self) -> FractIncomplete<'_> {
8903 FractIncomplete { ref_self: self }
8904 }
8905
8906 /// Gets the integer and fractional parts of the number,
8907 /// rounding to the nearest.
8908 ///
8909 /// The integer part is stored in `self` and keeps its
8910 /// precision, while the fractional part is stored in `fract`
8911 /// keeping its precision.
8912 ///
8913 /// The initial value of `fract` is ignored.
8914 ///
8915 /// # Examples
8916 ///
8917 /// ```rust
8918 /// use rug::Float;
8919 /// let f1 = Float::with_val(53, -23.75);
8920 /// let (trunc1, fract1) = f1.trunc_fract(Float::new(53));
8921 /// assert_eq!(trunc1, -23);
8922 /// assert_eq!(fract1, -0.75);
8923 /// let f2 = Float::with_val(53, 23.75);
8924 /// let (trunc2, fract2) = f2.trunc_fract(Float::new(53));
8925 /// assert_eq!(trunc2, 23);
8926 /// assert_eq!(fract2, 0.75);
8927 /// ```
8928 #[inline]
trunc_fract(mut self, mut fract: Self) -> (Self, Self)8929 pub fn trunc_fract(mut self, mut fract: Self) -> (Self, Self) {
8930 self.trunc_fract_round(&mut fract, Round::Nearest);
8931 (self, fract)
8932 }
8933
8934 /// Gets the integer and fractional parts of the number,
8935 /// rounding to the nearest.
8936 ///
8937 /// The integer part is stored in `self` and keeps its
8938 /// precision, while the fractional part is stored in `fract`
8939 /// keeping its precision.
8940 ///
8941 /// The initial value of `fract` is ignored.
8942 ///
8943 /// # Examples
8944 ///
8945 /// ```rust
8946 /// use rug::Float;
8947 /// let mut f1 = Float::with_val(53, -23.75);
8948 /// let mut fract1 = Float::new(53);
8949 /// f1.trunc_fract_mut(&mut fract1);
8950 /// assert_eq!(f1, -23);
8951 /// assert_eq!(fract1, -0.75);
8952 /// let mut f2 = Float::with_val(53, 23.75);
8953 /// let mut fract2 = Float::new(53);
8954 /// f2.trunc_fract_mut(&mut fract2);
8955 /// assert_eq!(f2, 23);
8956 /// assert_eq!(fract2, 0.75);
8957 /// ```
8958 #[inline]
trunc_fract_mut(&mut self, fract: &mut Self)8959 pub fn trunc_fract_mut(&mut self, fract: &mut Self) {
8960 self.trunc_fract_round(fract, Round::Nearest);
8961 }
8962
8963 /// Gets the integer and fractional parts of the number,
8964 /// applying the specified rounding method.
8965 ///
8966 /// The first element of the returned tuple of rounding
8967 /// directions is always
8968 /// <code>[Ordering][`Ordering`]::[Equal][`Equal`]</code>, as
8969 /// truncating a value in place will always be exact.
8970 ///
8971 /// The integer part is stored in `self` and keeps its
8972 /// precision, while the fractional part is stored in `fract`
8973 /// keeping its precision.
8974 ///
8975 /// The initial value of `fract` is ignored.
8976 ///
8977 /// # Examples
8978 ///
8979 /// ```rust
8980 /// use core::cmp::Ordering;
8981 /// use rug::{float::Round, Float};
8982 /// // 0.515625 in binary is 0.100001
8983 /// let mut f1 = Float::with_val(53, -23.515625);
8984 /// let mut fract1 = Float::new(4);
8985 /// let dir1 = f1.trunc_fract_round(&mut fract1, Round::Nearest);
8986 /// assert_eq!(f1, -23);
8987 /// assert_eq!(fract1, -0.5);
8988 /// assert_eq!(dir1, (Ordering::Equal, Ordering::Greater));
8989 /// let mut f2 = Float::with_val(53, 23.515625);
8990 /// let mut fract2 = Float::new(4);
8991 /// let dir2 = f2.trunc_fract_round(&mut fract2, Round::Nearest);
8992 /// assert_eq!(f2, 23);
8993 /// assert_eq!(fract2, 0.5);
8994 /// assert_eq!(dir2, (Ordering::Equal, Ordering::Less));
8995 /// ```
8996 ///
8997 /// [`Equal`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html#variant.Equal
8998 /// [`Ordering`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html
8999 #[inline]
trunc_fract_round(&mut self, fract: &mut Self, round: Round) -> (Ordering, Ordering)9000 pub fn trunc_fract_round(&mut self, fract: &mut Self, round: Round) -> (Ordering, Ordering) {
9001 xmpfr::modf(self, fract, (), round)
9002 }
9003
9004 /// Gets the integer and fractional parts of the number.
9005 ///
9006 /// The following are implemented with the returned
9007 /// [incomplete-computation value][icv] as `Src`:
9008 /// * <code>[Assign][`Assign`]<Src> for
9009 /// [(][tuple][Float][`Float`],
9010 /// [Float][`Float`][)][tuple]</code>
9011 /// * <code>[Assign][`Assign`]<Src> for
9012 /// [(][tuple]&mut [Float][`Float`],
9013 /// &mut [Float][`Float`][)][tuple]</code>
9014 /// * <code>[AssignRound][`AssignRound`]<Src> for
9015 /// [(][tuple][Float][`Float`],
9016 /// [Float][`Float`][)][tuple]</code>
9017 /// * <code>[AssignRound][`AssignRound`]<Src> for
9018 /// [(][tuple]&mut [Float][`Float`],
9019 /// &mut [Float][`Float`][)][tuple]</code>
9020 ///
9021 /// # Examples
9022 ///
9023 /// ```rust
9024 /// use rug::{Assign, Float};
9025 /// let f1 = Float::with_val(53, -23.75);
9026 /// let r1 = f1.trunc_fract_ref();
9027 /// let (mut trunc1, mut fract1) = (Float::new(53), Float::new(53));
9028 /// (&mut trunc1, &mut fract1).assign(r1);
9029 /// assert_eq!(trunc1, -23);
9030 /// assert_eq!(fract1, -0.75);
9031 /// let f2 = Float::with_val(53, -23.75);
9032 /// let r2 = f2.trunc_fract_ref();
9033 /// let (mut trunc2, mut fract2) = (Float::new(53), Float::new(53));
9034 /// (&mut trunc2, &mut fract2).assign(r2);
9035 /// assert_eq!(trunc2, -23);
9036 /// assert_eq!(fract2, -0.75);
9037 /// ```
9038 ///
9039 /// [`AssignRound`]: ops/trait.AssignRound.html
9040 /// [`Assign`]: trait.Assign.html
9041 /// [`Float`]: struct.Float.html
9042 /// [icv]: index.html#incomplete-computation-values
9043 /// [tuple]: https://doc.rust-lang.org/nightly/std/primitive.tuple.html
9044 #[inline]
trunc_fract_ref(&self) -> TruncFractIncomplete<'_>9045 pub fn trunc_fract_ref(&self) -> TruncFractIncomplete<'_> {
9046 TruncFractIncomplete { ref_self: self }
9047 }
9048
9049 #[cfg(feature = "rand")]
9050 /// Generates a random number in the range 0 ≤ <i>x</i> < 1.
9051 ///
9052 /// This is equivalent to generating a random integer in the range
9053 /// 0 ≤ <i>x</i> < 2<sup><i>p</i></sup>, where
9054 /// 2<sup><i>p</i></sup> is two raised to the power of the
9055 /// precision, and then dividing the integer by
9056 /// 2<sup><i>p</i></sup>. The smallest non-zero result will thus
9057 /// be 2<sup>−<i>p</i></sup>, and will only have one bit set. In
9058 /// the smaller possible results, many bits will be zero, and not
9059 /// all the precision will be used.
9060 ///
9061 /// There is a corner case where the generated random number is
9062 /// converted to NaN: if the precision is very large, the
9063 /// generated random number could have an exponent less than the
9064 /// allowed minimum exponent, and NaN is used to indicate this.
9065 /// For this to occur in practice, the minimum exponent has to be
9066 /// set to have a very small magnitude using the low-level MPFR
9067 /// interface, or the random number generator has to be designed
9068 /// specifically to trigger this case.
9069 ///
9070 /// <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
9071 /// is implemented with the returned
9072 /// [incomplete-computation value][icv] as `Src`.
9073 ///
9074 /// # Examples
9075 ///
9076 /// ```rust
9077 /// use rug::{rand::RandState, Assign, Float};
9078 /// let mut rand = RandState::new();
9079 /// let mut f = Float::new(2);
9080 /// f.assign(Float::random_bits(&mut rand));
9081 /// assert!(f == 0.0 || f == 0.25 || f == 0.5 || f == 0.75);
9082 /// println!("0.0 ≤ {} < 1.0", f);
9083 /// ```
9084 ///
9085 /// [`Assign`]: trait.Assign.html
9086 /// [`Float`]: struct.Float.html
9087 /// [icv]: index.html#incomplete-computation-values
9088 #[inline]
random_bits(rng: &mut dyn MutRandState) -> RandomBitsIncomplete9089 pub fn random_bits(rng: &mut dyn MutRandState) -> RandomBitsIncomplete {
9090 RandomBitsIncomplete { rng }
9091 }
9092
9093 #[cfg(feature = "rand")]
9094 /// Generates a random number in the continuous range 0 ≤ <i>x</i> < 1.
9095 ///
9096 /// The result can be rounded up to be equal to one. Unlike the
9097 /// [`random_bits`] method which generates a discrete random
9098 /// number at intervals depending on the precision, this method is
9099 /// equivalent to generating a continuous random number with
9100 /// infinite precision and then rounding the result. This means
9101 /// that even the smaller numbers will be using all the available
9102 /// precision bits, and rounding is performed in all cases, not in
9103 /// some corner case.
9104 ///
9105 /// Rounding directions for generated random numbers cannot be
9106 /// <code>[Ordering][`Ordering`]::[Equal][`Equal`]</code>, as the
9107 /// random numbers generated can be considered to have infinite
9108 /// precision before rounding.
9109 ///
9110 /// The following are implemented with the returned
9111 /// [incomplete-computation value][icv] as `Src`:
9112 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
9113 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
9114 ///
9115 /// # Examples
9116 ///
9117 /// ```rust
9118 /// use rug::{rand::RandState, Float};
9119 /// let mut rand = RandState::new();
9120 /// let f = Float::with_val(2, Float::random_cont(&mut rand));
9121 /// // The significand is either 0b10 or 0b11
9122 /// assert!(
9123 /// f == 1.0
9124 /// || f == 0.75
9125 /// || f == 0.5
9126 /// || f == 0.375
9127 /// || f == 0.25
9128 /// || f <= 0.1875
9129 /// );
9130 /// ```
9131 ///
9132 /// [`AssignRound`]: ops/trait.AssignRound.html
9133 /// [`Assign`]: trait.Assign.html
9134 /// [`Equal`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html#variant.Equal
9135 /// [`Float`]: struct.Float.html
9136 /// [`Ordering`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html
9137 /// [`random_bits`]: #method.random_bits
9138 /// [icv]: index.html#incomplete-computation-values
9139 #[inline]
random_cont(rng: &mut dyn MutRandState) -> RandomContIncomplete9140 pub fn random_cont(rng: &mut dyn MutRandState) -> RandomContIncomplete {
9141 RandomContIncomplete { rng }
9142 }
9143
9144 #[cfg(feature = "rand")]
9145 /// Generates a random number according to a standard normal
9146 /// Gaussian distribution, rounding to the nearest.
9147 ///
9148 /// Rounding directions for generated random numbers cannot be
9149 /// <code>[Ordering][`Ordering`]::[Equal][`Equal`]</code>, as the
9150 /// random numbers generated can be considered to have infinite
9151 /// precision before rounding.
9152 ///
9153 /// The following are implemented with the returned
9154 /// [incomplete-computation value][icv] as `Src`:
9155 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
9156 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
9157 ///
9158 /// # Examples
9159 ///
9160 /// ```rust
9161 /// use rug::{rand::RandState, Float};
9162 /// let mut rand = RandState::new();
9163 /// let f = Float::with_val(53, Float::random_normal(&mut rand));
9164 /// println!("Normal random number: {}", f);
9165 /// ```
9166 ///
9167 /// [`AssignRound`]: ops/trait.AssignRound.html
9168 /// [`Assign`]: trait.Assign.html
9169 /// [`Equal`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html#variant.Equal
9170 /// [`Float`]: struct.Float.html
9171 /// [`Ordering`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html
9172 /// [icv]: index.html#incomplete-computation-values
9173 #[inline]
random_normal(rng: &mut dyn MutRandState) -> RandomNormalIncomplete9174 pub fn random_normal(rng: &mut dyn MutRandState) -> RandomNormalIncomplete {
9175 RandomNormalIncomplete { rng }
9176 }
9177
9178 #[cfg(feature = "rand")]
9179 /// Generates a random number according to an exponential
9180 /// distribution with mean one, rounding to the nearest.
9181 ///
9182 /// Rounding directions for generated random numbers cannot be
9183 /// <code>[Ordering][`Ordering`]::[Equal][`Equal`]</code>, as the
9184 /// random numbers generated can be considered to have infinite
9185 /// precision before rounding.
9186 ///
9187 /// The following are implemented with the returned
9188 /// [incomplete-computation value][icv] as `Src`:
9189 /// * <code>[Assign][`Assign`]<Src> for [Float][`Float`]</code>
9190 /// * <code>[AssignRound][`AssignRound`]<Src> for [Float][`Float`]</code>
9191 ///
9192 /// # Examples
9193 ///
9194 /// ```rust
9195 /// use rug::{rand::RandState, Float};
9196 /// let mut rand = RandState::new();
9197 /// let f = Float::with_val(53, Float::random_exp(&mut rand));
9198 /// println!("Exponential random number: {}", f);
9199 /// ```
9200 ///
9201 /// [`AssignRound`]: ops/trait.AssignRound.html
9202 /// [`Assign`]: trait.Assign.html
9203 /// [`Equal`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html#variant.Equal
9204 /// [`Float`]: struct.Float.html
9205 /// [`Ordering`]: https://doc.rust-lang.org/nightly/core/cmp/enum.Ordering.html
9206 /// [icv]: index.html#incomplete-computation-values
9207 #[inline]
random_exp(rng: &mut dyn MutRandState) -> RandomExpIncomplete9208 pub fn random_exp(rng: &mut dyn MutRandState) -> RandomExpIncomplete {
9209 RandomExpIncomplete { rng }
9210 }
9211 }
9212
9213 #[derive(Debug)]
9214 pub struct SumIncomplete<'a, I>
9215 where
9216 I: Iterator<Item = &'a Float>,
9217 {
9218 values: I,
9219 }
9220
9221 impl<'a, I> AssignRound<SumIncomplete<'a, I>> for Float
9222 where
9223 I: Iterator<Item = &'a Self>,
9224 {
9225 type Round = Round;
9226 type Ordering = Ordering;
9227 #[inline]
assign_round(&mut self, src: SumIncomplete<'a, I>, round: Round) -> Ordering9228 fn assign_round(&mut self, src: SumIncomplete<'a, I>, round: Round) -> Ordering {
9229 xmpfr::sum(self, src.values, round)
9230 }
9231 }
9232
9233 impl<'a, I> Add<SumIncomplete<'a, I>> for Float
9234 where
9235 I: Iterator<Item = &'a Self>,
9236 {
9237 type Output = Self;
9238 #[inline]
add(mut self, rhs: SumIncomplete<'a, I>) -> Self9239 fn add(mut self, rhs: SumIncomplete<'a, I>) -> Self {
9240 self.add_assign_round(rhs, Round::Nearest);
9241 self
9242 }
9243 }
9244
9245 impl<'a, I> AddAssign<SumIncomplete<'a, I>> for Float
9246 where
9247 I: Iterator<Item = &'a Self>,
9248 {
9249 #[inline]
add_assign(&mut self, rhs: SumIncomplete<'a, I>)9250 fn add_assign(&mut self, rhs: SumIncomplete<'a, I>) {
9251 self.add_assign_round(rhs, Round::Nearest);
9252 }
9253 }
9254
9255 impl<'a, I> AddAssignRound<SumIncomplete<'a, I>> for Float
9256 where
9257 I: Iterator<Item = &'a Self>,
9258 {
9259 type Round = Round;
9260 type Ordering = Ordering;
9261 #[inline]
add_assign_round(&mut self, src: SumIncomplete<'a, I>, round: Round) -> Ordering9262 fn add_assign_round(&mut self, src: SumIncomplete<'a, I>, round: Round) -> Ordering {
9263 xmpfr::sum_including_old(self, src.values, round)
9264 }
9265 }
9266
9267 #[derive(Debug)]
9268 pub struct DotIncomplete<'a, I>
9269 where
9270 I: Iterator<Item = (&'a Float, &'a Float)>,
9271 {
9272 values: I,
9273 }
9274
9275 impl<'a, I> AssignRound<DotIncomplete<'a, I>> for Float
9276 where
9277 I: Iterator<Item = (&'a Self, &'a Self)>,
9278 {
9279 type Round = Round;
9280 type Ordering = Ordering;
9281 #[inline]
assign_round(&mut self, src: DotIncomplete<'a, I>, round: Round) -> Ordering9282 fn assign_round(&mut self, src: DotIncomplete<'a, I>, round: Round) -> Ordering {
9283 xmpfr::dot(self, src.values, round)
9284 }
9285 }
9286
9287 impl<'a, I> Add<DotIncomplete<'a, I>> for Float
9288 where
9289 I: Iterator<Item = (&'a Self, &'a Self)>,
9290 {
9291 type Output = Self;
9292 #[inline]
add(mut self, rhs: DotIncomplete<'a, I>) -> Self9293 fn add(mut self, rhs: DotIncomplete<'a, I>) -> Self {
9294 self.add_assign_round(rhs, Round::Nearest);
9295 self
9296 }
9297 }
9298
9299 impl<'a, I> AddAssign<DotIncomplete<'a, I>> for Float
9300 where
9301 I: Iterator<Item = (&'a Self, &'a Self)>,
9302 {
9303 #[inline]
add_assign(&mut self, rhs: DotIncomplete<'a, I>)9304 fn add_assign(&mut self, rhs: DotIncomplete<'a, I>) {
9305 self.add_assign_round(rhs, Round::Nearest);
9306 }
9307 }
9308
9309 impl<'a, I> AddAssignRound<DotIncomplete<'a, I>> for Float
9310 where
9311 I: Iterator<Item = (&'a Self, &'a Self)>,
9312 {
9313 type Round = Round;
9314 type Ordering = Ordering;
9315 #[inline]
add_assign_round(&mut self, src: DotIncomplete<'a, I>, round: Round) -> Ordering9316 fn add_assign_round(&mut self, src: DotIncomplete<'a, I>, round: Round) -> Ordering {
9317 xmpfr::dot_including_old(self, src.values, round)
9318 }
9319 }
9320
9321 ref_math_op2_float! { xmpfr::remainder; struct RemainderIncomplete { divisor } }
9322 ref_math_op0_float! { xmpfr::ui_2exp; struct UExpIncomplete { u: u32, exp: i32 } }
9323 ref_math_op0_float! { xmpfr::si_2exp; struct IExpIncomplete { i: i32, exp: i32 } }
9324 ref_math_op0_float! { xmpfr::ui_pow_ui; struct UPowUIncomplete { base: u32, exponent: u32 } }
9325 ref_math_op0_float! { xmpfr::si_pow_ui; struct IPowUIncomplete { base: i32, exponent: u32 } }
9326 ref_math_op1_float! { xmpfr::sqr; struct SquareIncomplete {} }
9327 ref_math_op1_float! { xmpfr::sqrt; struct SqrtIncomplete {} }
9328 ref_math_op0_float! { xmpfr::sqrt_ui; struct SqrtUIncomplete { u: u32 } }
9329 ref_math_op1_float! { xmpfr::rec_sqrt; struct RecipSqrtIncomplete {} }
9330 ref_math_op1_float! { xmpfr::cbrt; struct CbrtIncomplete {} }
9331 ref_math_op1_float! { xmpfr::rootn_ui; struct RootIncomplete { k: u32 } }
9332 ref_math_op1_float! { xmpfr::abs; struct AbsIncomplete {} }
9333 ref_math_op1_float! { xmpfr::signum; struct SignumIncomplete {} }
9334 ref_math_op2_float! { xmpfr::copysign; struct CopysignIncomplete { y } }
9335
9336 #[derive(Debug)]
9337 pub struct ClampIncomplete<'s, 'min, 'max, Min, Max>
9338 where
9339 Float: PartialOrd<Min>
9340 + PartialOrd<Max>
9341 + for<'a> AssignRound<&'a Min, Round = Round, Ordering = Ordering>
9342 + for<'a> AssignRound<&'a Max, Round = Round, Ordering = Ordering>,
9343 {
9344 ref_self: &'s Float,
9345 min: &'min Min,
9346 max: &'max Max,
9347 }
9348
9349 impl<Min, Max> AssignRound<ClampIncomplete<'_, '_, '_, Min, Max>> for Float
9350 where
9351 Self: PartialOrd<Min>
9352 + PartialOrd<Max>
9353 + for<'a> AssignRound<&'a Min, Round = Round, Ordering = Ordering>
9354 + for<'a> AssignRound<&'a Max, Round = Round, Ordering = Ordering>,
9355 {
9356 type Round = Round;
9357 type Ordering = Ordering;
9358 #[inline]
assign_round(&mut self, src: ClampIncomplete<Min, Max>, round: Round) -> Ordering9359 fn assign_round(&mut self, src: ClampIncomplete<Min, Max>, round: Round) -> Ordering {
9360 if src.ref_self.lt(src.min) {
9361 let dir = self.assign_round(src.min, round);
9362 if (*self).gt(src.max) {
9363 let dir2 = self.assign_round(src.max, round);
9364 assert!(
9365 dir == dir2 && !(*self).lt(src.min),
9366 "minimum larger than maximum"
9367 );
9368 dir
9369 } else {
9370 dir
9371 }
9372 } else if src.ref_self.gt(src.max) {
9373 let dir = self.assign_round(src.max, round);
9374 if (*self).lt(src.min) {
9375 let dir2 = self.assign_round(src.min, round);
9376 assert!(
9377 dir == dir2 && !(*self).gt(src.max),
9378 "minimum larger than maximum"
9379 );
9380 dir
9381 } else {
9382 dir
9383 }
9384 } else {
9385 self.assign_round(src.ref_self, round)
9386 }
9387 }
9388 }
9389
9390 ref_math_op1_float! { xmpfr::recip; struct RecipIncomplete {} }
9391 ref_math_op2_float! { xmpfr::min; struct MinIncomplete { other } }
9392 ref_math_op2_float! { xmpfr::max; struct MaxIncomplete { other } }
9393 ref_math_op2_float! { xmpfr::dim; struct PositiveDiffIncomplete { other } }
9394 ref_math_op1_float! { xmpfr::log; struct LnIncomplete {} }
9395 ref_math_op0_float! { xmpfr::log_ui; struct LnUIncomplete { u: u32 } }
9396 ref_math_op1_float! { xmpfr::log2; struct Log2Incomplete {} }
9397 ref_math_op1_float! { xmpfr::log10; struct Log10Incomplete {} }
9398 ref_math_op1_float! { xmpfr::exp; struct ExpIncomplete {} }
9399 ref_math_op1_float! { xmpfr::exp2; struct Exp2Incomplete {} }
9400 ref_math_op1_float! { xmpfr::exp10; struct Exp10Incomplete {} }
9401 ref_math_op1_float! { xmpfr::sin; struct SinIncomplete {} }
9402 ref_math_op1_float! { xmpfr::cos; struct CosIncomplete {} }
9403 ref_math_op1_float! { xmpfr::tan; struct TanIncomplete {} }
9404 ref_math_op1_2_float! { xmpfr::sin_cos; struct SinCosIncomplete {} }
9405 ref_math_op1_float! { xmpfr::sec; struct SecIncomplete {} }
9406 ref_math_op1_float! { xmpfr::csc; struct CscIncomplete {} }
9407 ref_math_op1_float! { xmpfr::cot; struct CotIncomplete {} }
9408 ref_math_op1_float! { xmpfr::acos; struct AcosIncomplete {} }
9409 ref_math_op1_float! { xmpfr::asin; struct AsinIncomplete {} }
9410 ref_math_op1_float! { xmpfr::atan; struct AtanIncomplete {} }
9411 ref_math_op2_float! { xmpfr::atan2; struct Atan2Incomplete { x } }
9412 ref_math_op1_float! { xmpfr::cosh; struct CoshIncomplete {} }
9413 ref_math_op1_float! { xmpfr::sinh; struct SinhIncomplete {} }
9414 ref_math_op1_float! { xmpfr::tanh; struct TanhIncomplete {} }
9415 ref_math_op1_2_float! { xmpfr::sinh_cosh; struct SinhCoshIncomplete {} }
9416 ref_math_op1_float! { xmpfr::sech; struct SechIncomplete {} }
9417 ref_math_op1_float! { xmpfr::csch; struct CschIncomplete {} }
9418 ref_math_op1_float! { xmpfr::coth; struct CothIncomplete {} }
9419 ref_math_op1_float! { xmpfr::acosh; struct AcoshIncomplete {} }
9420 ref_math_op1_float! { xmpfr::asinh; struct AsinhIncomplete {} }
9421 ref_math_op1_float! { xmpfr::atanh; struct AtanhIncomplete {} }
9422 ref_math_op0_float! { xmpfr::fac_ui; struct FactorialIncomplete { n: u32 } }
9423 ref_math_op1_float! { xmpfr::log1p; struct Ln1pIncomplete {} }
9424 ref_math_op1_float! { xmpfr::expm1; struct ExpM1Incomplete {} }
9425 ref_math_op1_float! { xmpfr::eint; struct EintIncomplete {} }
9426 ref_math_op1_float! { xmpfr::li2; struct Li2Incomplete {} }
9427 ref_math_op1_float! { xmpfr::gamma; struct GammaIncomplete {} }
9428 ref_math_op2_float! { xmpfr::gamma_inc; struct GammaIncIncomplete { x } }
9429 ref_math_op1_float! { xmpfr::lngamma; struct LnGammaIncomplete {} }
9430
9431 pub struct LnAbsGammaIncomplete<'a> {
9432 ref_self: &'a Float,
9433 }
9434
9435 impl AssignRound<LnAbsGammaIncomplete<'_>> for (&mut Float, &mut Ordering) {
9436 type Round = Round;
9437 type Ordering = Ordering;
9438 #[inline]
assign_round(&mut self, src: LnAbsGammaIncomplete<'_>, round: Round) -> Ordering9439 fn assign_round(&mut self, src: LnAbsGammaIncomplete<'_>, round: Round) -> Ordering {
9440 let (sign_ord, ord) = xmpfr::lgamma(self.0, src.ref_self, round);
9441 *self.1 = sign_ord;
9442 ord
9443 }
9444 }
9445
9446 impl AssignRound<LnAbsGammaIncomplete<'_>> for (Float, Ordering) {
9447 type Round = Round;
9448 type Ordering = Ordering;
9449 #[inline]
assign_round(&mut self, src: LnAbsGammaIncomplete<'_>, round: Round) -> Ordering9450 fn assign_round(&mut self, src: LnAbsGammaIncomplete<'_>, round: Round) -> Ordering {
9451 (&mut self.0, &mut self.1).assign_round(src, round)
9452 }
9453 }
9454
9455 impl Assign<LnAbsGammaIncomplete<'_>> for (&mut Float, &mut Ordering) {
9456 #[inline]
assign(&mut self, src: LnAbsGammaIncomplete<'_>)9457 fn assign(&mut self, src: LnAbsGammaIncomplete<'_>) {
9458 self.assign_round(src, Round::Nearest);
9459 }
9460 }
9461
9462 impl Assign<LnAbsGammaIncomplete<'_>> for (Float, Ordering) {
9463 #[inline]
assign(&mut self, src: LnAbsGammaIncomplete<'_>)9464 fn assign(&mut self, src: LnAbsGammaIncomplete<'_>) {
9465 (&mut self.0, &mut self.1).assign_round(src, Round::Nearest);
9466 }
9467 }
9468
9469 ref_math_op1_float! { xmpfr::digamma; struct DigammaIncomplete {} }
9470 ref_math_op1_float! { xmpfr::zeta; struct ZetaIncomplete {} }
9471 ref_math_op0_float! { xmpfr::zeta_ui; struct ZetaUIncomplete { u: u32 } }
9472 ref_math_op1_float! { xmpfr::erf; struct ErfIncomplete {} }
9473 ref_math_op1_float! { xmpfr::erfc; struct ErfcIncomplete {} }
9474 ref_math_op1_float! { xmpfr::j0; struct J0Incomplete {} }
9475 ref_math_op1_float! { xmpfr::j1; struct J1Incomplete {} }
9476 ref_math_op1_float! { xmpfr::jn; struct JnIncomplete { n: i32 } }
9477 ref_math_op1_float! { xmpfr::y0; struct Y0Incomplete {} }
9478 ref_math_op1_float! { xmpfr::y1; struct Y1Incomplete {} }
9479 ref_math_op1_float! { xmpfr::yn; struct YnIncomplete { n: i32 } }
9480 ref_math_op2_float! { xmpfr::agm; struct AgmIncomplete { other } }
9481 ref_math_op2_float! { xmpfr::hypot; struct HypotIncomplete { other } }
9482 ref_math_op1_float! { xmpfr::ai; struct AiIncomplete {} }
9483 ref_math_op1_float! { xmpfr::rint_ceil; struct CeilIncomplete {} }
9484 ref_math_op1_float! { xmpfr::rint_floor; struct FloorIncomplete {} }
9485 ref_math_op1_float! { xmpfr::rint_round; struct RoundIncomplete {} }
9486 ref_math_op1_float! { xmpfr::rint_roundeven; struct RoundEvenIncomplete {} }
9487 ref_math_op1_float! { xmpfr::rint_trunc; struct TruncIncomplete {} }
9488 ref_math_op1_float! { xmpfr::frac; struct FractIncomplete {} }
9489 ref_math_op1_2_float! { xmpfr::modf; struct TruncFractIncomplete {} }
9490
9491 #[cfg(feature = "rand")]
9492 pub struct RandomBitsIncomplete<'a> {
9493 rng: &'a mut dyn MutRandState,
9494 }
9495
9496 #[cfg(feature = "rand")]
9497 impl Assign<RandomBitsIncomplete<'_>> for Float {
9498 #[inline]
assign(&mut self, src: RandomBitsIncomplete)9499 fn assign(&mut self, src: RandomBitsIncomplete) {
9500 xmpfr::urandomb(self, src.rng);
9501 }
9502 }
9503
9504 #[cfg(feature = "rand")]
9505 pub struct RandomContIncomplete<'a> {
9506 rng: &'a mut dyn MutRandState,
9507 }
9508
9509 #[cfg(feature = "rand")]
9510 impl AssignRound<RandomContIncomplete<'_>> for Float {
9511 type Round = Round;
9512 type Ordering = Ordering;
9513 #[inline]
assign_round(&mut self, src: RandomContIncomplete, round: Round) -> Ordering9514 fn assign_round(&mut self, src: RandomContIncomplete, round: Round) -> Ordering {
9515 xmpfr::urandom(self, src.rng, round)
9516 }
9517 }
9518
9519 #[cfg(feature = "rand")]
9520 pub struct RandomNormalIncomplete<'a> {
9521 rng: &'a mut dyn MutRandState,
9522 }
9523
9524 #[cfg(feature = "rand")]
9525 impl AssignRound<RandomNormalIncomplete<'_>> for Float {
9526 type Round = Round;
9527 type Ordering = Ordering;
9528 #[inline]
assign_round(&mut self, src: RandomNormalIncomplete, round: Round) -> Ordering9529 fn assign_round(&mut self, src: RandomNormalIncomplete, round: Round) -> Ordering {
9530 xmpfr::nrandom(self, src.rng, round)
9531 }
9532 }
9533
9534 #[cfg(feature = "rand")]
9535 pub struct RandomExpIncomplete<'a> {
9536 rng: &'a mut dyn MutRandState,
9537 }
9538
9539 #[cfg(feature = "rand")]
9540 impl AssignRound<RandomExpIncomplete<'_>> for Float {
9541 type Round = Round;
9542 type Ordering = Ordering;
9543 #[inline]
assign_round(&mut self, src: RandomExpIncomplete, round: Round) -> Ordering9544 fn assign_round(&mut self, src: RandomExpIncomplete, round: Round) -> Ordering {
9545 xmpfr::erandom(self, src.rng, round)
9546 }
9547 }
9548
9549 #[derive(Debug)]
9550 #[repr(transparent)]
9551 pub struct BorrowFloat<'a> {
9552 inner: ManuallyDrop<Float>,
9553 phantom: PhantomData<&'a Float>,
9554 }
9555
9556 impl BorrowFloat<'_> {
9557 // unsafe because the lifetime is obtained from return type
from_raw<'a>(raw: mpfr_t) -> BorrowFloat<'a>9558 unsafe fn from_raw<'a>(raw: mpfr_t) -> BorrowFloat<'a> {
9559 BorrowFloat {
9560 inner: ManuallyDrop::new(Float::from_raw(raw)),
9561 phantom: PhantomData,
9562 }
9563 }
9564 }
9565
9566 impl Deref for BorrowFloat<'_> {
9567 type Target = Float;
9568 #[inline]
deref(&self) -> &Float9569 fn deref(&self) -> &Float {
9570 &*self.inner
9571 }
9572 }
9573
9574 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
9575 pub(crate) enum ExpFormat {
9576 Exp,
9577 Point,
9578 }
9579
9580 #[derive(Clone, Copy, Debug)]
9581 pub(crate) struct Format {
9582 pub radix: i32,
9583 pub precision: Option<usize>,
9584 pub round: Round,
9585 pub to_upper: bool,
9586 pub exp: ExpFormat,
9587 }
9588
9589 impl Default for Format {
9590 #[inline]
default() -> Format9591 fn default() -> Format {
9592 Format {
9593 radix: 10,
9594 precision: None,
9595 round: Round::default(),
9596 to_upper: false,
9597 exp: ExpFormat::Point,
9598 }
9599 }
9600 }
9601
req_chars(f: &Float, format: Format, extra: usize) -> usize9602 pub(crate) fn req_chars(f: &Float, format: Format, extra: usize) -> usize {
9603 assert!(
9604 format.radix >= 2 && format.radix <= 36,
9605 "radix {} out of range",
9606 format.radix
9607 );
9608 // Although append_str processess singular values before calling
9609 // req_chars, req_chars is called from outside append_str too.
9610 let size_no_sign = if f.is_zero() {
9611 1
9612 } else if f.is_infinite() || f.is_nan() {
9613 if format.radix > 10 {
9614 5
9615 } else {
9616 3
9617 }
9618 } else {
9619 let digits = req_digits(f, format);
9620 let log2_radix = f64::from(format.radix).log2();
9621 #[allow(clippy::approx_constant)]
9622 const LOG10_2: f64 = 0.301_029_995_663_981_2f64;
9623 let exp = (xmpfr::get_exp(f).az::<f64>() / log2_radix - 1.0).abs();
9624 // add 1 for '-' and an extra 1 in case of rounding errors
9625 let exp_digits = (exp * LOG10_2).ceil().az::<usize>() + 2;
9626 // '.', exp separator, exp_digits
9627 digits.checked_add(2 + exp_digits).expect("overflow")
9628 };
9629 let size = if f.is_sign_negative() {
9630 size_no_sign.checked_add(1).expect("overflow")
9631 } else {
9632 size_no_sign
9633 };
9634 size.checked_add(extra).expect("overflow")
9635 }
9636
req_digits(f: &Float, format: Format) -> usize9637 pub(crate) fn req_digits(f: &Float, format: Format) -> usize {
9638 let digits = format.precision.unwrap_or(0);
9639 if digits > 0 {
9640 digits
9641 } else {
9642 let m = xmpfr::get_str_ndigits(format.radix, xmpfr::get_prec(f));
9643 m.checked_add(1).expect("overflow")
9644 }
9645 }
9646
append_to_string(s: &mut String, f: &Float, format: Format)9647 pub(crate) fn append_to_string(s: &mut String, f: &Float, format: Format) {
9648 use core::fmt::Write;
9649
9650 if f.is_zero() {
9651 s.push_str(if f.is_sign_negative() { "-0" } else { "0" });
9652 return;
9653 }
9654 if f.is_infinite() {
9655 s.push_str(match (format.radix > 10, f.is_sign_negative()) {
9656 (false, false) => "inf",
9657 (false, true) => "-inf",
9658 (true, false) => "@inf@",
9659 (true, true) => "-@inf@",
9660 });
9661 return;
9662 }
9663 if f.is_nan() {
9664 s.push_str(match (format.radix > 10, f.is_sign_negative()) {
9665 (false, false) => "NaN",
9666 (false, true) => "-NaN",
9667 (true, false) => "@NaN@",
9668 (true, true) => "-@NaN@",
9669 });
9670 return;
9671 }
9672
9673 // no need to add 1 for nul, as req_chars includes an allocation for '.'
9674 let size = req_chars(f, format, 0);
9675 s.reserve(size);
9676 let reserved_ptr = s.as_ptr();
9677
9678 let radix_with_case = if format.to_upper {
9679 -format.radix
9680 } else {
9681 format.radix
9682 };
9683 let digits = format.precision.unwrap_or(0);
9684 let mut exp: exp_t;
9685 unsafe {
9686 let vec = s.as_mut_vec();
9687 let write_ptr = vec.as_mut_ptr().add(vec.len());
9688 let mut maybe_exp = MaybeUninit::uninit();
9689 let c_buf = mpfr::get_str(
9690 write_ptr as *mut c_char,
9691 maybe_exp.as_mut_ptr(),
9692 radix_with_case.unwrapped_cast(),
9693 digits,
9694 f.as_raw(),
9695 raw_round(format.round),
9696 );
9697 assert_eq!(c_buf, write_ptr as *mut c_char);
9698 exp = maybe_exp.assume_init();
9699 let c_len = CStr::from_ptr(write_ptr as *mut c_char).to_bytes().len();
9700 // there is also 1 byte for nul character, which will be used for point
9701 assert!(c_len + 1 < size, "buffer overflow");
9702 let added_sign = *write_ptr == b'-';
9703 let added_digits = c_len - if added_sign { 1 } else { 0 };
9704 let digits_before_point = if format.exp == ExpFormat::Exp
9705 || exp <= 0
9706 || exp.unwrapped_as::<usize>() > added_digits
9707 {
9708 exp = exp.checked_sub(1).expect("overflow");
9709 1
9710 } else {
9711 let e = exp.wrapping_as::<usize>();
9712 exp = 0;
9713 e
9714 };
9715 let bytes_before_point = digits_before_point + if added_sign { 1 } else { 0 };
9716 if bytes_before_point == c_len {
9717 // no point
9718 vec.set_len(vec.len() + c_len)
9719 } else {
9720 let point_ptr = write_ptr.add(bytes_before_point);
9721 point_ptr.copy_to(point_ptr.offset(1), c_len - bytes_before_point);
9722 *point_ptr = b'.';
9723 vec.set_len(vec.len() + c_len + 1);
9724 }
9725 }
9726 if format.exp == ExpFormat::Exp || exp != 0 {
9727 s.push(if format.radix > 10 {
9728 '@'
9729 } else if format.to_upper {
9730 'E'
9731 } else {
9732 'e'
9733 });
9734 write!(s, "{}", exp).unwrap();
9735 }
9736 debug_assert_eq!(reserved_ptr, s.as_ptr());
9737 }
9738
9739 #[derive(Debug)]
9740 pub enum ParseIncomplete {
9741 CString { c_string: CString, radix: i32 },
9742 Special(Special),
9743 NegNan,
9744 }
9745
9746 impl AssignRound<ParseIncomplete> for Float {
9747 type Round = Round;
9748 type Ordering = Ordering;
assign_round(&mut self, src: ParseIncomplete, round: Round) -> Ordering9749 fn assign_round(&mut self, src: ParseIncomplete, round: Round) -> Ordering {
9750 let (c_string, radix) = match src {
9751 ParseIncomplete::CString { c_string, radix } => (c_string, radix),
9752 ParseIncomplete::Special(special) => {
9753 self.assign(special);
9754 return Ordering::Equal;
9755 }
9756 ParseIncomplete::NegNan => {
9757 self.assign(Special::Nan);
9758 self.neg_assign();
9759 return Ordering::Equal;
9760 }
9761 };
9762 let mut c_str_end = MaybeUninit::uninit();
9763 let ret = unsafe {
9764 mpfr::strtofr(
9765 self.as_raw_mut(),
9766 c_string.as_ptr(),
9767 c_str_end.as_mut_ptr(),
9768 radix.unwrapped_cast(),
9769 raw_round(round),
9770 )
9771 };
9772 let nul = cast_ptr!(c_string.as_bytes_with_nul().last().unwrap(), c_char);
9773 assert_eq!(unsafe { c_str_end.assume_init() } as *const c_char, nul);
9774 ordering1(ret)
9775 }
9776 }
9777
9778 macro_rules! parse_error {
9779 ($kind:expr) => {
9780 Err(ParseFloatError { kind: $kind })
9781 };
9782 }
9783
parse(mut bytes: &[u8], radix: i32) -> Result<ParseIncomplete, ParseFloatError>9784 fn parse(mut bytes: &[u8], radix: i32) -> Result<ParseIncomplete, ParseFloatError> {
9785 assert!(radix >= 2 && radix <= 36, "radix {} out of range", radix);
9786 let bradix = radix.unwrapped_as::<u8>();
9787 let small_bound = b'a' - 10 + bradix;
9788 let capital_bound = b'A' - 10 + bradix;
9789 let digit_bound = b'0' + bradix;
9790
9791 bytes = misc::trim_start(bytes);
9792 bytes = misc::trim_end(bytes);
9793 if bytes.is_empty() {
9794 return parse_error!(ParseErrorKind::NoDigits);
9795 }
9796
9797 let mut has_sign = false;
9798 let mut has_minus = false;
9799 if bytes[0] == b'+' || bytes[0] == b'-' {
9800 has_sign = true;
9801 has_minus = bytes[0] == b'-';
9802 bytes = misc::trim_start(&bytes[1..]);
9803 if bytes.is_empty() {
9804 return parse_error!(ParseErrorKind::NoDigits);
9805 }
9806 }
9807
9808 if let Some(special) = parse_special(bytes, radix, has_minus) {
9809 return special;
9810 }
9811
9812 let mut v = Vec::with_capacity(bytes.len() + 2);
9813 if has_minus {
9814 v.push(b'-');
9815 }
9816 let mut has_digits = false;
9817 let mut has_point = false;
9818 let mut exp = false;
9819 for &b in bytes {
9820 let b = if radix <= 10 && (b == b'e' || b == b'E') {
9821 b'@'
9822 } else {
9823 b
9824 };
9825 let valid_digit = match b {
9826 b'.' if exp => return parse_error!(ParseErrorKind::PointInExp),
9827 b'.' if has_point => return parse_error!(ParseErrorKind::TooManyPoints),
9828 b'.' => {
9829 v.push(b'.');
9830 has_point = true;
9831 continue;
9832 }
9833 b'@' if exp => return parse_error!(ParseErrorKind::TooManyExp),
9834 b'@' if !has_digits => return parse_error!(ParseErrorKind::SignifNoDigits),
9835 b'@' => {
9836 v.push(b'@');
9837 exp = true;
9838 has_sign = false;
9839 has_digits = false;
9840 continue;
9841 }
9842 b'+' if exp && !has_sign && !has_digits => {
9843 has_sign = true;
9844 continue;
9845 }
9846 b'-' if exp && !has_sign && !has_digits => {
9847 v.push(b'-');
9848 has_sign = true;
9849 continue;
9850 }
9851 b'_' if has_digits => continue,
9852 b' ' | b'\t' | b'\n' | 0x0b | 0x0c | 0x0d => continue,
9853
9854 b'0'..=b'9' => exp || b < digit_bound,
9855 b'a'..=b'z' => !exp && b < small_bound,
9856 b'A'..=b'Z' => !exp && b < capital_bound,
9857 _ => false,
9858 };
9859 if !valid_digit {
9860 return parse_error!(ParseErrorKind::InvalidDigit);
9861 }
9862 v.push(b);
9863 has_digits = true;
9864 }
9865 if !has_digits {
9866 if exp {
9867 return parse_error!(ParseErrorKind::ExpNoDigits);
9868 } else {
9869 return parse_error!(ParseErrorKind::NoDigits);
9870 }
9871 }
9872 // we've only added checked bytes, so we know there are no nuls
9873 let c_string = unsafe { CString::from_vec_unchecked(v) };
9874 Ok(ParseIncomplete::CString { c_string, radix })
9875 }
9876
parse_special( bytes: &[u8], radix: i32, negative: bool, ) -> Option<Result<ParseIncomplete, ParseFloatError>>9877 fn parse_special(
9878 bytes: &[u8],
9879 radix: i32,
9880 negative: bool,
9881 ) -> Option<Result<ParseIncomplete, ParseFloatError>> {
9882 let small = if radix <= 10 { Some(()) } else { None };
9883
9884 let inf10: &[&[u8]] = &[b"inf", b"infinity"];
9885 let inf: &[&[u8]] = &[b"@inf@", b"@infinity@"];
9886 if let Some(after_inf) = small
9887 .and_then(|()| misc::skip_lcase_match(bytes, inf10))
9888 .or_else(|| misc::skip_lcase_match(bytes, inf))
9889 .map(misc::trim_start)
9890 {
9891 if !after_inf.is_empty() {
9892 return Some(parse_error!(ParseErrorKind::InvalidDigit));
9893 }
9894 return if negative {
9895 Some(Ok(ParseIncomplete::Special(Special::NegInfinity)))
9896 } else {
9897 Some(Ok(ParseIncomplete::Special(Special::Infinity)))
9898 };
9899 }
9900
9901 let nan10: &[&[u8]] = &[b"nan", b"+nan"];
9902 let nan: &[&[u8]] = &[b"@nan@", b"+@nan@"];
9903 if let Some(after_nan) = small
9904 .and_then(|()| misc::skip_lcase_match(bytes, nan10))
9905 .or_else(|| misc::skip_lcase_match(bytes, nan))
9906 .map(misc::trim_start)
9907 {
9908 let trailing = if let Some(after_extra) = skip_nan_extra(after_nan).map(misc::trim_start) {
9909 after_extra
9910 } else {
9911 after_nan
9912 };
9913 if !trailing.is_empty() {
9914 return Some(parse_error!(ParseErrorKind::InvalidDigit));
9915 }
9916 return if negative {
9917 Some(Ok(ParseIncomplete::NegNan))
9918 } else {
9919 Some(Ok(ParseIncomplete::Special(Special::Nan)))
9920 };
9921 }
9922 None
9923 }
9924
9925 // If bytes starts with nan extras e.g. b"(stuff)", return bytes with
9926 // the match skipped.
skip_nan_extra(bytes: &[u8]) -> Option<&[u8]>9927 fn skip_nan_extra(bytes: &[u8]) -> Option<&[u8]> {
9928 let mut iter = bytes.iter().enumerate();
9929 match iter.next() {
9930 Some((_, &b'(')) => {}
9931 _ => return None,
9932 }
9933 for (i, &b) in iter {
9934 match b {
9935 b')' => return Some(&bytes[i + 1..]),
9936 b'0'..=b'9'
9937 | b'a'..=b'z'
9938 | b'A'..=b'Z'
9939 | b'_'
9940 | b' '
9941 | b'\t'
9942 | b'\n'
9943 | 0x0b
9944 | 0x0c
9945 | 0x0d => {}
9946 _ => return None,
9947 }
9948 }
9949 None
9950 }
9951
9952 #[derive(Debug)]
9953 /**
9954 An error which can be returned when parsing a [`Float`].
9955
9956 See the <code>[Float][`Float`]::[parse_radix][`parse_radix`]</code>
9957 method for details on what strings are accepted.
9958
9959 # Examples
9960
9961 ```rust
9962 use rug::{float::ParseFloatError, Float};
9963 // This string is not a floating-point number.
9964 let s = "something completely different (_!_!_)";
9965 let error: ParseFloatError = match Float::parse_radix(s, 4) {
9966 Ok(_) => unreachable!(),
9967 Err(error) => error,
9968 };
9969 println!("Parse error: {}", error);
9970 ```
9971
9972 [`Float`]: ../struct.Float.html
9973 [`parse_radix`]: ../struct.Float.html#method.parse_radix
9974 */
9975 pub struct ParseFloatError {
9976 kind: ParseErrorKind,
9977 }
9978
9979 #[derive(Debug)]
9980 enum ParseErrorKind {
9981 InvalidDigit,
9982 NoDigits,
9983 SignifNoDigits,
9984 ExpNoDigits,
9985 PointInExp,
9986 TooManyPoints,
9987 TooManyExp,
9988 }
9989
9990 impl ParseFloatError {
desc(&self) -> &str9991 fn desc(&self) -> &str {
9992 use self::ParseErrorKind::*;
9993 match self.kind {
9994 InvalidDigit => "invalid digit found in string",
9995 NoDigits => "string has no digits",
9996 SignifNoDigits => "string has no digits for significand",
9997 ExpNoDigits => "string has no digits for exponent",
9998 PointInExp => "string has point in exponent",
9999 TooManyPoints => "more than one point found in string",
10000 TooManyExp => "more than one exponent found in string",
10001 }
10002 }
10003 }
10004
10005 impl Error for ParseFloatError {
description(&self) -> &str10006 fn description(&self) -> &str {
10007 self.desc()
10008 }
10009 }
10010
10011 impl Display for ParseFloatError {
fmt(&self, f: &mut Formatter<'_>) -> FmtResult10012 fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
10013 Display::fmt(self.desc(), f)
10014 }
10015 }
10016
ieee_storage_bits_for_prec(prec: u32) -> Option<u32>10017 fn ieee_storage_bits_for_prec(prec: u32) -> Option<u32> {
10018 // p = prec, k = storage bits
10019 match prec {
10020 11 => return Some(16),
10021 24 => return Some(32),
10022 53 => return Some(64),
10023 _ => {}
10024 }
10025 // When k > 64, k must be a multiple of 32 ≥ 128 (96 is skipped by the standard).
10026 // p = k - round(4 log2 k) + 13
10027 // When k = 128, p = 113.
10028 // When k = 2^32 (overflow), p = 2^32 - 115 = MAX - 114.
10029 // When k = max allowed = 2^32 - 32, p = 2^32 - 32 - 115 = MAX - 146.
10030 if prec < 113 || prec > u32::max_value() - 146 {
10031 return None;
10032 }
10033
10034 // k = p - 13 + round(4 log2 k)
10035 // But we only need to find an approximation for k with error < 16,
10036 // and log2 k - log2 p < 1/5 when p ≥ 113.
10037 // estimate = p - 13 + 4 * log2 p
10038 // log2 p is approximately 31.5 - prec.leading_zeros()
10039 // estimate = p - 13 + 4 * (31.5 - zeros) = p - 4 * zeros + 113.
10040 // Since we already checked that p <= MAX - 146, p + 113 never overflows.
10041 let estimate = prec - 4 * prec.leading_zeros() + 113;
10042 // k must be a multiple of 32
10043 let k = (estimate + 16) & !31;
10044 let p = k - (f64::from(k).log2() * 4.0).round().unwrapped_as::<u32>() + 13;
10045 if p == prec {
10046 Some(k)
10047 } else {
10048 None
10049 }
10050 }
10051
10052 impl PartialOrd<UExpIncomplete> for Float {
10053 #[inline]
partial_cmp(&self, other: &UExpIncomplete) -> Option<Ordering>10054 fn partial_cmp(&self, other: &UExpIncomplete) -> Option<Ordering> {
10055 if self.is_nan() {
10056 None
10057 } else {
10058 Some(xmpfr::cmp_u32_2exp(self, other.u, other.exp))
10059 }
10060 }
10061 }
10062
10063 impl PartialOrd<IExpIncomplete> for Float {
10064 #[inline]
partial_cmp(&self, other: &IExpIncomplete) -> Option<Ordering>10065 fn partial_cmp(&self, other: &IExpIncomplete) -> Option<Ordering> {
10066 if self.is_nan() {
10067 None
10068 } else {
10069 Some(xmpfr::cmp_i32_2exp(self, other.i, other.exp))
10070 }
10071 }
10072 }
10073
10074 #[cfg(test)]
10075 mod tests {
10076 use super::ieee_storage_bits_for_prec;
10077
10078 #[test]
check_ieee_storage_bits()10079 fn check_ieee_storage_bits() {
10080 assert_eq!(ieee_storage_bits_for_prec(0), None);
10081 assert_eq!(ieee_storage_bits_for_prec(11), Some(16));
10082 assert_eq!(ieee_storage_bits_for_prec(24), Some(32));
10083 assert_eq!(ieee_storage_bits_for_prec(53), Some(64));
10084 assert_eq!(ieee_storage_bits_for_prec(83), None); // no 96
10085 assert_eq!(ieee_storage_bits_for_prec(113), Some(128));
10086 assert_eq!(ieee_storage_bits_for_prec(144), Some(160));
10087 assert_eq!(ieee_storage_bits_for_prec(237), Some(256));
10088 assert_eq!(
10089 ieee_storage_bits_for_prec(u32::max_value() - 178),
10090 Some(u32::max_value() - 63)
10091 );
10092 assert_eq!(ieee_storage_bits_for_prec(u32::max_value() - 145), None);
10093 assert_eq!(
10094 ieee_storage_bits_for_prec(u32::max_value() - 146),
10095 Some(u32::max_value() - 31)
10096 );
10097 assert_eq!(ieee_storage_bits_for_prec(u32::max_value() - 147), None);
10098 assert_eq!(ieee_storage_bits_for_prec(u32::max_value() - 114), None);
10099 assert_eq!(ieee_storage_bits_for_prec(u32::max_value()), None);
10100 }
10101 }
10102