1 | //! Constants for the `f32` single-precision floating point type. |
---|---|

2 | //! |

3 | //! *[See also the `f32` primitive type](primitive@f32).* |

4 | //! |

5 | //! Mathematically significant numbers are provided in the `consts` sub-module. |

6 | //! |

7 | //! For the constants defined directly in this module |

8 | //! (as distinct from those defined in the `consts` sub-module), |

9 | //! new code should instead use the associated constants |

10 | //! defined directly on the `f32` type. |

11 | |

12 | #![stable(feature = "rust1", since = "1.0.0")] |

13 | #![allow(missing_docs)] |

14 | |

15 | #[cfg(test)] |

16 | mod tests; |

17 | |

18 | #[cfg(not(test))] |

19 | use crate::intrinsics; |

20 | #[cfg(not(test))] |

21 | use crate::sys::cmath; |

22 | |

23 | #[stable(feature = "rust1", since = "1.0.0")] |

24 | #[allow(deprecated, deprecated_in_future)] |

25 | pub use core::f32::{ |

26 | consts, DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_10_EXP, |

27 | MIN_EXP, MIN_POSITIVE, NAN, NEG_INFINITY, RADIX, |

28 | }; |

29 | |

30 | #[cfg(not(test))] |

31 | impl f32 { |

32 | /// Returns the largest integer less than or equal to `self`. |

33 | /// |

34 | /// # Examples |

35 | /// |

36 | /// ``` |

37 | /// let f = 3.7_f32; |

38 | /// let g = 3.0_f32; |

39 | /// let h = -3.7_f32; |

40 | /// |

41 | /// assert_eq!(f.floor(), 3.0); |

42 | /// assert_eq!(g.floor(), 3.0); |

43 | /// assert_eq!(h.floor(), -4.0); |

44 | /// ``` |

45 | #[rustc_allow_incoherent_impl] |

46 | #[must_use= "method returns a new number and does not mutate the original value"] |

47 | #[stable(feature = "rust1", since = "1.0.0")] |

48 | #[inline] |

49 | pub fn floor(self) -> f32 { |

50 | unsafe { intrinsics::floorf32(self) } |

51 | } |

52 | |

53 | /// Returns the smallest integer greater than or equal to `self`. |

54 | /// |

55 | /// # Examples |

56 | /// |

57 | /// ``` |

58 | /// let f = 3.01_f32; |

59 | /// let g = 4.0_f32; |

60 | /// |

61 | /// assert_eq!(f.ceil(), 4.0); |

62 | /// assert_eq!(g.ceil(), 4.0); |

63 | /// ``` |

64 | #[doc(alias = "ceiling")] |

65 | #[rustc_allow_incoherent_impl] |

66 | #[must_use= "method returns a new number and does not mutate the original value"] |

67 | #[stable(feature = "rust1", since = "1.0.0")] |

68 | #[inline] |

69 | pub fn ceil(self) -> f32 { |

70 | unsafe { intrinsics::ceilf32(self) } |

71 | } |

72 | |

73 | /// Returns the nearest integer to `self`. If a value is half-way between two |

74 | /// integers, round away from `0.0`. |

75 | /// |

76 | /// # Examples |

77 | /// |

78 | /// ``` |

79 | /// let f = 3.3_f32; |

80 | /// let g = -3.3_f32; |

81 | /// let h = -3.7_f32; |

82 | /// let i = 3.5_f32; |

83 | /// let j = 4.5_f32; |

84 | /// |

85 | /// assert_eq!(f.round(), 3.0); |

86 | /// assert_eq!(g.round(), -3.0); |

87 | /// assert_eq!(h.round(), -4.0); |

88 | /// assert_eq!(i.round(), 4.0); |

89 | /// assert_eq!(j.round(), 5.0); |

90 | /// ``` |

91 | #[rustc_allow_incoherent_impl] |

92 | #[must_use= "method returns a new number and does not mutate the original value"] |

93 | #[stable(feature = "rust1", since = "1.0.0")] |

94 | #[inline] |

95 | pub fn round(self) -> f32 { |

96 | unsafe { intrinsics::roundf32(self) } |

97 | } |

98 | |

99 | /// Returns the nearest integer to a number. Rounds half-way cases to the number |

100 | /// with an even least significant digit. |

101 | /// |

102 | /// # Examples |

103 | /// |

104 | /// ``` |

105 | /// let f = 3.3_f32; |

106 | /// let g = -3.3_f32; |

107 | /// let h = 3.5_f32; |

108 | /// let i = 4.5_f32; |

109 | /// |

110 | /// assert_eq!(f.round_ties_even(), 3.0); |

111 | /// assert_eq!(g.round_ties_even(), -3.0); |

112 | /// assert_eq!(h.round_ties_even(), 4.0); |

113 | /// assert_eq!(i.round_ties_even(), 4.0); |

114 | /// ``` |

115 | #[rustc_allow_incoherent_impl] |

116 | #[must_use= "method returns a new number and does not mutate the original value"] |

117 | #[stable(feature = "round_ties_even", since = "1.77.0")] |

118 | #[inline] |

119 | pub fn round_ties_even(self) -> f32 { |

120 | unsafe { intrinsics::rintf32(self) } |

121 | } |

122 | |

123 | /// Returns the integer part of `self`. |

124 | /// This means that non-integer numbers are always truncated towards zero. |

125 | /// |

126 | /// # Examples |

127 | /// |

128 | /// ``` |

129 | /// let f = 3.7_f32; |

130 | /// let g = 3.0_f32; |

131 | /// let h = -3.7_f32; |

132 | /// |

133 | /// assert_eq!(f.trunc(), 3.0); |

134 | /// assert_eq!(g.trunc(), 3.0); |

135 | /// assert_eq!(h.trunc(), -3.0); |

136 | /// ``` |

137 | #[doc(alias = "truncate")] |

138 | #[rustc_allow_incoherent_impl] |

139 | #[must_use= "method returns a new number and does not mutate the original value"] |

140 | #[stable(feature = "rust1", since = "1.0.0")] |

141 | #[inline] |

142 | pub fn trunc(self) -> f32 { |

143 | unsafe { intrinsics::truncf32(self) } |

144 | } |

145 | |

146 | /// Returns the fractional part of `self`. |

147 | /// |

148 | /// # Examples |

149 | /// |

150 | /// ``` |

151 | /// let x = 3.6_f32; |

152 | /// let y = -3.6_f32; |

153 | /// let abs_difference_x = (x.fract() - 0.6).abs(); |

154 | /// let abs_difference_y = (y.fract() - (-0.6)).abs(); |

155 | /// |

156 | /// assert!(abs_difference_x <= f32::EPSILON); |

157 | /// assert!(abs_difference_y <= f32::EPSILON); |

158 | /// ``` |

159 | #[rustc_allow_incoherent_impl] |

160 | #[must_use= "method returns a new number and does not mutate the original value"] |

161 | #[stable(feature = "rust1", since = "1.0.0")] |

162 | #[inline] |

163 | pub fn fract(self) -> f32 { |

164 | self - self.trunc() |

165 | } |

166 | |

167 | /// Computes the absolute value of `self`. |

168 | /// |

169 | /// # Examples |

170 | /// |

171 | /// ``` |

172 | /// let x = 3.5_f32; |

173 | /// let y = -3.5_f32; |

174 | /// |

175 | /// let abs_difference_x = (x.abs() - x).abs(); |

176 | /// let abs_difference_y = (y.abs() - (-y)).abs(); |

177 | /// |

178 | /// assert!(abs_difference_x <= f32::EPSILON); |

179 | /// assert!(abs_difference_y <= f32::EPSILON); |

180 | /// |

181 | /// assert!(f32::NAN.abs().is_nan()); |

182 | /// ``` |

183 | #[rustc_allow_incoherent_impl] |

184 | #[must_use= "method returns a new number and does not mutate the original value"] |

185 | #[stable(feature = "rust1", since = "1.0.0")] |

186 | #[inline] |

187 | pub fn abs(self) -> f32 { |

188 | unsafe { intrinsics::fabsf32(self) } |

189 | } |

190 | |

191 | /// Returns a number that represents the sign of `self`. |

192 | /// |

193 | /// - `1.0` if the number is positive, `+0.0` or `INFINITY` |

194 | /// - `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY` |

195 | /// - NaN if the number is NaN |

196 | /// |

197 | /// # Examples |

198 | /// |

199 | /// ``` |

200 | /// let f = 3.5_f32; |

201 | /// |

202 | /// assert_eq!(f.signum(), 1.0); |

203 | /// assert_eq!(f32::NEG_INFINITY.signum(), -1.0); |

204 | /// |

205 | /// assert!(f32::NAN.signum().is_nan()); |

206 | /// ``` |

207 | #[rustc_allow_incoherent_impl] |

208 | #[must_use= "method returns a new number and does not mutate the original value"] |

209 | #[stable(feature = "rust1", since = "1.0.0")] |

210 | #[inline] |

211 | pub fn signum(self) -> f32 { |

212 | if self.is_nan() { Self::NAN } else { 1.0_f32.copysign(self) } |

213 | } |

214 | |

215 | /// Returns a number composed of the magnitude of `self` and the sign of |

216 | /// `sign`. |

217 | /// |

218 | /// Equal to `self` if the sign of `self` and `sign` are the same, otherwise |

219 | /// equal to `-self`. If `self` is a NaN, then a NaN with the sign bit of |

220 | /// `sign` is returned. Note, however, that conserving the sign bit on NaN |

221 | /// across arithmetical operations is not generally guaranteed. |

222 | /// See [explanation of NaN as a special value](primitive@f32) for more info. |

223 | /// |

224 | /// # Examples |

225 | /// |

226 | /// ``` |

227 | /// let f = 3.5_f32; |

228 | /// |

229 | /// assert_eq!(f.copysign(0.42), 3.5_f32); |

230 | /// assert_eq!(f.copysign(-0.42), -3.5_f32); |

231 | /// assert_eq!((-f).copysign(0.42), 3.5_f32); |

232 | /// assert_eq!((-f).copysign(-0.42), -3.5_f32); |

233 | /// |

234 | /// assert!(f32::NAN.copysign(1.0).is_nan()); |

235 | /// ``` |

236 | #[rustc_allow_incoherent_impl] |

237 | #[must_use= "method returns a new number and does not mutate the original value"] |

238 | #[inline] |

239 | #[stable(feature = "copysign", since = "1.35.0")] |

240 | pub fn copysign(self, sign: f32) -> f32 { |

241 | unsafe { intrinsics::copysignf32(self, sign) } |

242 | } |

243 | |

244 | /// Fused multiply-add. Computes `(self * a) + b` with only one rounding |

245 | /// error, yielding a more accurate result than an unfused multiply-add. |

246 | /// |

247 | /// Using `mul_add` *may* be more performant than an unfused multiply-add if |

248 | /// the target architecture has a dedicated `fma` CPU instruction. However, |

249 | /// this is not always true, and will be heavily dependant on designing |

250 | /// algorithms with specific target hardware in mind. |

251 | /// |

252 | /// # Examples |

253 | /// |

254 | /// ``` |

255 | /// let m = 10.0_f32; |

256 | /// let x = 4.0_f32; |

257 | /// let b = 60.0_f32; |

258 | /// |

259 | /// // 100.0 |

260 | /// let abs_difference = (m.mul_add(x, b) - ((m * x) + b)).abs(); |

261 | /// |

262 | /// assert!(abs_difference <= f32::EPSILON); |

263 | /// ``` |

264 | #[rustc_allow_incoherent_impl] |

265 | #[must_use= "method returns a new number and does not mutate the original value"] |

266 | #[stable(feature = "rust1", since = "1.0.0")] |

267 | #[inline] |

268 | pub fn mul_add(self, a: f32, b: f32) -> f32 { |

269 | unsafe { intrinsics::fmaf32(self, a, b) } |

270 | } |

271 | |

272 | /// Calculates Euclidean division, the matching method for `rem_euclid`. |

273 | /// |

274 | /// This computes the integer `n` such that |

275 | /// `self = n * rhs + self.rem_euclid(rhs)`. |

276 | /// In other words, the result is `self / rhs` rounded to the integer `n` |

277 | /// such that `self >= n * rhs`. |

278 | /// |

279 | /// # Examples |

280 | /// |

281 | /// ``` |

282 | /// let a: f32 = 7.0; |

283 | /// let b = 4.0; |

284 | /// assert_eq!(a.div_euclid(b), 1.0); // 7.0 > 4.0 * 1.0 |

285 | /// assert_eq!((-a).div_euclid(b), -2.0); // -7.0 >= 4.0 * -2.0 |

286 | /// assert_eq!(a.div_euclid(-b), -1.0); // 7.0 >= -4.0 * -1.0 |

287 | /// assert_eq!((-a).div_euclid(-b), 2.0); // -7.0 >= -4.0 * 2.0 |

288 | /// ``` |

289 | #[rustc_allow_incoherent_impl] |

290 | #[must_use= "method returns a new number and does not mutate the original value"] |

291 | #[inline] |

292 | #[stable(feature = "euclidean_division", since = "1.38.0")] |

293 | pub fn div_euclid(self, rhs: f32) -> f32 { |

294 | let q = (self / rhs).trunc(); |

295 | if self % rhs < 0.0 { |

296 | return if rhs > 0.0 { q - 1.0 } else { q + 1.0 }; |

297 | } |

298 | q |

299 | } |

300 | |

301 | /// Calculates the least nonnegative remainder of `self (mod rhs)`. |

302 | /// |

303 | /// In particular, the return value `r` satisfies `0.0 <= r < rhs.abs()` in |

304 | /// most cases. However, due to a floating point round-off error it can |

305 | /// result in `r == rhs.abs()`, violating the mathematical definition, if |

306 | /// `self` is much smaller than `rhs.abs()` in magnitude and `self < 0.0`. |

307 | /// This result is not an element of the function's codomain, but it is the |

308 | /// closest floating point number in the real numbers and thus fulfills the |

309 | /// property `self == self.div_euclid(rhs) * rhs + self.rem_euclid(rhs)` |

310 | /// approximately. |

311 | /// |

312 | /// # Examples |

313 | /// |

314 | /// ``` |

315 | /// let a: f32 = 7.0; |

316 | /// let b = 4.0; |

317 | /// assert_eq!(a.rem_euclid(b), 3.0); |

318 | /// assert_eq!((-a).rem_euclid(b), 1.0); |

319 | /// assert_eq!(a.rem_euclid(-b), 3.0); |

320 | /// assert_eq!((-a).rem_euclid(-b), 1.0); |

321 | /// // limitation due to round-off error |

322 | /// assert!((-f32::EPSILON).rem_euclid(3.0) != 0.0); |

323 | /// ``` |

324 | #[doc(alias = "modulo", alias = "mod")] |

325 | #[rustc_allow_incoherent_impl] |

326 | #[must_use= "method returns a new number and does not mutate the original value"] |

327 | #[inline] |

328 | #[stable(feature = "euclidean_division", since = "1.38.0")] |

329 | pub fn rem_euclid(self, rhs: f32) -> f32 { |

330 | let r = self % rhs; |

331 | if r < 0.0 { r + rhs.abs() } else { r } |

332 | } |

333 | |

334 | /// Raises a number to an integer power. |

335 | /// |

336 | /// Using this function is generally faster than using `powf`. |

337 | /// It might have a different sequence of rounding operations than `powf`, |

338 | /// so the results are not guaranteed to agree. |

339 | /// |

340 | /// # Examples |

341 | /// |

342 | /// ``` |

343 | /// let x = 2.0_f32; |

344 | /// let abs_difference = (x.powi(2) - (x * x)).abs(); |

345 | /// |

346 | /// assert!(abs_difference <= f32::EPSILON); |

347 | /// ``` |

348 | #[rustc_allow_incoherent_impl] |

349 | #[must_use= "method returns a new number and does not mutate the original value"] |

350 | #[stable(feature = "rust1", since = "1.0.0")] |

351 | #[inline] |

352 | pub fn powi(self, n: i32) -> f32 { |

353 | unsafe { intrinsics::powif32(self, n) } |

354 | } |

355 | |

356 | /// Raises a number to a floating point power. |

357 | /// |

358 | /// # Examples |

359 | /// |

360 | /// ``` |

361 | /// let x = 2.0_f32; |

362 | /// let abs_difference = (x.powf(2.0) - (x * x)).abs(); |

363 | /// |

364 | /// assert!(abs_difference <= f32::EPSILON); |

365 | /// ``` |

366 | #[rustc_allow_incoherent_impl] |

367 | #[must_use= "method returns a new number and does not mutate the original value"] |

368 | #[stable(feature = "rust1", since = "1.0.0")] |

369 | #[inline] |

370 | pub fn powf(self, n: f32) -> f32 { |

371 | unsafe { intrinsics::powf32(self, n) } |

372 | } |

373 | |

374 | /// Returns the square root of a number. |

375 | /// |

376 | /// Returns NaN if `self` is a negative number other than `-0.0`. |

377 | /// |

378 | /// # Examples |

379 | /// |

380 | /// ``` |

381 | /// let positive = 4.0_f32; |

382 | /// let negative = -4.0_f32; |

383 | /// let negative_zero = -0.0_f32; |

384 | /// |

385 | /// let abs_difference = (positive.sqrt() - 2.0).abs(); |

386 | /// |

387 | /// assert!(abs_difference <= f32::EPSILON); |

388 | /// assert!(negative.sqrt().is_nan()); |

389 | /// assert!(negative_zero.sqrt() == negative_zero); |

390 | /// ``` |

391 | #[rustc_allow_incoherent_impl] |

392 | #[must_use= "method returns a new number and does not mutate the original value"] |

393 | #[stable(feature = "rust1", since = "1.0.0")] |

394 | #[inline] |

395 | pub fn sqrt(self) -> f32 { |

396 | unsafe { intrinsics::sqrtf32(self) } |

397 | } |

398 | |

399 | /// Returns `e^(self)`, (the exponential function). |

400 | /// |

401 | /// # Examples |

402 | /// |

403 | /// ``` |

404 | /// let one = 1.0f32; |

405 | /// // e^1 |

406 | /// let e = one.exp(); |

407 | /// |

408 | /// // ln(e) - 1 == 0 |

409 | /// let abs_difference = (e.ln() - 1.0).abs(); |

410 | /// |

411 | /// assert!(abs_difference <= f32::EPSILON); |

412 | /// ``` |

413 | #[rustc_allow_incoherent_impl] |

414 | #[must_use= "method returns a new number and does not mutate the original value"] |

415 | #[stable(feature = "rust1", since = "1.0.0")] |

416 | #[inline] |

417 | pub fn exp(self) -> f32 { |

418 | unsafe { intrinsics::expf32(self) } |

419 | } |

420 | |

421 | /// Returns `2^(self)`. |

422 | /// |

423 | /// # Examples |

424 | /// |

425 | /// ``` |

426 | /// let f = 2.0f32; |

427 | /// |

428 | /// // 2^2 - 4 == 0 |

429 | /// let abs_difference = (f.exp2() - 4.0).abs(); |

430 | /// |

431 | /// assert!(abs_difference <= f32::EPSILON); |

432 | /// ``` |

433 | #[rustc_allow_incoherent_impl] |

434 | #[must_use= "method returns a new number and does not mutate the original value"] |

435 | #[stable(feature = "rust1", since = "1.0.0")] |

436 | #[inline] |

437 | pub fn exp2(self) -> f32 { |

438 | unsafe { intrinsics::exp2f32(self) } |

439 | } |

440 | |

441 | /// Returns the natural logarithm of the number. |

442 | /// |

443 | /// # Examples |

444 | /// |

445 | /// ``` |

446 | /// let one = 1.0f32; |

447 | /// // e^1 |

448 | /// let e = one.exp(); |

449 | /// |

450 | /// // ln(e) - 1 == 0 |

451 | /// let abs_difference = (e.ln() - 1.0).abs(); |

452 | /// |

453 | /// assert!(abs_difference <= f32::EPSILON); |

454 | /// ``` |

455 | #[rustc_allow_incoherent_impl] |

456 | #[must_use= "method returns a new number and does not mutate the original value"] |

457 | #[stable(feature = "rust1", since = "1.0.0")] |

458 | #[inline] |

459 | pub fn ln(self) -> f32 { |

460 | unsafe { intrinsics::logf32(self) } |

461 | } |

462 | |

463 | /// Returns the logarithm of the number with respect to an arbitrary base. |

464 | /// |

465 | /// The result might not be correctly rounded owing to implementation details; |

466 | /// `self.log2()` can produce more accurate results for base 2, and |

467 | /// `self.log10()` can produce more accurate results for base 10. |

468 | /// |

469 | /// # Examples |

470 | /// |

471 | /// ``` |

472 | /// let five = 5.0f32; |

473 | /// |

474 | /// // log5(5) - 1 == 0 |

475 | /// let abs_difference = (five.log(5.0) - 1.0).abs(); |

476 | /// |

477 | /// assert!(abs_difference <= f32::EPSILON); |

478 | /// ``` |

479 | #[rustc_allow_incoherent_impl] |

480 | #[must_use= "method returns a new number and does not mutate the original value"] |

481 | #[stable(feature = "rust1", since = "1.0.0")] |

482 | #[inline] |

483 | pub fn log(self, base: f32) -> f32 { |

484 | self.ln() / base.ln() |

485 | } |

486 | |

487 | /// Returns the base 2 logarithm of the number. |

488 | /// |

489 | /// # Examples |

490 | /// |

491 | /// ``` |

492 | /// let two = 2.0f32; |

493 | /// |

494 | /// // log2(2) - 1 == 0 |

495 | /// let abs_difference = (two.log2() - 1.0).abs(); |

496 | /// |

497 | /// assert!(abs_difference <= f32::EPSILON); |

498 | /// ``` |

499 | #[rustc_allow_incoherent_impl] |

500 | #[must_use= "method returns a new number and does not mutate the original value"] |

501 | #[stable(feature = "rust1", since = "1.0.0")] |

502 | #[inline] |

503 | pub fn log2(self) -> f32 { |

504 | crate::sys::log2f32(self) |

505 | } |

506 | |

507 | /// Returns the base 10 logarithm of the number. |

508 | /// |

509 | /// # Examples |

510 | /// |

511 | /// ``` |

512 | /// let ten = 10.0f32; |

513 | /// |

514 | /// // log10(10) - 1 == 0 |

515 | /// let abs_difference = (ten.log10() - 1.0).abs(); |

516 | /// |

517 | /// assert!(abs_difference <= f32::EPSILON); |

518 | /// ``` |

519 | #[rustc_allow_incoherent_impl] |

520 | #[must_use= "method returns a new number and does not mutate the original value"] |

521 | #[stable(feature = "rust1", since = "1.0.0")] |

522 | #[inline] |

523 | pub fn log10(self) -> f32 { |

524 | unsafe { intrinsics::log10f32(self) } |

525 | } |

526 | |

527 | /// The positive difference of two numbers. |

528 | /// |

529 | /// * If `self <= other`: `0.0` |

530 | /// * Else: `self - other` |

531 | /// |

532 | /// # Examples |

533 | /// |

534 | /// ``` |

535 | /// let x = 3.0f32; |

536 | /// let y = -3.0f32; |

537 | /// |

538 | /// let abs_difference_x = (x.abs_sub(1.0) - 2.0).abs(); |

539 | /// let abs_difference_y = (y.abs_sub(1.0) - 0.0).abs(); |

540 | /// |

541 | /// assert!(abs_difference_x <= f32::EPSILON); |

542 | /// assert!(abs_difference_y <= f32::EPSILON); |

543 | /// ``` |

544 | #[rustc_allow_incoherent_impl] |

545 | #[must_use= "method returns a new number and does not mutate the original value"] |

546 | #[stable(feature = "rust1", since = "1.0.0")] |

547 | #[inline] |

548 | #[deprecated( |

549 | since = "1.10.0", |

550 | note = "you probably meant `(self - other).abs()`: \ |

551 | this operation is `(self - other).max(0.0)` \ |

552 | except that `abs_sub` also propagates NaNs (also \ |

553 | known as `fdimf` in C). If you truly need the positive \ |

554 | difference, consider using that expression or the C function \ |

555 | `fdimf`, depending on how you wish to handle NaN (please consider \ |

556 | filing an issue describing your use-case too)." |

557 | )] |

