Class PeriodFormatter

java.lang.Object
cloud.opencode.base.date.formatter.PeriodFormatter
public final class PeriodFormatter extends Object
Formats and parses Period and Duration objects as human-readable strings 将Period和Duration对象格式化和解析为人类可读的字符串

This class provides methods to format periods and durations into various human-readable formats, and parse strings back into temporal amounts.

此类提供将周期和持续时间格式化为各种人类可读格式的方法， 并将字符串解析回时间量。

Features | 主要功能:

  • Format Period as readable string - 将Period格式化为可读字符串
  • Format Duration as readable string - 将Duration格式化为可读字符串
  • Parse human-readable strings - 解析人类可读的字符串
  • Multiple format styles (full, short, compact) - 多种格式样式

Usage Examples | 使用示例:

Period period = Period.of(1, 2, 15);
String formatted = PeriodFormatter.format(period);
// "1 year, 2 months, 15 days"

Duration duration = Duration.ofHours(25).plusMinutes(30);
String durationStr = PeriodFormatter.format(duration);
// "1 day, 1 hour, 30 minutes"

// Parse back
Period parsed = PeriodFormatter.parsePeriod("2 years 3 months");
Duration parsedDur = PeriodFormatter.parseDuration("5h 30m");

Security | 安全性:

  • Thread-safe: Yes - 线程安全: 是
  • Null-safe: Yes (with explicit null checks) - 空值安全: 是（有明确的空值检查）

Performance | 性能特性:

  • Time complexity: O(1) for format methods (fixed number of period/duration fields); O(n) for parsePeriod/parseDuration where n=input string length (regex match) - 时间复杂度: format 方法为 O(1)（固定数量的周期/持续时间字段）；parsePeriod/parseDuration 为 O(n)，n 为输入字符串长度（正则匹配）
  • Space complexity: O(1) - compiled regex patterns are cached as static fields - 空间复杂度: O(1) - 编译的正则表达式模式缓存为静态字段
