codegen: tweak/extend shift comments · rust-lang/rust@17bd43c (original) (raw)

File tree

2 files changed

lines changed

2 files changed

lines changed

Original file line number Diff line number Diff line change
@@ -293,12 +293,13 @@ pub fn coerce_unsized_into<'a, 'tcx, Bx: BuilderMethods<'a, 'tcx>>(
293 293 }
294 294 }
295 295
296 -/// Returns `rhs` sufficiently masked, truncated, and/or extended so that
297 -/// it can be used to shift `lhs`.
296 +/// Returns `rhs` sufficiently masked, truncated, and/or extended so that it can be used to shift
297 +/// `lhs`: it has the same size as `lhs`, and the value, when interpreted unsigned (no matter its
298 +/// type), will not exceed the size of `lhs`.
298 299 ///
299 -/// Shifts in MIR are all allowed to have mismatched LHS & RHS types.
300 +/// Shifts in MIR are all allowed to have mismatched LHS & RHS types, and signed RHS.
300 301 /// The shift methods in `BuilderMethods`, however, are fully homogeneous
301 -/// (both parameters and the return type are all the same type).
302 +/// (both parameters and the return type are all the same size) and assume an unsigned RHS.
302 303 ///
303 304 /// If `is_unchecked` is false, this masks the RHS to ensure it stays in-bounds,
304 305 /// as the `BuilderMethods` shifts are UB for out-of-bounds shift amounts.
Original file line number Diff line number Diff line change
@@ -110,8 +110,16 @@ pub trait BuilderMethods<'a, 'tcx>:
110 110 fn frem(&mut self, lhs: Self::Value, rhs: Self::Value) -> Self::Value;
111 111 fn frem_fast(&mut self, lhs: Self::Value, rhs: Self::Value) -> Self::Value;
112 112 fn frem_algebraic(&mut self, lhs: Self::Value, rhs: Self::Value) -> Self::Value;
113 +/// Generate a left-shift. Both operands must have the same size. The right operand must be
114 + /// interpreted as unsigned and can be assumed to be less than the size of the left operand.
113 115 fn shl(&mut self, lhs: Self::Value, rhs: Self::Value) -> Self::Value;
116 +/// Generate a logical right-shift. Both operands must have the same size. The right operand
117 + /// must be interpreted as unsigned and can be assumed to be less than the size of the left
118 + /// operand.
114 119 fn lshr(&mut self, lhs: Self::Value, rhs: Self::Value) -> Self::Value;
120 +/// Generate an arithmetic right-shift. Both operands must have the same size. The right operand
121 + /// must be interpreted as unsigned and can be assumed to be less than the size of the left
122 + /// operand.
115 123 fn ashr(&mut self, lhs: Self::Value, rhs: Self::Value) -> Self::Value;
116 124 fn unchecked_sadd(&mut self, lhs: Self::Value, rhs: Self::Value) -> Self::Value;
117 125 fn unchecked_uadd(&mut self, lhs: Self::Value, rhs: Self::Value) -> Self::Value;