Version Project Documentation
Version Structure
A version in this project consists of four parts:
- Prefix: An optional string that appears before the version number (e.g.,
v, release-).
- Version Part: The main version number, typically in the format
major.minor.patch (e.g., 1.2.3).
- PreRelease Part: An optional part indicating pre-release status, separated by a hyphen (e.g.,
-alpha.1).
- Build Metadata: An optional part for build information, separated by a plus sign (e.g.,
+build.20251121).
Dot-Separated Subparts
Example: Empty Parts Treated as Zero
1..1 → major=1, minor=0, patch=1
1.2.3-alpha..1 → preRelease=
Major Version Number
- The major version number (the first part of the Version Part) must be a number (e.g.,
1 in 1.2.3).
- Other subparts (minor, patch, pre-release, build metadata) can be either numbers or alphanumeric strings (e.g.,
alpha, , ).
Summary Table
Usage Examples
Creating Versions
import nl.w8mr.version.Version
val v1 = Version("1.2.3")
val v2 = Version("v2.0.0-alpha.1+build.20251121")
val v3 = Version("release-2.5.0-rc.2")
Creating Versions from Strings
You can easily create a Version object from a string using the extension function String.toVersion():
val v = "1.2.3-alpha.1+build.20251121".toVersion()
println(v.major)
println(v.preRelease)
This is equivalent to calling Version("1.2.3-alpha.1+build.20251121") directly, but provides a more idiomatic way to convert strings to version objects in Kotlin.
Accessing Version Parts
println(v1.major)
println(v2.prefix)
println(v2.preRelease)
println(v2.buildMetadata)
val v = Version("1..1")
println(v.major)
println(v.minor)
println(v.patch)
Comparing Versions
Versions can be compared to determine which is newer, older, or if they are equal. The comparison follows these rules:
Comparison Logic
Summary of Comparison Steps
- Compare Version Part subparts left to right.
- If equal, compare PreRelease Part (absence means higher precedence).
- Ignore Prefix and Build Metadata for ordering.
Example Comparisons
1.2.3 > 1.2.3-alpha.1
1.2.3-alpha.2 >
Comparing Versions
val v1 = Version("1.2.3")
val v2 = Version("1.2.3-alpha.1")
val v3 = Version("1.2.10")
println(v1 > v2)
println(v3 > v1)
println(v1 == Version("v1.2.3"))
println(Version("1.2.3+build.1") == Version("1.2.3+build.2"))
Custom Comparison
val versions = listOf(
Version("1.2.3"),
Version("1.2.3-alpha.1"),
Version("1.2.10"),
Version("v1.2.3"),
Version("1.2.3+build.1")
)
val sorted = versions.sorted()
sorted.forEach { println(it) }