<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="dateinterval.format" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

<refnamediv>

<refname>DateInterval::format</refname>

<refpurpose>間隔をフォーマットする</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis role="DateInterval">

<modifier>public</modifier> <type>string</type><methodname>DateInterval::format</methodname>

<methodparam><type>string</type><parameter>format</parameter></methodparam>

</methodsynopsis>

<para>

間隔をフォーマットします。

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>format</parameter></term>

<listitem>

<para>

<table>

<title>

次の文字を、

<parameter>format</parameter> パラメータ文字列に使用することができます。

フォーマット文字は、パーセント記号

(<literal>%</literal>) で始めなければなりません。

</title>

<tgroup cols="3">

<thead>

<row>

<entry><parameter>format</parameter> 文字</entry>

<entry>説明</entry>

<entry>値の例</entry>

</row>

</thead>

<tbody>

<row>

<entry><literal>%</literal></entry>

<entry>リテラルとしての <literal>%</literal></entry>

<entry><literal>%</literal></entry>

</row>

<row>

<entry><literal>Y</literal></entry>

<entry>年、数値、先頭に 0 を含む 2 桁</entry>

<entry><literal>01</literal>, <literal>03</literal></entry>

</row>

<row>

<entry><literal>y</literal></entry>

<entry>年、数値</entry>

<entry><literal>1</literal>, <literal>3</literal></entry>

</row>

<row>

<entry><literal>M</literal></entry>

<entry>月、数値、先頭に 0 を含む 2 桁</entry>

<entry><literal>01</literal>, <literal>03</literal>, <literal>12</literal></entry>

</row>

<row>

<entry><literal>m</literal></entry>

<entry>月、数値</entry>

<entry><literal>1</literal>, <literal>3</literal>, <literal>12</literal></entry>

</row>

<row>

<entry><literal>D</literal></entry>

<entry>日、数値、先頭に 0 を含む 2 桁</entry>

<entry><literal>01</literal>, <literal>03</literal>, <literal>31</literal></entry>

</row>

<row>

<entry><literal>d</literal></entry>

<entry>日、数値</entry>

<entry><literal>1</literal>, <literal>3</literal>, <literal>31</literal></entry>

</row>

<row>

<entry><literal>a</literal></entry>

<entry><methodname>DateTime::diff</methodname> の結果に使った場合は総日数、それ以外の場合は <literal>(unknown)</literal></entry>

<entry><literal>4</literal>, <literal>18</literal>, <literal>8123</literal></entry>

</row>

<row>

<entry><literal>H</literal></entry>

<entry>時間、数値、先頭に 0 を含む 2 桁</entry>

<entry><literal>01</literal>, <literal>03</literal>, <literal>23</literal></entry>

</row>

<row>

<entry><literal>h</literal></entry>

<entry>時間、数値</entry>

<entry><literal>1</literal>, <literal>3</literal>, <literal>23</literal></entry>

</row>

<row>

<entry><literal>I</literal></entry>

<entry>分、数値、先頭に 0 を含む 2 桁</entry>

<entry><literal>01</literal>, <literal>03</literal>, <literal>59</literal></entry>

</row>

<row>

<entry><literal>i</literal></entry>

<entry>分、数値</entry>

<entry><literal>1</literal>, <literal>3</literal>, <literal>59</literal></entry>

</row>

<row>

<entry><literal>S</literal></entry>

<entry>秒、数値、先頭に 0 を含む 2 桁</entry>

<entry><literal>01</literal>, <literal>03</literal>, <literal>57</literal></entry>

</row>

<row>

<entry><literal>s</literal></entry>

<entry>秒、数値</entry>

<entry><literal>1</literal>, <literal>3</literal>, <literal>57</literal></entry>

</row>

<row>

<entry><literal>F</literal></entry>

<entry>マイクロ秒、少なくとも6桁。足りない分は先頭が0埋めされます。

</entry>

<entry><literal>007701</literal>, <literal>052738</literal>, <literal>428291</literal></entry>

</row>

<row>

<entry><literal>f</literal></entry>

<entry>マイクロ秒、数値</entry>

<entry><literal>7701</literal>, <literal>52738</literal>, <literal>428291</literal></entry>

</row>

<row>

<entry><literal>R</literal></entry>

<entry>負の値の場合は "<literal>-</literal>"、正の値の場合は "<literal>+</literal>"</entry>

<entry><literal>-</literal>, <literal>+</literal></entry>

</row>

<row>

<entry><literal>r</literal></entry>

<entry>負の値の場合は "<literal>-</literal>"、正の値の場合は空文字</entry>

<entry><literal>-</literal>, <literal/></entry>

</row>

</tbody>

</tgroup>

</table>

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

フォーマットされた間隔を返します。

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<para>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>7.2.12</entry>

<entry><literal>F</literal> と <literal>f</literal>

フォーマットの値は、常に正の数値になりました。</entry>

</row>

<row>

<entry>7.1.0</entry>

<entry>

フォーマット文字 <literal>F</literal> と <literal>f</literal> が追加されました。

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title><classname>DateInterval</classname> の例</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen role="php">

</screen>

</example>

</para>

<para>

<example>

<title><classname>DateInterval</classname> での繰り越しの例</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen role="php">

</screen>

</example>

</para>

<para>

<example>

<title>

<classname>DateInterval</classname> および

<methodname>DateTime::diff</methodname> での修飾子 %a および %d

</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen role="php">

</screen>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<note>

<para>

<methodname>DateInterval::format</methodname> メソッドは、

時刻文字列や日付セグメントでの繰り越しを再計算しません。

これは意図的な仕様です。なぜなら <literal>"32 days"</literal>

のようにオーバーフローした値は <literal>"1 month and 4 days"</literal>

から <literal>"1 month and 1 day"</literal>

までのどれとでも解釈可能だからです。

</para>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><methodname>DateTime::diff</methodname></member>

</simplelist>

</para>

</refsect1>

</refentry>