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

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

/// Contains the API configuration as prescribed by ECMA 402.
///
/// The meaning of the options is the same as in the similarly named
/// options in the JS version.
///
/// See [Options] for the contents of the options.  See the [Collator::try_new]
/// for the use of the options.
pub mod options {

    /// Set the intended usage for this collation.
    #[derive(Eq, PartialEq, Debug, Clone)]
    pub enum Usage {
        /// Use collation for sorting. Default.
        Sort,
        /// Use collation for searching.
        Search,
    }

    /// Set the sensitivity of the collation.
    ///
    /// Which differences in the strings should lead to non-zero result values.
    #[derive(Eq, PartialEq, Debug, Clone)]
    pub enum Sensitivity {
        /// Only strings that differ in base letters compare as unequal.
        /// Examples: a ≠ b, a = á, a = A.
        Base,
        /// Only strings that differ in base letters or accents and other diacritic marks compare
        /// as unequal. Examples: a ≠ b, a ≠ á, a = A.
        Accent,
        /// Only strings that differ in base letters or case compare as unequal.
        /// Examples: a ≠ b, a = á, a ≠ A.
        Case,
        /// Strings that differ in base letters, accents and other diacritic marks, or case compare
        /// as unequal. Other differences may also be taken into consideration.
        /// Examples: a ≠ b, a ≠ á, a ≠ A.
        Variant,
    }

    /// Whether punctuation should be ignored.
    #[derive(Eq, PartialEq, Debug, Clone)]
    pub enum Punctuation {
        /// Ignore punctuation.
        Ignore,
        /// Honor punctuation.
        Honor,
    }

    /// Whether numeric collation should be used, such that "1" < "2" < "10".
    ///
    /// This option can be set through an options property or through a Unicode extension key; if
    /// both are provided, the options property takes precedence. Implementations are not required
    /// to support this property.
    #[derive(Eq, PartialEq, Debug, Clone)]
    pub enum Numeric {
        /// Use numeric comparison.
        Use,
        /// Do not use numeric comparision.
        Ignore,
    }

    /// Whether upper case or lower case should sort first.
    ///
    /// This option can be set through an options property or through a Unicode extension key; if
    /// both are provided, the options property takes precedence. Implementations are not required
    /// to support this property.
    #[derive(Eq, PartialEq, Debug, Clone)]
    pub enum CaseFirst {
        /// Sort upper case first.
        Upper,
        /// Sort lower case first.
        Lower,
        /// Use locale default for case sorting.
        False,
    }
}

/// The options set by the user at construction time.  See discussion at the top level
/// about the name choice.  Provides as a "bag of options" since we don't expect any
/// implementations to be attached to this struct.
///
/// The default values of all the options are prescribed in by the [TC39 report][tc39].
///
/// [tc39]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator
#[derive(Eq, PartialEq, Debug, Clone)]
pub struct Options {
    pub usage: options::Usage,
    pub sensitivity: options::Sensitivity,
    pub punctuation: options::Punctuation,
    pub numeric: options::Numeric,
    pub case_first: options::CaseFirst,
}

impl Default for Options {
    /// Gets the default values of [Options] if omitted at setup.  The
    /// default values are prescribed by the TC39.  See [Collator][tc39c].
    ///
    /// [tc39c]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator
    fn default() -> Self {
        Options {
            usage: options::Usage::Sort,
            sensitivity: options::Sensitivity::Variant,
            punctuation: options::Punctuation::Honor,
            numeric: options::Numeric::Ignore,
            case_first: options::CaseFirst::False,
        }
    }
}

pub trait Collator {
    /// The type of error reported, if any.
    type Error: std::error::Error;

    /// Creates a new [Collator].
    ///
    /// Creation may fail, for example, if the locale-specific data is not loaded, or if
    /// the supplied options are inconsistent.
    fn try_new<L>(l: L, opts: Options) -> Result<Self, Self::Error>
    where
        L: crate::Locale,
        Self: Sized;

    /// Compares two strings according to the sort order of this [Collator].
    ///
    /// Returns 0 if `first` and `second` are equal.  Returns a negative value
    /// if `first` is less, and a positive value of `second` is less.
    fn compare<P, Q>(first: P, second: Q) -> i8
    where
        P: AsRef<str>,
        Q: AsRef<str>;
}