Fix inability to express a positive offset of less than an hour

CHANGELOG.md

@@ -18,6 +18,8 @@
 - `Innmind\TimeContinuum\Period::millisecond()` named constructor
 - `Innmind\TimeContinuum\PointInTime::microsecond()`
 - `Innmind\TimeContinuum\Clock::ofFormat()`
+- `Innmind\TimeContinuum\Offset::plus()`
+- `Innmind\TimeContinuum\Offset::minus()`
 
 ### Changed
 
@@ -69,6 +71,7 @@
 - `Innmind\TimeContinuum\ElapsedPeriod::maybe()`
 - `Innmind\TimeContinuum\ElapsedPeriod::ofPeriod()`
 - `Innmind\TimeContinuum\PointInTime::milliseconds()`
+- `Innmind\TimeContinuum\Offset::of()`
 
 ## 3.4.1 - 2023-09-17
 

README.md

@@ -62,7 +62,7 @@ use Innmind\TimeContinuum\{
 
 function foo(PointInTime $point)
 {
-    $point = $point->changeOffset(Offset::of(1, 0));
+    $point = $point->changeOffset(Offset::plus(1, 0));
 }
 ```
 

docs/getting-started/time-offsets.md

@@ -22,7 +22,7 @@ use Innmind\TimeContinuum\{
 };
 
 $utc = Clock::live()->now();
-$newYork = $utc->changeOffset(Offset::of(-5));
+$newYork = $utc->changeOffset(Offset::minus(5));
 ```
 
 If `#!php $utc` represents `#!php '2024-11-24T14:25:00+00:00'` then `#!php $newYork` represents `#!php '2024-11-24T09:25:00-05:00'`.

docs/preface/terminology.md

@@ -30,7 +30,7 @@ Due to politics a city may change its offset at any time (1). And for economic r
 1. This means some points in time don't exist in certain countries or exist twice.
 2. Usually they increase/decrease their offset by 1 or 2 hours.
 
-Because asking the offset for a timezone will yeild different results depending on when you ask for it, it's part of the world that changes. This means that timezones are handled at the [clock](#clock) level.
+Because asking the offset for a timezone will yield different results depending on when you ask for it, it's part of the world that changes. This means that timezones are handled at the [clock](#clock) level.
 
 ## Period
 

docs/upgrade/v3-to-v4.md

@@ -81,7 +81,7 @@ These are the main changes, for an extensive list of changes go to the [changelo
     $clock->now()->timezone()->minutes();
     ```
 
-=== "Before"
+=== "After"
     ```php
     $clock->now()->offset()->hours();
     $clock->now()->offset()->minutes();
@@ -94,9 +94,9 @@ These are the main changes, for an extensive list of changes go to the [changelo
     $clock->now()->changeTimezone(new Earth\Timezone\UTC(2, 0));
     ```
 
-=== "Before"
+=== "After"
     ```php
-    $clock->now()->changeOffset(Offset::of(2, 0));
+    $clock->now()->changeOffset(Offset::plus(2, 0));
     ```
 
 ## Periods

src/Offset.php

@@ -24,18 +24,29 @@ private function __construct(
      */
     public static function utc(): self
     {
-        return self::of(0, 0);
+        return self::plus(0, 0);
     }
 
     /**
      * @psalm-pure
      *
-     * @param int<-12, 14> $hours
+     * @param int<0, 14> $hours
+     * @param int<0, 59> $minutes
+     */
+    public static function plus(int $hours, int $minutes = 0): self
+    {
+        return new self($hours, $minutes, true);
+    }
+
+    /**
+     * @psalm-pure
+     *
+     * @param int<0, 12> $hours
      * @param int<0, 59> $minutes
      */
-    public static function of(int $hours, int $minutes = 0): self
+    public static function minus(int $hours, int $minutes = 0): self
     {
-        return new self($hours, $minutes, $hours > 0);
+        return new self(-$hours, $minutes, false);
     }
 
     /**

tests/ClockTest.php

@@ -41,7 +41,6 @@ public function testSwitchTimezone($switch)
         $live = Clock::live();
         $clock = $live->switch($switch);
 
-        $this->assertNotEquals($live, $clock);
         $this->assertIsString($clock->now()->format(Format::iso8601()));
     }
 

tests/NowTest.php

@@ -67,7 +67,7 @@ public function testChangeOffset()
         $now = new \DateTimeImmutable;
         $now = $now->setTimezone(new \DateTimeZone('-02:30'));
         $point = PointInTime::now();
-        $point2 = $point->changeOffset(Offset::of(-2, 30));
+        $point2 = $point->changeOffset(Offset::minus(2, 30));
 
         $this->assertNotSame($point, $point2);
         $this->assertNotSame($point->year(), $point2->year());

tests/PointInTimeTest.php

@@ -65,7 +65,7 @@ public function testFormat()
     public function testChangeOffset()
     {
         $point = PointInTime::at(new \DateTimeImmutable('2016-10-05T08:01:30.123+02:00'));
-        $point2 = $point->changeOffset(Offset::of(-2, 30));
+        $point2 = $point->changeOffset(Offset::minus(2, 30));
 
         $this->assertNotSame($point, $point2);
         $this->assertNotSame($point->year(), $point2->year());