format method

String format({
  1. String pattern = 'dd-MM-yyyy',
})

Formats the current date-time object into a custom string pattern.

This method replaces specific placeholders in the given pattern with the corresponding date-time components, such as year, month, day, hour, minute, second, and more.

Supported Pattern Placeholders:

  • yyyy → Full year (e.g., 2025)
  • yy → Two-digit year (e.g., 25)
  • MMMM → Full month name (e.g., February)
  • MMM → Abbreviated month name (e.g., Feb)
  • MM → Two-digit month (e.g., 02)
  • M → Single-digit month (e.g., 2)
  • dd → Two-digit day (e.g., 05)
  • d → Single-digit day (e.g., 5)
  • EEEE → Full weekday name (e.g., Tuesday)
  • EEE → Abbreviated weekday name (e.g., Tue)
  • HH → 24-hour format (e.g., 17)
  • H → 24-hour format without leading zero (e.g., 5)
  • hh → 12-hour format (e.g., 05)
  • h → 12-hour format without leading zero (e.g., 5)
  • mm → Two-digit minutes (e.g., 09)
  • m → Single-digit minutes (e.g., 9)
  • ss → Two-digit seconds (e.g., 07)
  • s → Single-digit seconds (e.g., 7)
  • SSS → Milliseconds (e.g., 007)
  • a → AM/PM (e.g., PM)
  • Z → Time zone offset (e.g., +0530)
  • z → Time zone name (e.g., IST)
  • Q → Quarter of the year (e.g., 1, 2, 3, 4)
  • DD → Day of the year, three-digit (e.g., 036)
  • D → Day of the year (e.g., 36)
  • ww → ISO week number, two-digit (e.g., 06)
  • w → ISO week number (e.g., 6)
  • u → ISO weekday number (1 = Monday, 7 = Sunday)

Example Usage:

final date = DateTime(2025, 2, 5, 17, 54);
print(date.format(pattern: 'd MMMM, yyyy at h:mm a Q'));
// Output: "5 February, 2025 at 5:54 PM 1"

Implementation

String format({String pattern = 'dd-MM-yyyy'}) {
  final isPM = hour >= 12;
  final hour12 = hour % 12 == 0 ? 12 : hour % 12;

  String formatted = pattern;

  final patternMap = {
    'yyyy': year.toString(),
    'yy': year.toString().substring(2),
    'MMMM': monthName(),
    'MMM': monthName(isHalfName: true),
    'MM': month.addZeroPrefix().validate(),
    'M': month.toString(),
    'dd': day.addZeroPrefix().validate(),
    'd': day.toString(),
    'EEEE': weekdayName(),
    'EEE': weekdayName(isHalfName: true),
    'HH': hour.addZeroPrefix().validate(),
    'H': hour.toString(),
    'hh': hour12.addZeroPrefix().validate(),
    'h': hour12.toString(),
    'mm': minute.addZeroPrefix().validate(),
    'm': minute.toString(),
    'ss': second.addZeroPrefix().validate(),
    's': second.toString(),
    'SSS': millisecond.toString().padLeft(3, '0'),
    'a': isPM ? 'PM' : 'AM',
    'Z': timeZoneOffSet(),
    'z': timeZoneName,
    'Q': ((month - 1) ~/ 3 + 1).toString(),
    'DD': dayOfYear().toString().padLeft(3, '0'),
    'D': dayOfYear().toString(),
    'ww': weekOfYear().addZeroPrefix().validate(),
    'w': weekOfYear().toString(),
    'u': weekday.toString(),
  };

  // Replace using regex to avoid unwanted replacements
  patternMap.forEach((key, value) {
    formatted = formatted.replaceAllMapped(
        RegExp(r'\b' + key + r'\b'), (match) => value);
  });

  return formatted;
}