Skip to content

Commit d069eb6

Browse files
derickrclaudepache
derickr
authored and
claudepache
committed
Incorporate useful information from notes (take php#3)
1 parent 98f2b79 commit d069eb6

21 files changed

+326
-91
lines changed

‎reference/datetime/datetime/createfromformat.xml

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,6 @@
1616
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
1717
<methodparam choice="opt"><type class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
1818
</methodsynopsis>
19-
<para>&style.procedural;</para>
20-
<methodsynopsis role="procedural">
21-
<type class="union"><type>DateTime</type><type>false</type></type><methodname>date_create_from_format</methodname>
22-
<methodparam><type>string</type><parameter>format</parameter></methodparam>
23-
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
24-
<methodparam choice="opt"><type class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
25-
</methodsynopsis>
2619

2720
<para>
2821
Returns a new DateTime object representing the date and time specified by the
@@ -33,6 +26,14 @@
3326
Like <methodname>DateTimeImmutable::createFromFormat</methodname> but
3427
creates an <classname>DateTime</classname> object.
3528
</para>
29+
30+
<para>&style.procedural;</para>
31+
<methodsynopsis role="procedural">
32+
<type class="union"><type>DateTime</type><type>false</type></type><methodname>date_create_from_format</methodname>
33+
<methodparam><type>string</type><parameter>format</parameter></methodparam>
34+
<methodparam><type>string</type><parameter>datetime</parameter></methodparam>
35+
<methodparam choice="opt"><type class="union"><type>DateTimeZone</type><type>null</type></type><parameter>timezone</parameter><initializer>&null;</initializer></methodparam>
36+
</methodsynopsis>
3637
<para>
3738
The procedural version takes the <classname>DateTime</classname> object as
3839
its first argument.

‎reference/datetime/formats.xml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -778,6 +778,11 @@ object(DateTimeImmutable)#1 (3) {
778778
<entry>"@" "-"? [0-9]+</entry>
779779
<entry>"@1215282385"</entry>
780780
</row>
781+
<row>
782+
<entry>Unix Timestamp with microseconds</entry>
783+
<entry>"@" "-"? [0-9]+ "." [0-9]{0,6}</entry>
784+
<entry>"@1607974647.503686"</entry>
785+
</row>
781786
<row>
782787
<entry>XMLRPC</entry>
783788
<entry><literal>YY</literal> <literal>MM</literal> <literal>DD</literal> "T" <literal>hh</literal> ":" <literal>II</literal> ":" <literal>SS</literal></entry>

‎reference/datetime/functions/date-parse-from-format.xml

Lines changed: 98 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
<term><parameter>format</parameter></term>
2828
<listitem>
2929
<para>
30-
Format accepted by <function>DateTime::createFromFormat</function>.
30+
Format accepted by <function>DateTimeImmutable::createFromFormat</function>.
3131
</para>
3232
</listitem>
3333
</varlistentry>
@@ -49,6 +49,48 @@
4949
<para>
5050
Returns associative array with detailed info about given date/time.
5151
</para>
52+
<para>
53+
The returned array has keys for <literal>year</literal>,
54+
<literal>month</literal>, <literal>day</literal>, <literal>hour</literal>,
55+
<literal>minute</literal>, <literal>second</literal>,
56+
<literal>fraction</literal>, and <literal>is_localtime</literal>.
57+
</para>
58+
<para>
59+
If <literal>is_localtime</literal> is present then
60+
<literal>zone_type</literal> indicates the type of timezone. For type
61+
<literal>1</literal> (UTC offset) the <literal>zone</literal>,
62+
<literal>is_dst</literal> fields are added; for type <literal>2</literal>
63+
(abbreviation) the fields <literal>tz_abbr</literal>,
64+
<literal>is_dst</literal> are added; and for type <literal>3</literal>
65+
(timezone identifier) the <literal>tz_abbr</literal>,
66+
<literal>tz_id</literal> are added.
67+
</para>
68+
<para>
69+
The array includes <literal>warning_count</literal> and
70+
<literal>warnings</literal> fields. The first one indicate how many
71+
warnings there were.
72+
The keys of elements <literal>warnings</literal> array indicate the
73+
position in the given <parameter>datetime</parameter> where the warning
74+
occurred, with the string value describing the warning itself. An example
75+
below shows such a warning.
76+
</para>
77+
<para>
78+
The array also contains <literal>error_count</literal> and
79+
<literal>errors</literal> fields. The first one indicate how many errors
80+
were found.
81+
The keys of elements <literal>errors</literal> array indicate the
82+
position in the given <parameter>datetime</parameter> where the error
83+
occurred, with the string value describing the error itself. An example
84+
below shows such an error.
85+
</para>
86+
<warning>
87+
<para>
88+
The number of array elements in the <literal>warnings</literal> and
89+
<literal>errors</literal> arrays might be less than
90+
<literal>warning_count</literal> or <literal>error_count</literal> if they
91+
occurred at the same position.
92+
</para>
93+
</warning>
5294
</refsect1>
5395

5496
<refsect1 role="changelog">
@@ -115,16 +157,70 @@ Array
115157
[zone] => 3600
116158
[is_dst] =>
117159
)
160+
]]>
161+
</screen>
162+
</example>
163+
</para>
164+
165+
<para>
166+
<example>
167+
<title><function>date_parse_from_format</function> with warnings example</title>
168+
<programlisting role="php">
169+
<![CDATA[
170+
<?php
171+
$date = "26 August 2022 22:30 pm";
172+
$parsed = date_parse_from_format("j F Y G:i a", $date);
173+
174+
echo "Warnings count: ", $parsed['warning_count'], "\n";
175+
foreach ($parsed['warnings'] as $position => $message) {
176+
echo "\tOn position {$position}: {$message}\n";
177+
}
178+
?>
179+
]]>
180+
</programlisting>
181+
&example.outputs;
182+
<screen>
183+
<![CDATA[
184+
Warnings count: 1
185+
On position 23: The parsed time was invalid
186+
]]>
187+
</screen>
188+
</example>
189+
</para>
190+
191+
<para>
192+
<example>
193+
<title><function>date_parse_from_format</function> with errors example</title>
194+
<programlisting role="php">
195+
<![CDATA[
196+
<?php
197+
$date = "26 August 2022 CEST";
198+
$parsed = date_parse_from_format("j F Y H:i", $date);
199+
200+
echo "Errors count: ", $parsed['error_count'], "\n";
201+
foreach ($parsed['errors'] as $position => $message) {
202+
echo "\tOn position {$position}: {$message}\n";
203+
}
204+
?>
205+
]]>
206+
</programlisting>
207+
&example.outputs;
208+
<screen>
209+
<![CDATA[
210+
Errors count: 3
211+
On position 15: A two digit hour could not be found
212+
On position 19: Data missing
118213
]]>
119214
</screen>
120215
</example>
121216
</para>
122217
</refsect1>
218+
123219
<refsect1 role="seealso">
124220
&reftitle.seealso;
125221
<para>
126222
<simplelist>
127-
<member><function>DateTime::createFromFormat</function></member>
223+
<member><function>DateTimeImmutable::createFromFormat</function></member>
128224
<member><function>checkdate</function></member>
129225
</simplelist>
130226
</para>

