wtime 0.7.0

WTIME provides a variety of functions for obtaining the current UTC and local times, as well as generating customizable timestamps to suit your needs.
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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250

<div style="text-align: center;">
  <a href="https://crates.io/crates/wtime"><img src="logo.svg" alt="LOGO" /></a>
</div>

<div style="text-align: center;">
  <a href="https://github.com/dr-montasir/wtime"><img src="https://img.shields.io/badge/github-dr%20montasir%20/%20wtime-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="24" style="margin-top: 10px;" alt="github" /></a> <a href="https://crates.io/crates/wtime"><img src="https://img.shields.io/crates/v/wtime.svg?style=for-the-badge&color=fc8d62&logo=rust" height="24" style="margin-top: 10px;" alt="crates.io"></a> <a href="https://docs.rs/wtime"><img src="https://img.shields.io/badge/docs.rs-wtime-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="24" style="margin-top: 10px;" alt="docs.rs"></a> <a href="https://choosealicense.com/licenses/apache-2.0"><img src="https://img.shields.io/badge/license-apache_2.0-4a98f7.svg?style=for-the-badge&labelColor=555555&logo=apache" height="24" style="margin-top: 10px;" alt="license"></a> <a href="https://choosealicense.com/licenses/mit"><img src="https://img.shields.io/badge/license-mit-4a98f7.svg?style=for-the-badge&labelColor=555555" height="24" style="margin-top: 10px;" alt="license"></a>
</div>

# WTIME

**WTIME** provides a variety of functions for obtaining the current UTC and local times, as well as generating customizable timestamps to suit your needs.

---

## Table of Contents