558 | pub fn abs_sub(self, other: f32) -> f32 { |

559 | unsafe { cmath::fdimf(self, other) } |

560 | } |

561 | |

562 | /// Returns the cube root of a number. |

563 | /// |

564 | /// # Examples |

565 | /// |

566 | /// ``` |

567 | /// let x = 8.0f32; |

568 | /// |

569 | /// // x^(1/3) - 2 == 0 |

570 | /// let abs_difference = (x.cbrt() - 2.0).abs(); |

571 | /// |

572 | /// assert!(abs_difference <= f32::EPSILON); |

573 | /// ``` |

574 | #[rustc_allow_incoherent_impl] |

575 | #[must_use= "method returns a new number and does not mutate the original value"] |

576 | #[stable(feature = "rust1", since = "1.0.0")] |

577 | #[inline] |

578 | pub fn cbrt(self) -> f32 { |

579 | unsafe { cmath::cbrtf(self) } |

580 | } |

581 | |

582 | /// Compute the distance between the origin and a point (`x`, `y`) on the |

583 | /// Euclidean plane. Equivalently, compute the length of the hypotenuse of a |

584 | /// right-angle triangle with other sides having length `x.abs()` and |

585 | /// `y.abs()`. |

586 | /// |

587 | /// # Examples |

588 | /// |