Since:
JDK 25, opencode-base-date V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    format(Duration duration)
    Formats a Duration as a human-readable string 将Duration格式化为人类可读的字符串
    static String
    format(Period period)
    Formats a Period as a human-readable string 将Period格式化为人类可读的字符串
    static String
    format(TemporalAmount amount)
    Formats any TemporalAmount as a human-readable string 将任意TemporalAmount格式化为人类可读的字符串
    static String
    formatChinese(Duration duration)
    Formats a Duration as a Chinese string 将Duration格式化为中文字符串
    static String
    formatChinese(Period period)
    Formats a Period as a Chinese string 将Period格式化为中文字符串
    static String
    formatCompact(Duration duration)
    Formats a Duration in compact form (e.g., "PT1H30M") 将Duration格式化为紧凑格式（如"PT1H30M"）
    static String
    formatCompact(Period period)
    Formats a Period in compact form (e.g., "P1Y2M15D") 将Period格式化为紧凑格式（如"P1Y2M15D"）
    static String
    formatShort(Duration duration)
    Formats a Duration in short form (e.g., "1d 2h 30m 15s") 将Duration格式化为短格式（如"1d 2h 30m 15s"）
    static String
    formatShort(Period period)
    Formats a Period in short form (e.g., "1y 2m 15d") 将Period格式化为短格式（如"1y 2m 15d"）
    static String
    formatTime(Duration duration)
    Formats a Duration as time format (HH:MM:SS) 将Duration格式化为时间格式（HH:MM:SS）
    static Duration
    parseDuration(String text)
    Parses a string into a Duration 将字符串解析为Duration
    static Period
    parsePeriod(String text)
    Parses a string into a Period 将字符串解析为Period
    static Duration
    tryParseDuration(String text)
    Tries to parse a string into a Duration, returning null if parsing fails 尝试将字符串解析为Duration，如果解析失败则返回null
    static Period
    tryParsePeriod(String text)
    Tries to parse a string into a Period, returning null if parsing fails 尝试将字符串解析为Period，如果解析失败则返回null

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • format

      public static String format(Period period)
      Formats a Period as a human-readable string 将Period格式化为人类可读的字符串
      Parameters:
      period - the period to format | 要格式化的Period
      Returns:
      the formatted string | 格式化的字符串

    • formatChinese

      public static String formatChinese(Period period)
      Formats a Period as a Chinese string 将Period格式化为中文字符串
      Parameters:
      period - the period to format | 要格式化的Period
      Returns:
      the formatted string in Chinese | 中文格式化的字符串

    • formatShort

      public static String formatShort(Period period)
      Formats a Period in short form (e.g., "1y 2m 15d") 将Period格式化为短格式（如"1y 2m 15d"）
      Parameters:
      period - the period to format | 要格式化的Period
      Returns:
      the short formatted string | 短格式字符串

    • formatCompact

      public static String formatCompact(Period period)
      Formats a Period in compact form (e.g., "P1Y2M15D") 将Period格式化为紧凑格式（如"P1Y2M15D"）
      Parameters:
      period - the period to format | 要格式化的Period
      Returns:
      the compact formatted string | 紧凑格式字符串

    • format

      public static String format(Duration duration)
      Formats a Duration as a human-readable string 将Duration格式化为人类可读的字符串
      Parameters:
      duration - the duration to format | 要格式化的Duration
      Returns:
      the formatted string | 格式化的字符串

    • formatChinese

      public static String formatChinese(Duration duration)
      Formats a Duration as a Chinese string 将Duration格式化为中文字符串
      Parameters:
      duration - the duration to format | 要格式化的Duration
      Returns:
      the formatted string in Chinese | 中文格式化的字符串

    • formatShort

      public static String formatShort(Duration duration)
      Formats a Duration in short form (e.g., "1d 2h 30m 15s") 将Duration格式化为短格式（如"1d 2h 30m 15s"）
      Parameters:
      duration - the duration to format | 要格式化的Duration
      Returns:
      the short formatted string | 短格式字符串

    • formatTime

      public static String formatTime(Duration duration)
      Formats a Duration as time format (HH:MM:SS) 将Duration格式化为时间格式（HH:MM:SS）
      Parameters:
      duration - the duration to format | 要格式化的Duration
      Returns:
      the time formatted string | 时间格式字符串

    • formatCompact

      public static String formatCompact(Duration duration)
      Formats a Duration in compact form (e.g., "PT1H30M") 将Duration格式化为紧凑格式（如"PT1H30M"）
      Parameters:
      duration - the duration to format | 要格式化的Duration
      Returns:
      the compact formatted string | 紧凑格式字符串

    • parsePeriod

      public static Period parsePeriod(String text)
      Parses a string into a Period 将字符串解析为Period
      Parameters:
      text - the text to parse | 要解析的文本
      Returns:
      the parsed Period | 解析的Period
      Throws:
      IllegalArgumentException - if the text cannot be parsed | 如果文本无法解析则抛出异常

    • parseDuration

      public static Duration parseDuration(String text)
      Parses a string into a Duration 将字符串解析为Duration
      Parameters:
      text - the text to parse | 要解析的文本
      Returns:
      the parsed Duration | 解析的Duration
      Throws:
      IllegalArgumentException - if the text cannot be parsed | 如果文本无法解析则抛出异常

    • tryParsePeriod

      public static Period tryParsePeriod(String text)
      Tries to parse a string into a Period, returning null if parsing fails 尝试将字符串解析为Period，如果解析失败则返回null
      Parameters:
      text - the text to parse | 要解析的文本
      Returns:
      the parsed Period, or null if parsing fails | 解析的Period，如果解析失败则返回null

    • tryParseDuration

      public static Duration tryParseDuration(String text)
      Tries to parse a string into a Duration, returning null if parsing fails 尝试将字符串解析为Duration，如果解析失败则返回null
      Parameters:
      text - the text to parse | 要解析的文本
      Returns:
      the parsed Duration, or null if parsing fails | 解析的Duration，如果解析失败则返回null

    • format

      public static String format(TemporalAmount amount)
      Formats any TemporalAmount as a human-readable string 将任意TemporalAmount格式化为人类可读的字符串
      Parameters:
      amount - the temporal amount to format | 要格式化的时间量
      Returns:
      the formatted string | 格式化的字符串