Module nimbus::versioning
source · Expand description
§Nimbus SDK App Version Comparison
The Nimbus SDK supports comparing app versions that follow the Firefox versioning scheme. This module was ported from the Firefox Desktop implementation. You can find the Desktop implementation in this C++ file There’s also some more documentation in the IDL
§How versioning works
This module defines one main struct, the Version
struct. A version is represented by a list of
dot separated Version Partss. When comparing two versions, we compare each version part in order.
If one of the versions has a version part, but the other has run out (i.e we have reached the end of the list of version parts)
we compare the existing version part with the default version part, which is the 0
. For example,
1.0
is equivalent to 1.0.0.0
.
For information what version parts are composed of, and how they are compared, read the next section.
§Example Versions
The following are all valid versions:
1
(one version part, representing the1
)- `` (one version part, representing the empty string, which is equal to
0
) 12+
(one version part, representing12+
which is equal to13pre
)98.1
(two version parts, one representing98
and another1
)98.2pre1.0-beta
(three version parts, one for98
, one for2pre1
and one for0-beta
)
§The Version Part
A version part is made from 4 elements that directly follow each other:
num_a
: A 32-bit base-10 formatted number that is at the start of the partstr_b
: A non-numeric ascii-encoded string that starts afternum_a
num_c
: Another 32-bit base-10 formatted number that followsstr_b
extra_d
: The rest of the version part as an ascii-encoded string
When two version parts are compared, each of num_a
, str_b
, num_c
and extra_d
are compared
in order. num_a
and num_c
are compared by normal integer comparison, str_b
and extra_b
are compared
by normal byte string comparison.
§Special values and cases
There two special characters that can be used in version parts:
- The
*
. This can be used to represent the whole version part. If used, it will set thenum_a
to be the maximum value possible (i32::MAX
). This can only be used as the whole version part string. It will parsed normally as the*
ascii character if it is preceded or followed by any other characters. - The
+
. This can be used as thestr_b
. Whenever a+
is used as astr_b
, it increments thenum_a
by 1 and sets thestr_b
to be equal topre
. For example,2+
is the same as3pre
- An empty
str_b
is always greater than astr_b
with a value. For example,93
>93pre
§Example version comparisons
The following comparisons are taken directly from the brief documentation in Mozilla-Central
use nimbus::versioning::Version;
let v1 = Version::try_from("1.0pre1").unwrap();
let v2 = Version::try_from("1.0pre2").unwrap();
let v3 = Version::try_from("1.0").unwrap();
let v4 = Version::try_from("1.0.0").unwrap();
let v5 = Version::try_from("1.0.0.0").unwrap();
let v6 = Version::try_from("1.1pre").unwrap();
let v7 = Version::try_from("1.1pre0").unwrap();
let v8 = Version::try_from("1.0+").unwrap();
let v9 = Version::try_from("1.1pre1a").unwrap();
let v10 = Version::try_from("1.1pre1").unwrap();
let v11 = Version::try_from("1.1pre10a").unwrap();
let v12 = Version::try_from("1.1pre10").unwrap();
assert!(v1 < v2);
assert!(v2 < v3);
assert!(v3 == v4);
assert!(v4 == v5);
assert!(v5 < v6);
assert!(v6 == v7);
assert!(v7 == v8);
assert!(v8 < v9);
assert!(v9 < v10);
assert!(v10 < v11);
assert!(v11 < v12);
What the above is comparing is: 1.0pre1 < 1.0pre2 < 1.0 == 1.0.0 == 1.0.0.0 < 1.1pre == 1.1pre0 == 1.0+ < 1.1pre1a < 1.1pre1 < 1.1pre10a < 1.1pre10