589 | /// ``` |

590 | /// let x = 2.0f32; |

591 | /// let y = 3.0f32; |

592 | /// |

593 | /// // sqrt(x^2 + y^2) |

594 | /// let abs_difference = (x.hypot(y) - (x.powi(2) + y.powi(2)).sqrt()).abs(); |

595 | /// |

596 | /// assert!(abs_difference <= f32::EPSILON); |

597 | /// ``` |

598 | #[rustc_allow_incoherent_impl] |

599 | #[must_use= "method returns a new number and does not mutate the original value"] |

600 | #[stable(feature = "rust1", since = "1.0.0")] |

601 | #[inline] |

602 | pub fn hypot(self, other: f32) -> f32 { |

603 | unsafe { cmath::hypotf(self, other) } |

604 | } |

605 | |

606 | /// Computes the sine of a number (in radians). |

607 | /// |

608 | /// # Examples |

609 | /// |

610 | /// ``` |

611 | /// let x = std::f32::consts::FRAC_PI_2; |

612 | /// |

613 | /// let abs_difference = (x.sin() - 1.0).abs(); |

614 | /// |

615 | /// assert!(abs_difference <= f32::EPSILON); |

616 | /// ``` |

617 | #[rustc_allow_incoherent_impl] |

618 | #[must_use= "method returns a new number and does not mutate the original value"] |

