Add the emptiness condition to the docs; add a PartialOrd example with NAN

diff --git a/src/libcore/ops/range.rs b/src/libcore/ops/range.rs
index 4e4d33475237033d1ebdbcb5d5ca4c42173c69fa..8a45444f1ab0c617322cc57010e36b211e0acb5f 100644 (file)
--- a/src/libcore/ops/range.rs
+++ b/src/libcore/ops/range.rs
@@ -60,7 +60,7 @@ fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
 /// (`start..end`).
 ///
 /// The `Range` `start..end` contains all values with `x >= start` and
-/// `x < end`.
+/// `x < end`.  It is empty unless `start < end`.
 ///
 /// # Examples
 ///
@@ -124,6 +124,17 @@ pub fn contains(&self, item: Idx) -> bool {
     /// assert!( (3..3).is_empty());
     /// assert!( (3..2).is_empty());
     /// ```
+    ///
+    /// The range is empty if either side is incomparable:
+    ///
+    /// ```
+    /// #![feature(range_is_empty,inclusive_range_syntax)]
+    ///
+    /// use std::f32::NAN;
+    /// assert!(!(3.0..5.0).is_empty());
+    /// assert!( (3.0..NAN).is_empty());
+    /// assert!( (NAN..5.0).is_empty());
+    /// ```
     #[unstable(feature = "range_is_empty", reason = "recently added", issue = "48111")]
     pub fn is_empty(&self) -> bool {
         !(self.start < self.end)
@@ -260,7 +271,7 @@ pub fn contains(&self, item: Idx) -> bool {
 /// An range bounded inclusively below and above (`start..=end`).
 ///
 /// The `RangeInclusive` `start..=end` contains all values with `x >= start`
-/// and `x <= end`.
+/// and `x <= end`.  It is empty unless `start <= end`.
 ///
 /// This iterator is [fused], but the specific values of `start` and `end` after
 /// iteration has finished are **unspecified** other than that [`.is_empty()`]
@@ -337,6 +348,17 @@ pub fn contains(&self, item: Idx) -> bool {
     /// assert!( (3..=2).is_empty());
     /// ```
     ///
+    /// The range is empty if either side is incomparable:
+    ///
+    /// ```
+    /// #![feature(range_is_empty,inclusive_range_syntax)]
+    ///
+    /// use std::f32::NAN;
+    /// assert!(!(3.0..=5.0).is_empty());
+    /// assert!( (3.0..=NAN).is_empty());
+    /// assert!( (NAN..=5.0).is_empty());
+    /// ```
+    ///
     /// This method returns `true` after iteration has finished:
     ///
     /// ```