20250625

* Добавлено перечисление VersionCompareRangeOption.
* В классе VersionInfo добавлен метод CompareWithRange.

sources/classes/VersionInfo.md

@@ -2,9 +2,10 @@
 
 ## Информация о версии
 
-Версия класса: 1.0
+Версия класса: 1.1
 
 Впервые введено в пакет с версии: 1.0.24
+Последнее обновление в версии: 1.0.27
 
 Описание класса: Класс, описывающий информацию о версии.
 
@@ -206,6 +207,106 @@
 
     -1|0|1
 
+#### Метод `CompareWithRange`
+
+Введено в версии `1.0.27`.
+
+Это метод, который проверяет, находится ли текущая версия в заданном диапазоне, указанном в **2 необязательных
+параметрах**:
+
+* `VersionInfo (или null) $left` - левая граница, по умолчанию, `null`;
+* `VersionInfo (или null) $right` - правая граница, по умолчанию, `null`.
+
+В случае, если будет передан `null` вместо левой границы, то метод создаст класс `VersionInfo` с минимально возможной
+версией `0.0.0.0 PreAlpha 0`, а вместо правой - `VersionInfo` с максимально возможной версией
+`9223372036854775807.9223372036854775807.9223372036854775807.9223372036854775807 Stable` (здесь `9223372036854775807` -
+максимальное число INT по умолчанию - у вас может быть другое).
+
+Границы могут совпадать, тогда поведение будет совпадать с методом `CompareWith` (при условии, что границы включены).
+Кроме того, работает защита "от дурака" и если границы перепутаны, то метод автоматически поменяет их местами.
+
+**3-й необязательный параметр** отвечает за параметры сравнения. Это `ObjectArray` из перечисления
+`VersionCompareRangeOption`, который может содержать следующие настройки:
+
+|      Настройка      |               Описание                | Включена по умолчанию |
+|:-------------------:|:-------------------------------------:|:---------------------:|
+| LeftBorderIncluded  | Включена ли левая граница в диапазон  |          ДА           |
+| RightBorderIncluded | Включена ли правая граница в диапазон |          ДА           |
+
+Этот метод возвращает `int`:
+
+|          Текущая версия           | Результат |
+|:---------------------------------:|:---------:|
+|         Младше диапазона          |    -1     |
+| Внутри диапазона (или на границе) |     0     |
+|         Старше диапазона          |     1     |
+
+Синтаксис:
+
+    public function CompareWithRange (?VersionInfo $left = null, ?VersionInfo $right = null, ?ObjectArray $options = null): int
+
+Пример,
+
+    // Создаю объекты
+    // - 1.2.3.4 Beta 1
+    $versionInfo1 = new VersionInfo(1, 2, 3, 4, VersionInfoStage::Beta, 1);
+
+    // - 1.1.3.4 Alpha 2
+    $versionInfo2 = new VersionInfo(1, 1, 3, 4, VersionInfoStage::Alpha, 2);
+
+    // - 1.1.1.1 Alpha 2
+    $versionInfo3 = new VersionInfo(1, 1, 1, 1, VersionInfoStage::Alpha, 2);
+    
+    // - 5.5.5.5 Stable
+    $versionInfo4 = new VersionInfo(5, 5, 5, 5, VersionInfoStage::Stable);
+
+    // Сравниваю
+    echo "Для начала простое сравнение: ";
+    $ver1d1 = $versionInfo1->CompareWithRange($versionInfo3, $versionInfo4);
+    $ver1d2 = $versionInfo2->CompareWithRange($versionInfo1, $versionInfo4);
+    $ver1d2 = $versionInfo4->CompareWithRange($versionInfo2, $versionInfo1);
+    echo "$ver1d1|$ver1d2|$ver1d3 \r\n"
+
+    echo "Немного перепутаем границы =) ";
+    $ver2d1 = $versionInfo4->CompareWithRange($versionInfo1, $versionInfo2);
+    echo "И получим: $ver2d1\r\n";
+
+    echo "А теперь с границами!\r\n";
+    echo "- значение равно левой границе: ";
+    $ver3d1 = $versionInfo2->CompareWithRange($versionInfo2, $versionInfo1);
+    echo " $ver3d1\r\n";
+    echo "- значение равно правой границе: ";
+    $ver3d2 = $versionInfo1->CompareWithRange($versionInfo2, $versionInfo1);
+    echo " $ver3d2\r\n";
+    echo "- а теперь с выключением границ:\r\n";
+    echo "-- для левой: ";
+    $ver3d3 = $versionInfo2->CompareWithRange($versionInfo2, $versionInfo1, $optionNotBorder);
+    echo " $ver3d3\r\n";
+    echo "-- для правой: ";
+    $ver3d4 = $versionInfo1->CompareWithRange($versionInfo2, $versionInfo1, $optionNotBorder);
+    echo " $ver3d4\r\n";
+    echo "А что если границы равны и значение равно?\r\n";
+    echo "- для включённых границ: ";
+    $ver4d1 = $versionInfo1->CompareWithRange($versionInfo1, $versionInfo1);
+    echo " $ver4d1\r\n";
+    echo "- для выключённых границ: ";
+    $ver4d2 = $versionInfo1->CompareWithRange($versionInfo1, $versionInfo1, $optionNotBorder);
+    echo " $ver4d2";
+
+В результате на экране появится:
+
+    Для начала простое сравнение: 0|-1|1
+    Немного перепутаем границы =) И получим: 1
+    А теперь с границами!
+    - значение равно левой границе: 0
+    - значение равно правой границе: 0
+    - а теперь с выключением границ:
+    -- для левой: -1
+    -- для правой: 1
+    А что если границы равны и значение равно?
+    - для включённых границ: 0
+    - для выключённых границ: -1
+
 ### Парсинг версий
 
 Для преобразования строки с версией в объект `VersionInfo` используется статичный метод `Parse`.

sources/classes/VersionInfo.php

@@ -11,7 +11,7 @@ use goodboyalex\php_components_pack\extensions\StringExtension;
  *
  * @author Александр Бабаев
  * @package php_components_pack
- * @version 1.0
+ * @version 1.1
  * @since 1.0.24
  */
 final class VersionInfo
@@ -329,6 +329,11 @@ final class VersionInfo
         // Устанавливаем правую границу
         $rightBorder = $right ?? $maxVersion;
 
+        // Проверяем, что границы не перепутаны
+        if ($leftBorder->CompareWith($rightBorder) == 0)
+            // - если границы перепутаны, то меняем их местами
+            [$leftBorder, $rightBorder] = [$rightBorder, $leftBorder];
+
         // Проверяем текущую версию относительно границ
         $compareLeft = $this->CompareWith($leftBorder);
         $compareRight = $this->CompareWith($rightBorder);