Version
Date: 2017-02-08

com.github.zafarkhaja.semver

## Class Version

- java.lang.Object
- - com.github.zafarkhaja.semver.Version

- All Implemented Interfaces:
    java.lang.Comparable<Version>

      public class Version
      extends java.lang.Object
      implements java.lang.Comparable<Version>

  The `Version` class is the main class of the Java SemVer library. This class implements the Facade design pattern. It is also immutable, which makes the class thread-safe.
  Since:
    0.1.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Version.Builder` A mutable builder for the immutable `Version` class.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.util.Comparator<Version>` | `BUILD_AWARE_ORDER` A comparator that respects the build metadata when comparing versions.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compareTo(Version other)` Compares this version to the other version.
    `int` | `compareWithBuildsTo(Version other)` Compare this version to the other version taking into account the build metadata.
    `boolean` | `equals(java.lang.Object other)` Checks if this version equals the other version.
    `static Version` | `forIntegers(int major)` Creates a new instance of `Version` for the specified version numbers.
    `static Version` | `forIntegers(int major, int minor)` Creates a new instance of `Version` for the specified version numbers.
    `static Version` | `forIntegers(int major, int minor, int patch)` Creates a new instance of `Version` for the specified version numbers.
    `java.lang.String` | `getBuildMetadata()` Returns the string representation of the build metadata.
    `int` | `getMajorVersion()` Returns the major version number.
    `int` | `getMinorVersion()` Returns the minor version number.
    `java.lang.String` | `getNormalVersion()` Returns the string representation of the normal version.
    `int` | `getPatchVersion()` Returns the patch version number.
    `java.lang.String` | `getPreReleaseVersion()` Returns the string representation of the pre-release version.
    `boolean` | `greaterThan(Version other)` Checks if this version is greater than the other version.
    `boolean` | `greaterThanOrEqualTo(Version other)` Checks if this version is greater than or equal to the other version.
    `int` | `hashCode()`
    `Version` | `incrementBuildMetadata()` Increments the build metadata.
    `Version` | `incrementMajorVersion()` Increments the major version.
    `Version` | `incrementMajorVersion(java.lang.String preRelease)` Increments the major version and appends the pre-release version.
    `Version` | `incrementMinorVersion()` Increments the minor version.
    `Version` | `incrementMinorVersion(java.lang.String preRelease)` Increments the minor version and appends the pre-release version.
    `Version` | `incrementPatchVersion()` Increments the patch version.
    `Version` | `incrementPatchVersion(java.lang.String preRelease)` Increments the patch version and appends the pre-release version.
    `Version` | `incrementPreReleaseVersion()` Increments the pre-release version.
    `boolean` | `lessThan(Version other)` Checks if this version is less than the other version.
    `boolean` | `lessThanOrEqualTo(Version other)` Checks if this version is less than or equal to the other version.
    `boolean` | `satisfies(Expression expr)` Checks if this version satisfies the specified SemVer Expression.
    `boolean` | `satisfies(java.lang.String expr)` Checks if this version satisfies the specified SemVer Expression string.
    `Version` | `setBuildMetadata(java.lang.String build)` Sets the build metadata.
    `Version` | `setPreReleaseVersion(java.lang.String preRelease)` Sets the pre-release version.
    `java.lang.String` | `toString()`
    `static Version` | `valueOf(java.lang.String version)` Creates a new instance of `Version` as a result of parsing the specified version string.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### BUILD_AWARE_ORDER

          public static final java.util.Comparator<Version> BUILD_AWARE_ORDER

      A comparator that respects the build metadata when comparing versions.

  - ### Method Detail

    - #### valueOf

          public static Version valueOf(java.lang.String version)

      Creates a new instance of `Version` as a result of parsing the specified version string.
      Parameters:
        `version` - the version string to parse
      Returns:
        a new instance of the `Version` class
      Throws:
        `java.lang.IllegalArgumentException` - if the input string is `NULL` or empty
        `ParseException` - when invalid version string is provided
        `UnexpectedCharacterException` - is a special case of `ParseException`

    - #### forIntegers

          public static Version forIntegers(int major)

      Creates a new instance of `Version` for the specified version numbers.
      Parameters:
        `major` - the major version number
      Returns:
        a new instance of the `Version` class
      Throws:
        `java.lang.IllegalArgumentException` - if a negative integer is passed
      Since:
        0.7.0

    - #### forIntegers

          public static Version forIntegers(int major,
                            int minor)

      Creates a new instance of `Version` for the specified version numbers.
      Parameters:
        `major` - the major version number
        `minor` - the minor version number
      Returns:
        a new instance of the `Version` class
      Throws:
        `java.lang.IllegalArgumentException` - if a negative integer is passed
      Since:
        0.7.0

    - #### forIntegers

          public static Version forIntegers(int major,
                            int minor,
                            int patch)

      Creates a new instance of `Version` for the specified version numbers.
      Parameters:
        `major` - the major version number
        `minor` - the minor version number
        `patch` - the patch version number
      Returns:
        a new instance of the `Version` class
      Throws:
        `java.lang.IllegalArgumentException` - if a negative integer is passed
      Since:
        0.7.0

    - #### satisfies

          public boolean satisfies(java.lang.String expr)

      Checks if this version satisfies the specified SemVer Expression string. This method is a part of the SemVer Expressions API.
      Parameters:
        `expr` - the SemVer Expression string
      Returns:
        `true` if this version satisfies the specified SemVer Expression or `false` otherwise
      Throws:
        `ParseException` - in case of a general parse error
        `LexerException` - when encounters an illegal character
        `UnexpectedTokenException` - when comes across an unexpected token
      Since:
        0.7.0

    - #### satisfies

          public boolean satisfies(Expression expr)

      Checks if this version satisfies the specified SemVer Expression. This method is a part of the SemVer Expressions API.
      Parameters:
        `expr` - the SemVer Expression
      Returns:
        `true` if this version satisfies the specified SemVer Expression or `false` otherwise
      Since:
        0.9.0

    - #### incrementMajorVersion

          public Version incrementMajorVersion()

      Increments the major version.
      Returns:
        a new instance of the `Version` class

    - #### incrementMajorVersion

          public Version incrementMajorVersion(java.lang.String preRelease)

      Increments the major version and appends the pre-release version.
      Parameters:
        `preRelease` - the pre-release version to append
      Returns:
        a new instance of the `Version` class
      Throws:
        `java.lang.IllegalArgumentException` - if the input string is `NULL` or empty
        `ParseException` - when invalid version string is provided
        `UnexpectedCharacterException` - is a special case of `ParseException`

    - #### incrementMinorVersion

          public Version incrementMinorVersion()

      Increments the minor version.
      Returns:
        a new instance of the `Version` class

    - #### incrementMinorVersion

          public Version incrementMinorVersion(java.lang.String preRelease)

      Increments the minor version and appends the pre-release version.
      Parameters:
        `preRelease` - the pre-release version to append
      Returns:
        a new instance of the `Version` class
      Throws:
        `java.lang.IllegalArgumentException` - if the input string is `NULL` or empty
        `ParseException` - when invalid version string is provided
        `UnexpectedCharacterException` - is a special case of `ParseException`

    - #### incrementPatchVersion

          public Version incrementPatchVersion()

      Increments the patch version.
      Returns:
        a new instance of the `Version` class

    - #### incrementPatchVersion

          public Version incrementPatchVersion(java.lang.String preRelease)

      Increments the patch version and appends the pre-release version.
      Parameters:
        `preRelease` - the pre-release version to append
      Returns:
        a new instance of the `Version` class
      Throws:
        `java.lang.IllegalArgumentException` - if the input string is `NULL` or empty
        `ParseException` - when invalid version string is provided
        `UnexpectedCharacterException` - is a special case of `ParseException`

    - #### incrementPreReleaseVersion

          public Version incrementPreReleaseVersion()

      Increments the pre-release version.
      Returns:
        a new instance of the `Version` class

    - #### incrementBuildMetadata

          public Version incrementBuildMetadata()

      Increments the build metadata.
      Returns:
        a new instance of the `Version` class

    - #### setPreReleaseVersion

          public Version setPreReleaseVersion(java.lang.String preRelease)

      Sets the pre-release version.
      Parameters:
        `preRelease` - the pre-release version to set
      Returns:
        a new instance of the `Version` class
      Throws:
        `java.lang.IllegalArgumentException` - if the input string is `NULL` or empty
        `ParseException` - when invalid version string is provided
        `UnexpectedCharacterException` - is a special case of `ParseException`

    - #### setBuildMetadata

          public Version setBuildMetadata(java.lang.String build)

      Sets the build metadata.
      Parameters:
        `build` - the build metadata to set
      Returns:
        a new instance of the `Version` class
      Throws:
        `java.lang.IllegalArgumentException` - if the input string is `NULL` or empty
        `ParseException` - when invalid version string is provided
        `UnexpectedCharacterException` - is a special case of `ParseException`

    - #### getMajorVersion

          public int getMajorVersion()

      Returns the major version number.
      Returns:
        the major version number

    - #### getMinorVersion

          public int getMinorVersion()

      Returns the minor version number.
      Returns:
        the minor version number

    - #### getPatchVersion

          public int getPatchVersion()

      Returns the patch version number.
      Returns:
        the patch version number

    - #### getNormalVersion

          public java.lang.String getNormalVersion()

      Returns the string representation of the normal version.
      Returns:
        the string representation of the normal version

    - #### getPreReleaseVersion

          public java.lang.String getPreReleaseVersion()

      Returns the string representation of the pre-release version.
      Returns:
        the string representation of the pre-release version

    - #### getBuildMetadata

          public java.lang.String getBuildMetadata()

      Returns the string representation of the build metadata.
      Returns:
        the string representation of the build metadata

    - #### greaterThan

          public boolean greaterThan(Version other)

      Checks if this version is greater than the other version.
      Parameters:
        `other` - the other version to compare to
      Returns:
        `true` if this version is greater than the other version or `false` otherwise
      See Also:
        `compareTo(Version other)`

    - #### greaterThanOrEqualTo

          public boolean greaterThanOrEqualTo(Version other)

      Checks if this version is greater than or equal to the other version.
      Parameters:
        `other` - the other version to compare to
      Returns:
        `true` if this version is greater than or equal to the other version or `false` otherwise
      See Also:
        `compareTo(Version other)`

    - #### lessThan

          public boolean lessThan(Version other)

      Checks if this version is less than the other version.
      Parameters:
        `other` - the other version to compare to
      Returns:
        `true` if this version is less than the other version or `false` otherwise
      See Also:
        `compareTo(Version other)`

    - #### lessThanOrEqualTo

          public boolean lessThanOrEqualTo(Version other)

      Checks if this version is less than or equal to the other version.
      Parameters:
        `other` - the other version to compare to
      Returns:
        `true` if this version is less than or equal to the other version or `false` otherwise
      See Also:
        `compareTo(Version other)`

    - #### equals

          public boolean equals(java.lang.Object other)

      Checks if this version equals the other version. The comparison is done by the `Version.compareTo` method.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `other` - the other version to compare to
      Returns:
        `true` if this version equals the other version or `false` otherwise
      See Also:
        `compareTo(Version other)`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### compareTo

          public int compareTo(Version other)

      Compares this version to the other version. This method does not take into account the versions' build metadata. If you want to compare the versions' build metadata use the `Version.compareWithBuildsTo` method or the `Version.BUILD_AWARE_ORDER` comparator.
      Specified by:
        `compareTo` in interface `java.lang.Comparable<Version>`
      Parameters:
        `other` - the other version to compare to
      Returns:
        a negative integer, zero or a positive integer if this version is less than, equal to or greater the the specified version
      See Also:
        `BUILD_AWARE_ORDER`, `compareWithBuildsTo(Version other)`

    - #### compareWithBuildsTo

          public int compareWithBuildsTo(Version other)

      Compare this version to the other version taking into account the build metadata. The method makes use of the `Version.BUILD_AWARE_ORDER` comparator.
      Parameters:
        `other` - the other version to compare to
      Returns:
        integer result of comparison compatible with that of the `Comparable.compareTo` method
      See Also:
        `BUILD_AWARE_ORDER`