date_filter_search

date_filter_search is a Rust library that streamlines working with dates. It provides robust functionality for converting dates to Unix seconds and Unix seconds back into dates, validating and auto-completing incomplete date inputs, configuring the active time zone, and parsing both absolute and relative date search queries for powerful date filtering.

Main Features

• Bi-directional Conversion: Convert dates to Unix seconds and convert Unix seconds back into human-readable dates.
• Date Validation and Completion: Validate date strings and automatically complete missing parts using default minimum or maximum values.
• Configurable Time Zone: Easily switch between local time and UTC by setting a global time zone.
  • Versatile Parsing and Search: Parse search queries—both absolute and relative—and obtain a time interval (start and end) in seconds for filtering dates.
  • Relative Search: Use keys Y, M, D, h, m, s for time intervals. Examples:
    • "10m": 10 minutes from now.
    • "2Y": 2 years from now.
    • "6M": 6 months from now.
  • Absolute Search: Specify complete dates or date ranges using allowed separators such as /, -, _, space, :, ;, ., or ,. Examples:
    • "2023-04-05 10:20:30": an exact date.
    • "2022-12": the entire month of December 2022.
    • "2021-3 to 2021-6": from March 2021 to June 2021.

Main Capabilities

• Bi-directional Conversion: Easily convert between DateTime structures and Unix seconds.
• Auto-completion of Incomplete Dates: Validate dates and fill in missing values automatically.
• Global Time Zone Setting: Customize your date handling by setting the time zone (Local or UTC).
• Flexible Search Parsing: Parse both relative and absolute date strings to derive time intervals for date filtering.

Installation

Add the following to your Cargo.toml file:

[dependencies]
date_filter_search = "0.1.1"

Be sure to update the version as necessary.

Usage

A practical example is available in the examples/ folder that demonstrates how to use date_filter_search in a command-line application. To run the example:

cargo run --example demo -- 1Y

Replace 1Y with the search query you wish to test (e.g., 10m, 2021-3 to 2021-6, etc.).

Demo Output

Below is a screenshot of the terminal output from the demo:

Main Functions

• parsing_search(input: &str) -> Result<(u64, u64), DateError> Parses the input as either an absolute or relative date search query and returns a tuple of Unix seconds representing the start and end of the interval.

• search_generic(target: u64, lower_bound: u64, upper_bound: u64) -> bool Determines whether the target Unix seconds timestamp falls within the specified interval.

• string_to_date_seconds(input: &str) -> Result<u64, DateError> Converts a date string into Unix seconds from the defined epoch.

• date_to_seconds(dt: DateTime) -> u64 Converts a DateTime structure into Unix seconds.

• seconds_to_date(seconds: u64) -> DateTime Converts Unix seconds back into a DateTime structure.

• validate_datetime(input: &str, default: bool) -> Result<DateTime, DateError> Validates and auto-completes a date string, returning a complete DateTime structure.

Error Handling

The library uses a custom DateError enum for error handling. Common error variants include:

• EmptyInput: The provided input is empty.
• InvalidDateFormat: The date format does not match the expected pattern.
• InvalidRegex: The regex pattern for parsing is incorrect.
• OutOfRange(String): A date component is out of the allowed range.
• ParsingError(String): An error occurred during value parsing.
• IncorrectUnit(String): An unrecognized unit was provided in a relative date.

Contributing

Contributions are welcome! To contribute:

• Fork the repository.
• Implement your changes.
• Open a pull request describing your modifications.

License

This project is distributed under the GNU General Public License (GPL), ensuring the freedom to modify and redistribute the software in accordance with free software standards.

Author

Written by Catoni Mirko (IMprojtech)

Contacts and Resources

• GitHub Repository: (https://github.com/IMprojtech/Date_Filter_Search)
• Issue Tracker: Use the GitHub repository to report issues or request new features.