feat(datetime): introduce DateTime component

Signed-off-by: azjezz <azjezz@protonmail.com>
azjezz · Apr 6, 2024 · d84159b · d84159b
1 parent a4bd1e9
commit d84159b
Show file tree

Hide file tree

Showing 106 changed files with 6,499 additions and 245 deletions.
diff --git a/Makefile b/Makefile
@@ -22,8 +22,8 @@ compare-benchmark-to-reference:
 	./vendor/bin/phpbench run --config config/phpbench.json --ref=benchmark_reference
 
 static-analysis:                                                                ## run static analysis checks
-	./vendor/bin/psalm -c config/psalm.xml --show-info=true --no-cache --threads=1
-	./vendor/bin/psalm -c config/psalm.xml tests/static-analysis --no-cache --threads=1
+	./vendor/bin/psalm -c config/psalm.xml --show-info=true --no-cache --threads=2
+	./vendor/bin/psalm -c config/psalm.xml tests/static-analysis --no-cache --threads=2
 
 type-coverage:                                                                  ## send static analysis type coverage metrics to https://shepherd.dev/
 	./vendor/bin/psalm -c config/psalm.xml --shepherd --stats --threads=1

diff --git a/config/.phpcs.xml b/config/.phpcs.xml
@@ -30,6 +30,7 @@
 
     <rule ref="PSR2">
         <type>error</type>
+        <exclude name="PSR2.ControlStructures.ControlStructureSpacing.SpacingAfterOpenBrace"/>
     </rule>
 
     <rule ref="PSR12">

diff --git a/docs/README.md b/docs/README.md
@@ -20,6 +20,7 @@
 - [Psl\Collection](./component/collection.md)
 - [Psl\Comparison](./component/comparison.md)
 - [Psl\DataStructure](./component/data-structure.md)
+- [Psl\DateTime](./component/date-time.md)
 - [Psl\Dict](./component/dict.md)
 - [Psl\Encoding\Base64](./component/encoding-base64.md)
 - [Psl\Encoding\Hex](./component/encoding-hex.md)

