reference/strings/functions/crc32.xml
e095023e408c8cb6378ae16bb6870343a3946919
...
...
@@ -10,19 +10,51 @@
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>int</type><methodname>crc32</methodname>
13
-
<methodparam><type>string</type><parameter>str</parameter></methodparam>
13
+
<methodparam><type>string</type><parameter>string</parameter></methodparam>
14
14
</methodsynopsis>
15
15
<para>
16
16
Generates the cyclic redundancy checksum polynomial of 32-bit
17
-
lengths of the <parameter>str</parameter>. This is usually used
17
+
lengths of the <parameter>string</parameter>. This is usually used
18
18
to validate the integrity of data being transmitted.
19
19
</para>
20
-
<para>
21
-
Because PHP's integer type is signed, and many crc32 checksums will
22
-
result in negative integers, you need to use the "%u" formatter of
23
-
<function>sprintf</function> or <function>printf</function> to get
24
-
the string representation of the unsigned crc32 checksum.
25
-
</para>
20
+
<warning>
21
+
<simpara>
22
+
Because PHP's integer type is signed many crc32 checksums will
23
+
result in negative integers on 32bit platforms. On 64bit installations
24
+
all <function>crc32</function> results will be positive integers though.
25
+
</simpara>
26
+
<simpara>
27
+
So you need to use the "%u" formatter of <function>sprintf</function> or
28
+
<function>printf</function> to get the string representation of the
29
+
unsigned <function>crc32</function> checksum in decimal format.
30
+
</simpara>
31
+
<simpara>
32
+
For a hexadecimal representation of the checksum you can either use the
33
+
"%x" formatter of <function>sprintf</function> or <function>printf</function>
34
+
or the <function>dechex</function> conversion functions, both of these
35
+
also take care of converting the <function>crc32</function> result to
36
+
an unsigned integer.
37
+
</simpara>
38
+
<simpara>
39
+
Having 64bit installations also return negative integers for higher
40
+
result values was considered but would break the hexadecimal conversion
41
+
as negatives would get an extra 0xFFFFFFFF######## offset then. As
42
+
hexadecimal representation seems to be the most common use case we
43
+
decided to not break this even if it breaks direct decimal comparisons
44
+
in about 50% of the cases when moving from 32 to 64bits.
45
+
</simpara>
46
+
<simpara>
47
+
In retrospect having the function return an integer maybe wasn't the
48
+
best idea and returning a hex string representation right away (as
49
+
e.g. <function>md5</function> does) might have been a better plan to
50
+
begin with.
51
+
</simpara>
52
+
<simpara>
53
+
For a more portable solution you may also consider the generic
54
+
<function>hash</function>. <code>hash("crc32b", $str)</code> will
55
+
return the same string as <code>str_pad(dechex(crc32($str)), 8, '0', STR_PAD_LEFT)</code>.
56
+
</simpara>
57
+
</warning>
26
58
</refsect1>
27
59

28
60
<refsect1 role="parameters">
...
...
@@ -30,7 +62,7 @@
30
62
<para>
31
63
<variablelist>
32
64
<varlistentry>
33
-
<term><parameter>str</parameter></term>
65
+
<term><parameter>string</parameter></term>
34
66
<listitem>
35
67
<para>
36
68
The data.
...
...
@@ -44,7 +76,7 @@
44
76
<refsect1 role="returnvalues">
45
77
&reftitle.returnvalues;
46
78
<para>
47
-
Returns the crc32 checksum of <parameter>str</parameter> as an integer.
79
+
Returns the crc32 checksum of <parameter>string</parameter> as an integer.
48
80
</para>
49
81
</refsect1>
50
82

...
...
@@ -73,6 +105,7 @@ printf("%u\n", $checksum);
73
105
&reftitle.seealso;
74
106
<para>
75
107
<simplelist>
108
+
<member><function>hash</function></member>
76
109
<member><function>md5</function></member>
77
110
<member><function>sha1</function></member>
78
111
</simplelist>
...
...
@@ -80,7 +113,6 @@ printf("%u\n", $checksum);
80
113
</refsect1>
81
114

82
115
</refentry>
83
-

84
116
<!-- Keep this comment at the end of the file
85
117
Local variables:
86
118
mode: sgml
87
119