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 the 1)
  • `` (one version part, representing the empty string, which is equal to 0)
  • 12+ (one version part, representing 12+ which is equal to 13pre)
  • 98.1 (two version parts, one representing 98 and another 1)
  • 98.2pre1.0-beta (three version parts, one for 98, one for 2pre1 and one for 0-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 part
  • str_b: A non-numeric ascii-encoded string that starts after num_a
  • num_c: Another 32-bit base-10 formatted number that follows str_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:

  1. The *. This can be used to represent the whole version part. If used, it will set the num_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.
  2. The +. This can be used as the str_b. Whenever a + is used as a str_b, it increments the num_a by 1 and sets the str_b to be equal to pre. For example, 2+ is the same as 3pre
  3. An empty str_b is always greater than a str_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

Structs§