reference/datetime/dateinterval.xml
9154789dfc9cb8aa5df644bfba5e86c2deba4cb8
...
...
@@ -1,6 +1,5 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-

4
3
<phpdoc:classref xml:id="class.dateinterval" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
5
4

6
5
<title>The DateInterval class</title>
...
...
@@ -17,7 +16,23 @@
17
16
<para>
18
17
A date interval stores either a fixed amount of time (in years, months,
19
18
days, hours etc) or a relative time string in the format that
20
-
<classname>DateTime</classname>'s constructor supports.
19
+
<classname>DateTimeImmutable</classname>'s and
20
+
<classname>DateTime</classname>'s constructors support.
21
+
</para>
22
+
<para>
23
+
More specifically, the information in an object of the
24
+
<classname>DateInterval</classname> class is an instruction to get from
25
+
one date/time to another date/time. This process is not always reversible.
26
+
</para>
27
+
<para>
28
+
A common way to create a <classname>DateInterval</classname> object
29
+
is by calculating the difference between two date/time objects through
30
+
<methodname>DateTimeInterface::diff</methodname>.
31
+
</para>
32
+
<para>
33
+
Since there is no well defined way to compare date intervals,
34
+
<classname>DateInterval</classname> instances are
35
+
<link linkend="language.operators.comparison.incomparable">incomparable</link>.
21
36
</para>
22
37
</section>
23
38
<!-- }}} -->
...
...
@@ -26,51 +41,50 @@
26
41
&reftitle.classsynopsis;
27
42

28
43
<!-- {{{ Synopsis -->
29
-
<classsynopsis>
30
-
<ooclass><classname>DateInterval</classname></ooclass>
31
-

32
-
<!-- {{{ Class synopsis -->
33
-
<classsynopsisinfo>
34
-
<ooclass>
35
-
<classname>DateInterval</classname>
36
-
</ooclass>
37
-
</classsynopsisinfo>
38
-
<!-- }}} -->
44
+
<classsynopsis class="class">
45
+
<ooclass>
46
+
<classname>DateInterval</classname>
47
+
</ooclass>
39
48

40
49
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
41
50
<fieldsynopsis>
42
51
<modifier>public</modifier>
43
-
<type>integer</type>
52
+
<type>int</type>
44
53
<varname linkend="dateinterval.props.y">y</varname>
45
54
</fieldsynopsis>
46
55
<fieldsynopsis>
47
56
<modifier>public</modifier>
48
-
<type>integer</type>
57
+
<type>int</type>
49
58
<varname linkend="dateinterval.props.m">m</varname>
50
59
</fieldsynopsis>
51
60
<fieldsynopsis>
52
61
<modifier>public</modifier>
53
-
<type>integer</type>
62
+
<type>int</type>
54
63
<varname linkend="dateinterval.props.d">d</varname>
55
64
</fieldsynopsis>
56
65
<fieldsynopsis>
57
66
<modifier>public</modifier>
58
-
<type>integer</type>
67
+
<type>int</type>
59
68
<varname linkend="dateinterval.props.h">h</varname>
60
69
</fieldsynopsis>
61
70
<fieldsynopsis>
62
71
<modifier>public</modifier>
63
-
<type>integer</type>
72
+
<type>int</type>
64
73
<varname linkend="dateinterval.props.i">i</varname>
65
74
</fieldsynopsis>
66
75
<fieldsynopsis>
67
76
<modifier>public</modifier>
68
-
<type>integer</type>
77
+
<type>int</type>
69
78
<varname linkend="dateinterval.props.s">s</varname>
70
79
</fieldsynopsis>
71
80
<fieldsynopsis>
72
81
<modifier>public</modifier>
73
-
<type>integer</type>
82
+
<type>float</type>
83
+
<varname linkend="dateinterval.props.f">f</varname>
84
+
</fieldsynopsis>
85
+
<fieldsynopsis>
86
+
<modifier>public</modifier>
87
+
<type>int</type>
74
88
<varname linkend="dateinterval.props.invert">invert</varname>
75
89
</fieldsynopsis>
76
90
<fieldsynopsis>
...
...
@@ -78,20 +92,24 @@
78
92
<type>mixed</type>
79
93
<varname linkend="dateinterval.props.days">days</varname>
80
94
</fieldsynopsis>
95
+
<fieldsynopsis>
96
+
<modifier>public</modifier>
97
+
<type>bool</type>
98
+
<varname linkend="dateinterval.props.from-string">from_string</varname>
99
+
</fieldsynopsis>
100
+
<fieldsynopsis>
101
+
<modifier>public</modifier>
102
+
<type>string</type>
103
+
<varname linkend="dateinterval.props.date-string">date_string</varname>
104
+
</fieldsynopsis>
81
105
82
106
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
83
-
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateinterval')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[not(@role='procedural')])">
84
-
<xi:fallback />
85
-
</xi:include>
86
-
<!--
87
-
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateinterval')/db:refentry/db:refsect1[@role='description']/descendant::db:destructorsynopsis[not(@role='procedural')])">
88
-
<xi:fallback />
107
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateinterval')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='DateInterval'])">
108
+
<xi:fallback/>
89
109
</xi:include>
90
-
-->
91
-
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateinterval')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])">
92
-
<xi:fallback />
110
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateinterval')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='DateInterval'])">
111
+
<xi:fallback/>
93
112
</xi:include>
94
-

95
113
</classsynopsis>
96
114
<!-- }}} -->
97
115

