[doc-en] master: localtime, parse, parseToCalendar: correct the offset semantics (#4820)

From: 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 &gt; 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> &gt; <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> &gt; <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>

« previous php.doc.cvs (#23685) next »