‎reference/datetime/functions/date-parse.xml

Lines changed: 51 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,56 @@
5454
Returns <type>array</type> with information about the parsed date/time
5555
on success&return.falseforfailure;.
5656
</para>
57+
<para>
58+
The returned array has keys for <literal>year</literal>,
59+
<literal>month</literal>, <literal>day</literal>, <literal>hour</literal>,
60+
<literal>minute</literal>, <literal>second</literal>,
61+
<literal>fraction</literal>, and <literal>is_localtime</literal>.
62+
</para>
63+
<para>
64+
If <literal>is_localtime</literal> is present then
65+
<literal>zone_type</literal> indicates the type of timezone. For type
66+
<literal>1</literal> (UTC offset) the <literal>zone</literal>,
67+
<literal>is_dst</literal> fields are added; for type <literal>2</literal>
68+
(abbreviation) the fields <literal>tz_abbr</literal>,
69+
<literal>is_dst</literal> are added; and for type <literal>3</literal>
70+
(timezone identifier) the <literal>tz_abbr</literal>,
71+
<literal>tz_id</literal> are added.
72+
</para>
73+
<para>
74+
If relative time elements are present in the
75+
<parameter>datetime</parameter> string such as <literal>+3 days</literal>,
76+
the then returned array includes a nested array with the key
77+
<literal>relative</literal>. This array then contains the keys
78+
<literal>year</literal>, <literal>month</literal>, <literal>day</literal>,
79+
<literal>hour</literal>, <literal>minute</literal>,
80+
<literal>second</literal>, and if necessary <literal>weekday</literal>, and
81+
<literal>weekdays</literal>, depending on the string that was passed in.
82+
</para>
83+
<para>
84+
The array includes <literal>warning_count</literal> and
85+
<literal>warnings</literal> fields. The first one indicate how many
86+
warnings there were.
87+
The keys of elements <literal>warnings</literal> array indicate the
88+
position in the given <parameter>datetime</parameter> where the warning
89+
occurred, with the string value describing the warning itself.
90+
</para>
91+
<para>
92+
The array also contains <literal>error_count</literal> and
93+
<literal>errors</literal> fields. The first one indicate how many errors
94+
were found.
95+
The keys of elements <literal>errors</literal> array indicate the
96+
position in the given <parameter>datetime</parameter> where the error
97+
occurred, with the string value describing the error itself.
98+
</para>
99+
<warning>
100+
<para>
101+
The number of array elements in the <literal>warnings</literal> and
102+
<literal>errors</literal> arrays might be less than
103+
<literal>warning_count</literal> or <literal>error_count</literal> if they
104+
occurred at the same position.
105+
</para>
106+
</warning>
57107
</refsect1>
58108

59109
<refsect1 role="errors">
@@ -335,7 +385,7 @@ array(13) {
335385
<simplelist>
336386
<member><function>date_parse_from_format</function> for
337387
parsing a <parameter>datetime</parameter> with a specific given format</member>
338-
<member><function>checkdate</function></member>
388+
<member><function>checkdate</function> for Gregorian date validation</member>
339389
<member><function>getdate</function></member>
340390
</simplelist>
341391
</para>

‎reference/datetime/functions/date-sub.xml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,16 @@
1313
</para>
1414
</refsect1>
1515

16+
<refsect1 role="seealso">
17+
&reftitle.seealso;
18+
<para>
19+
<simplelist>
20+
<member><function>DateTimeImmutable::sub</function></member>
21+
<member><function>DateTime::sub</function></member>
22+
</simplelist>
23+
</para>
24+
</refsect1>
25+
1626
</refentry>
1727

1828
<!-- Keep this comment at the end of the file

0 commit comments

Comments
 (0)