semver/io.github.z4kn4fein.semver/Version

Version

@Serializable(with = VersionSerializer::class)

class Version : Comparable<Version> (source)

This class describes a semantic version and related operations following the semver 2.0.0 specification. Instances of this class are immutable, which makes them thread-safe.

Samples

import io.github.z4kn4fein.semver.Inc
import io.github.z4kn4fein.semver.LooseVersionSerializer
import io.github.z4kn4fein.semver.Version
import io.github.z4kn4fein.semver.VersionSerializer
import io.github.z4kn4fein.semver.constraints.toConstraint
import io.github.z4kn4fein.semver.inc
import io.github.z4kn4fein.semver.nextMajor
import io.github.z4kn4fein.semver.nextMinor
import io.github.z4kn4fein.semver.nextPatch
import io.github.z4kn4fein.semver.nextPreRelease
import io.github.z4kn4fein.semver.satisfies
import io.github.z4kn4fein.semver.satisfiesAll
import io.github.z4kn4fein.semver.satisfiesAny
import io.github.z4kn4fein.semver.toVersion
import io.github.z4kn4fein.semver.toVersionOrNull
import io.github.z4kn4fein.semver.withoutSuffixes
import kotlinx.serialization.json.Json

fun main() { 
   //sampleStart 
   val version = "1.2.3-alpha.1+build.1".toVersion()
println("Version: $version")
println("Major: ${version.major}, Minor: ${version.minor}, Patch: ${version.patch}")
println("Pre-release: ${version.preRelease}")
println("Build metadata: ${version.buildMetadata}")
println("Is it pre-release? ${version.isPreRelease}")
println("Is it stable? ${version.isStable}")

// equality
println("Is 1.0.0 == 1.0.0? ${"1.0.0".toVersion() == "1.0.0".toVersion()}")
println("Is 1.0.0 == 1.0.1? ${"1.0.0".toVersion() == "1.0.1".toVersion()}")

// comparison
println("Is 1.0.1 > 1.0.0? ${"1.0.1".toVersion() > "1.0.0".toVersion()}")
println("Is 1.0.0-alpha.1 > 1.0.0-alpha.0? ${"1.0.0-alpha.1".toVersion() > "1.0.0-alpha.0".toVersion()}")

// range
println("Is 1.0.1 in 1.0.0 .. 1.0.2? ${"1.0.1".toVersion() in "1.0.0".toVersion().."1.0.2".toVersion()}")

// destructuring
print("Destructuring: ")
val (major, minor, patch, preRelease, build) = "1.0.0-alpha+build".toVersion()
print("$major $minor $patch $preRelease $build") 
   //sampleEnd
}

Constructors

Version

constructor(major: Int = 0, minor: Int = 0, patch: Int = 0, preRelease: String? = null, buildMetadata: String? = null)

Constructs a semantic version from the given arguments following the pattern: <major>.<minor>.<patch>-<preRelease>+<buildMetadata>

Types

Companion

object Companion

Companion object of Version.

Properties

buildMetadata

val buildMetadata: String? = null

The BUILD metadata of the version.

isPreRelease

val isPreRelease: Boolean

Determines whether the version is pre-release or not.

isStable

val isStable: Boolean

Determines whether the version is considered stable or not. Stable versions have a positive major number and no pre-release identifier.

major

val major: Int

The MAJOR number of the version.

minor

val minor: Int

The MINOR number of the version.

patch

val patch: Int

The PATCH number of the version.

preRelease

val preRelease: String?

The PRE-RELEASE identifier of the version.

Functions

compareTo

open operator override fun compareTo(other: Version): Int

component1

operator fun component1(): Int

Component function that returns the MAJOR number of the version upon destructuring.

component2

operator fun component2(): Int

Component function that returns the MINOR number of the version upon destructuring.

component3

operator fun component3(): Int

Component function that returns the PATCH number of the version upon destructuring.

component4

operator fun component4(): String?

Component function that returns the PRE-RELEASE identifier of the version upon destructuring.

component5

operator fun component5(): String?

Component function that returns the BUILD metadata of the version upon destructuring.

copy

fun copy(major: Int = this.major, minor: Int = this.minor, patch: Int = this.patch, preRelease: String? = this.preRelease, buildMetadata: String? = this.buildMetadata): Version

Constructs a copy of the Version. The copied object's properties can be altered with the optional parameters.

equals

open operator override fun equals(other: Any?): Boolean

hashCode

open override fun hashCode(): Int

inc

fun Version.inc(by: Inc, preRelease: String? = null): Version

Increases the version by its Inc.MAJOR, Inc.MINOR, Inc.PATCH, or Inc.PRE_RELEASE segment.

nextMajor

fun Version.nextMajor(preRelease: String? = null): Version

Increments the version by its MAJOR number. When the preRelease parameter is set, a pre-release version will be produced from the next MAJOR version. The value of preRelease will be the first pre-release identifier of the new version.

nextMinor

fun Version.nextMinor(preRelease: String? = null): Version

Increments the version by its MINOR number. When the preRelease parameter is set, a pre-release version will be produced from the next MINOR version. The value of preRelease will be the first pre-release identifier of the new version.

nextPatch

fun Version.nextPatch(preRelease: String? = null): Version

Increments the version by its PATCH number. When the version is pre-release, the PATCH number will not be incremented, only the pre-release identifier will be removed.

nextPreRelease

fun Version.nextPreRelease(preRelease: String? = null): Version

Increments the version by its PRE-RELEASE identifier or produces the next pre-release of a stable version. The preRelease parameter's value is used for setting the pre-release identity when the version is stable or has a different pre-release name. If the version is already pre-release and the first identifier matches with the preRelease parameter, a simple incrementation will apply.

satisfies

infix fun Version.satisfies(constraint: Constraint): Boolean

Determines whether a Version satisfies a Constraint or not.

satisfiesAll

infix fun Version.satisfiesAll(constraints: Iterable<Constraint>): Boolean

Determines whether a Version satisfies each Constraint in a collection or not.

satisfiesAny

infix fun Version.satisfiesAny(constraints: Iterable<Constraint>): Boolean

Determines whether a Version satisfies at least one Constraint in a collection or not.

toString

open override fun toString(): String

withoutSuffixes

fun Version.withoutSuffixes(): Version

Produces a copy of the Version without the PRE-RELEASE and BUILD METADATA identities.