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

use super::{utc::format_utc_ts, local::format_local_ts};

/// Generates a 10-character string of letters starting from a specific index, wrapping around the alphabet.
///
/// The effective starting index is calculated using modulo 26.
/// For example:
/// - index = 0 -> "abcdefghij"
/// - index = 16 -> "qrstuvwxyz"
/// - index = 17 -> "rstuvwxyza"
/// - index = 26 -> "abcdefghij" (same as index 0)
///
/// # Arguments
///
/// * `index` - The starting index (0-based) in the alphabet.
///
/// # Returns
///
/// * A 10-character `String` containing the shifted letters.
fn get_shifted_letters(index: u8) -> String {
    let eng_letters = "abcdefghijklmnopqrstuvwxyz";
    let len = eng_letters.len();
    let start_index = (index as usize) % len;
    let mut result = String::with_capacity(10);

    for i in 0..10 {
        let current_index = (start_index + i) % len;
        // This indexing is safe because current_index will always be within the 0-25 range.
        result.push(eng_letters.chars().nth(current_index).unwrap());
    }

    result
}

/// Transforms a given input string by replacing its digits with characters
/// derived from a shifted alphabet mapping.
///
/// This is a private helper function used by `uid_utc` and `uid_local`.
///
/// It uses the `index` argument to determine a 10-character mapping
/// (e.g., index 0 maps '0' to 'a', '1' to 'b', etc.).
/// Digits in the `input` string are replaced using this mapping. Non-digit
/// characters (like hyphens or colons) are either kept as hyphens or removed
/// based on the `hyphen` flag.
///
/// # Arguments
///
/// * `index` - The starting index (0-based) for the 10-character digit mapping (0-9).
/// * `hyphen` - If `true`, non-digit separators in the timestamp are replaced by hyphens (`-`);
///              if `false`, they are omitted.
/// * `input` - The string containing digits to be replaced (e.g., a timestamp).
///
/// # Returns
///
/// * The transformed string with letters replacing digits.
fn timestamps_letters(index: u8, hyphen: bool, input: &str) -> String {
    // Generates the 10-char mapping needed for digits 0-9
    let mapping = get_shifted_letters(index);

    let mapping_bytes = mapping.as_bytes();
    
    // Allocate enough space for the output string, assuming separators are kept.
    let mut output = Vec::with_capacity(input.len());

    for &byte in input.as_bytes() {
        if byte >= b'0' && byte <= b'9' {
            let idx = (byte - b'0') as usize;
            output.push(mapping_bytes[idx]);
        } else if hyphen {
            // Treat any non-digit character (like 'T', '-', ':') as a hyphen if requested.
            output.push(b'-');
        }
        // If hyphen is false, non-digit characters are simply ignored/skipped.
    }

    // The result should always be valid UTF-8 if the input was valid and the mapping is ASCII letters.
    String::from_utf8(output).expect("Invalid UTF-8")
}

/// Generates a unique ID based on the current UTC timestamp, using letters
/// instead of numbers and optionally including hyphens.
///
/// This function calls `format_utc_ts()` internally to get the standard
/// UTC timestamp string before transforming it.
///
/// # Arguments
///
/// * `index` - The starting index (0-based) for the 10-character digit mapping (0-9).
/// * `hyphen` - If `true`, separators in the timestamp are replaced by hyphens (`-`);
///              if `false`, they are omitted.
///
/// # Returns
///
/// * A `String` containing the UTC timestamp transformed into letters.
/// 
/// ```
/// use wtime::uid::uid_utc;
///
/// println!("uid: {}", uid_utc(16, true));
/// println!("uid: {}", uid_utc(16, false));
/// ```
pub fn uid_utc(index: u8, hyphen: bool) -> String {
    let uid = timestamps_letters(index, hyphen, &format_utc_ts());
    uid 
}

/// Generates a unique ID based on the current local timestamp (server time), using letters
/// instead of numbers and optionally including hyphens.
///
/// This function calls `format_local_ts()` internally to get the standard
/// local timestamp string before transforming it.
///
/// # Arguments
///
/// * `index` - The starting index (0-based) for the 10-character digit mapping (0-9).
/// * `hyphen` - If `true`, separators in the timestamp are replaced by hyphens (`-`);
///              if `false`, they are omitted.
///
/// # Returns
///
/// * A `String` containing the local timestamp transformed into letters.
/// 
/// ```
/// use wtime::uid::uid_local;
///
/// println!("uid: {}", uid_local(0, true));
/// println!("uid: {}", uid_local(0, false));
/// ```
pub fn uid_local(index: u8, hyphen: bool) -> String {
    let uid = timestamps_letters(index, hyphen, &format_local_ts());
    uid 
}