[doc-en] master: localtime, parse, parseToCalendar: correct the offset semantics (#4820)
| From: | Mikhail Alferov via GitHub | Date: | Tue, 01 Sep 2026 12:44:21 +0000 |
| Subject: | [doc-en] master: localtime, parse, parseToCalendar: correct the offset semantics (#4820) | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-23685@lists.php.net to get a copy of this message | ||
Author: Mikhail Alferov (mmalferov)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-09-01T14:44:19+02:00
Commit: https://github.com/php/doc-en/commit/8871302d240f124f7e9dabac85862e31bf97b442
Raw diff: https://github.com/php/doc-en/commit/8871302d240f124f7e9dabac85862e31bf97b442.diff
localtime, parse, parseToCalendar: correct the offset semantics (#4820)
offset never comes back as -1: it holds the position at which parsing ended,
on success and on failure alike, verified on PHP 8.5.4 with ext/intl. A value
past the end of the string fails immediately without touching it; on
localtime() and parse() a negative value does too, while parseToCalendar()
exempts -1 from that check.
Also finish the prose cleanup on localtime(): mark up the parameter
references the rename left behind, qualify the localtime() compatibility
claim since tm_yday is 1-based here and 0-based there, and describe the
formatter parameter of parse() as the object it has always been.
Co-authored-by: Louis-Arnaud <la.catoire@gmail.com>
Changed paths:
M reference/intl/dateformatter/localtime.xml
M reference/intl/dateformatter/parse.xml
M reference/intl/dateformatter/parsetocalendar.xml
Diff:
diff --git a/reference/intl/dateformatter/localtime.xml b/reference/intl/dateformatter/localtime.xml
index 8260e20578d5..eb2a35824357 100644
--- a/reference/intl/dateformatter/localtime.xml
+++ b/reference/intl/dateformatter/localtime.xml
@@ -25,11 +25,12 @@
<methodparam><type>string</type><parameter>string</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter
role="reference">offset</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
- <para>
- Converts string $value to a field-based time value ( an array of various fields), starting at
-$parse_pos and consuming as much of the input value as possible.
- </para>
- </refsect1>
+ <simpara>
+ Converts <parameter>string</parameter> to a field-based time value (an array
+ of various fields), starting at <parameter>offset</parameter> and consuming
+ as much of the input string as possible.
+ </simpara>
+ </refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
@@ -38,43 +39,48 @@ $parse_pos and consuming as much of the input value as possible.
<varlistentry>
<term><parameter>formatter</parameter></term>
<listitem>
- <para>
- The formatter resource
- </para>
+ <simpara>
+ The <classname>IntlDateFormatter</classname> object.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>string</parameter></term>
<listitem>
- <para>
- string to convert to a time
- </para>
+ <simpara>
+ String to convert to a time.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
- <para>
- Position at which to start the parsing in $value (zero-based).
- If no error occurs before $value is consumed, $parse_pos will contain -1
- otherwise it will contain the position at which parsing ended .
- If $parse_pos > strlen($value), the parse fails immediately.
- </para>
+ <simpara>
+ Position at which to start the parsing in <parameter>string</parameter>
+ (zero-based).
+ On return, <parameter>offset</parameter> holds the position at which
+ parsing ended, whether or not the parse succeeded.
+ If <parameter>offset</parameter> is negative or greater than
+ <literal>strlen($string)</literal>, the parse fails immediately and
+ <parameter>offset</parameter> is left unchanged.
+ </simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
-
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
- Localtime compatible array of integers : contains 24 hour clock value in tm_hour field,
- &return.falseforfailure;.
- </para>
+ <simpara>
+ An associative array of integers whose keys are those of
+ <function>localtime</function>, with the hour given on a 24-hour clock in
+ <literal>tm_hour</literal>&return.falseforfailure;.
+ Note that <literal>tm_yday</literal> is 1-based here, whereas
+ <function>localtime</function> returns it 0-based.
+ </simpara>
</refsect1>
-
+
<refsect1 role="examples">
&reftitle.examples;
<example>
@@ -90,7 +96,9 @@ $fmt = datefmt_create(
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
+
$arr = datefmt_localtime($fmt, 'Wednesday, December 31, 1969 at 4:00:00 PM Pacific Standard
Time', $offset);
+
echo 'First parsed output is ';
if ($arr) {
foreach ($arr as $key => $value) {
@@ -107,6 +115,7 @@ if ($arr) {
<programlisting role="php">
<![CDATA[
<?php
+
$fmt = new IntlDateFormatter(
'en_US',
IntlDateFormatter::FULL,
@@ -114,7 +123,9 @@ $fmt = new IntlDateFormatter(
'America/Los_Angeles',
IntlDateFormatter::GREGORIAN
);
+
$arr = $fmt->localtime('Wednesday, December 31, 1969 at 4:00:00 PM Pacific Standard
Time', $offset);
+
echo 'First parsed output is ';
if ($arr) {
foreach ($arr as $key => $value) {
diff --git a/reference/intl/dateformatter/parse.xml b/reference/intl/dateformatter/parse.xml
index ced1ea84843d..4d9505998e97 100644
--- a/reference/intl/dateformatter/parse.xml
+++ b/reference/intl/dateformatter/parse.xml
@@ -38,9 +38,9 @@
<varlistentry>
<term><parameter>formatter</parameter></term>
<listitem>
- <para>
- The formatter resource
- </para>
+ <simpara>
+ The <classname>IntlDateFormatter</classname> object.
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
@@ -54,13 +54,15 @@
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
- <para>
- Position at which to start the parsing in <parameter>string</parameter>
(zero-based).
- If no error occurs before <parameter>string</parameter> is consumed,
<parameter>offset</parameter> will contain -1
- otherwise it will contain the position at which parsing ended (and the error occurred).
- This variable will contain the end position if the parse fails.
- If <parameter>offset</parameter> >
<code>strlen($string)</code>, the parse fails immediately.
- </para>
+ <simpara>
+ Position at which to start the parsing in <parameter>string</parameter>
+ (zero-based).
+ On return, <parameter>offset</parameter> holds the position at which
+ parsing ended, whether or not the parse succeeded.
+ If <parameter>offset</parameter> is negative or greater than
+ <literal>strlen($string)</literal>, the parse fails immediately and
+ <parameter>offset</parameter> is left unchanged.
+ </simpara>
</listitem>
</varlistentry>
</variablelist>
diff --git a/reference/intl/dateformatter/parsetocalendar.xml
b/reference/intl/dateformatter/parsetocalendar.xml
index 3513b5aa8ae7..19e8e47c3f97 100644
--- a/reference/intl/dateformatter/parsetocalendar.xml
+++ b/reference/intl/dateformatter/parsetocalendar.xml
@@ -37,12 +37,13 @@
<term><parameter>offset</parameter></term>
<listitem>
<simpara>
- Position at which to start the parsing in <parameter>string</parameter>
(zero-based).
- If no error occurs before <parameter>string</parameter> is consumed,
- <parameter>offset</parameter> will contain -1, otherwise it will contain the
position
- at which parsing ended (and the error occurred).
- This variable will contain the end position if the parse fails.
- If <parameter>offset</parameter> >
<code>strlen($string)</code>, the parse fails immediately.
+ Position at which to start the parsing in <parameter>string</parameter>
+ (zero-based).
+ On return, <parameter>offset</parameter> holds the position at which
+ parsing ended, whether or not the parse succeeded.
+ If <parameter>offset</parameter> is greater than
+ <literal>strlen($string)</literal>, the parse fails immediately and
+ <parameter>offset</parameter> is left unchanged.
</simpara>
</listitem>
</varlistentry>