619 | #[stable(feature = "rust1", since = "1.0.0")] |

620 | #[inline] |

621 | pub fn sin(self) -> f32 { |

622 | unsafe { intrinsics::sinf32(self) } |

623 | } |

624 | |

625 | /// Computes the cosine of a number (in radians). |

626 | /// |

627 | /// # Examples |

628 | /// |

629 | /// ``` |

630 | /// let x = 2.0 * std::f32::consts::PI; |

631 | /// |

632 | /// let abs_difference = (x.cos() - 1.0).abs(); |

633 | /// |

634 | /// assert!(abs_difference <= f32::EPSILON); |

635 | /// ``` |

636 | #[rustc_allow_incoherent_impl] |

637 | #[must_use= "method returns a new number and does not mutate the original value"] |

638 | #[stable(feature = "rust1", since = "1.0.0")] |

639 | #[inline] |

640 | pub fn cos(self) -> f32 { |

641 | unsafe { intrinsics::cosf32(self) } |

642 | } |

643 | |

644 | /// Computes the tangent of a number (in radians). |

645 | /// |

646 | /// # Examples |

647 | /// |

648 | /// ``` |

649 | /// let x = std::f32::consts::FRAC_PI_4; |

650 | /// let abs_difference = (x.tan() - 1.0).abs(); |

