date_filter_search 0.1.1

Date Filter Search is a Rust library that makes working with dates a breeze. It seamlessly converts dates to Unix seconds and Unix seconds back to dates, validates and completes partial date inputs, supports a configurable time zone (Local or UTC), and features robust parsing of both absolute and relative search strings for powerful date filtering.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116


# 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:

```toml
[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:

![Demo Output Screenshot](Images/Screenshot.png)

## 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.