src/libcore/array.rs

   1 //! Implementations of things like `Eq` for fixed-length arrays
   2 //! up to a certain length. Eventually we should able to generalize
   3 //! to all lengths.
   4 //!
   5 //! *[See also the array primitive type](../../std/primitive.array.html).*
   6
   7 #![stable(feature = "core_array", since = "1.36.0")]
   8
   9 use crate::borrow::{Borrow, BorrowMut};
  10 use crate::cmp::Ordering;
  11 use crate::convert::{Infallible, TryFrom};
  12 use crate::fmt;
  13 use crate::hash::{Hash, self};
  14 use crate::marker::Unsize;
  15 use crate::slice::{Iter, IterMut};
  16
  17 /// Utility trait implemented only on arrays of fixed size
  18 ///
  19 /// This trait can be used to implement other traits on fixed-size arrays
  20 /// without causing much metadata bloat.
  21 ///
  22 /// The trait is marked unsafe in order to restrict implementors to fixed-size
  23 /// arrays. User of this trait can assume that implementors have the exact
  24 /// layout in memory of a fixed size array (for example, for unsafe
  25 /// initialization).
  26 ///
  27 /// Note that the traits AsRef and AsMut provide similar methods for types that
  28 /// may not be fixed-size arrays. Implementors should prefer those traits
  29 /// instead.
  30 #[unstable(feature = "fixed_size_array", issue = "27778")]
  31 pub unsafe trait FixedSizeArray<T> {
  32     /// Converts the array to immutable slice
  33     #[unstable(feature = "fixed_size_array", issue = "27778")]
  34     fn as_slice(&self) -> &[T];
  35     /// Converts the array to mutable slice
  36     #[unstable(feature = "fixed_size_array", issue = "27778")]
  37     fn as_mut_slice(&mut self) -> &mut [T];
  38 }
  39
  40 #[unstable(feature = "fixed_size_array", issue = "27778")]
  41 unsafe impl<T, A: Unsize<[T]>> FixedSizeArray<T> for A {
  42     #[inline]
  43     fn as_slice(&self) -> &[T] {
  44         self
  45     }
  46     #[inline]
  47     fn as_mut_slice(&mut self) -> &mut [T] {
  48         self
  49     }
  50 }
  51
  52 /// The error type returned when a conversion from a slice to an array fails.
  53 #[stable(feature = "try_from", since = "1.34.0")]
  54 #[derive(Debug, Copy, Clone)]
  55 pub struct TryFromSliceError(());
  56
  57 #[stable(feature = "core_array", since = "1.36.0")]
  58 impl fmt::Display for TryFromSliceError {
  59     #[inline]
  60     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  61         fmt::Display::fmt(self.__description(), f)
  62     }
  63 }
  64
  65 impl TryFromSliceError {
  66     #[unstable(feature = "array_error_internals",
  67            reason = "available through Error trait and this method should not \
  68                      be exposed publicly",
  69            issue = "0")]
  70     #[inline]
  71     #[doc(hidden)]
  72     pub fn __description(&self) -> &str {
  73         "could not convert slice to array"
  74     }
  75 }
  76
  77 #[stable(feature = "try_from_slice_error", since = "1.36.0")]
  78 impl From<Infallible> for TryFromSliceError {
  79     fn from(x: Infallible) -> TryFromSliceError {
  80         match x {}
  81     }
  82 }
  83
  84 macro_rules! __impl_slice_eq1 {
  85     ($Lhs: ty, $Rhs: ty) => {
  86         __impl_slice_eq1! { $Lhs, $Rhs, Sized }
  87     };
  88     ($Lhs: ty, $Rhs: ty, $Bound: ident) => {
  89         #[stable(feature = "rust1", since = "1.0.0")]
  90         impl<'a, 'b, A: $Bound, B> PartialEq<$Rhs> for $Lhs where A: PartialEq<B> {
  91             #[inline]
  92             fn eq(&self, other: &$Rhs) -> bool { self[..] == other[..] }
  93             #[inline]
  94             fn ne(&self, other: &$Rhs) -> bool { self[..] != other[..] }
  95         }
  96     }
  97 }
  98
  99 macro_rules! __impl_slice_eq2 {
 100     ($Lhs: ty, $Rhs: ty) => {
 101         __impl_slice_eq2! { $Lhs, $Rhs, Sized }
 102     };
 103     ($Lhs: ty, $Rhs: ty, $Bound: ident) => {
 104         __impl_slice_eq1!($Lhs, $Rhs, $Bound);
 105
 106         #[stable(feature = "rust1", since = "1.0.0")]
 107         impl<'a, 'b, A: $Bound, B> PartialEq<$Lhs> for $Rhs where B: PartialEq<A> {
 108             #[inline]
 109             fn eq(&self, other: &$Lhs) -> bool { self[..] == other[..] }
 110             #[inline]
 111             fn ne(&self, other: &$Lhs) -> bool { self[..] != other[..] }
 112         }
 113     }
 114 }
 115
 116 // macro for implementing n-element array functions and operations
 117 macro_rules! array_impls {
 118     ($($N:expr)+) => {
 119         $(
 120             #[stable(feature = "rust1", since = "1.0.0")]
 121             impl<T> AsRef<[T]> for [T; $N] {
 122                 #[inline]
 123                 fn as_ref(&self) -> &[T] {
 124                     &self[..]
 125                 }
 126             }
 127
 128             #[stable(feature = "rust1", since = "1.0.0")]
 129             impl<T> AsMut<[T]> for [T; $N] {
 130                 #[inline]
 131                 fn as_mut(&mut self) -> &mut [T] {
 132                     &mut self[..]
 133                 }
 134             }
 135
 136             #[stable(feature = "array_borrow", since = "1.4.0")]
 137             impl<T> Borrow<[T]> for [T; $N] {
 138                 fn borrow(&self) -> &[T] {
 139                     self
 140                 }
 141             }
 142
 143             #[stable(feature = "array_borrow", since = "1.4.0")]
 144             impl<T> BorrowMut<[T]> for [T; $N] {
 145                 fn borrow_mut(&mut self) -> &mut [T] {
 146                     self
 147                 }
 148             }
 149
 150             #[stable(feature = "try_from", since = "1.34.0")]
 151             impl<T> TryFrom<&[T]> for [T; $N] where T: Copy {
 152                 type Error = TryFromSliceError;
 153
 154                 fn try_from(slice: &[T]) -> Result<[T; $N], TryFromSliceError> {
 155                     <&Self>::try_from(slice).map(|r| *r)
 156                 }
 157             }
 158
 159             #[stable(feature = "try_from", since = "1.34.0")]
 160             impl<'a, T> TryFrom<&'a [T]> for &'a [T; $N] {
 161                 type Error = TryFromSliceError;
 162
 163                 fn try_from(slice: &[T]) -> Result<&[T; $N], TryFromSliceError> {
 164                     if slice.len() == $N {
 165                         let ptr = slice.as_ptr() as *const [T; $N];
 166                         unsafe { Ok(&*ptr) }
 167                     } else {
 168                         Err(TryFromSliceError(()))
 169                     }
 170                 }
 171             }
 172
 173             #[stable(feature = "try_from", since = "1.34.0")]
 174             impl<'a, T> TryFrom<&'a mut [T]> for &'a mut [T; $N] {
 175                 type Error = TryFromSliceError;
 176
 177                 fn try_from(slice: &mut [T]) -> Result<&mut [T; $N], TryFromSliceError> {
 178                     if slice.len() == $N {
 179                         let ptr = slice.as_mut_ptr() as *mut [T; $N];
 180                         unsafe { Ok(&mut *ptr) }
 181                     } else {
 182                         Err(TryFromSliceError(()))
 183                     }
 184                 }
 185             }
 186
 187             #[stable(feature = "rust1", since = "1.0.0")]
 188             impl<T: Hash> Hash for [T; $N] {
 189                 fn hash<H: hash::Hasher>(&self, state: &mut H) {
 190                     Hash::hash(&self[..], state)
 191                 }
 192             }
 193
 194             #[stable(feature = "rust1", since = "1.0.0")]
 195             impl<T: fmt::Debug> fmt::Debug for [T; $N] {
 196                 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 197                     fmt::Debug::fmt(&&self[..], f)
 198                 }
 199             }
 200
 201             #[stable(feature = "rust1", since = "1.0.0")]
 202             impl<'a, T> IntoIterator for &'a [T; $N] {
 203                 type Item = &'a T;
 204                 type IntoIter = Iter<'a, T>;
 205
 206                 fn into_iter(self) -> Iter<'a, T> {
 207                     self.iter()
 208                 }
 209             }
 210
 211             #[stable(feature = "rust1", since = "1.0.0")]
 212             impl<'a, T> IntoIterator for &'a mut [T; $N] {
 213                 type Item = &'a mut T;
 214                 type IntoIter = IterMut<'a, T>;
 215
 216                 fn into_iter(self) -> IterMut<'a, T> {
 217                     self.iter_mut()
 218                 }
 219             }
 220
 221             // NOTE: some less important impls are omitted to reduce code bloat
 222             __impl_slice_eq1! { [A; $N], [B; $N] }
 223             __impl_slice_eq2! { [A; $N], [B] }
 224             __impl_slice_eq2! { [A; $N], &'b [B] }
 225             __impl_slice_eq2! { [A; $N], &'b mut [B] }
 226             // __impl_slice_eq2! { [A; $N], &'b [B; $N] }
 227             // __impl_slice_eq2! { [A; $N], &'b mut [B; $N] }
 228
 229             #[stable(feature = "rust1", since = "1.0.0")]
 230             impl<T:Eq> Eq for [T; $N] { }
 231
 232             #[stable(feature = "rust1", since = "1.0.0")]
 233             impl<T:PartialOrd> PartialOrd for [T; $N] {
 234                 #[inline]
 235                 fn partial_cmp(&self, other: &[T; $N]) -> Option<Ordering> {
 236                     PartialOrd::partial_cmp(&&self[..], &&other[..])
 237                 }
 238                 #[inline]
 239                 fn lt(&self, other: &[T; $N]) -> bool {
 240                     PartialOrd::lt(&&self[..], &&other[..])
 241                 }
 242                 #[inline]
 243                 fn le(&self, other: &[T; $N]) -> bool {
 244                     PartialOrd::le(&&self[..], &&other[..])
 245                 }
 246                 #[inline]
 247                 fn ge(&self, other: &[T; $N]) -> bool {
 248                     PartialOrd::ge(&&self[..], &&other[..])
 249                 }
 250                 #[inline]
 251                 fn gt(&self, other: &[T; $N]) -> bool {
 252                     PartialOrd::gt(&&self[..], &&other[..])
 253                 }
 254             }
 255
 256             #[stable(feature = "rust1", since = "1.0.0")]
 257             impl<T:Ord> Ord for [T; $N] {
 258                 #[inline]
 259                 fn cmp(&self, other: &[T; $N]) -> Ordering {
 260                     Ord::cmp(&&self[..], &&other[..])
 261                 }
 262             }
 263         )+
 264     }
 265 }
 266
 267 array_impls! {
 268      0  1  2  3  4  5  6  7  8  9
 269     10 11 12 13 14 15 16 17 18 19
 270     20 21 22 23 24 25 26 27 28 29
 271     30 31 32
 272 }
 273
 274 // The Default impls cannot be generated using the array_impls! macro because
 275 // they require array literals.
 276
 277 macro_rules! array_impl_default {
 278     {$n:expr, $t:ident $($ts:ident)*} => {
 279         #[stable(since = "1.4.0", feature = "array_default")]
 280         impl<T> Default for [T; $n] where T: Default {
 281             fn default() -> [T; $n] {
 282                 [$t::default(), $($ts::default()),*]
 283             }
 284         }
 285         array_impl_default!{($n - 1), $($ts)*}
 286     };
 287     {$n:expr,} => {
 288         #[stable(since = "1.4.0", feature = "array_default")]
 289         impl<T> Default for [T; $n] {
 290             fn default() -> [T; $n] { [] }
 291         }
 292     };
 293 }
 294
 295 array_impl_default!{32, T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T}