651 | /// |

652 | /// assert!(abs_difference <= f32::EPSILON); |

653 | /// ``` |

654 | #[rustc_allow_incoherent_impl] |

655 | #[must_use= "method returns a new number and does not mutate the original value"] |

656 | #[stable(feature = "rust1", since = "1.0.0")] |

657 | #[inline] |

658 | pub fn tan(self) -> f32 { |

659 | unsafe { cmath::tanf(self) } |

660 | } |

661 | |

662 | /// Computes the arcsine of a number. Return value is in radians in |

663 | /// the range [-pi/2, pi/2] or NaN if the number is outside the range |

664 | /// [-1, 1]. |

665 | /// |

666 | /// # Examples |

667 | /// |

668 | /// ``` |

669 | /// let f = std::f32::consts::FRAC_PI_2; |

670 | /// |

671 | /// // asin(sin(pi/2)) |

672 | /// let abs_difference = (f.sin().asin() - std::f32::consts::FRAC_PI_2).abs(); |

673 | /// |

674 | /// assert!(abs_difference <= f32::EPSILON); |

675 | /// ``` |

676 | #[doc(alias = "arcsin")] |

677 | #[rustc_allow_incoherent_impl] |

678 | #[must_use= "method returns a new number and does not mutate the original value"] |

679 | #[stable(feature = "rust1", since = "1.0.0")] |

