The Locale class in Java can accept 3 arguments: language, country and variant.
The first two are self-explanatory. However, I don't understand the purpose of the variant argument.
This is the description from the official documentation:
Any arbitrary value used to indicate a variation of a Locale. ... additional variations that define a language or its dialects that are not covered by any combinations of language, script and region subtags. However, the variant field in Locale has historically been used for any kind of variation, not just language variations. For example, some supported variants available in Java SE Runtime Environments indicate alternative cultural behaviors such as calendar type or number script.
However, after reading this it's still not clear what the purpose is of the Locale variant. Could someone provide an example where having a different variant produces a different result in locale-sensitive code ?
Edit: Updated documentation to more recent version.
Purpose of Variants
You wrote: I don't understand the purpose of the variant argument.
You can read more about the purpose of variants here:
Variant subtags are values used to indicate dialects or script variations not already covered by combinations of language, script and region subtag.
Some examples are given in that article (as well as in the comments posted to your question). The article's examples are:
sl-nedis - the Nadiza dialect of Slovenian
sl-rozaj - the Rezijan dialect of Slovenian
sl-IT-nedis - the specific variant of the Nadiza dialect of Slovenian that is spoken in Italy
de-CH-1901 - the variant of German orthography dating from the 1901 reforms, as seen in Switzerland
You can see the full set of language tag variants in the IANA language subtag registry.
Java Locale - Any Demonstrable Differences?
You asked for an example where having a different variant produces a different result in locale-sensitive code.
I don't have such an example, although there may well be some. If there are any, I expect their usage is fairly rare (if not downright obscure). Someone else may prove me wrong by providing a (relatively?) commonly used example.
Useful for Metadata
However, variants (and BCP 47 language tags in general) can be useful as metadata. For example, if you have an audio file of someone speaking the Nadiza dialect of Slovenian, you can use the sl-nedis tag to document this. Or if you have a Early Middle French document, you can use fr-1694acad, which the IANA subtag registry helpfully tells us is for '17th century French, as catalogued in the "Dictionnaire de l'académie françoise", 4eme ed. 1694'.
Java's Locale class is, in large part, based on BCP 47 - hence it supports the "variant" subtag, as part of its support for BCP 47.
But that does not mean there will automatically be a different set of names for the days of the week, or currencies, or date formats (for example), compared to those names/values/formats in the variant's base language. There may well be no differences at all. And even if there are differences, they may not be captured by the Unicode Common Locale Data Repository (CLDR), or in Java's implementation of the CLDR.
If your Java code really needs to, it can pass around variant metdata in a Locale object (although that may be over-engineering, as opposed to just using the language tag string).