Skip to content

Commit e1b9f58

Browse files
lacatoirelacatoire
authored
ext/intl: Add IntlListFormatter class documentation (PHP 8.5) (#5692)
1 parent 844a420 commit e1b9f58

5 files changed

Lines changed: 398 additions & 9 deletions

File tree

‎appendices/migration85/new-classes.xml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,13 @@
2929
<!-- RFC: https://wiki.php.net/rfc/filter_throw_on_failure -->
3030
</sect2>
3131

32+
<sect2 xml:id="migration85.new-classes.intl">
33+
<title>Intl</title>
34+
<simplelist>
35+
<member><classname>IntlListFormatter</classname></member>
36+
</simplelist>
37+
</sect2>
38+
3239
<sect2 xml:id="migration85.new-classes.uri">
3340
<title>URI</title>
3441
<simplelist>

‎reference/intl/book.xml‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,26 +9,26 @@
99
<!-- {{{ Preface -->
1010
<preface xml:id="intro.intl">
1111
&reftitle.intro;
12-
<para>
12+
<simpara>
1313
Internationalization extension (further is referred as Intl) is a wrapper
1414
for <link xlink:href="&url.icu.home;">ICU</link>
1515
library, enabling PHP programmers to perform various locale-aware operations including
1616
but not limited to formatting, transliteration, encoding conversion, calendar operations,
1717
<link xlink:href="&url.icu.uca;">UCA</link>-conformant collation, locating
1818
text boundaries and working with locale identifiers, timezones and graphemes.
19-
</para>
19+
</simpara>
2020

21-
<para>
21+
<simpara>
2222
It tends to closely follow ICU APIs, so that people having experience
2323
working with ICU in either C/C++ or Java could easily use the PHP API.
2424
Also, this way ICU documentation would be useful to understand various ICU
2525
functions.
26-
</para>
26+
</simpara>
2727

28-
<para>
28+
<simpara>
2929
Intl consists of several modules, each of them exposes the corresponding
3030
ICU API:
31-
</para>
31+
</simpara>
3232

3333
<itemizedlist>
3434
<listitem>
@@ -98,13 +98,13 @@
9898
<title>Links</title>
9999
<itemizedlist>
100100
<listitem>
101-
<para><link xlink:href="&url.icu.docs;">Miscellaneous ICU docs</link></para>
101+
<simpara><link xlink:href="&url.icu.docs;">Miscellaneous ICU docs</link></simpara>
102102
</listitem>
103103
<listitem>
104-
<para><link xlink:href="&url.icu.userguide;">ICU User Guide</link></para>
104+
<simpara><link xlink:href="&url.icu.userguide;">ICU User Guide</link></simpara>
105105
</listitem>
106106
<listitem>
107-
<para><link xlink:href="&url.icu.uca;">Unicode Collation Algorithm</link></para>
107+
<simpara><link xlink:href="&url.icu.uca;">Unicode Collation Algorithm</link></simpara>
108108
</listitem>
109109
</itemizedlist>
110110
</section>
@@ -133,6 +133,7 @@
133133
&reference.intl.intlrulebasedbreakiterator;
134134
&reference.intl.intlcodepointbreakiterator;
135135
&reference.intl.intldatepatterngenerator;
136+
&reference.intl.intllistformatter;
136137
&reference.intl.intlpartsiterator;
137138
&reference.intl.uconverter;
138139

‎reference/intl/intllistformatter.xml‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
<reference xml:id="class.intllistformatter" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
4+
<title>The IntlListFormatter class</title>
5+
<titleabbrev>IntlListFormatter</titleabbrev>
6+
7+
<partintro>
8+
9+
<!-- {{{ IntlListFormatter intro -->
10+
<section xml:id="intllistformatter.intro">
11+
&reftitle.intro;
12+
<simpara>
13+
Formats, orders, and punctuates a list of items according to locale-specific rules.
14+
Requires ICU 67 or later.
15+
</simpara>
16+
</section>
17+
<!-- }}} -->
18+
19+
<section xml:id="intllistformatter.synopsis">
20+
&reftitle.classsynopsis;
21+
22+
<!-- {{{ Synopsis -->
23+
<classsynopsis class="class">
24+
<ooclass>
25+
<classname>IntlListFormatter</classname>
26+
</ooclass>
27+
28+
<classsynopsisinfo role="comment">&Constants;</classsynopsisinfo>
29+
<fieldsynopsis>
30+
<modifier>public</modifier>
31+
<modifier>const</modifier>
32+
<type>int</type>
33+
<varname linkend="intllistformatter.constants.type-and">IntlListFormatter::TYPE_AND</varname>
34+
</fieldsynopsis>
35+
<fieldsynopsis>
36+
<modifier>public</modifier>
37+
<modifier>const</modifier>
38+
<type>int</type>
39+
<varname linkend="intllistformatter.constants.type-or">IntlListFormatter::TYPE_OR</varname>
40+
</fieldsynopsis>
41+
<fieldsynopsis>
42+
<modifier>public</modifier>
43+
<modifier>const</modifier>
44+
<type>int</type>
45+
<varname linkend="intllistformatter.constants.type-units">IntlListFormatter::TYPE_UNITS</varname>
46+
</fieldsynopsis>
47+
<fieldsynopsis>
48+
<modifier>public</modifier>
49+
<modifier>const</modifier>
50+
<type>int</type>
51+
<varname linkend="intllistformatter.constants.width-wide">IntlListFormatter::WIDTH_WIDE</varname>
52+
</fieldsynopsis>
53+
<fieldsynopsis>
54+
<modifier>public</modifier>
55+
<modifier>const</modifier>
56+
<type>int</type>
57+
<varname linkend="intllistformatter.constants.width-short">IntlListFormatter::WIDTH_SHORT</varname>
58+
</fieldsynopsis>
59+
<fieldsynopsis>
60+
<modifier>public</modifier>
61+
<modifier>const</modifier>
62+
<type>int</type>
63+
<varname linkend="intllistformatter.constants.width-narrow">IntlListFormatter::WIDTH_NARROW</varname>
64+
</fieldsynopsis>
65+
66+
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
67+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.intllistformatter')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='IntlListFormatter'])">
68+
<xi:fallback/>
69+
</xi:include>
70+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.intllistformatter')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='IntlListFormatter'])">
71+
<xi:fallback/>
72+
</xi:include>
73+
</classsynopsis>
74+
<!-- }}} -->
75+
76+
</section>
77+
78+
<section xml:id="intllistformatter.constants">
79+
&reftitle.constants;
80+
<variablelist>
81+
<varlistentry xml:id="intllistformatter.constants.type-and">
82+
<term><constant>IntlListFormatter::TYPE_AND</constant></term>
83+
<listitem>
84+
<simpara>
85+
Formats a list using conjunction (e.g. "A, B, and C").
86+
</simpara>
87+
</listitem>
88+
</varlistentry>
89+
<varlistentry xml:id="intllistformatter.constants.type-or">
90+
<term><constant>IntlListFormatter::TYPE_OR</constant></term>
91+
<listitem>
92+
<simpara>
93+
Formats a list using disjunction (e.g. "A, B, or C").
94+
</simpara>
95+
</listitem>
96+
</varlistentry>
97+
<varlistentry xml:id="intllistformatter.constants.type-units">
98+
<term><constant>IntlListFormatter::TYPE_UNITS</constant></term>
99+
<listitem>
100+
<simpara>
101+
Formats a list of units (e.g. "3 ft, 7 in").
102+
</simpara>
103+
</listitem>
104+
</varlistentry>
105+
<varlistentry xml:id="intllistformatter.constants.width-wide">
106+
<term><constant>IntlListFormatter::WIDTH_WIDE</constant></term>
107+
<listitem>
108+
<simpara>
109+
Uses the widest (most verbose) list format, typically with conjunctions spelled out in full.
110+
</simpara>
111+
</listitem>
112+
</varlistentry>
113+
<varlistentry xml:id="intllistformatter.constants.width-short">
114+
<term><constant>IntlListFormatter::WIDTH_SHORT</constant></term>
115+
<listitem>
116+
<simpara>
117+
Uses a short list format, typically using abbreviations.
118+
</simpara>
119+
</listitem>
120+
</varlistentry>
121+
<varlistentry xml:id="intllistformatter.constants.width-narrow">
122+
<term><constant>IntlListFormatter::WIDTH_NARROW</constant></term>
123+
<listitem>
124+
<simpara>
125+
Uses the narrowest list format, with minimal punctuation.
126+
</simpara>
127+
</listitem>
128+
</varlistentry>
129+
</variablelist>
130+
</section>
131+
132+
<section role="changelog" xml:id="intllistformatter.changelog">
133+
&reftitle.changelog;
134+
<informaltable>
135+
<tgroup cols="2">
136+
<thead>
137+
<row>
138+
<entry>&Version;</entry>
139+
<entry>&Description;</entry>
140+
</row>
141+
</thead>
142+
<tbody>
143+
<row>
144+
<entry>8.5.0</entry>
145+
<entry>
146+
The class was added.
147+
</entry>
148+
</row>
149+
</tbody>
150+
</tgroup>
151+
</informaltable>
152+
</section>
153+
154+
</partintro>
155+
156+
&reference.intl.entities.intllistformatter;
157+
158+
</reference>
159+
<!-- Keep this comment at the end of the file
160+
Local variables:
161+
mode: sgml
162+
sgml-omittag:t
163+
sgml-shorttag:t
164+
sgml-minimize-attributes:nil
165+
sgml-always-quote-attributes:t
166+
sgml-indent-step:1
167+
sgml-indent-data:t
168+
indent-tabs-mode:nil
169+
sgml-parent-document:nil
170+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
171+
sgml-exposed-tags:nil
172+
sgml-local-catalogs:nil
173+
sgml-local-ecat-files:nil
174+
End:
175+
vim600: syn=xml fen fdm=syntax fdl=2 si
176+
vim: et tw=78 syn=sgml
177+
vi: ts=1 sw=1
178+
-->

‎reference/intl/intllistformatter/construct.xml‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
<refentry xml:id="intllistformatter.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4+
<refnamediv>
5+
<refname>IntlListFormatter::__construct</refname>
6+
<refpurpose>Creates a new IntlListFormatter instance</refpurpose>
7+
</refnamediv>
8+
9+
<refsect1 role="description">
10+
&reftitle.description;
11+
<constructorsynopsis role="IntlListFormatter">
12+
<modifier>public</modifier> <methodname>IntlListFormatter::__construct</methodname>
13+
<methodparam><type>string</type><parameter>locale</parameter></methodparam>
14+
<methodparam choice="opt"><type>int</type><parameter>type</parameter><initializer><constant>IntlListFormatter::TYPE_AND</constant></initializer></methodparam>
15+
<methodparam choice="opt"><type>int</type><parameter>width</parameter><initializer><constant>IntlListFormatter::WIDTH_WIDE</constant></initializer></methodparam>
16+
</constructorsynopsis>
17+
<simpara>
18+
Creates a new <classname>IntlListFormatter</classname> instance for the given locale.
19+
</simpara>
20+
</refsect1>
21+
22+
<refsect1 role="parameters">
23+
&reftitle.parameters;
24+
<variablelist>
25+
<varlistentry>
26+
<term><parameter>locale</parameter></term>
27+
<listitem>
28+
<simpara>
29+
The locale to use for formatting.
30+
</simpara>
31+
</listitem>
32+
</varlistentry>
33+
<varlistentry>
34+
<term><parameter>type</parameter></term>
35+
<listitem>
36+
<simpara>
37+
The list type. One of the <constant>IntlListFormatter::TYPE_<replaceable>*</replaceable></constant> constants:
38+
<constant>IntlListFormatter::TYPE_AND</constant>,
39+
<constant>IntlListFormatter::TYPE_OR</constant>, or
40+
<constant>IntlListFormatter::TYPE_UNITS</constant>.
41+
</simpara>
42+
</listitem>
43+
</varlistentry>
44+
<varlistentry>
45+
<term><parameter>width</parameter></term>
46+
<listitem>
47+
<simpara>
48+
The list width. One of the <constant>IntlListFormatter::WIDTH_<replaceable>*</replaceable></constant> constants:
49+
<constant>IntlListFormatter::WIDTH_WIDE</constant>,
50+
<constant>IntlListFormatter::WIDTH_SHORT</constant>, or
51+
<constant>IntlListFormatter::WIDTH_NARROW</constant>.
52+
</simpara>
53+
</listitem>
54+
</varlistentry>
55+
</variablelist>
56+
</refsect1>
57+
58+
<refsect1 role="errors">
59+
&reftitle.errors;
60+
<simpara>
61+
Throws an <exceptionname>IntlException</exceptionname> if the formatter cannot be created
62+
(e.g. invalid locale or ICU version is below 67).
63+
</simpara>
64+
</refsect1>
65+
66+
<refsect1 role="changelog">
67+
&reftitle.changelog;
68+
<informaltable>
69+
<tgroup cols="2">
70+
<thead>
71+
<row>
72+
<entry>&Version;</entry>
73+
<entry>&Description;</entry>
74+
</row>
75+
</thead>
76+
<tbody>
77+
<row>
78+
<entry>8.5.0</entry>
79+
<entry>
80+
The class was added.
81+
</entry>
82+
</row>
83+
</tbody>
84+
</tgroup>
85+
</informaltable>
86+
</refsect1>
87+
88+
<refsect1 role="seealso">
89+
&reftitle.seealso;
90+
<simplelist>
91+
<member><methodname>IntlListFormatter::format</methodname></member>
92+
</simplelist>
93+
</refsect1>
94+
95+
</refentry>
96+
<!-- Keep this comment at the end of the file
97+
Local variables:
98+
mode: sgml
99+
sgml-omittag:t
100+
sgml-shorttag:t
101+
sgml-minimize-attributes:nil
102+
sgml-always-quote-attributes:t
103+
sgml-indent-step:1
104+
sgml-indent-data:t
105+
indent-tabs-mode:nil
106+
sgml-parent-document:nil
107+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
108+
sgml-exposed-tags:nil
109+
sgml-local-catalogs:nil
110+
sgml-local-ecat-files:nil
111+
End:
112+
vim600: syn=xml fen fdm=syntax fdl=2 si
113+
vim: et tw=78 syn=sgml
114+
vi: ts=1 sw=1
115+
-->

0 commit comments

Comments
 (0)