Rollup merge of rust-lang#78347 - Rustin-Liu:rustin-patch-doc, r=kennytm

Add lexicographical comparison doc

close rust-lang#72255

Author: JohnTitor

library/alloc/src/vec.rs

@@ -2566,7 +2566,7 @@ __impl_slice_eq1! { [const N: usize] Vec<A>, &[B; N], #[stable(feature = "rust1"
 //__impl_slice_eq1! { [const N: usize] Cow<'a, [A]>, &[B; N], }
 //__impl_slice_eq1! { [const N: usize] Cow<'a, [A]>, &mut [B; N], }
 
-/// Implements comparison of vectors, lexicographically.
+/// Implements comparison of vectors, [lexicographically](core::cmp::Ord#lexicographical-comparison).
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: PartialOrd> PartialOrd for Vec<T> {
     #[inline]
@@ -2578,7 +2578,7 @@ impl<T: PartialOrd> PartialOrd for Vec<T> {
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Eq> Eq for Vec<T> {}
 
-/// Implements ordering of vectors, lexicographically.
+/// Implements ordering of vectors, [lexicographically](core::cmp::Ord#lexicographical-comparison).
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Ord> Ord for Vec<T> {
     #[inline]

library/core/src/array/mod.rs

@@ -344,7 +344,7 @@ impl<T: PartialOrd, const N: usize> PartialOrd for [T; N] {
     }
 }
 
-/// Implements comparison of arrays lexicographically.
+/// Implements comparison of arrays [lexicographically](Ord#lexicographical-comparison).
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Ord, const N: usize> Ord for [T; N] {
     #[inline]

library/core/src/cmp.rs

@@ -506,9 +506,19 @@ impl<T: Ord> Ord for Reverse<T> {
 /// ## Derivable
 ///
 /// This trait can be used with `#[derive]`. When `derive`d on structs, it will produce a
-/// lexicographic ordering based on the top-to-bottom declaration order of the struct's members.
+/// [lexicographic](https://en.wikipedia.org/wiki/Lexicographic_order) ordering based on the top-to-bottom declaration order of the struct's members.
 /// When `derive`d on enums, variants are ordered by their top-to-bottom discriminant order.
 ///
+/// ## Lexicographical comparison
+///
+/// Lexicographical comparison is an operation with the following properties:
+///  - Two sequences are compared element by element.
+///  - The first mismatching element defines which sequence is lexicographically less or greater than the other.
+///  - If one sequence is a prefix of another, the shorter sequence is lexicographically less than the other.
+///  - If two sequence have equivalent elements and are of the same length, then the sequences are lexicographically equal.
+///  - An empty sequence is lexicographically less than any non-empty sequence.
+///  - Two empty sequences are lexicographically equal.
+///
 /// ## How can I implement `Ord`?
 ///
 /// `Ord` requires that the type also be [`PartialOrd`] and [`Eq`] (which requires [`PartialEq`]).

library/core/src/iter/traits/iterator.rs

@@ -2851,7 +2851,7 @@ pub trait Iterator {
         Product::product(self)
     }
 
-    /// Lexicographically compares the elements of this [`Iterator`] with those
+    /// [Lexicographically](Ord#lexicographical-comparison) compares the elements of this [`Iterator`] with those
     /// of another.
     ///
     /// # Examples
@@ -2873,7 +2873,7 @@ pub trait Iterator {
         self.cmp_by(other, |x, y| x.cmp(&y))
     }
 
-    /// Lexicographically compares the elements of this [`Iterator`] with those
+    /// [Lexicographically](Ord#lexicographical-comparison) compares the elements of this [`Iterator`] with those
     /// of another with respect to the specified comparison function.
     ///
     /// # Examples
@@ -2925,7 +2925,7 @@ pub trait Iterator {
         }
     }
 
-    /// Lexicographically compares the elements of this [`Iterator`] with those
+    /// [Lexicographically](Ord#lexicographical-comparison) compares the elements of this [`Iterator`] with those
     /// of another.
     ///
     /// # Examples
@@ -2949,7 +2949,7 @@ pub trait Iterator {
         self.partial_cmp_by(other, |x, y| x.partial_cmp(&y))
     }
 
-    /// Lexicographically compares the elements of this [`Iterator`] with those
+    /// [Lexicographically](Ord#lexicographical-comparison) compares the elements of this [`Iterator`] with those
     /// of another with respect to the specified comparison function.
     ///
     /// # Examples
@@ -3089,7 +3089,7 @@ pub trait Iterator {
         !self.eq(other)
     }
 
-    /// Determines if the elements of this [`Iterator`] are lexicographically
+    /// Determines if the elements of this [`Iterator`] are [lexicographically](Ord#lexicographical-comparison)
     /// less than those of another.
     ///
     /// # Examples
@@ -3110,7 +3110,7 @@ pub trait Iterator {
         self.partial_cmp(other) == Some(Ordering::Less)
     }
 
-    /// Determines if the elements of this [`Iterator`] are lexicographically
+    /// Determines if the elements of this [`Iterator`] are [lexicographically](Ord#lexicographical-comparison)
     /// less or equal to those of another.
     ///
     /// # Examples
@@ -3131,7 +3131,7 @@ pub trait Iterator {
         matches!(self.partial_cmp(other), Some(Ordering::Less | Ordering::Equal))
     }
 
-    /// Determines if the elements of this [`Iterator`] are lexicographically
+    /// Determines if the elements of this [`Iterator`] are [lexicographically](Ord#lexicographical-comparison)
     /// greater than those of another.
     ///
     /// # Examples
@@ -3152,7 +3152,7 @@ pub trait Iterator {
         self.partial_cmp(other) == Some(Ordering::Greater)
     }
 
-    /// Determines if the elements of this [`Iterator`] are lexicographically
+    /// Determines if the elements of this [`Iterator`] are [lexicographically](Ord#lexicographical-comparison)
     /// greater than or equal to those of another.
     ///
     /// # Examples

library/core/src/slice/cmp.rs

@@ -35,15 +35,15 @@ where
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Eq> Eq for [T] {}
 
-/// Implements comparison of vectors lexicographically.
+/// Implements comparison of vectors [lexicographically](Ord#lexicographical-comparison).
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Ord> Ord for [T] {
     fn cmp(&self, other: &[T]) -> Ordering {
         SliceOrd::compare(self, other)
     }
 }
 
-/// Implements comparison of vectors lexicographically.
+/// Implements comparison of vectors [lexicographically](Ord#lexicographical-comparison).
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: PartialOrd> PartialOrd for [T] {
     fn partial_cmp(&self, other: &[T]) -> Option<Ordering> {

library/core/src/str/traits.rs

@@ -9,7 +9,7 @@ use super::ParseBoolError;
 
 /// Implements ordering of strings.
 ///
-/// Strings are ordered  lexicographically by their byte values. This orders Unicode code
+/// Strings are ordered  [lexicographically](Ord#lexicographical-comparison) by their byte values. This orders Unicode code
 /// points based on their positions in the code charts. This is not necessarily the same as
 /// "alphabetical" order, which varies by language and locale. Sorting strings according to
 /// culturally-accepted standards requires locale-specific data that is outside the scope of
@@ -39,7 +39,7 @@ impl Eq for str {}
 
 /// Implements comparison operations on strings.
 ///
-/// Strings are compared lexicographically by their byte values. This compares Unicode code
+/// Strings are compared [lexicographically](Ord#lexicographical-comparison) by their byte values. This compares Unicode code
 /// points based on their positions in the code charts. This is not necessarily the same as
 /// "alphabetical" order, which varies by language and locale. Comparing strings according to
 /// culturally-accepted standards requires locale-specific data that is outside the scope of