From f687b30399cfe628966db0897ec31c072a5ba270 Mon Sep 17 00:00:00 2001 From: Baptiste Langlade Date: Sat, 17 Jan 2026 18:14:41 +0100 Subject: [PATCH] fix documentation --- docs/getting-started/clocks.md | 24 ++-- docs/getting-started/elapsed-period.md | 4 +- docs/getting-started/formats.md | 16 +-- docs/getting-started/halt.md | 13 +++ docs/getting-started/index.md | 2 +- docs/getting-started/periods.md | 6 +- docs/getting-started/points-in-time.md | 6 +- docs/getting-started/time-offsets.md | 6 +- docs/getting-started/timezones.md | 10 +- docs/index.md | 6 +- docs/preface/philosophy.md | 2 +- docs/preface/terminology.md | 10 +- docs/upgrade/v3-to-v4.md | 155 ------------------------- mkdocs.yml | 9 +- 14 files changed, 65 insertions(+), 204 deletions(-) create mode 100644 docs/getting-started/halt.md delete mode 100644 docs/upgrade/v3-to-v4.md diff --git a/docs/getting-started/clocks.md b/docs/getting-started/clocks.md index 9b59cdf..4cebbba 100644 --- a/docs/getting-started/clocks.md +++ b/docs/getting-started/clocks.md @@ -10,39 +10,39 @@ This is the clock you should use in your programs. By default it's set to the [U To access the current time you would do: ```php -use Innmind\TimeContinuum\{ +use Innmind\Time\{ Clock, - PointInTime, + Point, }; $clock = Clock::live(); -$point = $clock->now(); // instance of PointInTime +$point = $clock->now(); // instance of Point echo $point->toString(); // prints something like 2024-11-24T12:34:25+00:00 ``` -And to build a [`PointInTime`](points-in-time.md) back from a `string`: +And to build a [`Point`](points-in-time.md) back from a `string`: ```php -use Innmind\TimeContinuum\{ +use Innmind\Time\{ Clock, Format, - PointInTime, + Point, }; use Innmind\Immutable\Attempt; $time = '2024-11-24T12:34:25+00:00'; $clock = Clock::live(); -$at = $clock->at($time, Format::iso8601()); // instance of Attempt +$at = $clock->at($time, Format::iso8601()); // instance of Attempt $point = $at->match( - static fn(PointInTime $point) => $point, + static fn(Point $point) => $point, static fn() => null, ); ``` -The `at` method returns an [`Attempt` monad](https://innmind.org/Immutable/structures/attempt/) that may contain a `PointInTime`. This is in case the `#!php $time` variable contains a value that doesn't correspond to the specified format (here `ISO8601`). +The `at` method returns an [`Attempt` monad](https://innmind.org/Immutable/structures/attempt/) that may contain a `Point`. This is in case the `#!php $time` variable contains a value that doesn't correspond to the specified format (here `ISO8601`). -This means that the `#!php $point` variable here is an instance of `PointInTime` because the `#!php $time` value is valid. If it's invalid then `#!php $point` is `#!php null`. +This means that the `#!php $point` variable here is an instance of `Point` because the `#!php $time` value is valid. If it's invalid then `#!php $point` is `#!php null`. ## Logger @@ -51,7 +51,7 @@ This clock will create a log everytime you call `#!php ->now()` or `#!php ->at() To build this clock you need another clock (typically a live one) and a [PSR logger](https://packagist.org/packages/psr/log): ```php -use Innmind\TimeContinuum\Clock; +use Innmind\Time\Clock; use Psr\Log\LoggerInterface; $clock = Clock::logger( @@ -71,7 +71,7 @@ This clock is only useful when testing your program. It allows to specify the po This way you can test your program for special scenarii like a leap year, daylight saving time and so on... ```php -use Innmind\TimeContinuum\{ +use Innmind\Time\{ Clock, Format, }; diff --git a/docs/getting-started/elapsed-period.md b/docs/getting-started/elapsed-period.md index b8a1710..f5d1b27 100644 --- a/docs/getting-started/elapsed-period.md +++ b/docs/getting-started/elapsed-period.md @@ -3,7 +3,7 @@ This is the number of microseconds between two [points in time](points-in-time.md). ```php -use Innmind\TimeContinuum\Clock; +use Innmind\Time\Clock; $clock = Clock::live(); $start = $clock->now(); @@ -13,7 +13,7 @@ $end = $clock->now(); $elapsed = $end->elapsedSince($start); ``` -`$elapsed` is an instance of `#!php Innmind\TimeContinuum\ElapsedPeriod`. +`$elapsed` is an instance of `#!php Innmind\Time\ElapsedPeriod`. This is especially useful when working with network I/O to check for timeouts. diff --git a/docs/getting-started/formats.md b/docs/getting-started/formats.md index bdb5d57..e09bbec 100644 --- a/docs/getting-started/formats.md +++ b/docs/getting-started/formats.md @@ -1,11 +1,11 @@ # Formats -A `Format` is a representation on how to convert a [`PointInTime`](points-in-time.md) to a `string`, or vice versa. +A `Format` is a representation on how to convert a [`Point`](points-in-time.md) to a `string`, or vice versa. By default this library comes with these formats: ```php -use Innmind\TimeContinuum\Format; +use Innmind\Time\Format; Format::cookie(); Format::iso8601(); @@ -22,7 +22,7 @@ Formats are wrapped in an object in order to give them a name. When used in your ## Convert to a string ```php -use Innmind\TimeContinuum\{ +use Innmind\Time\{ Clock, Format, }; @@ -37,16 +37,16 @@ This would print something like `#!php '2024-11-24T14:50:00+00:00'`. ## Convert from a string ```php -use Innmind\TimeContinuum\{ +use Innmind\Time\{ Clock, Format, - PointInTime, + Point, }; $point = Clock::live() ->at('some string', Format::iso8601()) ->match( - static fn(PointInTime $point) => $point, + static fn(Point $point) => $point, static fn() => null, ); ``` @@ -61,7 +61,7 @@ You're encouraged to statically define these formats somewhere in your program l === "Static method" ```php - use Innmind\TimeContinuum\Format; + use Innmind\Time\Format; final class MyFormats { @@ -74,7 +74,7 @@ You're encouraged to statically define these formats somewhere in your program l === "Enum" ```php - use Innmind\TimeContinuum\Format; + use Innmind\Time\Format; enum MyFormats: string implements Format\Custom { diff --git a/docs/getting-started/halt.md b/docs/getting-started/halt.md new file mode 100644 index 0000000..6bd842e --- /dev/null +++ b/docs/getting-started/halt.md @@ -0,0 +1,13 @@ +# Halt process + +```php +use Innmind\Time\{ + Halt, + Period, +}; + +$halt = Halt::new(); +$halt(Period::second(1))->unwrap(); +``` + +This is the equivalent of `sleep(1)`. diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 4971c3d..1503e33 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -3,5 +3,5 @@ ## Installation ```sh -composer require innmind/time-continuum +composer require innmind/time ``` diff --git a/docs/getting-started/periods.md b/docs/getting-started/periods.md index 3f15f7a..7f69c5c 100644 --- a/docs/getting-started/periods.md +++ b/docs/getting-started/periods.md @@ -3,7 +3,7 @@ ## Go forward in time ```php -use Innmind\TimeContinuum\{ +use Innmind\Time\{ Clock, Period, }; @@ -21,7 +21,7 @@ $future = Clock::live() ## Go back in time ```php -use Innmind\TimeContinuum\{ +use Innmind\Time\{ Clock, Period, }; @@ -39,7 +39,7 @@ $past = Clock::live() ## Compare to an elapsed period ```php -use Innmind\TimeContinuum\{ +use Innmind\Time\{ Clock, Period, }; diff --git a/docs/getting-started/points-in-time.md b/docs/getting-started/points-in-time.md index 63968ba..9e99d28 100644 --- a/docs/getting-started/points-in-time.md +++ b/docs/getting-started/points-in-time.md @@ -2,7 +2,7 @@ See the [clocks](clocks.md) to learn to have access to these objects. -All examples below use the `#!php $point` variable that reference an instance of `#!php Innmind\TimeContinuum\PointInTime`. +All examples below use the `#!php $point` variable that reference an instance of `#!php Innmind\Time\Point`. ## Year @@ -24,7 +24,7 @@ This returns `#!php 365` or `#!php 366` on leap years. $point->month()->ofYear(); ``` -This returns a value from the enum `#!php Innmind\TimeContinuum\Calendar\Month`. +This returns a value from the enum `#!php Innmind\Time\Calendar\Month`. ```php $point->month()->numberOfDays(); @@ -50,7 +50,7 @@ This returns an `int` between `#!php 1` and `#!php 31`. $point->day()->ofWeek(); ``` -This returns a value from the enum `#!php Innmind\TimeContinuum\Calendar\Day`. +This returns a value from the enum `#!php Innmind\Time\Calendar\Day`. ## Hour diff --git a/docs/getting-started/time-offsets.md b/docs/getting-started/time-offsets.md index 3672e0e..aaed1c1 100644 --- a/docs/getting-started/time-offsets.md +++ b/docs/getting-started/time-offsets.md @@ -3,7 +3,7 @@ This is a value retrieved from a [point in time](points-in-time.md) and is expressed in a number of hours and minutes. ```php -use Innmind\TimeContinuum\Clock; +use Innmind\Time\Clock; $offset = Clock::live()->now()->offset(); ``` @@ -13,10 +13,10 @@ $offset = Clock::live()->now()->offset(); Via this object you cannot know in which [timezone](timezones.md) you're in. If you need to keep track of this you should model this in your program and not rely on this information. -When you have access to a `PointInTime` you can change its offset like this: +When you have access to a `Point` you can change its offset like this: ```php -use Innmind\TimeContinuum\{ +use Innmind\Time\{ Clock, Offset, }; diff --git a/docs/getting-started/timezones.md b/docs/getting-started/timezones.md index fbfce16..210b6f0 100644 --- a/docs/getting-started/timezones.md +++ b/docs/getting-started/timezones.md @@ -2,19 +2,19 @@ A timezone is a [time offset](time-offsets.md) referenced by a city name. -As described in the [terminology](../preface/terminology.md#timezone) section the offset for a city may not always be the same depending when you are in time. +As described in the [terminology](../preface/terminology.md#zone) section the offset for a city may not always be the same depending when you are in time. Because it can change, a timezone is handled at the [clock](clocks.md) level. By default the clock offset is `+00:00` but you can change it like this: ```php -use Innmind\TimeContinuum\{ +use Innmind\Time\{ Clock, - Timezones, + Zones, }; $utc = Clock::live(); $paris = $utc->switch( - static fn(Timezones $timezones) => $timezones + static fn(Zones $timezones) => $timezones ->europe() ->paris(), ); @@ -29,7 +29,7 @@ We now have two clocks. `#!php $utc` is still at `+00:00` and `#!php $paris` wil ## Available timezones -`#!php $timezones` represents an intance of `Innmind\TimeContinuum\Timezones`. +`#!php $timezones` represents an intance of `Innmind\Time\Zones`. === "Africa" ```php diff --git a/docs/index.md b/docs/index.md index c802b1c..455f8e0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,9 +4,9 @@ hide: - toc --- -# Welcome to TimeContinnum +# Welcome to Time -TimeContinuum is a time abstraction library. +This is a time abstraction library. The goal is to provide a safe way to manipulate time in your programs. @@ -17,7 +17,7 @@ It achieves this via: ??? example "Sneak peek" ```php - use Innmind\TimeContinuum\{ + use Innmind\Time\{ Clock, Format, }; diff --git a/docs/preface/philosophy.md b/docs/preface/philosophy.md index 203aed5..d9e8bf0 100644 --- a/docs/preface/philosophy.md +++ b/docs/preface/philosophy.md @@ -1,6 +1,6 @@ # Philosophy -TimeContinuum is designed around these objectives: +It is designed around these objectives: - an expressive API through a clear naming - to handle time with precision diff --git a/docs/preface/terminology.md b/docs/preface/terminology.md index bcaca6e..588110d 100644 --- a/docs/preface/terminology.md +++ b/docs/preface/terminology.md @@ -4,12 +4,12 @@ A `Clock` is the root object to access time. Like a real clock, each time you demand the time it will provide a new value. This is part of the world that can change. -Unlike real clocks, in a program we often have the use case to convert a `string` back to a [time](#point-in-time) representation (1). Clocks provide a method for this. You can think of it as a factory. Even though this is done by a clock this method is determinist, meaning that you'll always have the same result for the same inputs. +Unlike real clocks, in a program we often have the use case to convert a `string` back to a [time](#point) representation (1). Clocks provide a method for this. You can think of it as a factory. Even though this is done by a clock this method is determinist, meaning that you'll always have the same result for the same inputs. {.annotate} 1. Such as reading a value from a database. -## Point in time +## Point As its name suggest it represents a fixed point in time on Earth. It represents time down to the microsecond. It also stores the time offset from [UTC](https://en.wikipedia.org/wiki/UTC%2B00:00). @@ -17,7 +17,7 @@ These objects are generated by clocks. Once an object is created it can no longer change. But you can still create objects relative to it by specifying a [period](#period) and the direction. -## Timezone +## Zone A timezone represents a time offset from [UTC](https://en.wikipedia.org/wiki/UTC%2B00:00) for a set of cities on Earth (1). {.annotate} @@ -70,3 +70,7 @@ This is an attempt to solve the problem (1) where the same format is duplicated {.annotate} 1. We can see this practive in a lot of programs. + +## Halt + +It represents the way to pause the process for a given [period](#period). diff --git a/docs/upgrade/v3-to-v4.md b/docs/upgrade/v3-to-v4.md deleted file mode 100644 index b01ce78..0000000 --- a/docs/upgrade/v3-to-v4.md +++ /dev/null @@ -1,155 +0,0 @@ -# From v3 to v4 - -All namespaces are relative to `\Innmind\TimeContinuum\`. - -These are the main changes, for an extensive list of changes go to the [changelog](https://github.com/Innmind/TimeContinuum/blob/develop/CHANGELOG.md). - -## Clocks - -### Live clock - -=== "Before" - ```php - $clock = new Earth\Clock; - ``` - -=== "After" - ```php - $clock = Clock::live(); - ``` - -### Logger - -=== "Before" - ```php - $clock = new Logger\Clock( - new Earth\Clock, - /* an instance of Psr\Log\LoggerInterface */ - ); - ``` - -=== "After" - ```php - $clock = Clock::logger( - Clock::live(), - /* an instance of Psr\Log\LoggerInterface */ - ); - ``` - -### Frozen - -=== "Before" - ```php - $clock = new Earth\FrozenClock( - new Earth\PointInTime\PointInTime('some date'), - ); - ``` - -=== "After" - ```php - $clock = Clock::live() - ->at('some date', Format::iso8601()) - ->match( - Clock::frozen(...), - static fn() => throw new \LogicException('Use a valid date'), - ); - ``` - -## Timezones - -=== "Before" - ```php - $clock = new Earth\Clock( - new Earth\Timezone\Europe\Paris, - ); - ``` - -=== "After" - ```php - $clock = Clock::live()->switch( - static fn(Timezones $timezones) => $timezones - ->europe() - ->paris(), - ); - ``` - -## Access point in time offset - -=== "Before" - ```php - $clock->now()->timezone()->hours(); - $clock->now()->timezone()->minutes(); - ``` - -=== "After" - ```php - $clock->now()->offset()->hours(); - $clock->now()->offset()->minutes(); - ``` - -## Modify point in time offset - -=== "Before" - ```php - $clock->now()->changeTimezone(new Earth\Timezone\UTC(2, 0)); - ``` - -=== "After" - ```php - $clock->now()->changeOffset(Offset::plus(2, 0)); - ``` - -## Periods - -=== "Before" - ```php - new Earth\Period\Year(42); - new Earth\Period\Month(42); - new Earth\Period\Day(42); - new Earth\Period\Hour(42); - new Earth\Period\Minute(42); - new Earth\Period\Second(42); - new Earth\Period\Millisecond(42); - ``` - -=== "After" - ```php - Period::year(42); - Period::month(42); - Period::day(42); - Period::hour(42); - Period::minute(42); - Period::second(42); - Period::millisecond(42); - ``` - -## Formats - -=== "Before" - ```php - $clock->now()->format(new Earth\Format\ISO8601); - ``` - -=== "After" - ```php - $clock->now()->format(Format::iso8601()); - ``` - -## Elapsed periods - -=== "Before" - ```php - $elapsed = /* any instance of ElapsedPeriod */ - $milliseconds = $elapsed->milliseconds(); - ``` - -=== "After" - ```php - $elapsed = /* any instance of ElapsedPeriod */ - $period = $elapsed->asPeriod(); - $milliseconds = Period\Value::day->seconds($period->days()); - $milliseconds += Period\Value::hour->seconds($period->hours()); - $milliseconds += Period\Value::minute->seconds($period->minutes()); - $milliseconds *= 1_000; - $milliseconds += $period->milliseconds(); - ``` diff --git a/mkdocs.yml b/mkdocs.yml index 05ec14f..6e43af1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ -site_name: Innmind/TimeContinuum -repo_name: Innmind/TimeContinuum +site_name: Innmind/Time +repo_name: Innmind/Time nav: - Home: index.md @@ -15,8 +15,7 @@ nav: - Timezones: getting-started/timezones.md - Formats: getting-started/formats.md - Periods: getting-started/periods.md - - Upgrade: - - From v3 to v4: upgrade/v3-to-v4.md + - Halt: getting-started/halt.md theme: name: material @@ -99,6 +98,6 @@ plugins: extra: social: - icon: fontawesome/brands/github - link: https://github.com/Innmind/TimeContinuum + link: https://github.com/Innmind/time - icon: fontawesome/brands/x-twitter link: https://twitter.com/Baptouuuu