...
...
@@ -99,6 +117,12 @@
99
117
100
118
<section xml:id="dateinterval.props">
101
119
&reftitle.properties;
120
+
<warning>
121
+
<para>
122
+
The available properties listed below depend on PHP version, and should
123
+
be considered as <emphasis>readonly</emphasis>.
124
+
</para>
125
+
</warning>
102
126
<variablelist>
103
127
<varlistentry xml:id="dateinterval.props.y">
104
128
<term><varname>y</varname></term>
...
...
@@ -148,6 +172,14 @@
148
172
</para>
149
173
</listitem>
150
174
</varlistentry>
175
+
<varlistentry xml:id="dateinterval.props.f">
176
+
<term><varname>f</varname></term>
177
+
<listitem>
178
+
<para>
179
+
Number of microseconds, as a fraction of a second.
180
+
</para>
181
+
</listitem>
182
+
</varlistentry>
151
183
<varlistentry xml:id="dateinterval.props.invert">
152
184
<term><varname>invert</varname></term>
153
185
<listitem>
...
...
@@ -164,25 +196,89 @@
164
196
<listitem>
165
197
<para>
166
198
If the DateInterval object was created by
167
-
<function>DateTime::diff</function>, then this is the total number of
168
-
days between the start and end dates. Otherwise,
199
+
<methodname>DateTimeImmutable::diff</methodname> or
200
+
<methodname>DateTime::diff</methodname>, then this is the
201
+
total number of full days between the start and end dates. Otherwise,
169
202
<varname>days</varname> will be &false;.
170
203
</para>
204
+
</listitem>
205
+
</varlistentry>
206
+
<varlistentry xml:id="dateinterval.props.from-string">
207
+
<term><varname>from_string</varname></term>
208
+
<listitem>
171
209
<para>
172
-
Before PHP 5.4.20/5.5.4 instead of &false; you will receive -99999 upon
173
-
accessing the property.
210
+
If the DateInterval object was created by
211
+
<methodname>DateInterval::createFromDateString</methodname>, then
212
+
this property's value will be &true;, and the
213
+
<varname>date_string</varname> property will be populated. Otherwise,
214
+
the value will be &false;, and the <varname>y</varname> to
215
+
<varname>f</varname>, <varname>invert</varname>, and
216
+
<varname>days</varname> properties will be populated.
217
+
</para>
218
+
</listitem>
219
+
</varlistentry>
220
+
<varlistentry xml:id="dateinterval.props.date-string">
221
+
<term><varname>date_string</varname></term>
222
+
<listitem>
223
+
<para>
224
+
The string used as argument to
225
+
<methodname>DateInterval::createFromDateString</methodname>.
174
226
</para>
175
227
</listitem>
176
228
</varlistentry>
177
229
</variablelist>
178
230
</section>
179
231

232
+
<section role="changelog" xml:id="dateinterval.changelog"><!-- {{{ -->
233
+
&reftitle.changelog;
234
+
<para>
235
+
<informaltable>
236
+
<tgroup cols="2">
237
+
<thead>
238
+
<row>
239
+
<entry>&Version;</entry>
240
+
<entry>&Description;</entry>
241
+
</row>
242
+
</thead>
243
+
<tbody>
244
+
<row>
245
+
<entry>8.2.0</entry>
246
+
<entry>
247
+
The <varname>from_string</varname> and <varname>date_string</varname>
248
+
properties were added for <classname>DateInterval</classname>
249
+
instances that were created using the
250
+
<methodname>DateInterval::createFromDateString</methodname> method.
251
+
</entry>
252
+
</row>
253
+
<row>
254
+
<entry>8.2.0</entry>
255
+
<entry>
256
+
Only the <literal>y</literal> to <literal>f</literal>,
257
+
<literal>invert</literal>, and <literal>days</literal> will be visible.
258
+
</entry>
259
+
</row>
260
+
<row>
261
+
<entry>7.4.0</entry>
262
+
<entry>
263
+
<classname>DateInterval</classname> instances are incomparable now;
264
+
previously, all <classname>DateInterval</classname> instances were considered equal.
265
+
</entry>
266
+
</row>
267
+
<row>
268
+
<entry>7.1.0</entry>
269
+
<entry>The <varname>f</varname> property was added.</entry>
270
+
</row>
271
+
</tbody>
272
+
</tgroup>
273
+
</informaltable>
274
+
</para>
275
+
</section><!-- }}} -->
276
+

180
277
</partintro>
181
278

182
279
&reference.datetime.entities.dateinterval;
183
280

184
281
</phpdoc:classref>
185
-

186
282
<!-- Keep this comment at the end of the file
187
283
Local variables:
188
284
mode: sgml
189
285