From ca01897d64baad43459268cfdb516baa6e7dfc95 Mon Sep 17 00:00:00 2001
From: Adam Harvey <aharvey@php.net>
Date: Mon, 10 Sep 2012 01:54:11 +0000
Subject: [PATCH] Fix doc bug #63027 (dechex may convert numbers up to
 PHP_INT_MAX) by clarifying that PHP treats the parameter as an unsigned int,
 and working through some of the implications of that from a userland
 perspective.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@327571 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/math/functions/dechex.xml | 45 +++++++++++++++++++++++++----
 1 file changed, 40 insertions(+), 5 deletions(-)

diff --git a/reference/math/functions/dechex.xml b/reference/math/functions/dechex.xml
index a6dff019fd..6099c4e72c 100644
--- a/reference/math/functions/dechex.xml
+++ b/reference/math/functions/dechex.xml
@@ -12,9 +12,15 @@
     <methodparam><type>int</type><parameter>number</parameter></methodparam>
    </methodsynopsis>
   <para>
-   Returns a string containing a hexadecimal representation of the
-   given <parameter>number</parameter> argument. The largest number that can
-   be converted is 4294967295 in decimal resulting to "ffffffff".
+   Returns a string containing a hexadecimal representation of the given
+   unsigned <parameter>number</parameter> argument.
+  </para>
+  <para>
+   The largest number that can be converted is
+   <constant>PHP_INT_MAX</constant><literal> * 2 + 1</literal> (or
+   <literal>-1</literal>): on 32-bit platforms, this will be
+   <literal>4294967295</literal> in decimal, which results in
+   <function>dechex</function> returning <literal>ffffffff</literal>.
   </para>
  </refsect1>
  <refsect1 role="parameters">
@@ -25,7 +31,12 @@
      <term><parameter>number</parameter></term>
      <listitem>
       <para>
-       Decimal value to convert
+       The decimal value to convert.
+      </para>
+      <para>
+       As PHP's <type>integer</type> type is signed, but
+       <function>dechex</function> deals with unsigned integers, negative
+       integers will be treated as though they were unsigned.
       </para>
      </listitem>
     </varlistentry>
@@ -35,7 +46,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Hexadecimal string representation of <parameter>number</parameter>
+   Hexadecimal string representation of <parameter>number</parameter>.
   </para>
  </refsect1>
  <refsect1 role="examples">
@@ -56,6 +67,30 @@ echo dechex(47);
 <![CDATA[
 a
 2f
+]]>
+    </screen>
+   </example>
+  </para>
+  <para>
+   <example>
+    <title><function>dechex</function> example with large integers</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// The output below assumes a 32-bit platform.
+// Note that the output is the same for all values.
+echo dechex(-1)."\n";
+echo dechex(PHP_INT_MAX * 2 + 1)."\n";
+echo dechex(pow(2, 32) - 1)."\n";
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+ffffffff
+ffffffff
+ffffffff
 ]]>
     </screen>
    </example>