# Описание класса VersionInfo

## Информация о версии

Версия класса: 1.0

Впервые введено в пакет с версии: 1.0.24

Описание класса: Класс, описывающий информацию о версии.

## Публичные свойства и константы класса

В классе определены следующие константы:

* `array StagesNames` - имена стадий сборки.
* `string DefaultTemplate` - шаблон вывода по умолчанию.

В классе определены следующе свойства:

* `int $Major` - мажорная версия (**только чтение**).
* `int $Minor` - минорная версия (**только чтение**).
* `int $Release` - номер релиза (**только чтение**).
* `int $Build` - номер сборки (**только чтение**).
* `VersionInfoStage $Stage` - стадия сборки (**только чтение**).
* `int $StageNumber` - номер стадии сборки (**только чтение**).

## Методы и функции

### Конструктор.

Конструктор принимает **4 обязательных** и **2 дополнительных параметра**:

* `int $Major` - мажорная версия (**обязательный**);
* `int $Minor` - минорная версия (**обязательный**);
* `int $Release` - номер релиза (**обязательный**);
* `int $Build` - номер сборки (**обязательный**);
* `VersionInfoStage` $Stage - стадия сборки (по умолчанию, `VersionInfoStage::Undefined`);
* `int $StageNumber` - номер стадии сборки (по умолчанию, `0`).

В результате создаётся новый класс `VersionInfo`.

Пример:

    $version = new VersionInfo (1, 0, 0, 0, VersionInfoStage::Beta, 1);

Создаст класс `VersionInfo` для версии `1.0.0.0 Beta 1`.

### Преобразование в строку.

За преобразование в строку отвечает 2 метода: `ToString` и `__toString ()`.

#### Метод `ToString`

Этот метод возвращает строковое представление версии. Он содержит **2 необязательных параметра**:

* `string $template` - шаблон вывода (по умолчанию, `DefaultTemplate`);
* `array $stagesNames` - имена стадий сборки (по умолчанию, `StagesNames`).

Метод возвращает `string` - строковое представление версии.

В шаблоне должны присутствовать маркеры:

|     Маркер     | Описание            | Обязательный |
|:--------------:|:--------------------|:------------:|
|    #{Major}    | Мажорная версия     |      ДА      |
|    #{Minor}    | Минорная версия     |      ДА      |
|   #{Release}   | Номер релиза        |      ДА      |
|    #{Build}    | Номер сборки        |      ДА      |
|    #{Stage}    | Стадия сборки       |     НЕТ      |
| #{StageNumber} | Номер стадии сборки |     НЕТ      |

Эти маркеры в шаблоне заменяются на значения соответствующих свойств.

Синтаксис:

    public function ToString (string $template, array $stagesNames): string

Пример,

    // Создаю объект
    $version = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);

    // Задаю шаблон
    $template = #{Major}.#{Minor}.#{Release} (сборка #{Build});

    // Вывожу
    echo $version->ToString($template);

В результате на экране появится:

    1.2.3 (сборка 4)

#### Метод `__toString`

Этот метод полностью аналогичен методу `ToString` с той лишь разницей, что в этом методе невозможно задать параметры
вывода (такие, как шаблон и имена стадий). Эти параметры берутся по умолчанию.

Этот метод необходим для вывода корректной информации при попытке привести объект класса `VersionInfo` к типу `string`.

Метод возвращает `string` - строковое представление версии.

Синтаксис:

    public function __toString (): string

Пример,

    // Создаю объект
    $version = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);

    // Вывожу
    echo $version;

В результате на экране появится:

    1.2.3.4 Beta 5

### Сравнение версий

Для сравнения версий используется две аналогичные друг другу (но различающиеся по способу вызова) функции: `Compare` и
`CompareWith`.

#### Метод `Compare`

Это статический метод, который сравнивает две версии, заданные в **2 обязательных параметрах**:

* `VersionInfo $version1` - версия 1;
* `VersionInfo $version2` - версия 2.

Этот метод возвращает `int`:

| version1  | version2  | Результат |
|:---------:|:---------:|:---------:|
|  Младше   |  Старше   |    -1     |
| Совпадает | Совпадает |     0     |
|  Старше   |  Младше   |     1     |

