semver 0.12.0
=============

Synopsis
--------

    CREATE EXTENSION semver;

    SELECT '1.2.1'::semver;
     semver
    --------
     1.2.1

    SELECT '1.2.0'::semver > '1.2.0b1'::semver;
     ?column?
    ----------
     t

Description
-----------

This library contains a single PostgreSQL extension, a semantic version data
type called `semver`. It's an implementation of the version number format
specified by the [Semantic Versioning 2.0.0
Specification](http://semver.org/spec/v2.0.0.html).

The two important points describing the structure of a semantic version and
how two versions compare are these, from [the spec](http://semver.org/):

> 2. A normal version number MUST take the form X.Y.Z where X, Y, and Z are
> non-negative integers, and MUST NOT contain leading zeroes. X is the
> major version, Y is the minor version, and Z is the patch
> version. Each element MUST increase numerically. For instance: 1.9.0
> -> 1.10.0 -> 1.11.0.

> 9. A pre-release version MAY be denoted by appending a hyphen and a
> series of dot separated identifiers immediately following the patch
> version. Identifiers MUST comprise only ASCII alphanumerics and hyphen
> [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST
> NOT include leading zeroes. Pre-release versions have a lower
> precedence than the associated normal version. A pre-release version
> indicates that the version is unstable and might not satisfy the
> intended compatibility requirements as denoted by its associated
> normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7,
> 1.0.0-x.7.z.92.

Usage
-----

Use like any other data type. Here's an example in a table:

    CREATE TABLE extensions (
        name        TEXT,
        version     SEMVER,
        description TEXT,
        PRIMARY KEY (name, version)
    );

The type can be in indexed using btree or hash indexes:

    CREATE INDEX idx_extension_version ON extensions(version);
    CREATE INDEX hdx_extension_version ON extensions USING hash (version);

Hash indexes aren't worth much, but the functionality is there to support hash
aggregates in query optimizations.

And some sample usage:

    INSERT INTO extensions
    VALUES ('pgtap', '0.35.0',    'PostgreSQL unit testing'),
           ('pgtap', '0.35.0-b1', 'PostgreSQL unit testing.'),
           ('pair',  '0.1.0',     'Key/value pair data type'),
           ('PostGIS', '1.5.0',   'Gelocation data types');

    SELECT * FROM extensions WHERE VERSION = '1.5.0';
      name   │ version │      description
    ---------+---------+-----------------------
     PostGIS │ 1.5.0   │ Gelocation data types

    SELECT * FROM extensions WHERE VERSION < '0.35.0';
     name  │ version   │       description
    -------+-----------+--------------------------
     pgtap │ 0.35.0-b1 │ PostgreSQL unit testing.
     pair  │ 0.1.0     │ Key/value pair data type

Note that "0.35.0-b1" is less than "0.35.0", as required by the specification.
Use `ORDER BY` to get more of a feel for semantic version ordering rules:

    SELECT version FROM extensions ORDER BY version;
     version
    -----------
     0.1.0
     0.35.0-b1
     0.35.0
     1.5.0

    SELECT version FROM extensions ORDER BY version DESC;
     version
    -----------
     1.5.0
     0.35.0
     0.35.0-b1
     0.1.0

Interface
---------

### Operators ###

 Operator | Description                               | Example                             | Result
----------|-------------------------------------------|-------------------------------------|--------
 `=`      | Are semvers equivalent                    | '1.2.0'semver = '1.2.00'::semver    | `t`
 `<>`     | Are semvers different                     | '1.2.0'semver <> '1.2.00'::semver   | `f`
 `<`      | Is semver less than right semver          | '3.4.0-b1'semver < '3.4.0'::semver  | `t`
 `<=`     | Is semver less than or equal to semver    | '3.4.0-b1'semver <= '3.4.0'::semver | `t`
 `>`      | Is semver greater than right semver       | '3.4.0-b1'semver > '3.4.0'::semver  | `f`
 `>=`     | Is semver greater than or equal to semver | '3.4.0-b1'semver >= '3.4.0'::semver | `f`

### Functions ###

 Function                        | Description                     | Example                             | Result
---------------------------------|---------------------------------|-------------------------------------|----------
 `to_semver(text)`               | Parse semver from text          | `to_semver('1.02')`                 | `1.2.0`
 `is_semver(text)`               | Test semver text                | `is_semver('1.02')`                 | true
 `semver(text)`                  | Cast text to semver             | `semver('1.2.1')`                   | `1.2.1`
 `semver(numeric)`               | Cast numeric to semver          | `semver(1.2)`                       | `1.2.0`
 `semver(real)`                  | Cast real to semver             | `semver(12.0::real)`                | `12.0.0`
 `semver(double precision)`      | Cast double precision to semver | `semver(9.2::double precision)`     | `9.2.0`
 `semver(integer)`               | Cast integer to semver          | `semver(42::integer)`               | `42.0.0`
 `semver(bigint)`                | Cast bigint to semver           | `semver(19::bigint)`                | `19.0.0`
 `semver(smallint)`              | Cast smallint to semver         | `semver(2::smallint)`               | `2.0.0`
 `text(semver)`                  | Cast semver to text             | `text('1.2.54'::semver)`            | `1.2.54`
 `get_semver_major(semver)`      | Get major version part          | `get_semver_major('4.2.0')`         | `4`
 `get_semver_minor(semver)`      | Get minor version part          | `get_semver_minor('4.2.0')`         | `2`
 `get_semver_patch(semver)`      | Get patch version part          | `get_semver_patch('4.2.0')`         | `0`
 `get_semver_prerelease(semver)` | Get prerelease version part     | `get_semver_prerelease('2.1.0-b2')` | `b2`

Numeric casts simply extract an integer from the decimal portion, so that
`1.20` and `1.02` would both be parsed as `1.2.0`.

The difference between `semver()` and `to_semver()` is that the former
requires a valid semver format, while the latter is a bit more permissive,
doing its best to convert other version number formats (including the older
[semver 1.0.0-beta](http://semver.org/spec/v1.0.0-beta.html) prerelease
format) to semantic versions:

    # select to_semver('1.0');
     to_semver
    -----------
     1.0.0
    (1 row)

    # select to_semver('1.0beta1');
     to_semver
    -----------
     1.0.0-beta1
    (1 row)

As for `is_semver()`, it returns true for a valid semver format, and false for
anything else, including formats that `semver()` would convert to valid
semvers. In other words, its interpretation of validity is strict.

And finally, the `get_semver_*` functions all return integers except for
`get_semver_prerelease()`, which returns text.

### Aggregate Functions ###

The examples assume the values inserted into the `extensions` table in the above examples.

 Function      | Return Type | Description               | Example                                | Result
---------------|-------------|---------------------------|----------------------------------------|--------
 `MIN(semver)` |  `semver`   | Return the lowest semver  | `SELECT MIN(version) FROM extensions;` | `0.1.0`
 `MAX(semver)` |  `semver`   | Return the highest semver | `SELECT MAX(version) FROM extensions;` | `1.5.0`

### Casts ###

 From             | To     | Example                         | Result
---------------------------|---------------------------------|---------
 text             | semver | `'1.2.1'::semver`               | `1.2.1`
 numeric          | semver | `1.2::semver`                   | `1.2.0`
 real             | semver | `12.0::real::semver`            | `12.0.0`
 double precision | semver | `9.2::double precision::semver` | `9.2.0`
 integer          | semver | `42::integer::semver`           | `42.0.0`
 bigint           | semver | `19::bigint::semver`            | `19.0.0`
 smallint         | semver | `2::smallint::semver`           | `2.0.0`
 semver           | text   | `'1.2.54'::semver::text`        | `1.2.54`

Note that numeric casts simply extract an integer from the decimal portion, so that
`1.20` and `1.02` would both be parsed as `1.2.0`.

Support
-------

This library is stored in an open
[GitHub repository](https://github.com/theory/pg-semver). Feel free to fork
and contribute! Please file bug reports via
[GitHub Issues](https://github.com/theory/pg-semver/issues/).

Authors
-------

* [David E. Wheeler](http://theory.pm/)
* [Sam Vilain](http://sam.vilain.net/)
* [Tom Davis](http://stacktory.com/)
* [Xavier Caron](https://github.com/maspalio)

Copyright and License
---------------------

Copyright (c) 2010-2016 The pg-semver Maintainers: David E. Wheeler, Sam
Vilain, Tom Davis, and Xavier Caron.

This module is free software; you can redistribute it and/or modify it under
the [PostgreSQL License](http://www.opensource.org/licenses/postgresql).

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose, without fee, and without a written agreement is
hereby granted, provided that the above copyright notice and this paragraph
and the following two paragraphs appear in all copies.

In no event shall The pg-semver Maintainers be liable to any party for direct,
indirect, special, incidental, or consequential damages, including lost
profits, arising out of the use of this software and its documentation, even
if The pg-semver Maintainers have been advised of the possibility of such
damage.

The pg-semver Maintainers specifically disclaim any warranties, including, but
not limited to, the implied warranties of merchantability and fitness for a
particular purpose. The software provided hereunder is on an "as is" basis,
and The pg-semver Maintainers no obligations to provide maintenance, support,
updates, enhancements, or modifications.