formatTimeInput static method

String formatTimeInput(String input, { bool isUtc = true, bool showLocalIndicator = false, })

Formats time input text into display format

Converts digits-only input into formatted time string with appropriate timezone suffix.

Examples (UTC):

• "1" → "01:00 z"
• "12" → "12:00 z"
• "25" → "01:00 z" (hour 25 wraps to 01)
• "200" → "20:00 z" (HH:M0 format, valid hour)
• "100" → "10:00 z" (HH:M0 format, valid hour)
• "230" → "23:00 z" (HH:M0 format, valid hour)
• "240" → "00:00 z" (hour 24 wraps to 00)
• "250" → "01:00 z" (hour 25 wraps to 01)
• "253" → "01:30 z" (hour 25 wraps to 01, M0 = 30)
• "330" → "03:30 z" (0H:MM format, hour 33 > 25 so use first digit as hour)
• "300" → "03:00 z" (0H:MM format, hour 30 > 25)
• "945" → "09:45 z" (0H:MM format, hour 94 > 25)
• "1234" → "12:34 z"
• "2440" → "00:40 z" (hour 24 wraps to 00)
• "2530" → "01:30 z" (hour 25 wraps to 01)

3-digit logic:

• If first two digits form a valid hour (0-23), treat as HH:M0 format
• If first two digits are 24-29, wrap the hour (% 24) and treat as HH:M0 format
• If first two digits >= 30 and last two digits form valid minutes (0-59), treat as 0H:MM format
• Otherwise, wrap the hours and use HH:M0 format

Examples:

• "253" → "01:30 z" (hour 25, wrap to 01, M0 = 30)
• "264" → "02:40 z" (hour 26, wrap to 02, M0 = 40)
• "297" → "05:70 z" (hour 29, wrap to 05, M0 = 70 - invalid but formatted)

Hour wrapping:

• Hours 24-99 are wrapped using modulo 24 (e.g., 25 → 01, 48 → 00)
• Applied to 2-digit, 3-digit (hours 24-25), and 4-digit inputs

Examples (Local with indicator):

• "1234" → "12:34 ʟ"

Examples (Local without indicator):

• "1234" → "12:34"

Process:

1. Remove all non-digit characters
2. Handle empty input
3. Pad with zeros to ensure proper formatting
4. Format based on length (1-4 digits) with intelligent 3-digit handling
5. Wrap hours > 23 using modulo 24
6. Add appropriate timezone suffix

input - Raw input string (may contain non-digits) isUtc - Whether the time is in UTC (defaults to true) showLocalIndicator - Whether to show 'L' for local time (defaults to false) Returns formatted time string (e.g., "HH:MM z", "HH:MM L", or "HH:MM") or empty string

Implementation

static String formatTimeInput(
  String input, {
  bool isUtc = true,
  bool showLocalIndicator = false,
}) {
  // Strip all non-digit characters using cached regex
  input = _removeNonDigits(input);

  // Handle empty input
  if (input.isEmpty) {
    return '';
  }

  // Get the appropriate suffix
  final suffix = TimezoneSuffixHelper.getSuffix(
    isUtc: isUtc,
    showLocalIndicator: showLocalIndicator,
  );

  // Format based on length
  if (input.length == 1) {
    // First typed digit fills the tens-of-hours slot (left-to-right entry: "1" → "10:00").
    return '${input[0]}0:00$suffix';
  } else if (input.length == 2) {
    // Two digits map directly to HH.
    return '$input:00$suffix';
  } else if (input.length == 3) {
    // Three digits map deterministically to HH:M0.
    return '${input.substring(0, 2)}:${input[2]}0$suffix';
  } else if (input.length >= 4) {
    // Four (or more) digits map directly to HH:MM using the first four digits.
    final hours = input.substring(0, 2);
    final minutes = input.substring(2, 4);
    return '$hours:$minutes$suffix';
  }
  return input;
}