Add PluralRules

[zbraniecki]

Fixes #116.

This is the initial WIP for the plural rules component.

I'm going to include the rules parser/ast/resolver for runtime resolution based on input string, but we could also compile AST into JSON if we wanted and then data provider could load an already parsed AST.
Finally, it should be possible to compose Rust functions out of the AST and store them as one of the optional data providers.

I didn't use Options constructor model because it seems like this struct will have really only two variables - locale and type.
Depending on how we'll hook in the DataProvider we may want to make the constructor fallible because it may not have locale/type for a given request.

I'm also not sure if I should keep the IntoOperands external to select or internal. In my original code I had it internal: https://github.com/zbraniecki/pluralrules/blob/master/intl_pluralrules/src/lib.rs#L140

but that means that select is fallible, which is not needed for usize etc. where the IntoOperands is not fallible.

Alternatively, we could have infallible select which accepts Into<Operands> and fallible try_select which accepts TryInto<Operands>, or even infallible select only, and then if someone wants to pass something fallible, they'll have to try_into explicitly before passing the result and handle the errors.

@sffc, @filmil - can you skim through and let me know if it looks like a good start?

[coveralls]

Pull Request Test Coverage Report for Build 0fd58a5041a6d641108f81bbae60cb40c0680c8f-PR-119

• 249 of 300 (83.0%) changed or added relevant lines in 6 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage decreased (-1.5%) to 89.272%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
components/pluralrules/src/lib.rs	3	7	42.86%
components/pluralrules/src/rules/lexer.rs	79	88	89.77%
components/pluralrules/src/operands.rs	42	54	77.78%
components/pluralrules/src/rules/ast.rs	9	35	25.71%

Totals
Change from base Build 9a296e8accc5ca174c2cb0432beec34491c266ff:	-1.5%
Covered Lines:	1398
Relevant Lines:	1566

---

💛 - Coveralls

[filmil]

I'll get to this tomorrow.

[zbraniecki]

The other thing I'm planning to do it to make Operands lazy. Many rules don't use most operand fields, so by making them lazy I think I can get better perf than I have in https://github.com/zbraniecki/pluralrules

[filmil]

Looking at this now.

[filmil]

I don't have substantial remarks. All nits inside, or discussion items.

[filmil]

How about keeping the more precise value, and down-converting at output time?

[zbraniecki]

what is "output" time here?

[filmil]

What I mean is, if the params kept the value of x in the widest type that would contain any of the values, we could avoid the need to make the wrapping decision here. However, since the fields n and i are public, we have to make that deliberation here.

[zbraniecki]

What is x?
PluralOperands are only used in plural rules resolution. I struggle to see a case where we'd benefit from lazy resolving them later, because I don't see a use case where we'd construct a PluralOperands but not want to get it's i or n.
And if we do, we'll want it for many rules as we test against them. So having them eagerly resolved seems like a cleaned API which caves to nice further optimizations.

For example, I can imagine scenarios where an instance of PluralOperands gets stored and passed around for use in PluralRules, and proc_macros will allow us to construct the operands at build time and have them validated and calculated at runtime for free.

[filmil]

@zbraniecki first review done.

[zbraniecki]

I want to also point out, especially for @sffc and @filmil that I am intentionally moving away from having minFractionDigits & friends on the PluralRules constructor.

Instead, I offer them on PluralOperands constructor, which is the input for the select.

This allows for the following use:

let pr = PluralRules::new(loc!("en"), PluralCategory::Ordinal);
pr.select(5); // used `Into<PluralOperands> for usize` - infallible

let operandsOptions = PluralOperandsOptions {
  min_fraction_digits: 3,
  ..Default::default()
};
let op = PluralOperands::new_with_options(5, operandsOptions);

pr.select(op); // now I passed Operands resolved with `minFractionDigits` 3

I think it's an improvement to have digits rounding and trimming when constructing Operands from input, because we're producing those Operands either implicitly for infallible, or explicitly for fallible or for cases where we want to go for non-default options.

How does it sound?

[zbraniecki]

Instead, I offer them on PluralOperands constructor, which is the input for the select.

After discussion with @sffc, I'm moving this to be based on FixedDecimal introduced in #141.
This seems like an even better solution for cases where the user wants to specify integer, significant and fraction digits via options.

[zbraniecki]

@sffc - I think this is mostly ready. It works, and it implements 4 "data sources" - json, bincode, inline source and rust functions.

I'd like to plug this into DataProvider next, at least the json/bincode pathways, and leave the inline source/rs options for later likely.

Can you onramp me on how to write the binding based on my data/io/*?

[filmil]

@zbraniecki done as requested

[sffc]

I mostly looked at overall code architecture, not the specific lexer and selection algorithms. If you want me to look at the algorithms, I will do that.

I expect the data code to be imminently replaced, so I was not too picky about that.

[sffc]

FYI, this is code I hope can be deleted once #182 is landed and wired up. Loading strings into a static JSON is hard to do correctly and should be done in a centralized place, not deeply embedded inside a component.

[zbraniecki]

Thank you for the first round of feedback! I applied most of it, and tried to keep comments open where I wanted the reviewer to verify my fix, while in trivial cases like spellings I closed it myself.

I left one open bit - the removal of conversion from f64 to PluralOperands, which I plan to remove before I merge it, but wanted to get another round of feedback and see if there's anything else left.

I'm going to open a number of issues based on all the comments - ranging from FixedDecimal and DataProvider integration, to certain optional performance optimizations (SmallVec) and other tweaks.

I'm looking now for anything that has not yet been mentioned and may require changes before this PR is mergable, so re-requesting reviews.

[zbraniecki]

I think this is ready for re-review!

[zbraniecki]

@filmil @echeran @nciric - ping?

[filmil]

I approved quite a while ago but am glad to reconfirm.