間隔をフォーマットする

# DateInterval::format

(PHP 5 >= 5.3.0, PHP 7)

DateInterval::format — 間隔をフォーマットする

### 説明

public DateInterval::format ( string `$format` ) : string

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

### パラメータ

`format`

  次の文字を、 `format` パラメータ文字列に使用することができます。 フォーマット文字は、パーセント記号 (%) で始めなければなりません。
  `format` 文字 | 説明 | 値の例
  --- | --- | ---
  % | リテラルとしての % | %
  Y | 年、数値、先頭に 0 を含む 2 桁 | 01, 03
  y | 年、数値 | 1, 3
  M | 月、数値、先頭に 0 を含む 2 桁 | 01, 03, 12
  m | 月、数値 | 1, 3, 12
  D | 日、数値、先頭に 0 を含む 2 桁 | 01, 03, 31
  d | 日、数値 | 1, 3, 31
  a | DateTime::diff() の結果に使った場合は総日数、それ以外の場合は (unknown) | 4, 18, 8123
  H | 時間、数値、先頭に 0 を含む 2 桁 | 01, 03, 23
  h | 時間、数値 | 1, 3, 23
  I | 分、数値、先頭に 0 を含む 2 桁 | 01, 03, 59
  i | 分、数値 | 1, 3, 59
  S | 秒、数値、先頭に 0 を含む 2 桁 | 01, 03, 57
  s | 秒、数値 | 1, 3, 57
  R | 負の値の場合は "-"、正の値の場合は "+" | -, +
  r | 負の値の場合は "-"、正の値の場合は空文字 | -,

### 返り値

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

### 注意

> 注意:

> DateInterval::format() メソッドは、 時刻文字列や日付セグメントでの繰り越しを再計算しません。 これは意図的な仕様です。なぜなら "32 days" のようにオーバーフローした値は "1 month and 4 days" から "1 month and 1 day" までのどれとでも解釈可能だからです。

### 例

例1 DateInterval の例

`<?php
$interval = new DateInterval('P2Y4DT6H8M');
echo $interval->format('%d days');
?>`

上の例の出力は以下となります。

    4 days

例2 DateInterval での繰り越しの例

`<?php
$interval = new DateInterval('P32D');
echo $interval->format('%d days');
?>`

上の例の出力は以下となります。

    32 days

例3 DateInterval および DateTime::diff() での修飾子 %a および %d

`<?php
$january = new DateTime('2010-01-01');
$february = new DateTime('2010-02-01');
$interval = $february->diff($january);
// %a は総日数を出力します
echo $interval->format('%a total days')."\n";
// 一方 %d は、月数に含まれない日数のみを出力します
echo $interval->format('%m month, %d days');
?>`

上の例の出力は以下となります。

    31 total days
    1 month, 0 days

### 参考

- DateTime::diff() - ふたつの DateTime オブジェクトの差を返す