toDateFormat method

String toDateFormat(
  1. String format, {
  2. String? locale,
  3. bool showLogTimeMilliseconds = false,
})

Formats this DateTime with an explicit intl format pattern.

Returns '' (never throws) on an invalid pattern, honoring the "always renders something" contract callers rely on for display. showLogTimeMilliseconds appends a 4-digit .0137 millisecond suffix for log timestamps.

Example:

DateTime(2026, 1, 15, 22, 30).toDateFormat('HH:mm'); // '22:30'

Audited: 2026-06-12 11:26 EDT

Implementation

String toDateFormat(
  String format, {
  String? locale,
  bool showLogTimeMilliseconds = false,
}) {
  // intl echoes unrecognized field letters (e.g. 'q') as literals instead of
  // throwing, so the try/catch alone cannot enforce the contract — reject
  // unknown fields up front so an invalid pattern degrades to '' as documented.
  if (_patternHasUnknownField(format)) {
    return '';
  }
  try {
    final String suffix = showLogTimeMilliseconds
        ? '.${millisecond.toString().padLeft(4, '0')}'
        : '';
    return DateFormat(format, locale).format(this) + suffix;
    // Invalid pattern / locale must degrade to empty rather than crash a UI.
    // ignore: require_catch_logging -- display contract: never throw, callers get ''
  } on Object {
    return '';
  }
}