add assert_{bits,ptr}; document which methods we hope to get rid of

Author: RalfJung

src/librustc/mir/interpret/value.rs

@@ -339,6 +339,10 @@ impl<'tcx, Tag> Scalar<Tag> {
         Scalar::Raw { data: f.to_bits(), size: 8 }
     }
 
+    /// This is very rarely the method you want!  You should dispatch on the type
+    /// and use `force_bits`/`assert_bits`/`force_ptr`/`assert_ptr`.
+    /// This method only exists for the benefit of low-level memory operations
+    /// as well as the implementation of the `force_*` methods.
     #[inline]
     pub fn to_bits_or_ptr(
         self,
@@ -359,6 +363,7 @@ impl<'tcx, Tag> Scalar<Tag> {
         }
     }
 
+    /// Do not call this method!  Use either `assert_bits` or `force_bits`.
     #[inline]
     pub fn to_bits(self, target_size: Size) -> InterpResult<'tcx, u128> {
         match self {
@@ -372,6 +377,12 @@ impl<'tcx, Tag> Scalar<Tag> {
         }
     }
 
+    #[inline(always)]
+    pub fn assert_bits(self, target_size: Size) -> u128 {
+        self.to_bits(target_size).expect("Expected Raw bits but got a Pointer")
+    }
+
+    /// Do not call this method!  Use either `assert_ptr` or `force_ptr`.
     #[inline]
     pub fn to_ptr(self) -> InterpResult<'tcx, Pointer<Tag>> {
         match self {
@@ -381,6 +392,12 @@ impl<'tcx, Tag> Scalar<Tag> {
         }
     }
 
+    #[inline(always)]
+    pub fn assert_ptr(self) -> Pointer<Tag> {
+        self.to_ptr().expect("Expected a Pointer but got Raw bits")
+    }
+
+    /// Do not call this method!  Dispatch based on the type instead.
     #[inline]
     pub fn is_bits(self) -> bool {
         match self {
@@ -389,6 +406,7 @@ impl<'tcx, Tag> Scalar<Tag> {
         }
     }
 
+    /// Do not call this method!  Dispatch based on the type instead.
     #[inline]
     pub fn is_ptr(self) -> bool {
         match self {
@@ -536,11 +554,13 @@ impl<'tcx, Tag> ScalarMaybeUndef<Tag> {
         }
     }
 
+    /// Do not call this method!  Use either `assert_ptr` or `force_ptr`.
     #[inline(always)]
     pub fn to_ptr(self) -> InterpResult<'tcx, Pointer<Tag>> {
         self.not_undef()?.to_ptr()
     }
 
+    /// Do not call this method!  Use either `assert_bits` or `force_bits`.
     #[inline(always)]
     pub fn to_bits(self, target_size: Size) -> InterpResult<'tcx, u128> {
         self.not_undef()?.to_bits(target_size)