diff --git a/docs/component/date-time.md b/docs/component/date-time.md
@@ -0,0 +1,64 @@
+<!--
+    This markdown file was generated using `docs/documenter.php`.
+
+    Any edits to it will likely be lost.
+-->
+
+[*index](./../README.md)
+
+---
+
+### `Psl\DateTime` Component
+
+#### `Constants`
+
+- [DAYS_PER_WEEK](./../../src/Psl/DateTime/constants.php#L0)
+- [HOURS_PER_DAY](./../../src/Psl/DateTime/constants.php#L0)
+- [HOURS_PER_WEEK](./../../src/Psl/DateTime/constants.php#L0)
+- [MICROSECONDS_PER_MILLISECOND](./../../src/Psl/DateTime/constants.php#L0)
+- [MICROSECONDS_PER_SECOND](./../../src/Psl/DateTime/constants.php#L0)
+- [MILLISECONDS_PER_SECOND](./../../src/Psl/DateTime/constants.php#L0)
+- [MINUTES_PER_DAY](./../../src/Psl/DateTime/constants.php#L0)
+- [MINUTES_PER_HOUR](./../../src/Psl/DateTime/constants.php#L0)
+- [MINUTES_PER_WEEK](./../../src/Psl/DateTime/constants.php#L0)
+- [MONTHS_PER_YEAR](./../../src/Psl/DateTime/constants.php#L0)
+- [NANOSECONDS_PER_MICROSECOND](./../../src/Psl/DateTime/constants.php#L0)
+- [NANOSECONDS_PER_MILLISECOND](./../../src/Psl/DateTime/constants.php#L0)
+- [NANOSECONDS_PER_SECOND](./../../src/Psl/DateTime/constants.php#L0)
+- [SECONDS_PER_DAY](./../../src/Psl/DateTime/constants.php#L0)
+- [SECONDS_PER_HOUR](./../../src/Psl/DateTime/constants.php#L0)
+- [SECONDS_PER_MINUTE](./../../src/Psl/DateTime/constants.php#L0)
+- [SECONDS_PER_WEEK](./../../src/Psl/DateTime/constants.php#L0)
+
+#### `Functions`
+
+- [is_leap_year](./../../src/Psl/DateTime/is_leap_year.php#L17)
+
+#### `Interfaces`
+
+- [DateTimeInterface](./../../src/Psl/DateTime/DateTimeInterface.php#L9)
+- [TemporalInterface](./../../src/Psl/DateTime/TemporalInterface.php#L20)
+
+#### `Classes`
+
+- [DateTime](./../../src/Psl/DateTime/DateTime.php#L13)
+- [Duration](./../../src/Psl/DateTime/Duration.php#L30)
+- [Timestamp](./../../src/Psl/DateTime/Timestamp.php#L16)
+
+#### `Traits`
+
+- [DateTimeConvenienceMethodsTrait](./../../src/Psl/DateTime/DateTimeConvenienceMethodsTrait.php#L15)
+- [TemporalConvenienceMethodsTrait](./../../src/Psl/DateTime/TemporalConvenienceMethodsTrait.php#L16)
+
+#### `Enums`
+
+- [Era](./../../src/Psl/DateTime/Era.php#L14)
+- [FormatDateStyle](./../../src/Psl/DateTime/FormatDateStyle.php#L23)
+- [FormatPattern](./../../src/Psl/DateTime/FormatPattern.php#L15)
+- [FormatTimeStyle](./../../src/Psl/DateTime/FormatTimeStyle.php#L23)
+- [Meridiem](./../../src/Psl/DateTime/Meridiem.php#L14)
+- [Month](./../../src/Psl/DateTime/Month.php#L15)
+- [Timezone](./../../src/Psl/DateTime/Timezone.php#L21)
+- [Weekday](./../../src/Psl/DateTime/Weekday.php#L15)
+
+
diff --git a/docs/component/file.md b/docs/component/file.md
@@ -28,9 +28,9 @@
 #### `Classes`
 
 - [Lock](./../../src/Psl/File/Lock.php#L9)
-- [ReadHandle](./../../src/Psl/File/ReadHandle.php#L10)
-- [ReadWriteHandle](./../../src/Psl/File/ReadWriteHandle.php#L11)
-- [WriteHandle](./../../src/Psl/File/WriteHandle.php#L11)
+- [ReadHandle](./../../src/Psl/File/ReadHandle.php#L11)
+- [ReadWriteHandle](./../../src/Psl/File/ReadWriteHandle.php#L12)
+- [WriteHandle](./../../src/Psl/File/WriteHandle.php#L12)
 
 #### `Enums`
 

diff --git a/docs/component/io.md b/docs/component/io.md
@@ -16,7 +16,7 @@
 - [input_handle](./../../src/Psl/IO/input_handle.php#L20)
 - [output_handle](./../../src/Psl/IO/output_handle.php#L20)
 - [pipe](./../../src/Psl/IO/pipe.php#L24)
-- [streaming](./../../src/Psl/IO/streaming.php#L38)
+- [streaming](./../../src/Psl/IO/streaming.php#L41)
 - [write](./../../src/Psl/IO/write.php#L21)
 - [write_error](./../../src/Psl/IO/write_error.php#L23)
 - [write_error_line](./../../src/Psl/IO/write_error_line.php#L23)
@@ -41,7 +41,7 @@
 - [CloseWriteHandleInterface](./../../src/Psl/IO/CloseWriteHandleInterface.php#L7)
 - [CloseWriteStreamHandleInterface](./../../src/Psl/IO/CloseWriteStreamHandleInterface.php#L9)
 - [HandleInterface](./../../src/Psl/IO/HandleInterface.php#L21)
-- [ReadHandleInterface](./../../src/Psl/IO/ReadHandleInterface.php#L10)
+- [ReadHandleInterface](./../../src/Psl/IO/ReadHandleInterface.php#L12)
 - [ReadStreamHandleInterface](./../../src/Psl/IO/ReadStreamHandleInterface.php#L9)
 - [ReadWriteHandleInterface](./../../src/Psl/IO/ReadWriteHandleInterface.php#L7)
 - [ReadWriteStreamHandleInterface](./../../src/Psl/IO/ReadWriteStreamHandleInterface.php#L9)
@@ -54,32 +54,32 @@
 - [SeekWriteHandleInterface](./../../src/Psl/IO/SeekWriteHandleInterface.php#L7)
 - [SeekWriteStreamHandleInterface](./../../src/Psl/IO/SeekWriteStreamHandleInterface.php#L9)
 - [StreamHandleInterface](./../../src/Psl/IO/StreamHandleInterface.php#L9)
-- [WriteHandleInterface](./../../src/Psl/IO/WriteHandleInterface.php#L10)
+- [WriteHandleInterface](./../../src/Psl/IO/WriteHandleInterface.php#L12)
 - [WriteStreamHandleInterface](./../../src/Psl/IO/WriteStreamHandleInterface.php#L9)
 
 #### `Classes`
 
-- [CloseReadStreamHandle](./../../src/Psl/IO/CloseReadStreamHandle.php#L12)
-- [CloseReadWriteStreamHandle](./../../src/Psl/IO/CloseReadWriteStreamHandle.php#L12)
-- [CloseSeekReadStreamHandle](./../../src/Psl/IO/CloseSeekReadStreamHandle.php#L12)
-- [CloseSeekReadWriteStreamHandle](./../../src/Psl/IO/CloseSeekReadWriteStreamHandle.php#L12)
+- [CloseReadStreamHandle](./../../src/Psl/IO/CloseReadStreamHandle.php#L13)
+- [CloseReadWriteStreamHandle](./../../src/Psl/IO/CloseReadWriteStreamHandle.php#L13)
+- [CloseSeekReadStreamHandle](./../../src/Psl/IO/CloseSeekReadStreamHandle.php#L13)
+- [CloseSeekReadWriteStreamHandle](./../../src/Psl/IO/CloseSeekReadWriteStreamHandle.php#L13)
 - [CloseSeekStreamHandle](./../../src/Psl/IO/CloseSeekStreamHandle.php#L10)
-- [CloseSeekWriteStreamHandle](./../../src/Psl/IO/CloseSeekWriteStreamHandle.php#L12)
+- [CloseSeekWriteStreamHandle](./../../src/Psl/IO/CloseSeekWriteStreamHandle.php#L13)
 - [CloseStreamHandle](./../../src/Psl/IO/CloseStreamHandle.php#L10)
-- [CloseWriteStreamHandle](./../../src/Psl/IO/CloseWriteStreamHandle.php#L12)
-- [MemoryHandle](./../../src/Psl/IO/MemoryHandle.php#L13)
-- [ReadStreamHandle](./../../src/Psl/IO/ReadStreamHandle.php#L12)
-- [ReadWriteStreamHandle](./../../src/Psl/IO/ReadWriteStreamHandle.php#L12)
-- [Reader](./../../src/Psl/IO/Reader.php#L16)
-- [SeekReadStreamHandle](./../../src/Psl/IO/SeekReadStreamHandle.php#L12)
-- [SeekReadWriteStreamHandle](./../../src/Psl/IO/SeekReadWriteStreamHandle.php#L12)
+- [CloseWriteStreamHandle](./../../src/Psl/IO/CloseWriteStreamHandle.php#L13)
+- [MemoryHandle](./../../src/Psl/IO/MemoryHandle.php#L14)
+- [ReadStreamHandle](./../../src/Psl/IO/ReadStreamHandle.php#L13)
+- [ReadWriteStreamHandle](./../../src/Psl/IO/ReadWriteStreamHandle.php#L13)
+- [Reader](./../../src/Psl/IO/Reader.php#L17)
+- [SeekReadStreamHandle](./../../src/Psl/IO/SeekReadStreamHandle.php#L13)
+- [SeekReadWriteStreamHandle](./../../src/Psl/IO/SeekReadWriteStreamHandle.php#L13)
 - [SeekStreamHandle](./../../src/Psl/IO/SeekStreamHandle.php#L10)
-- [SeekWriteStreamHandle](./../../src/Psl/IO/SeekWriteStreamHandle.php#L12)
-- [WriteStreamHandle](./../../src/Psl/IO/WriteStreamHandle.php#L12)
+- [SeekWriteStreamHandle](./../../src/Psl/IO/SeekWriteStreamHandle.php#L13)
+- [WriteStreamHandle](./../../src/Psl/IO/WriteStreamHandle.php#L13)
 
 #### `Traits`
 
-- [ReadHandleConvenienceMethodsTrait](./../../src/Psl/IO/ReadHandleConvenienceMethodsTrait.php#L15)
-- [WriteHandleConvenienceMethodsTrait](./../../src/Psl/IO/WriteHandleConvenienceMethodsTrait.php#L16)
+- [ReadHandleConvenienceMethodsTrait](./../../src/Psl/IO/ReadHandleConvenienceMethodsTrait.php#L16)
+- [WriteHandleConvenienceMethodsTrait](./../../src/Psl/IO/WriteHandleConvenienceMethodsTrait.php#L17)
 
 
diff --git a/docs/component/shell.md b/docs/component/shell.md
@@ -12,7 +12,7 @@
 
 #### `Functions`
 
-- [execute](./../../src/Psl/Shell/execute.php#L41)
+- [execute](./../../src/Psl/Shell/execute.php#L42)
 - [stream_unpack](./../../src/Psl/Shell/stream_unpack.php#L30)
 - [unpack](./../../src/Psl/Shell/unpack.php#L16)
 

diff --git a/docs/component/tcp.md b/docs/component/tcp.md
@@ -12,7 +12,7 @@
 
 #### `Functions`
 
-- [connect](./../../src/Psl/TCP/connect.php#L18)
+- [connect](./../../src/Psl/TCP/connect.php#L19)
 
 #### `Classes`
 

diff --git a/docs/component/unix.md b/docs/component/unix.md
@@ -12,7 +12,7 @@
 
 #### `Functions`
 
-- [connect](./../../src/Psl/Unix/connect.php#L18)
+- [connect](./../../src/Psl/Unix/connect.php#L19)
 
 #### `Classes`
 

diff --git a/docs/documenter.php b/docs/documenter.php
@@ -191,6 +191,7 @@ function get_all_components(): array
         'Psl\\Collection',
         'Psl\\Comparison',
         'Psl\\DataStructure',
+        'Psl\\DateTime',
         'Psl\\Dict',
         'Psl\\Encoding\\Base64',
         'Psl\\Encoding\\Hex',

diff --git a/examples/async/usleep.php b/examples/async/usleep.php
@@ -5,22 +5,27 @@
 namespace Psl\Example\IO;
 
 use Psl\Async;
+use Psl\DateTime;
 use Psl\IO;
 
 require __DIR__ . '/../../vendor/autoload.php';
 
 Async\main(static function (): int {
-    $start = time();
+    $start = DateTime\Timestamp::monotonic();
 
     Async\concurrently([
-        static fn() => Async\sleep(2.0),
-        static fn() => Async\sleep(2.0),
-        static fn() => Async\sleep(2.0),
+        static fn() => Async\sleep(DateTime\Duration::hours(0)),
+        static fn() => Async\sleep(DateTime\Duration::minutes(0)),
+        static fn() => Async\sleep(DateTime\Duration::zero()),
+        static fn() => Async\sleep(DateTime\Duration::seconds(2)),
+        static fn() => Async\sleep(DateTime\Duration::nanoseconds(20000000)),
+        static fn() => Async\sleep(DateTime\Duration::microseconds(200000)),
+        static fn() => Async\sleep(DateTime\Duration::milliseconds(2000)),
     ]);
 
-    $duration = time() - $start;
+    $duration = DateTime\Timestamp::monotonic()->since($start);
 
-    IO\write_error_line("duration: %d.", $duration);
+    IO\write_error_line("duration : %s.", $duration->toString(max_decimals: 5));
 
     return 0;
 });
diff --git a/examples/channel/main.php b/examples/channel/main.php
@@ -6,6 +6,7 @@
 
 use Psl\Async;
 use Psl\Channel;
+use Psl\DateTime\Duration;
 use Psl\IO;
 
 require __DIR__ . '/../../vendor/autoload.php';
@@ -16,7 +17,7 @@
  */
 [$receiver, $sender] = Channel\unbounded();
 
-Async\Scheduler::delay(1, static function () use ($sender) {
+Async\Scheduler::delay(Duration::seconds(1), static function () use ($sender) {
     $sender->send('Hello, World!');
 });
 

diff --git a/examples/io/benchmark.php b/examples/io/benchmark.php
@@ -5,13 +5,15 @@
 namespace Psl\Example\IO;
 
 use Psl\Async;
+use Psl\DateTime;
 use Psl\IO;
+use Psl\Math;
 use Psl\Regex;
+
 use function fopen;
 use function getopt;
 use function memory_get_peak_usage;
-use function microtime;
-use function round;
+
 use const PHP_OS_FAMILY;
 
 require __DIR__ . '/../../vendor/autoload.php';
@@ -26,7 +28,7 @@
     $args = getopt('i:o:t:');
     $input_file = $args['i'] ?? '/dev/zero';
     $output_file = $args['o'] ?? '/dev/null';
-    $seconds = (int)($args['t'] ?? 5);
+    $seconds = DateTime\Duration::seconds((int)($args['t'] ?? 5));
 
     // passing file descriptors requires mapping paths (https://bugs.php.net/bug.php?id=53465)
     $input_file = Regex\replace($input_file, '(^/dev/fd/)', 'php://fd/');
@@ -39,7 +41,7 @@
 
     Async\Scheduler::delay($seconds, static fn() => $input->close());
 
-    $start = microtime(true);
+    $start = DateTime\Timestamp::monotonic();
     $i = 0;
     try {
         while ($chunk = $input->read(65536)) {
@@ -51,12 +53,12 @@
     } catch (IO\Exception\AlreadyClosedException) {
     }
 
-    $seconds = microtime(true) - $start;
+    $duration = DateTime\Timestamp::monotonic()->since($start);
     $bytes = $i * 65536;
-    $bytes_formatted = round($bytes / 1024 / 1024 / $seconds, 1);
+    $bytes_formatted = Math\round($bytes / 1024 / 1024 / $duration->getTotalSeconds(), 1);
 
-    IO\write_error_line('read %d byte(s) in %d second(s) => %dMiB/s', $bytes, round($seconds, 3), $bytes_formatted);
-    IO\write_error_line('peak memory usage of %dMiB', round(memory_get_peak_usage(true) / 1024 / 1024, 1));
+    IO\write_error_line('read %d byte(s) in %s => %dMiB/s', $bytes, $duration->toString(), $bytes_formatted);
+    IO\write_error_line('peak memory usage of %dMiB', Math\round(memory_get_peak_usage(true) / 1024 / 1024, 1));
 
     return 0;
 });
diff --git a/examples/io/pipe.php b/examples/io/pipe.php
@@ -5,6 +5,7 @@
 namespace Psl\Example\IO;
 
 use Psl\Async;
+use Psl\DateTime\Duration;
 use Psl\IO;
 
 require __DIR__ . '/../../vendor/autoload.php';
@@ -16,7 +17,7 @@
         static function() use($read): void {
             IO\write_error_line("< sleeping.");
 
-            Async\sleep(0.01);
+            Async\sleep(Duration::milliseconds(10));
 
             IO\write_error_line("< waiting for content.");
 
@@ -30,7 +31,7 @@ static function() use($read): void {
         static function() use($write): void {
             IO\write_error_line('> sleeping.');
 
-            Async\sleep(0.1);
+            Async\sleep(Duration::milliseconds(100));
 
             IO\write_error_line('> writing.');
 

diff --git a/examples/io/queued.php b/examples/io/queued.php
@@ -15,7 +15,7 @@
 
     $he = Async\run(static fn(): string => $read->readFixedSize(2));
 
-    Async\sleep(0.001);
+    Async\sleep(Psl\DateTime\Duration::milliseconds(200));
 
     $write->write("hello");
 

diff --git a/examples/run.php b/examples/run.php
@@ -6,6 +6,7 @@
 namespace Psl\Example\IO;
 
 use Psl\Async;
+use Psl\DateTime;
 use Psl\Filesystem;
 use Psl\IO;
 use Psl\Shell;
@@ -34,9 +35,9 @@
             IO\write_error_line('- %s/%s   -> started', $component, $script);
 
             $awaitables[] = Async\run(static function() use($component, $script, $file): array {
-                $start = microtime(true);
+                $start = DateTime\Timestamp::monotonic();
                 Shell\execute(PHP_BINARY, [$file]);
-                $duration = microtime(true) - $start;
+                $duration = DateTime\Timestamp::monotonic()->since($start);
 
                 return [$component, $script, $duration];
             });
@@ -46,7 +47,7 @@
     foreach (Async\Awaitable::iterate($awaitables) as $awaitable) {
         [$component, $script, $duration] = $awaitable->await();
 
-        IO\write_error_line('+ %s/%s   -> finished in %ds', $component, $script, $duration);
+        IO\write_error_line('+ %s/%s   -> finished in %s', $component, $script, $duration->toString());
     }
 
     return 0;

diff --git a/examples/shell/timeout.php b/examples/shell/timeout.php
@@ -5,14 +5,15 @@
 namespace Psl\Example\Shell;
 
 use Psl\Async;
+use Psl\DateTime;
 use Psl\IO;
 use Psl\Shell;
 
 require __DIR__ . '/../../vendor/autoload.php';
 
 Async\main(static function (): void {
     try {
-        Shell\execute('sleep', ['1'], timeout: 0.5);
+        Shell\execute('sleep', ['1'], timeout: DateTime\Duration::milliseconds(500));
     } catch (Shell\Exception\TimeoutException $exception) {
         IO\write_error_line($exception->getMessage());
     }