680 | #[inline] |

681 | pub fn asin(self) -> f32 { |

682 | unsafe { cmath::asinf(self) } |

683 | } |

684 | |

685 | /// Computes the arccosine of a number. Return value is in radians in |

686 | /// the range [0, pi] or NaN if the number is outside the range |

687 | /// [-1, 1]. |

688 | /// |

689 | /// # Examples |

690 | /// |

691 | /// ``` |

692 | /// let f = std::f32::consts::FRAC_PI_4; |

693 | /// |

694 | /// // acos(cos(pi/4)) |

695 | /// let abs_difference = (f.cos().acos() - std::f32::consts::FRAC_PI_4).abs(); |

696 | /// |

697 | /// assert!(abs_difference <= f32::EPSILON); |

698 | /// ``` |

699 | #[doc(alias = "arccos")] |

700 | #[rustc_allow_incoherent_impl] |

701 | #[must_use= "method returns a new number and does not mutate the original value"] |

702 | #[stable(feature = "rust1", since = "1.0.0")] |

703 | #[inline] |

704 | pub fn acos(self) -> f32 { |

705 | unsafe { cmath::acosf(self) } |

706 | } |

707 | |

708 | /// Computes the arctangent of a number. Return value is in radians in the |

709 | /// range [-pi/2, pi/2]; |

710 | /// |

711 | /// # Examples |

712 | /// |

713 | /// ``` |

714 | /// let f = 1.0f32; |

715 | /// |

716 | /// // atan(tan(1)) |

717 | /// let abs_difference = (f.tan().atan() - 1.0).abs(); |

718 | /// |

719 | /// assert!(abs_difference <= f32::EPSILON); |

720 | /// ``` |

721 | #[doc(alias = "arctan")] |

722 | #[rustc_allow_incoherent_impl] |

723 | #[must_use= "method returns a new number and does not mutate the original value"] |

724 | #[stable(feature = "rust1", since = "1.0.0")] |

725 | #[inline] |

726 | pub fn atan(self) -> f32 { |

727 | unsafe { cmath::atanf(self) } |

728 | } |

729 | |

730 | /// Computes the four quadrant arctangent of `self` (`y`) and `other` (`x`) in radians. |

731 | /// |

732 | /// * `x = 0`, `y = 0`: `0` |

733 | /// * `x >= 0`: `arctan(y/x)` -> `[-pi/2, pi/2]` |

734 | /// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]` |

735 | /// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)` |

736 | /// |

737 | /// # Examples |

738 | /// |

739 | /// ``` |

740 | /// // Positive angles measured counter-clockwise |

741 | /// // from positive x axis |

742 | /// // -pi/4 radians (45 deg clockwise) |

743 | /// let x1 = 3.0f32; |

744 | /// let y1 = -3.0f32; |

745 | /// |

746 | /// // 3pi/4 radians (135 deg counter-clockwise) |

747 | /// let x2 = -3.0f32; |

748 | /// let y2 = 3.0f32; |

749 | /// |

750 | /// let abs_difference_1 = (y1.atan2(x1) - (-std::f32::consts::FRAC_PI_4)).abs(); |

751 | /// let abs_difference_2 = (y2.atan2(x2) - (3.0 * std::f32::consts::FRAC_PI_4)).abs(); |

752 | /// |