- [Installation](#installation)
- [Changelog](#changelog)
- [Features](#features)
- [Usage](#usage)
- [Documentation](#documentation)
- [License](#license)
- [Contributing](#contributing)
- [Author](#author)

## Installation

**Run the following Cargo command in your project directory:**

```terminal
cargo add wtime
```

**Or add `wtime` to your `Cargo.toml` file:**

```toml
[dependencies]
wtime = "MAJOR.MINOR.PATCH" # Replace with the latest version
```

## Changelog

[![github](https://img.shields.io/badge/github-%20changelog-8da0cb?style=for-the-badge&labelColor=555555&logo=github)](https://github.com/dr-montasir/wtime/blob/main/CHANGELOG.md)

## Features

1. ### Current Time Retrieval

   - **UTC and Local Time**: WTIME offers seamless access to both current UTC and local times, making it easy to work with time zones and coordinate time-related functionalities.

2. ### Customizable Timestamps

   - **Flexible Formatting**: Generate timestamps in various formats to meet your specific requirements, whether for logging, database entries, or user interfaces.
   - **Configuration Options**: Tailor timestamp outputs to include or exclude specific components (e.g., date, time, time zone) based on your project needs.

3. ### Time Zone Support

   - **Multiple Time Zones**: Easily convert between different time zones, allowing for applications that require global time management.
   - **Daylight Saving Time Adjustments**: Automatic adjustments for daylight saving time ensure that your applications reflect accurate local time.

4. ### Easy Integration

   - **User-Friendly API**: The WTIME API is designed with simplicity in mind, allowing developers to implement time-related functions with minimal effort.
   - **Comprehensive Documentation**: Well-documented functions and examples help users quickly understand how to leverage the crate effectively.

5. ### High Performance

   - **Efficiency**: WTIME is optimized for performance, ensuring that time retrieval and manipulation operations are fast and resource-friendly.
   - **Lightweight**: The crate is designed to be lightweight, minimizing overhead while providing extensive functionality.

6. ### Unique ID (UID) Generation
   - **Timestamp-Based UIDs**: Generate unique identifiers derived from either the current UTC (uid_utc) or local server time (uid_local).
   - **Alphanumeric Obfuscation**: Digits within the timestamp are transformed into letters using a shifting alphabetical mapping, allowing for non-numeric, human-readable IDs.
   - **Flexible Formatting**: Control the output format by choosing whether to include hyphens as separators or generate a compact, continuous string of letters.
   - **Configurable Indexing**: Customize the alphabetical shift using an index parameter, providing control over the generated letter sequence while maintaining a time-based ID structure.

## Usage

### 1. CALC

```rust
use wtime::calc::{calc_date, calc_week, get_day_name};
use wtime::utc::get_day;

fn main() {
    let (year, month, day) = calc_date(1728933069);
    println!("Date: {}-{}-{}", year, month, day); // Date: 2024-10-14

    let week_number = calc_week((2024, 10, 14));
    println!("Week number: {}", week_number); // 42

    let day = get_day();
    let day_name = get_day_name(1_670_000_000);
    println!("Day name: {}", day_name); // Day name: Friday
    println!("Day name: {}", get_day_name(day));
}
```

### 2. LOCAL

```rust
use wtime::local::{format_local_ts, local_ts_nanos};
use wtime::utc::utc_ts_nanos;

fn main() {
    let local_timestamp_nanos = local_ts_nanos();
    println!("Current Local Timestamp in Nanoseconds: {}", local_timestamp_nanos);

    let utc_timestamp_nanos = utc_ts_nanos();
    println!("Current UTC Timestamp in Nanoseconds: {}", utc_timestamp_nanos);
    
    let timestamp = format_local_ts();
    println!("Formatted Local Timestamp: {}", timestamp);
}
```

### 3. TZ

```rust
use wtime::tz::{tz_number, tz_string};

fn main() {
    let offset_number = tz_number();
    println!("Current timezone offset in hours: {}", offset_number);

    let offset_string = tz_string();
    println!("Current timezone offset: {}", offset_string);
}
```

### 4. UTC

```rust
use wtime::utc::{format_utc_ts, get_day};

fn main() {
    let day = get_day();
    println!("Current day: {}", day);

    let timestamp = format_utc_ts();
    println!("Formatted UTC Timestamp: {}", timestamp);

    // Simulate generating a unique ID with a suffix
    let unique_id_with_suffix = format!("ID-{}-{}", format_utc_ts(), "random_suffix"); // Replace with actual random suffix function
    println!("Generated Unique ID with Suffix: {}", unique_id_with_suffix);

    // Simulate generating a unique ID without a suffix
    let unique_id_without_suffix = format!("ID-{}", format_utc_ts());
    println!("Generated Unique ID without Suffix: {}", unique_id_without_suffix);

    // Simulate generating a blog post UTC timestamp
    let blog_post_timestamp = format!("BlogPost Timestamp: {}", format_utc_ts());
    println!("Generated Blog Post UTC Timestamp: {}", blog_post_timestamp);
}
```

### 5. UID

```rust
use wtime::uid::{uid_utc, uid_local};

fn main() {
   let uid1 = uid_local(0, true);  // cacf-bc-ai-bf-de-af-hfc-efebaa
   let uid2 = uid_local(1, true);  // dbdg-cd-bj-cg-ef-bg-igd-gefbbb
   let uid3 = uid_utc(2, false);   // ecehdeckdefgchjhehhefcc
   let uid4 = uid_utc(3, false);   // fdfiefdlefghdikifijmedd
   let uid5 = uid_utc(4, false);   // gegjfgemfghiejljgjmkeee
   let uid6 = uid_utc(5, false);   // hfhkghfnghijfkmkhlfilff
   let uid7 = uid_utc(6, false);   // igilhigohijkglnlimihngg
   let uid8 = uid_utc(7, false);   // jhjmijhpijklhmomjnlhnhh
   let uid9 = uid_utc(8, false);   // kiknjkiqjklminpnkooilii
   let uid10 = uid_utc(9, false);  // ljlokljrklmnjoqolpqsnjj
   let uid11 = uid_utc(10, false); // mkmplmkslmnokprpmqttnkk
   let uid12 = uid_utc(11, false); // nlnqmnltmnoplqsqnsnmmll
   let uid13 = uid_utc(12, false); // omornomunopqmrtrotqtmmm
   let uid14 = uid_utc(13, false); // pnpsopnvopqrnsusputwonn
   let uid15 = uid_utc(14, false); // qoqtpqowpqrsotvtqvxqqoo
   let uid16 = uid_utc(15, false); // rpruqrpxqrstpuwurxqvqpp
   let uid17 = uid_utc(16, false); // sqsvrsqyrstuqvxvsyuquqq
   let uid18 = uid_utc(17, false); // trtwstrzstuvrwywtzxwwrr
   let uid19 = uid_utc(18, false); // usuxtusatuvwsxzxuaabxss
   let uid20 = uid_utc(19, false); // vtvyuvtbuvwxtyayvcuvytt
   let uid21 = uid_utc(20, false); // wuwzvwucvwxyuzbzwdxyyuu
   let uid22 = uid_utc(21, false); // xvxawxvdwxyzvacaxeazbvv
   let uid23 = uid_utc(22, false); // ywybxywexyzawbdbyfdzbww
   let uid24 = uid_utc(23, false); // zxzcyzxfyzabxceczggycxx
   let uid25 = uid_utc(24, false); // ayadzaygzabcydfdbyygayy
   let uid26 = uid_utc(25, false); // bzbeabzhabcdzegeczbdbzz
   let uid27 = uid_utc(26, false); // cacfbcaibcdeafhfdadjdaa
   let uid28 = uid_utc(27, false); // dbdgcdbjcdefbgigebgeebb

    println!("{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n{}", uid1, uid2, uid3, uid4, uid5, uid6, uid7, uid8, uid9, uid10, uid11, uid12, uid13, uid14, uid15, uid16, uid17, uid18, uid19, uid20, uid21, uid22, uid23, uid24, uid25, uid26, uid27, uid28);
}
```

## Documentation

### [CALC](https://docs.rs/wtime/latest/wtime/calc/index.html)

|                           Function                           |                           Function                           |                           Function                           |
| :----------------------------------------------------------: | :----------------------------------------------------------: | :----------------------------------------------------------: |
| [calc_date](https://docs.rs/wtime/latest/wtime/calc/fn.calc_date.html) | [calc_week](https://docs.rs/wtime/latest/wtime/calc/fn.calc_week.html) | [duration_since](https://docs.rs/wtime/latest/wtime/calc/fn.duration_since.html) |
| [get_day_name](https://docs.rs/wtime/latest/wtime/calc/fn.get_day_name.html) | [get_millis](https://docs.rs/wtime/latest/wtime/calc/fn.get_millis.html) | [get_minute](https://docs.rs/wtime/latest/wtime/calc/fn.get_minute.html) |
| [get_month_name](https://docs.rs/wtime/latest/wtime/calc/fn.get_month_name.html) | [get_nanos](https://docs.rs/wtime/latest/wtime/calc/fn.get_nanos.html) | [get_second](https://docs.rs/wtime/latest/wtime/calc/fn.get_second.html) |
|                              -                               | [is_leap_year](https://docs.rs/wtime/latest/wtime/calc/fn.is_leap_year.html) |                              -                               |

### [LOCAL](https://docs.rs/wtime/latest/wtime/local/index.html)

|                           Function                           |                           Function                           |                           Function                           |
| :----------------------------------------------------------: | :----------------------------------------------------------: | :----------------------------------------------------------: |
| [format_local_ts](https://docs.rs/wtime/latest/wtime/local/fn.format_local_ts.html) | [get_local_day](https://docs.rs/wtime/latest/wtime/local/fn.get_local_day.html) | [get_local_hour](https://docs.rs/wtime/latest/wtime/local/fn.get_local_hour.html) |
| [get_local_month](https://docs.rs/wtime/latest/wtime/local/fn.get_local_month.html) | [get_local_year](https://docs.rs/wtime/latest/wtime/local/fn.get_local_year.html) | [local_now](https://docs.rs/wtime/latest/wtime/local/fn.local_now.html) |
| [local_ts_millis](https://docs.rs/wtime/latest/wtime/local/fn.local_ts_millis.html) | [local_ts_nanos](https://docs.rs/wtime/latest/wtime/local/fn.local_ts_nanos.html) | [local_ts_sec](https://docs.rs/wtime/latest/wtime/local/fn.local_ts_sec.html) |

### [TZ](https://docs.rs/wtime/latest/wtime/tz/index.html)

|                               Function                               |                               Function                               |
| :------------------------------------------------------------------: | :------------------------------------------------------------------: |
| [tz_number](https://docs.rs/wtime/latest/wtime/tz/fn.tz_number.html) | [tz_string](https://docs.rs/wtime/latest/wtime/tz/fn.tz_string.html) |

### [UTC](https://docs.rs/wtime/latest/wtime/utc/index.html)

|                           Function                           |                           Function                           |                           Function                           |
| :----------------------------------------------------------: | :----------------------------------------------------------: | :----------------------------------------------------------: |
| [format_utc_ts](https://docs.rs/wtime/latest/wtime/utc/fn.format_utc_ts.html) | [get_day](https://docs.rs/wtime/latest/wtime/utc/fn.get_day.html) | [get_hour](https://docs.rs/wtime/latest/wtime/utc/fn.get_hour.html) |
| [get_month](https://docs.rs/wtime/latest/wtime/utc/fn.get_month.html) | [get_year](https://docs.rs/wtime/latest/wtime/utc/fn.get_year.html) | [utc_now](https://docs.rs/wtime/latest/wtime/utc/fn.utc_now.html) |
| [utc_ts_millis](https://docs.rs/wtime/latest/wtime/utc/fn.utc_ts_millis.html) | [utc_ts_nanos](https://docs.rs/wtime/latest/wtime/utc/fn.utc_ts_nanos.html) | [utc_ts_sec](https://docs.rs/wtime/latest/wtime/utc/fn.utc_ts_sec.html) |

### [UID](https://docs.rs/wtime/latest/wtime/uid/index.html)

|                               Function                               |                               Function                               |
| :------------------------------------------------------------------: | :------------------------------------------------------------------: |
| [uid_utc](https://docs.rs/wtime/latest/wtime/uid/fn.uid_utc.html) | [uid_local](https://docs.rs/wtime/latest/wtime/uid/fn.uid_local.html) |

## License

This project is licensed under either of the following licenses:

- MIT License
- Apache License, Version 2.0

You may choose either license for your purposes.

## Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue for any feature requests or bug reports.

## Author

[Dr. Montasir Mirghani](https://github.com/dr-montasir)