s3uri 0.1.0

AWS S3 URIs
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

use std::{fmt, ops::Deref};

use crate::S3Key;

impl Deref for S3Key {
    type Target = str;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

impl PartialEq<str> for S3Key {
    fn eq(&self, other: &str) -> bool {
        self.0.eq(other)
    }

    fn ne(&self, other: &str) -> bool {
        !self.eq(other)
    }
}

impl PartialEq<&str> for S3Key {
    fn eq(&self, other: &&str) -> bool {
        self.0.eq(other)
    }

    fn ne(&self, other: &&str) -> bool {
        !self.eq(other)
    }
}

impl fmt::Display for S3Key {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str(self)
    }
}

impl S3Key {
    /// Creates an empty S3 key.
    ///
    /// ```rust
    /// let key = s3uri::S3Key::empty();
    /// assert!(key.is_empty());
    /// ```
    pub fn empty() -> S3Key {
        S3Key(String::from(""))
    }

    /// Joins a suffix to the key.
    ///
    /// Slashes at the start and end of the suffix will be normalised as-needed.
    ///
    /// For example, to join the prefix "images" and "clowns.jpg":
    ///
    /// ```rust
    /// let key = s3uri::S3Key::new("images")
    ///     .join("clowns.jpg");
    ///
    /// assert_eq!(key, "images/clowns.jpg");
    /// ```
    ///
    /// The same result is reached if slashes are included:
    ///
    /// ```rust
    /// let key = s3uri::S3Key::new("images/")
    ///     .join("/clowns.jpg");
    ///
    /// assert_eq!(key, "images/clowns.jpg");
    /// ```
    ///
    /// `.join()` calls can be chained:
    ///
    /// ```rust
    /// let key = s3uri::S3Key::new("images")
    ///     .join("staff")
    ///     .join("clowns.jpg");
    ///
    /// assert_eq!(key, "images/staff/clowns.jpg");
    /// ```
    ///
    /// This example creates an "images" key prefix and uses it to create two
    /// further keys.
    ///
    /// ```rust
    /// let images = s3uri::S3Key::new("images");
    /// let clowns = images.join("clowns.jpg");
    /// let tents = images.join("tents.jpg");
    ///
    /// assert_eq!(clowns, "images/clowns.jpg");
    /// assert_eq!(tents, "images/tents.jpg");
    /// ```
    pub fn join(&self, part: &str) -> S3Key {
        let suffix = if part.ends_with("/") { "/" } else { "" };
        let normalized = part.trim_matches('/').to_string();
        let needs_separator = !self.is_empty() && !self.ends_with("/");
        let separator = if needs_separator { "/" } else { "" };
        S3Key(format!("{}{}{}{}", self, separator, normalized, suffix))
    }

    /// Creates a new S3 key.
    ///
    /// `key` can be a full key, or a key prefix to add to later with `S3Key::join`.
    ///
    /// ```rust
    /// let key = s3uri::S3Key::new("clowns.jpg");
    /// assert_eq!(key, "clowns.jpg");
    /// ```
    pub fn new(key: &str) -> S3Key {
        S3Key::empty().join(key)
    }
}

#[cfg(test)]
mod tests {
    use crate::S3Key;

    #[test]
    fn test_empty() {
        let key = S3Key::empty();
        assert_eq!(key, "");
    }

    #[test]
    fn test_new() {
        let cases = [
            ["clowns.jpg", "clowns.jpg"],
            ["/clowns.jpg", "clowns.jpg"],
            ["//clowns.jpg", "clowns.jpg"],
            ["images/", "images/"],
            ["images//", "images/"],
        ];

        for case in cases {
            let key = S3Key::new(case[0]);
            assert_eq!(key, case[1]);
        }
    }

    #[test]
    fn test_join_chained() {
        let cases = [
            ["images", "clowns.jpg", "images/clowns.jpg"],
            ["images/", "clowns.jpg", "images/clowns.jpg"],
            ["images", "/clowns.jpg", "images/clowns.jpg"],
            ["images/", "/clowns.jpg", "images/clowns.jpg"],
        ];

        for case in cases {
            let key = S3Key::new(case[0]).join(case[1]);
            assert_eq!(key, case[2]);
        }
    }
}