smvr (version 0.2.0)

smvr: A vector representing versions following Semantic Versioning

Description

The smvr class represents versions that follow the Semantic Versioning Specification (SemVer). A version number contains three components, MAJOR.MINOR.PATCH, and optional pre-release and build metadata labels.

This is similar to the base R's numeric_version class, but always has three components (major, minor, patch) and supports pre-release and build metadata labels. And, unlike numeric_version, SemVer uses dots (.) as separators and does not allow hyphens (-) except to indicate the start of a pre-release label.

There are two functions to create smvr objects:

• smvr() is a constructor from each component. Each component must have the same length or length 1 (will be recycled).

• parse_semver() parses a character vector.

Usage

smvr(major = integer(), minor = 0L, patch = 0L, pre_release = "", build = "")
parse_semver(x)

Value

A smvr class vector.

Arguments

major, minor, patch

Non-negative integers representing the major, minor, and patch version components. The default values for minor and patch are 0.

pre_release

Something that can be cast to a pre_release_ids vector. This can be empty ("") meaning non pre-release (default).

build

Optional build metadata character vector. Should have the pattern ^[a-zA-Z0-9-]+ and can contain multiple components separated by dots (.). This can be empty ("") meaning no build metadata (default).

x

A character vector representing semantic versions. Each version should follow the Semantic Versioning Specification. Partial matches are not allowed (e.g., "1.0" is not valid).

Details

Build metadata is not used for ordering, but the == and != operators check it and exactly same build metadata is required for equality. The other operators (<, <=, >, >=) ignore build metadata.

See Also

• as_smvr() to convert other classes to smvr.

• extract-component functions to extract components of a smvr object. (Operations opposite to smvr()).

• update-version functions to update components of a smvr object.

Examples

# SemVer versions from components
smvr(4, 1:5)

# Parse SemVer versions from character
v <- parse_semver(c(
  "1.0.0",
  "1.0.0-alpha",
  "1.0.0-beta",
  "1.0.0-rc.2",
  "1.0.0-rc.10",
  NA
))
v

# Sorting
vctrs::vec_sort(v)

# Can be compared with string notation
v[v >= "1.0.0-rc.2" & !is.na(v)]

# Partial version components are treated as NA
suppressWarnings(parse_semver("1.5"))

# The numeric_version class supports versions with
# less than 3 components, and can be cast to smvr.
numeric_version("1.5") |>
  vctrs::vec_cast(smvr())

# Be careful with hyphens in numeric_version and SemVer.
# The following examples yield opposite results.
numeric_version("1.0.0-1") > "1.0.0" # 1.0.0-1 is the same as 1.0.0.1
parse_semver("1.0.0-1") > "1.0.0"    # 1.0.0-1 is a pre-release version