> ## Documentation Index
> Fetch the complete documentation index at: https://neo.tvk.company/llms.txt
> Use this file to discover all available pages before exploring further.

# Date Validator

> A comprehensive utility class for validating, parsing, and formatting dates with detailed error messages and various validation rules.

## Examples

<Tabs>
  <Tab title="Basic Validation">
    <CodeGroup>
      ```dart Simple Validation lines theme={null}
      DateTime date = NeoDateValidator.validate("31-10-2024");
      ```

      ```dart With Error Handling lines theme={null}
      try {
        DateTime date = NeoDateValidator.validate("25-12-2023");
        NeoLogger.trace("Valid date: $date");
      } catch (e) {
        NeoLogger.error("This is not a valid date", error: e);
      }
      ```

      ```dart With Business Rules lines theme={null}
      try {
        DateTime date = NeoDateValidator.validate("25-12-2023");
        NeoDateValidator.validateIsNotFuture(date);
        NeoLogger.trace("Valid past date");
      } on FormatException catch (e) {
        NeoLogger.error("This is not a valid date", error: e);
      } on ArgumentError catch (e) {
        NeoLogger.error("Date cannot be in the future", error: e);
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Date Formatting">
    <CodeGroup>
      ```dart Format DateTime lines theme={null}
      final date = DateTime(2023, 12, 25);
      String formatted = NeoDateValidator.format(date); // "25-12-2023"
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Form Integration">
    <CodeGroup>
      ```dart With NeoDateField lines theme={null}
      final dateString = useState("");
      final errorMessage = useState<String?>(null);

      NeoDateField(
        dateString: dateString.value,
        label: "Birth Date",
        errorText: errorMessage.value,
        onSubmitted: (value) {
          dateString.value = value;
          try {
            final date = NeoDateValidator.validate(value);
            NeoDateValidator.validateIsNotFuture(date);
            errorMessage.value = null;
          } on FormatException catch (e) {
            errorMessage.value = e.message;
          } on ArgumentError catch (e) {
            errorMessage.value = e.message;
          }
        },
      ),
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Methods

### NeoDateValidator.validate()

Validates and parses a date string in DD-MM-YYYY format with comprehensive error checking.

#### Parameters

<ParamField path="dateString" type="String" required>
  The date string to validate in DD-MM-YYYY format.
</ParamField>

#### Return Value

<ParamField path="returns" type="DateTime">
  The parsed DateTime if the string is valid.
</ParamField>

#### Exceptions

<ParamField path="throws" type="FormatException">
  Thrown with specific error messages for invalid formats, incomplete segments, or invalid dates (e.g., "Day 30 is not valid for February 2023").
</ParamField>

### NeoDateValidator.validateIsBefore()

Validates that a date occurs before another specified date.

#### Parameters

<ParamField path="date" type="DateTime" required>
  The date to validate.
</ParamField>

<ParamField path="beforeDate" type="DateTime" required>
  The date that `date` must be before.
</ParamField>

#### Exceptions

<ParamField path="throws" type="ArgumentError">
  Thrown if the date is not before the specified date.
</ParamField>

### NeoDateValidator.validateIsAfter()

Validates that a date occurs after another specified date.

#### Parameters

<ParamField path="date" type="DateTime" required>
  The date to validate.
</ParamField>

<ParamField path="afterDate" type="DateTime" required>
  The date that `date` must be after.
</ParamField>

#### Exceptions

<ParamField path="throws" type="ArgumentError">
  Thrown if the date is not after the specified date.
</ParamField>

### NeoDateValidator.validateIsInRange()

Validates that a date falls within a specified range (inclusive).

#### Parameters

<ParamField path="date" type="DateTime" required>
  The date to validate.
</ParamField>

<ParamField path="startDate" type="DateTime" required>
  The start of the valid range (inclusive).
</ParamField>

<ParamField path="endDate" type="DateTime" required>
  The end of the valid range (inclusive).
</ParamField>

#### Exceptions

<ParamField path="throws" type="ArgumentError">
  Thrown if the date is not within the specified range.
</ParamField>

### NeoDateValidator.validateIsNotFuture()

Validates that a date is not in the future (today or earlier).

#### Parameters

<ParamField path="date" type="DateTime" required>
  The date to validate.
</ParamField>

#### Exceptions

<ParamField path="throws" type="ArgumentError">
  Thrown if the date is in the future.
</ParamField>

### NeoDateValidator.validateIsNotPast()

Validates that a date is not in the past (today or later).

#### Parameters

<ParamField path="date" type="DateTime" required>
  The date to validate.
</ParamField>

#### Exceptions

<ParamField path="throws" type="ArgumentError">
  Thrown if the date is in the past.
</ParamField>

### NeoDateValidator.format()

Formats a DateTime object to a DD-MM-YYYY string.

#### Parameters

<ParamField path="date" type="DateTime" required>
  The DateTime object to format.
</ParamField>

#### Return Value

<ParamField path="returns" type="String">
  The formatted date string in DD-MM-YYYY format.
</ParamField>

## Best Practices

* **Handle exceptions properly**: Use try-catch blocks to handle `FormatException` and `ArgumentError` separately
* **Combine validation methods**: Chain multiple validations for comprehensive date checking
* **Use in form callbacks**: Validate in `onSubmitted` callbacks for immediate feedback
* **Implement business rules**: Combine with custom validation logic for application-specific requirements

## Integration Notes

* **Detailed error messages**: Provides specific error messages that can be displayed directly to users
* **NeoDateField integration**: Designed to work seamlessly with the string-based NeoDateField API