753 | /// assert!(abs_difference_1 <= f32::EPSILON); |

754 | /// assert!(abs_difference_2 <= f32::EPSILON); |

755 | /// ``` |

756 | #[rustc_allow_incoherent_impl] |

757 | #[must_use= "method returns a new number and does not mutate the original value"] |

758 | #[stable(feature = "rust1", since = "1.0.0")] |

759 | #[inline] |

760 | pub fn atan2(self, other: f32) -> f32 { |

761 | unsafe { cmath::atan2f(self, other) } |

762 | } |

763 | |

764 | /// Simultaneously computes the sine and cosine of the number, `x`. Returns |

765 | /// `(sin(x), cos(x))`. |

766 | /// |

767 | /// # Examples |

768 | /// |

769 | /// ``` |

770 | /// let x = std::f32::consts::FRAC_PI_4; |

771 | /// let f = x.sin_cos(); |

772 | /// |

773 | /// let abs_difference_0 = (f.0 - x.sin()).abs(); |

774 | /// let abs_difference_1 = (f.1 - x.cos()).abs(); |

775 | /// |

776 | /// assert!(abs_difference_0 <= f32::EPSILON); |

777 | /// assert!(abs_difference_1 <= f32::EPSILON); |

778 | /// ``` |

779 | #[doc(alias = "sincos")] |

780 | #[rustc_allow_incoherent_impl] |

781 | #[stable(feature = "rust1", since = "1.0.0")] |

782 | #[inline] |

783 | pub fn sin_cos(self) -> (f32, f32) { |

784 | (self.sin(), self.cos()) |

785 | } |

786 | |

787 | /// Returns `e^(self) - 1` in a way that is accurate even if the |

788 | /// number is close to zero. |

789 | /// |

790 | /// # Examples |

791 | /// |

792 | /// ``` |

793 | /// let x = 1e-8_f32; |

794 | /// |

795 | /// // for very small x, e^x is approximately 1 + x + x^2 / 2 |

796 | /// let approx = x + x * x / 2.0; |

797 | /// let abs_difference = (x.exp_m1() - approx).abs(); |

798 | /// |

799 | /// assert!(abs_difference < 1e-10); |

800 | /// ``` |

801 | #[rustc_allow_incoherent_impl] |

802 | #[must_use= "method returns a new number and does not mutate the original value"] |

803 | #[stable(feature = "rust1", since = "1.0.0")] |

804 | #[inline] |

805 | pub fn exp_m1(self) -> f32 { |

806 | unsafe { cmath::expm1f(self) } |

807 | } |

808 | |

809 | /// Returns `ln(1+n)` (natural logarithm) more accurately than if |

810 | /// the operations were performed separately. |

811 | /// |

812 | /// # Examples |

813 | /// |

814 | /// ``` |

815 | /// let x = 1e-8_f32; |

816 | /// |

817 | /// // for very small x, ln(1 + x) is approximately x - x^2 / 2 |

818 | /// let approx = x - x * x / 2.0; |

819 | /// let abs_difference = (x.ln_1p() - approx).abs(); |

820 | /// |

821 | /// assert!(abs_difference < 1e-10); |

822 | /// ``` |

823 | #[doc(alias = "log1p")] |

824 | #[rustc_allow_incoherent_impl] |

825 | #[must_use= "method returns a new number and does not mutate the original value"] |

826 | #[stable(feature = "rust1", since = "1.0.0")] |

827 | #[inline] |

828 | pub fn ln_1p(self) -> f32 { |

829 | unsafe { cmath::log1pf(self) } |

830 | } |

831 | |

832 | /// Hyperbolic sine function. |

833 | /// |

834 | /// # Examples |

835 | /// |

836 | /// ``` |

837 | /// let e = std::f32::consts::E; |

838 | /// let x = 1.0f32; |

839 | /// |

840 | /// let f = x.sinh(); |

841 | /// // Solving sinh() at 1 gives `(e^2-1)/(2e)` |

842 | /// let g = ((e * e) - 1.0) / (2.0 * e); |

843 | /// let abs_difference = (f - g).abs(); |

844 | /// |

845 | /// assert!(abs_difference <= f32::EPSILON); |

846 | /// ``` |

847 | #[rustc_allow_incoherent_impl] |

848 | #[must_use= "method returns a new number and does not mutate the original value"] |

849 | #[stable(feature = "rust1", since = "1.0.0")] |

850 | #[inline] |

851 | pub fn sinh(self) -> f32 { |

852 | unsafe { cmath::sinhf(self) } |

853 | } |

854 | |

855 | /// Hyperbolic cosine function. |

856 | /// |

857 | /// # Examples |

858 | /// |

859 | /// ``` |

860 | /// let e = std::f32::consts::E; |

861 | /// let x = 1.0f32; |

862 | /// let f = x.cosh(); |

863 | /// // Solving cosh() at 1 gives this result |

864 | /// let g = ((e * e) + 1.0) / (2.0 * e); |

865 | /// let abs_difference = (f - g).abs(); |

866 | /// |

867 | /// // Same result |

868 | /// assert!(abs_difference <= f32::EPSILON); |

869 | /// ``` |

870 | #[rustc_allow_incoherent_impl] |

871 | #[must_use= "method returns a new number and does not mutate the original value"] |

872 | #[stable(feature = "rust1", since = "1.0.0")] |

873 | #[inline] |

874 | pub fn cosh(self) -> f32 { |

875 | unsafe { cmath::coshf(self) } |

876 | } |

877 | |

878 | /// Hyperbolic tangent function. |

879 | /// |

880 | /// # Examples |

881 | /// |

882 | /// ``` |

