README.md in versionaire-0.1.0 vs README.md in versionaire-1.0.0
- old
+ new
@@ -5,31 +5,34 @@
[](https://codeclimate.com/github/bkuhlmann/versionaire)
[](https://gemnasium.com/bkuhlmann/versionaire)
[](https://travis-ci.org/bkuhlmann/versionaire)
[](https://www.patreon.com/bkuhlmann)
-Provides immutable, semantic versioning.
+Provides immutable, thread-safe, semantic versioning.
<!-- Tocer[start]: Auto-generated, don't remove. -->
# Table of Contents
- [Features](#features)
- [Screencasts](#screencasts)
- [Requirements](#requirements)
- [Setup](#setup)
- [Usage](#usage)
- - [Basic](#basic)
- - [Math](#math)
- - [Add](#add)
- - [Subtract](#subtract)
- - [Comparisons](#comparisons)
+ - [Initialization](#initialization)
- [Equality](#equality)
- - [Identity](#identity)
- - [Implicit Conversions](#implicit-conversions)
- - [Explicit Conversions](#explicit-conversions)
- - [Conversions (Casting)](#conversions-casting)
+ - [Value (`#==`)](#value-)
+ - [Hash (`#eql?`)](#hash-eql)
+ - [Case (`#===`)](#case-)
+ - [Identity (`#equal?`)](#identity-equal)
+ - [Conversions](#conversions)
+ - [Function (Casting)](#function-casting)
+ - [Implicit](#implicit)
+ - [Explicit](#explicit)
+ - [Math](#math)
+ - [Addition](#addition)
+ - [Subtraction](#subtraction)
- [Tests](#tests)
- [Versioning](#versioning)
- [Code of Conduct](#code-of-conduct)
- [Contributions](#contributions)
- [License](#license)
@@ -39,18 +42,16 @@
<!-- Tocer[finish]: Auto-generated, don't remove. -->
# Features
- Provides [Semantic Versioning](http://semver.org).
-- Provides immutable version instances.
-- Provides conversions (casts) from a `String`, `Array`, `Hash`, or `Version` to a new `Version`.
-- Provides impicit conversion to a `String`.
-- Provides explicit conversions to a `String`, `Array`, and a `Hash`.
+- Provides immutable, thread-safe version instances.
+- Provides conversions (casts) from a `String`, `Array`, `Hash`, or `Version` to a `Version`.
# Screencasts
-TBD
+[](https://asciinema.org/a/40455)
# Requirements
0. [MRI 2.3.0](https://www.ruby-lang.org)
@@ -72,112 +73,110 @@
gem "versionaire"
# Usage
-## Basic
+## Initialization
A new version can be initialized in a variety of ways:
Versionaire::Version.new # "0.0.0"
Versionaire::Version.new major: 1 # "1.0.0"
Versionaire::Version.new major: 1, minor: 2 # "1.2.0"
Versionaire::Version.new major: 1, minor: 2, maintenance: 3 # "1.2.3"
-## Math
+## Equality
-Versions can be added and subtracted from each other.
+### Value (`#==`)
-### Add
+Equality is deterimined by the state of the object. This means that a version is equal to another version as long as
+all of the values (i.e. state) are equal to each other. Example:
- version_1 = Versionaire::Version.new major: 1, minor: 2, maintenance: 3
- version_2 = Versionaire::Version.new major: 2, minor: 5, maintenance: 7
- version_1 + version_2 # "3.7.10"
+ version_a = Versionaire::Version.new major: 1
+ version_b = Versionaire::Version.new major: 2
+ version_c = Versionaire::Version.new major: 1
-### Subtract
+ version_a == version_a # true
+ version_a == version_b # false
+ version_a == version_c # true
- version_1 = Versionaire::Version.new major: 1, minor: 2, maintenance: 3
- version_2 = Versionaire::Version.new major: 1, minor: 1, maintenance: 1
- version_1 - version_2 # "0.1.2"
+Knowning this, versions can be compared against one another too:
- version_1 = Versionaire::Version.new major: 1
- version_2 = Versionaire::Version.new major: 5
- version_1 - version_2 # Fails with a Versionaire::Errors::NegativeNumber
+ version_a > version_b # false
+ version_a < version_b # true
+ version_a.between? version_c, version_b # true
-## Comparisons
+### Hash (`#eql?`)
-Versions can be compared against other versions:
+Behaves exactly as `#==`.
- version_1 = Versionaire::Version.new major: 1
- version_2 = Versionaire::Version.new major: 5
+### Case (`#===`)
- version_1 > version_2 # false
- version_1 == version_2 # false
- version_1 < version_2 # true
+Behaves exactly as `#==`.
-Versions can't be compared to similar objects:
+### Identity (`#equal?`)
- version = Versionaire::Version.new major: 1
+Works like any other standard Ruby object where an object is equal only to itself.
- version == "1.0.0" # false
- version == [1, 0, 0] # false
- version == {major: 1, minor: 0, maintenance: 0} # false
+ version_a = Versionaire::Version.new major: 1
+ version_b = Versionaire::Version.new major: 2
+ version_c = Versionaire::Version.new major: 1
-## Equality
+ version_a.equal? version_a # true
+ version_a.equal? version_b # false
+ version_a.equal? version_c # false
-Equality is based on the values that make up the version, not identity.
+## Conversions
- version = Versionaire::Version.new major: 1, minor: 2, maintenance: 3
- identical = Versionaire::Version.new major: 1, minor: 2, maintenance: 3
- different = Versionaire::Version.new major: 3
+### Function (Casting)
- version == version # true
- version == identical # true
- version == different # false
+The `Versionaire::Version` function is provided for explicit casting to a version:
-This is the same behavior for `#eql?` method too.
+ version = Versionaire::Version.new major: 1
-## Identity
+ Versionaire::Version "1.0.0"
+ Versionaire::Version [1, 0, 0]
+ Versionaire::Version major: 1, minor: 0, maintenance: 0
+ Versionaire::Version version
-Identity is composed of the values that make up the version plus the class:
+Each of these conversions will result in a version object that represents "1.0.0". When attempting to convert an
+unsupported type, a `Versionaire::Errors::Conversion` exception will be thrown.
- version = Versionaire::Version.new major: 1, minor: 2, maintenance: 3
- identical = Versionaire::Version.new major: 1, minor: 2, maintenance: 3
- different = Versionaire::Version.new major: 3
+### Implicit
- version.hash # -4162833121614102126
- identical.hash # -4162833121614102126
- different.hash # -2082793513660996236
-
-## Implicit Conversions
-
Implicit conversion to a `String` is supported:
"1.0.0".match Versionaire::Version.new(major: 1) # <MatchData "1.0.0">
-## Explicit Conversions
+### Explicit
-Explicit converting to a `String`, `Array`, or `Hash` is supported:
+Explicit conversion to a `String`, `Array`, or `Hash` is supported:
version = Versionaire::Version.new
version.to_s # "0.0.0"
version.to_a # [0, 0, 0]
version.to_h # {major: 0, minor: 0, maintenance: 0}
-## Conversions (Casting)
+## Math
-The `Versionaire::Version` function is provided for explicit conversion (casting) to a new version:
+Versions can be added and subtracted from each other.
- version = Versionaire::Version.new major: 1
+### Addition
- Versionaire::Version "1.0.0"
- Versionaire::Version [1, 0, 0]
- Versionaire::Version major: 1, minor: 0, maintenance: 0
- Versionaire::Version version
+ version_1 = Versionaire::Version.new major: 1, minor: 2, maintenance: 3
+ version_2 = Versionaire::Version.new major: 2, minor: 5, maintenance: 7
+ version_1 + version_2 # "3.7.10"
-Each of these conversions will result in a new version object that is equal to "1.0.0". When attempting to convert an
-unsupported type, a `Versionaire::Errors::Conversion` exception will be thrown.
+### Subtraction
+
+ version_1 = Versionaire::Version.new major: 1, minor: 2, maintenance: 3
+ version_2 = Versionaire::Version.new major: 1, minor: 1, maintenance: 1
+ version_1 - version_2 # "0.1.2"
+
+ version_1 = Versionaire::Version.new major: 1
+ version_2 = Versionaire::Version.new major: 5
+ version_1 - version_2 # Fails with a Versionaire::Errors::NegativeNumber
# Tests
To test, run: