間隔をフォーマットする

# DateInterval::format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

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

### 説明

public function 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`
  `F` | マイクロ秒、少なくとも6桁。足りない分は先頭が0埋めされます。 | `007701`, `052738`, `428291`
  `f` | マイクロ秒、数値 | `7701`, `52738`, `428291`
  `R` | 負の値の場合は "`-`"、正の値の場合は "`+`" | `-`, `+`
  `r` | 負の値の場合は "`-`"、正の値の場合は空文字 | `-`, ``

### 戻り値

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

### 変更履歴

バージョン | 説明
--- | ---
7.2.12 | `F` と `f` フォーマットの値は、常に正の数値になりました。
7.1.0 | フォーマット文字 `F` と `f` が追加されました。

### 例

例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

### 注意

> 注意:

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

### 参考

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

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open