883 | /// let e = std::f32::consts::E; |

884 | /// let x = 1.0f32; |

885 | /// |

886 | /// let f = x.tanh(); |

887 | /// // Solving tanh() at 1 gives `(1 - e^(-2))/(1 + e^(-2))` |

888 | /// let g = (1.0 - e.powi(-2)) / (1.0 + e.powi(-2)); |

889 | /// let abs_difference = (f - g).abs(); |

890 | /// |

891 | /// assert!(abs_difference <= f32::EPSILON); |

892 | /// ``` |

893 | #[rustc_allow_incoherent_impl] |

894 | #[must_use= "method returns a new number and does not mutate the original value"] |

895 | #[stable(feature = "rust1", since = "1.0.0")] |

896 | #[inline] |

897 | pub fn tanh(self) -> f32 { |

898 | unsafe { cmath::tanhf(self) } |

899 | } |

900 | |

901 | /// Inverse hyperbolic sine function. |

902 | /// |

903 | /// # Examples |

904 | /// |

905 | /// ``` |

906 | /// let x = 1.0f32; |

907 | /// let f = x.sinh().asinh(); |

908 | /// |

909 | /// let abs_difference = (f - x).abs(); |

910 | /// |

911 | /// assert!(abs_difference <= f32::EPSILON); |

912 | /// ``` |

913 | #[doc(alias = "arcsinh")] |

914 | #[rustc_allow_incoherent_impl] |

915 | #[must_use= "method returns a new number and does not mutate the original value"] |

916 | #[stable(feature = "rust1", since = "1.0.0")] |

917 | #[inline] |

918 | pub fn asinh(self) -> f32 { |

919 | let ax = self.abs(); |

920 | let ix = 1.0 / ax; |

921 | (ax + (ax / (Self::hypot(1.0, ix) + ix))).ln_1p().copysign(self) |

922 | } |

923 | |

924 | /// Inverse hyperbolic cosine function. |

925 | /// |

926 | /// # Examples |

927 | /// |

928 | /// ``` |

929 | /// let x = 1.0f32; |

930 | /// let f = x.cosh().acosh(); |

931 | /// |

932 | /// let abs_difference = (f - x).abs(); |

933 | /// |

934 | /// assert!(abs_difference <= f32::EPSILON); |

935 | /// ``` |

936 | #[doc(alias = "arccosh")] |

937 | #[rustc_allow_incoherent_impl] |

938 | #[must_use= "method returns a new number and does not mutate the original value"] |

939 | #[stable(feature = "rust1", since = "1.0.0")] |

940 | #[inline] |

941 | pub fn acosh(self) -> f32 { |

942 | if self < 1.0 { |

943 | Self::NAN |

944 | } else { |

945 | (self + ((self - 1.0).sqrt() * (self + 1.0).sqrt())).ln() |

946 | } |

947 | } |

948 | |

949 | /// Inverse hyperbolic tangent function. |

950 | /// |

951 | /// # Examples |

952 | /// |

953 | /// ``` |

954 | /// let e = std::f32::consts::E; |

955 | /// let f = e.tanh().atanh(); |

956 | /// |

957 | /// let abs_difference = (f - e).abs(); |

958 | /// |

959 | /// assert!(abs_difference <= 1e-5); |

960 | /// ``` |

961 | #[doc(alias = "arctanh")] |

962 | #[rustc_allow_incoherent_impl] |

963 | #[must_use= "method returns a new number and does not mutate the original value"] |

964 | #[stable(feature = "rust1", since = "1.0.0")] |

965 | #[inline] |

966 | pub fn atanh(self) -> f32 { |

967 | 0.5 * ((2.0 * self) / (1.0 - self)).ln_1p() |

968 | } |

969 | |

970 | /// Gamma function. |

971 | /// |

972 | /// # Examples |

973 | /// |

974 | /// ``` |

975 | /// #![feature(float_gamma)] |

976 | /// let x = 5.0f32; |

977 | /// |

978 | /// let abs_difference = (x.gamma() - 24.0).abs(); |

979 | /// |

980 | /// assert!(abs_difference <= f32::EPSILON); |

981 | /// ``` |

982 | #[rustc_allow_incoherent_impl] |

983 | #[must_use= "method returns a new number and does not mutate the original value"] |

984 | #[unstable(feature = "float_gamma", issue = "99842")] |

985 | #[inline] |

986 | pub fn gamma(self) -> f32 { |

987 | unsafe { cmath::tgammaf(self) } |

988 | } |

989 | |

990 | /// Natural logarithm of the absolute value of the gamma function |

991 | /// |

992 | /// The integer part of the tuple indicates the sign of the gamma function. |

993 | /// |

994 | /// # Examples |

995 | /// |

996 | /// ``` |

997 | /// #![feature(float_gamma)] |

998 | /// let x = 2.0f32; |

999 | /// |

1000 | /// let abs_difference = (x.ln_gamma().0 - 0.0).abs(); |

1001 | /// |

1002 | /// assert!(abs_difference <= f32::EPSILON); |

1003 | /// ``` |

1004 | #[rustc_allow_incoherent_impl] |

1005 | #[must_use= "method returns a new number and does not mutate the original value"] |

1006 | #[unstable(feature = "float_gamma", issue = "99842")] |

1007 | #[inline] |

1008 | pub fn ln_gamma(self) -> (f32, i32) { |

1009 | let mut signgamp: i32 = 0; |

1010 | let x = unsafe { cmath::lgammaf_r(self, &mut signgamp) }; |

1011 | (x, signgamp) |

1012 | } |

1013 | } |

1014 |