Package org.eclipse.aether.util.version

package org.eclipse.aether.util.version
Version scheme for parsing/comparing versions and utility classes.

Contains the "generic" scheme GenericVersionScheme that serves as a "factory" (and/or parser) for corresponding package private classes.

On the other hand, the UnionVersionRange is a universal implementation of "unions" of various VersionRange instances.

A version string is parsed according to the Version Order Specification. These rules are summarized here:

  • The version string is parsed into segments, from left to right.
  • Segments are explicitly delimited by a single "." (dot), "-" (hyphen), or "_" (underscore) character.
  • Segments are implicitly delimited by a transition between ASCII digits and non-digits.
  • Segments are classified as numeric, string, qualifiers (special case of string), and min/max.
  • Numeric segments are composed of the ASCII digits 0-9. Non-ASCII digits are treated as letters.
  • Numeric segments are sorted numerically, ascending.
  • Non-numeric segments may be qualifiers (predefined) or strings (non-empty letter sequences). All of them are interpreted as being case-insensitive in the ROOT locale.
  • Qualifier segments (strings listed below) and their sort order (ascending) are:
    • "alpha" (== "a" when immediately followed by number)
    • "beta" (== "b" when immediately followed by number)
    • "milestone" (== "m" when immediately followed by number)
    • "rc" == "cr" (use of "cr" is discouraged)
    • "snapshot"
    • "ga" == "final" == "release"
    • "sp"
  • String segments are sorted lexicographically and case-insensitively per ROOT locale, ascending.
  • There are two special segments, "min" and "max" that represent absolute minimum and absolute maximum in comparisons. They can be used only as the trailing segment.
  • As last step, trailing "zero segments" are trimmed. Similarly, "zero segments" positioned before numeric and non-numeric transitions (either explicitly or implicitly delimited) are trimmed.
  • When trimming, "zero segments" are qualifiers "ga", "final", "release" only if being last (right-most) segment, empty string and "0" always.
  • When comparing the same kind of segments, the type of segment determines comparison rules.
  • When comparing different kinds of segments, the following applies: max > numeric > string > qualifier > min.
  • Any version can be considered to have an infinite number of invisible trailing "zero segments", for the purposes of comparison (in other words, "1" == "1.0.0.0.0.0.0.0.0....")
  • It is common that a version identifier starts with numeric segment (consider this "best practice").

Note: this version spec does not document (or cover) many corner cases that we believe are "atypical" or not commonly used. Some known examples are:

  • Using "min" or "max" special segments as a non-trailing segment. Comparisons with such strings are "undefined" and should be avoided.
  • Having a non-number as the first segment of a version. Versions are expected (but not enforced) to start with numbers.
  • Using special, non-ASCII characters in version. The recommendation is to keep version strings simple.