Skip to content

Commit c75f19c

Browse files
GirgiasGirgias
authored
Fix GH-3336: String arguments that are converted have misleading explanation (#3337)
1 parent b35a226 commit c75f19c

File tree

3 files changed

+76
-90
lines changed

3 files changed

+76
-90
lines changed

‎language-snippets.ent

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2182,7 +2182,12 @@ or an explicit call to <function>chr</function> should be made.</para></warning>
21822182

21832183
<!-- GMP Notes -->
21842184
<!ENTITY gmp.return 'A <classname xmlns="http://docbook.org/ns/docbook">GMP</classname> object.'>
2185-
<!ENTITY gmp.parameter '<para xmlns="http://docbook.org/ns/docbook">A <classname>GMP</classname> object, an &integer; or a numeric &string;.</para>'>
2185+
<!ENTITY gmp.parameter '<para xmlns="http://docbook.org/ns/docbook">
2186+
A <classname>GMP</classname> object, an &integer;,
2187+
or a &string; that can be interpreted as a number following the same logic
2188+
as if the string was used in <function>gmp_init</function> with automatic
2189+
base detection (i.e. when <parameter>base</parameter> is equal to 0).
2190+
</para>'>
21862191

21872192
<!-- MySQLi Notes -->
21882193
<!ENTITY mysqli.result.description '<varlistentry xmlns="http://docbook.org/ns/docbook"><term>

‎reference/gmp/functions/gmp-init.xml

Lines changed: 66 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -20,37 +20,47 @@
2020

2121
<refsect1 role="parameters">
2222
&reftitle.parameters;
23-
<para>
24-
<variablelist>
25-
<varlistentry>
26-
<term><parameter>num</parameter></term>
27-
<listitem>
28-
<para>
29-
An integer or a string. The string representation can be decimal,
30-
hexadecimal or octal.
31-
</para>
32-
</listitem>
33-
</varlistentry>
34-
<varlistentry>
35-
<term><parameter>base</parameter></term>
36-
<listitem>
37-
<para>
38-
The base.
39-
</para>
40-
<para>
41-
The base may vary from 2 to 62. If base is 0 (default value), the
42-
actual base is determined from the leading characters: if the first
43-
two characters are <literal>0x</literal> or <literal>0X</literal>,
44-
hexadecimal is assumed, if the first two characters are <literal>0b</literal> or <literal>0B</literal>,
45-
binary is assumed, otherwise if the first character is <literal>0</literal>,
46-
octal is assumed, otherwise decimal is assumed.
47-
For bases up to 36, case is ignored; upper-case and lower-case letters have the same value.
48-
For bases 37 to 62, upper-case letter represent the usual 10 to 35 while lower-case letter represent 36 to 61.
49-
</para>
50-
</listitem>
51-
</varlistentry>
52-
</variablelist>
53-
</para>
23+
<variablelist>
24+
<varlistentry>
25+
<term><parameter>num</parameter></term>
26+
<listitem>
27+
<simpara>
28+
An integer or a string. The string representation can be decimal,
29+
hexadecimal, octal, or binary.
30+
</simpara>
31+
</listitem>
32+
</varlistentry>
33+
<varlistentry>
34+
<term><parameter>base</parameter></term>
35+
<listitem>
36+
<simpara>
37+
The base to use for converting a <type>string</type> representation.
38+
</simpara>
39+
<simpara>
40+
An explicit base can be between <literal>2</literal> and <literal>62</literal>.
41+
For bases up to <literal>36</literal>, case is ignored;
42+
upper-case and lower-case letters have the same value.
43+
For bases <literal>37</literal> to <literal>62</literal>,
44+
upper-case letter represent the values <literal>10</literal> to
45+
<literal>35</literal> and lower-case letter represent the values
46+
<literal>36</literal> to <literal>61</literal>.
47+
</simpara>
48+
<simpara>
49+
If <parameter>base</parameter> is <literal>0</literal> then the actual
50+
base is determined from the leading characters of <parameter>num</parameter>.
51+
If the first two characters are <literal>0x</literal> or <literal>0X</literal>,
52+
the string is interpreted as a hexadecimal integer.
53+
If the first two characters are <literal>0b</literal> or <literal>0B</literal>,
54+
the string is interpreted as a binary integer.
55+
If the first two characters are <literal>0o</literal> or <literal>0o</literal>,
56+
the string is interpreted as an octal integer.
57+
Moreover, if the first character is <literal>0</literal> the string
58+
is also interpreted as an octal integer.
59+
In all other cases, the string is interpreted as a decimal integer.
60+
</simpara>
61+
</listitem>
62+
</varlistentry>
63+
</variablelist>
5464
</refsect1>
5565

5666
<refsect1 role="returnvalues">
@@ -60,6 +70,31 @@
6070
</para>
6171
</refsect1>
6272

73+
<refsect1 role="changelog">
74+
&reftitle.changelog;
75+
<informaltable>
76+
<tgroup cols="2">
77+
<thead>
78+
<row>
79+
<entry>&Version;</entry>
80+
<entry>&Description;</entry>
81+
</row>
82+
</thead>
83+
<tbody>
84+
<row>
85+
<entry>8.1.0</entry>
86+
<entry>
87+
Support for explicit octal prefixes <literal>0o</literal> and
88+
<literal>0o</literal> has been added for <parameter>num</parameter> strings.
89+
Interpretation of such prefixes when <parameter>base</parameter> is
90+
<literal>0</literal> has also been added.
91+
</entry>
92+
</row>
93+
</tbody>
94+
</tgroup>
95+
</informaltable>
96+
</refsect1>
97+
6398
<refsect1 role="examples">
6499
&reftitle.examples;
65100
<para>

‎reference/gmp/gmp/construct.xml

Lines changed: 4 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<?xml version="1.0" encoding="utf-8"?>
2-
<refentry xml:id="gmp.construct" xmlns="http://docbook.org/ns/docbook">
2+
<refentry xml:id="gmp.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
33
<refnamediv>
44
<refname>GMP::__construct</refname>
55
<refpurpose>Create GMP number</refpurpose>
@@ -18,64 +18,10 @@
1818
</refsect1>
1919

2020
<refsect1 role="parameters">
21-
&reftitle.parameters;
22-
<para>
23-
<variablelist>
24-
<varlistentry>
25-
<term><parameter>num</parameter></term>
26-
<listitem>
27-
<para>
28-
An integer or a string. The string representation can be decimal,
29-
hexadecimal or octal.
30-
</para>
31-
</listitem>
32-
</varlistentry>
33-
<varlistentry>
34-
<term><parameter>base</parameter></term>
35-
<listitem>
36-
<para>
37-
The base.
38-
</para>
39-
<para>
40-
The base may vary from 2 to 62. If base is 0 (default value), the
41-
actual base is determined from the leading characters: if the first
42-
two characters are <literal>0x</literal> or <literal>0X</literal>,
43-
hexadecimal is assumed, if the first two characters are <literal>0b</literal> or <literal>0B</literal>,
44-
binary is assumed, otherwise if the first character is <literal>0</literal>,
45-
octal is assumed, otherwise decimal is assumed.
46-
For bases up to 36, case is ignored; upper-case and lower-case letters have the same value.
47-
For bases 37 to 62, upper-case letter represent the usual 10 to 35 while lower-case letter represent 36 to 61.
48-
</para>
49-
</listitem>
50-
</varlistentry>
51-
</variablelist>
52-
</para>
53-
</refsect1>
54-
55-
<!--
56-
<refsect1 role="examples">
57-
&reftitle.examples;
58-
<example xml:id="gmp.construct.example.basic">
59-
<title><methodname>GMP::__construct</methodname> example</title>
60-
<para>
61-
Description.
62-
</para>
63-
<programlisting role="php">
64-
<![CDATA[
65-
<?php
66-
echo "Code example";
67-
?>
68-
]]>
69-
</programlisting>
70-
&example.outputs;
71-
<screen>
72-
<![CDATA[
73-
Code example
74-
]]>
75-
</screen>
76-
</example>
21+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.gmp-init')/db:refsect1[@role='parameters']/*)">
22+
<xi:fallback/>
23+
</xi:include>
7724
</refsect1>
78-
-->
7925

8026
<refsect1 role="seealso">
8127
&reftitle.seealso;

0 commit comments

Comments
 (0)