Add Ord::clamp_min and clamp_max · rust-lang/rust@af5b798 (original) (raw)

5 files changed

lines changed

Original file line number Diff line number Diff line change
@@ -1096,6 +1096,54 @@ pub const trait Ord: [const] Eq + [const] PartialOrd + PointeeSized {
1096 1096 self
1097 1097 }
1098 1098 }
1099 +
1100 +/// Restricts a value to a maximum bound.
1101 + ///
1102 + /// Returns `max` if `self` is greater than `max`, otherwise returns `self`.
1103 + ///
1104 + /// This is identical to `min`, but is easier to read when using method call syntax.
1105 + ///
1106 + /// # Examples
1107 + ///
1108 + /// ```
1109 + /// #![feature(clamp_min_max)]
1110 + /// assert_eq!(12.clamp_max(10), 10);
1111 + /// assert_eq!(4.clamp_max(7), 4);
1112 + /// let s = "hello";
1113 + /// assert_eq!(&s[..32.clamp_max(s.len())], s);
1114 + /// ```
1115 + #[must_use]
1116 +#[inline]
1117 +#[unstable(feature = "clamp_min_max", issue = "147781")]
1118 +fn clamp_max(self, min: Self) -> Self
1119 +where
1120 +Self: Sized + [const] Destruct,
1121 +{
1122 +self.min(min)
1123 +}
1124 +
1125 +/// Restricts a value to a minimum bound.
1126 + ///
1127 + /// Returns `min` if `self` is less than `min`, otherwise returns `self`.
1128 + ///
1129 + /// This is identical to `max`, but is easier to read when using method call syntax.
1130 + ///
1131 + /// # Examples
1132 + ///
1133 + /// ```
1134 + /// #![feature(clamp_min_max)]
1135 + /// assert_eq!((-3).clamp_min(0), 0);
1136 + /// assert_eq!(4.clamp_min(0), 4);
1137 + /// ```
1138 + #[must_use]
1139 +#[inline]
1140 +#[unstable(feature = "clamp_min_max", issue = "147781")]
1141 +fn clamp_min(self, min: Self) -> Self
1142 +where
1143 +Self: Sized + [const] Destruct,
1144 +{
1145 +self.max(min)
1146 +}
1099 1147 }
1100 1148
1101 1149 /// Derive macro generating an impl of the trait [`Ord`].
Original file line number Diff line number Diff line change
@@ -1276,6 +1276,54 @@ impl f128 {
1276 1276 self
1277 1277 }
1278 1278
1279 +/// Restrict a value to a maximum bound.
1280 + ///
1281 + /// Returns `max` if `self` is greater than `max`. Otherwise this returns `self`. If either `self` or `max` is NaN, the other is returned.
1282 + ///
1283 + /// This is identical to [`f128::min`], but is easier to read when using method call syntax.
1284 + ///
1285 + /// # Examples
1286 + ///
1287 + /// ```
1288 + /// #![feature(f128, clamp_min_max)]
1289 + /// assert_eq!((3.0f128).clamp_max(1.0), 1.0);
1290 + /// assert_eq!((0.0f128).clamp_max(1.0), 0.0);
1291 + /// assert_eq!((f128::NAN).clamp_max(1.0), 1.0);
1292 + /// assert_eq!((0.0f128).clamp_max(f128::NAN), 0.0);
1293 + /// ```
1294 + #[inline]
1295 +#[unstable(feature = "f128", issue = "116909")]
1296 +// #[unstable(feature = "clamp_min_max", issue = "147781")]
1297 +#[rustc_const_unstable(feature = "f128", issue = "116909")]
1298 +#[must_use = "method returns a new number and does not mutate the original value"]
1299 +pub const fn clamp_max(self, max: f128) -> f128 {
1300 +self.min(max)
1301 +}
1302 +
1303 +/// Restrict a value to a minimum bound.
1304 + ///
1305 + /// Returns `min` if `self` is less than `min`. Otherwise this returns `self`. If either `self` or `min` is NaN, the other is returned.
1306 + ///
1307 + /// This is identical to [`f128::max`], but is easier to read when using method call syntax.
1308 + ///
1309 + /// # Examples
1310 + ///
1311 + /// ```
1312 + /// #![feature(f128, clamp_min_max)]
1313 + /// assert_eq!((-3.0f128).clamp_min(-2.0), -2.0);
1314 + /// assert_eq!((0.0f128).clamp_min(-2.0), 0.0);
1315 + /// assert_eq!((f128::NAN).clamp_min(-2.0), -2.0);
1316 + /// assert_eq!((0.0f128).clamp_min(f128::NAN), 0.0);
1317 + /// ```
1318 + #[inline]
1319 +#[unstable(feature = "f128", issue = "116909")]
1320 +// #[unstable(feature = "clamp_min_max", issue = "147781")]
1321 +#[rustc_const_unstable(feature = "f128", issue = "116909")]
1322 +#[must_use = "method returns a new number and does not mutate the original value"]
1323 +pub const fn clamp_min(self, min: f128) -> f128 {
1324 +self.max(min)
1325 +}
1326 +
1279 1327 /// Computes the absolute value of `self`.
1280 1328 ///
1281 1329 /// This function always returns the precise result.
Original file line number Diff line number Diff line change
@@ -1254,6 +1254,54 @@ impl f16 {
1254 1254 self
1255 1255 }
1256 1256
1257 +/// Restrict a value to a maximum bound.
1258 + ///
1259 + /// Returns `max` if `self` is greater than `max`. Otherwise this returns `self`. If either `self` or `max` is NaN, the other is returned.
1260 + ///
1261 + /// This is identical to [`f16::min`], but is easier to read when using method call syntax.
1262 + ///
1263 + /// # Examples
1264 + ///
1265 + /// ```
1266 + /// #![feature(f16, clamp_min_max)]
1267 + /// assert_eq!((3.0f16).clamp_max(1.0), 1.0);
1268 + /// assert_eq!((0.0f16).clamp_max(1.0), 0.0);
1269 + /// assert_eq!((f16::NAN).clamp_max(1.0), 1.0);
1270 + /// assert_eq!((0.0f16).clamp_max(f16::NAN), 0.0);
1271 + /// ```
1272 + #[inline]
1273 +#[unstable(feature = "f16", issue = "116909")]
1274 +// #[unstable(feature = "clamp_min_max", issue = "147781")]
1275 +#[rustc_const_unstable(feature = "f16", issue = "116909")]
1276 +#[must_use = "method returns a new number and does not mutate the original value"]
1277 +pub const fn clamp_max(self, max: f16) -> f16 {
1278 +self.min(max)
1279 +}
1280 +
1281 +/// Restrict a value to a minimum bound.
1282 + ///
1283 + /// Returns `min` if `self` is less than `min`. Otherwise this returns `self`. If either `self` or `min` is NaN, the other is returned.
1284 + ///
1285 + /// This is identical to [`f16::max`], but is easier to read when using method call syntax.
1286 + ///
1287 + /// # Examples
1288 + ///
1289 + /// ```
1290 + /// #![feature(f16, clamp_min_max)]
1291 + /// assert_eq!((-3.0f16).clamp_min(-2.0), -2.0);
1292 + /// assert_eq!((0.0f16).clamp_min(-2.0), 0.0);
1293 + /// assert_eq!((f16::NAN).clamp_min(-2.0), -2.0);
1294 + /// assert_eq!((0.0f16).clamp_min(f16::NAN), 0.0);
1295 + /// ```
1296 + #[inline]
1297 +#[unstable(feature = "f16", issue = "116909")]
1298 +// #[unstable(feature = "clamp_min_max", issue = "147781")]
1299 +#[rustc_const_unstable(feature = "f16", issue = "116909")]
1300 +#[must_use = "method returns a new number and does not mutate the original value"]
1301 +pub const fn clamp_min(self, min: f16) -> f16 {
1302 +self.max(min)
1303 +}
1304 +
1257 1305 /// Computes the absolute value of `self`.
1258 1306 ///
1259 1307 /// This function always returns the precise result.
Original file line number Diff line number Diff line change
@@ -1431,6 +1431,50 @@ impl f32 {
1431 1431 self
1432 1432 }
1433 1433
1434 +/// Restrict a value to a maximum bound.
1435 + ///
1436 + /// Returns `max` if `self` is greater than `max`. Otherwise this returns `self`. If either `self` or `max` is NaN, the other is returned.
1437 + ///
1438 + /// This is identical to [`f32::min`], but is easier to read when using method call syntax.
1439 + ///
1440 + /// # Examples
1441 + ///
1442 + /// ```
1443 + /// #![feature(clamp_min_max)]
1444 + /// assert_eq!((3.0f32).clamp_max(1.0), 1.0);
1445 + /// assert_eq!((0.0f32).clamp_max(1.0), 0.0);
1446 + /// assert_eq!((f32::NAN).clamp_max(1.0), 1.0);
1447 + /// assert_eq!((0.0f32).clamp_max(f32::NAN), 0.0);
1448 + /// ```
1449 + #[must_use = "method returns a new number and does not mutate the original value"]
1450 +#[unstable(feature = "clamp_min_max", issue = "147781")]
1451 +#[inline]
1452 +pub const fn clamp_max(self, max: f32) -> f32 {
1453 +self.min(max)
1454 +}
1455 +
1456 +/// Restrict a value to a minimum bound.
1457 + ///
1458 + /// Returns `min` if `self` is less than `min`. Otherwise this returns `self`. If either `self` or `min` is NaN, the other is returned.
1459 + ///
1460 + /// This is identical to [`f32::max`], but is easier to read when using method call syntax.
1461 + ///
1462 + /// # Examples
1463 + ///
1464 + /// ```
1465 + /// #![feature(clamp_min_max)]
1466 + /// assert_eq!((-3.0f32).clamp_min(-2.0), -2.0);
1467 + /// assert_eq!((0.0f32).clamp_min(-2.0), 0.0);
1468 + /// assert_eq!((f32::NAN).clamp_min(-2.0), -2.0);
1469 + /// assert_eq!((0.0f32).clamp_min(f32::NAN), 0.0);
1470 + /// ```
1471 + #[must_use = "method returns a new number and does not mutate the original value"]
1472 +#[unstable(feature = "clamp_min_max", issue = "147781")]
1473 +#[inline]
1474 +pub const fn clamp_min(self, min: f32) -> f32 {
1475 +self.max(min)
1476 +}
1477 +
1434 1478 /// Computes the absolute value of `self`.
1435 1479 ///
1436 1480 /// This function always returns the precise result.
Original file line number Diff line number Diff line change
@@ -1429,6 +1429,50 @@ impl f64 {
1429 1429 self
1430 1430 }
1431 1431
1432 +/// Restrict a value to a maximum bound.
1433 + ///
1434 + /// Returns `max` if `self` is greater than `max`. Otherwise this returns `self`. If either `self` or `max` is NaN, the other is returned.
1435 + ///
1436 + /// This is identical to [`f64::min`], but is easier to read when using method call syntax.
1437 + ///
1438 + /// # Examples
1439 + ///
1440 + /// ```
1441 + /// #![feature(clamp_min_max)]
1442 + /// assert_eq!((3.0f64).clamp_max(1.0), 1.0);
1443 + /// assert_eq!((0.0f64).clamp_max(1.0), 0.0);
1444 + /// assert_eq!((f64::NAN).clamp_max(1.0), 1.0);
1445 + /// assert_eq!((0.0f64).clamp_max(f64::NAN), 0.0);
1446 + /// ```
1447 + #[must_use = "method returns a new number and does not mutate the original value"]
1448 +#[unstable(feature = "clamp_min_max", issue = "147781")]
1449 +#[inline]
1450 +pub const fn clamp_max(self, max: f64) -> f64 {
1451 +self.min(max)
1452 +}
1453 +
1454 +/// Restrict a value to a minimum bound.
1455 + ///
1456 + /// Returns `min` if `self` is less than `min`. Otherwise this returns `self`. If either `self` or `min` is NaN, the other is returned.
1457 + ///
1458 + /// This is identical to [`f64::max`], but is easier to read when using method call syntax.
1459 + ///
1460 + /// # Examples
1461 + ///
1462 + /// ```
1463 + /// #![feature(clamp_min_max)]
1464 + /// assert_eq!((-3.0f64).clamp_min(-2.0), -2.0);
1465 + /// assert_eq!((0.0f64).clamp_min(-2.0), 0.0);
1466 + /// assert_eq!((f64::NAN).clamp_min(-2.0), -2.0);
1467 + /// assert_eq!((0.0f64).clamp_min(f64::NAN), 0.0);
1468 + /// ```
1469 + #[must_use = "method returns a new number and does not mutate the original value"]
1470 +#[unstable(feature = "clamp_min_max", issue = "147781")]
1471 +#[inline]
1472 +pub const fn clamp_min(self, min: f64) -> f64 {
1473 +self.max(min)
1474 +}
1475 +
1432 1476 /// Computes the absolute value of `self`.
1433 1477 ///
1434 1478 /// This function always returns the precise result.