From a99f70b1e424595dbdcbad4a415f549a6d6686bc Mon Sep 17 00:00:00 2001
From: Corey Farwell <coreyf@rwell.org>
Date: Sun, 11 Dec 2016 13:36:03 -0800
Subject: [PATCH] Clarify zero-value behavior of `ctlz`/`cttz` intrinsics.

Fixes https://github.com/rust-lang/rust/issues/34381.
---
 src/libcore/intrinsics.rs | 52 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 50 insertions(+), 2 deletions(-)

diff --git a/src/libcore/intrinsics.rs b/src/libcore/intrinsics.rs
index 3726eee9a93..31a0cc68841 100644
--- a/src/libcore/intrinsics.rs
+++ b/src/libcore/intrinsics.rs
@@ -1156,10 +1156,58 @@ pub fn volatile_copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T,
     /// Returns the number of bits set in an integer type `T`
     pub fn ctpop<T>(x: T) -> T;
 
-    /// Returns the number of leading bits unset in an integer type `T`
+    /// Returns the number of leading unset bits (zeroes) in an integer type `T`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(core_intrinsics)]
+    ///
+    /// use std::intrinsics::ctlz;
+    ///
+    /// let x = 0b0001_1100_u8;
+    /// let num_leading = unsafe { ctlz(x) };
+    /// assert_eq!(num_leading, 3);
+    /// ```
+    ///
+    /// An `x` with value `0` will return the bit width of `T`.
+    ///
+    /// ```
+    /// #![feature(core_intrinsics)]
+    ///
+    /// use std::intrinsics::ctlz;
+    ///
+    /// let x = 0u16;
+    /// let num_leading = unsafe { ctlz(x) };
+    /// assert_eq!(num_leading, 16);
+    /// ```
     pub fn ctlz<T>(x: T) -> T;
 
-    /// Returns the number of trailing bits unset in an integer type `T`
+    /// Returns the number of trailing unset bits (zeroes) in an integer type `T`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(core_intrinsics)]
+    ///
+    /// use std::intrinsics::cttz;
+    ///
+    /// let x = 0b0011_1000_u8;
+    /// let num_trailing = unsafe { cttz(x) };
+    /// assert_eq!(num_trailing, 3);
+    /// ```
+    ///
+    /// An `x` with value `0` will return the bit width of `T`:
+    ///
+    /// ```
+    /// #![feature(core_intrinsics)]
+    ///
+    /// use std::intrinsics::cttz;
+    ///
+    /// let x = 0u16;
+    /// let num_trailing = unsafe { cttz(x) };
+    /// assert_eq!(num_trailing, 16);
+    /// ```
     pub fn cttz<T>(x: T) -> T;
 
     /// Reverses the bytes in an integer type `T`.