Синтаксис:

    public static function Compare (VersionInfo $version1, VersionInfo $version2): int

Пример,

    // Создаю объекты
    // - $version11 младше $version12
    $version11 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);
    $version12 = new VersionInfo (1, 2, 3, 5, VersionInfoStage::Beta, 6);

    // $version21 совпадает с $version22
    $version21 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);
    $version22 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);

    // $version31 старше $version32
    $version31 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Stable);
    $version32 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);

    // Сравниваю
    $verCompare1 = VersionInfo::Compare($version11, $version12);
    $verCompare2 = VersionInfo::Compare($version21, $version22);
    $verCompare3 = VersionInfo::Compare($version31, $version32);

    // Вывожу
    echo $verCompare1 . '|' . $verCompare2 . '|' . $verCompare3;

В результате на экране появится:

    -1|0|1

#### Метод `CompareWith`

Этот метод полностью аналогичен методу `Compare`. Он отличается лишь только тем, что **не статичен** и вызывается из
ранее созданного экземпляра класса. Он сравнивает текущую версию с переданной. Этот метод имеет только **1 обязательный
параметр**: `VersionInfo $version` - переданная версия.

Этот метод возвращает `int`: `1`, если текущая версия старше переданной, `0`, если совпадает и `-1`, если текущая версия
младше переданной.

Синтаксис:

    public function CompareWith (VersionInfo $version): int

Пример,

    // Создаю объекты
    // - $version11 младше $version12
    $version11 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);
    $version12 = new VersionInfo (1, 2, 3, 5, VersionInfoStage::Beta, 6);

    // $version21 совпадает с $version22
    $version21 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);
    $version22 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);

    // $version31 старше $version32
    $version31 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Stable);
    $version32 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);

    // Сравниваю
    $verCompare1 = $version11->CompareWith($version12);
    $verCompare2 = $version21->CompareWith($version22);
    $verCompare3 = $version31->CompareWith($version32);

    // Вывожу
    echo $verCompare1 . '|' . $verCompare2 . '|' . $verCompare3;

В результате на экране появится:

    -1|0|1

### Парсинг версий

Для преобразования строки с версией в объект `VersionInfo` используется статичный метод `Parse`.

Он требует **1 обязательный параметр** и **1 необязательный**:

* `string $version` - строка с версией (она должна быть в формате
  `#{Major}.#{Minor}.#{Release}.#{Build} #{Stage} #{StageNumber}`, причём `#{Stage}` и `#{StageNumber}` можно не
  указывать);
* `array $stagesNames` - имена стадий сборки (по умолчанию, `StagesNames`).

Этот метод возвращает объект {@link VersionInfo} с данными о версии или `new VersionInfo(0, 0, 0, 0)` в случае ошибки.

Синтаксис:

    public static function Parse (string $version, array $stagesNames = self::StagesNames): VersionInfo

Пример,

    // Создаю текст
    $verText = '1.2.3.4 Beta 2';    
    
    // Преобразую
    $version = VersionInfo::Parse($verText);

    // Вывожу
    echo $version;

В результате на экране появится:

    1.2.3.4 Beta 2

### Вспомогательные методы

#### Метод `IsNotUndefinedOrStable`

Этот **статический** метод проверяет, является ли версия в неопределённой стадии или уже релизом.

Он имеет только **1 обязательный параметр**: `VersionInfoStage $versionStage` - стадия сборки.

Этот метод возвращает `bool`: `true`, если стадия сборки определена и не является релизом и `false` в противном случае.

Синтаксис:

    public static function IsNotUndefinedOrStable (VersionInfoStage $versionStage): bool

Пример,

    // Создаю объекты
    $version1 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Undefined, 5);
    $version2 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);
    $version3 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Stable);

    // Сравниваю
    $res1 = VersionInfo::IsNotUndefinedOrStabl($version1->Stage);
    $res2 = VersionInfo::IsNotUndefinedOrStabl($version2->Stage);
    $res3 = VersionInfo::IsNotUndefinedOrStabl($version3->Stage);

    // Вывожу
    echo $res1 . '|' . $res2 . '|' . $res3;

В результате на экране появится:

    false|true|false