Skip to content

Commit

Permalink
Update package docblocks
Browse files Browse the repository at this point in the history
  • Loading branch information
@nyamsprod
nyamsprod committed May 23, 2022
1 parent 00f8928 commit 99bcedb
Show file tree
Hide file tree
Showing 4 changed files with 47 additions and 33 deletions.
8 changes: 4 additions & 4 deletions src/Bounds.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -100,10 +100,10 @@ public function buildIso80000(string $start, string $end): string
public function buildBourbaki(string $start, string $end): string
{
return match ($this) {
self::IncludeAll => "[$start, $end]",
self::IncludeStartExcludeEnd => "[$start, {$end}[",
self::ExcludeAll => "]$start, {$end}[",
self::ExcludeStartIncludeEnd => "]$start, $end]",
self::IncludeAll => '['.$start.', '.$end.']',
self::IncludeStartExcludeEnd => '['.$start.', '.$end.'[',
self::ExcludeAll => ']'.$start.', '.$end.'[',
self::ExcludeStartIncludeEnd => ']'.$start.', '.$end.']',
};
}

Expand Down
4 changes: 4 additions & 0 deletions src/DatePoint.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
use DateTimeImmutable;
use DateTimeInterface;
use DateTimeZone;
use Exception;
use function date_default_timezone_get;
use function intdiv;

Expand Down Expand Up @@ -50,6 +51,9 @@ public static function fromDate(DateTimeInterface $date): self
return new self($date);
}

/**
* @throws Exception
*/
public static function fromDateString(string $dateString, DateTimeZone|string $timezone = null): self
{
$timezone ??= date_default_timezone_get();
Expand Down
3 changes: 3 additions & 0 deletions src/Duration.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
use DateInterval;
use DateTimeImmutable;
use DateTimeInterface;
use Exception;
use InvalidArgumentException;
use function preg_match;
use function str_pad;
Expand Down Expand Up @@ -61,6 +62,8 @@ public static function __set_state(array $properties): self

/**
* Returns a new instance from an interval specification.
*
* @throws Exception
*/
public static function fromIsoString(string $duration): self
{
Expand Down
65 changes: 36 additions & 29 deletions src/Period.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@
use DateTimeImmutable;
use DateTimeInterface;
use DateTimeZone;
use Exception;
use Generator;
use JsonSerializable;
use Throwable;

/**
* An immutable value object class to manipulate DateTimeInterface interval.
Expand Down Expand Up @@ -69,13 +69,13 @@ public static function fromIso8601(string $format, string $notation, Bounds $bou
$end = trim($found['end']);

$findDuration = static function (string $duration): Duration|null {
if (1 !== preg_match('/^P([YMDTHS\d\.]+)$/', $duration)) {
if (1 !== preg_match('/^P([YMDTHS\d.]+)$/', $duration)) {
return null;
}

try {
return Duration::fromIsoString($duration);
} catch (Throwable) {
} catch (Exception) {
return null;
}
};
Expand Down Expand Up @@ -157,6 +157,9 @@ private static function fromDateString(string $format, string $startDate, string
);
}

/**
* @throws Exception
*/
public static function fromDate(
DatePoint|DateTimeInterface|string $startDate,
DatePoint|DateTimeInterface|string $endDate,
Expand All @@ -165,13 +168,16 @@ public static function fromDate(
return new self(self::filterDatePoint($startDate), self::filterDatePoint($endDate), $bounds);
}

private static function filterDatePoint(DatePoint|DateTimeInterface|string $datepoint): DateTimeImmutable
/**
* @throws Exception
*/
private static function filterDatePoint(DatePoint|DateTimeInterface|string $datePoint): DateTimeImmutable
{
return match (true) {
$datepoint instanceof DatePoint => $datepoint->date,
$datepoint instanceof DateTimeImmutable => $datepoint,
$datepoint instanceof DateTimeInterface => DateTimeImmutable::createFromInterface($datepoint),
default => DatePoint::fromDateString($datepoint)->date,
$datePoint instanceof DatePoint => $datePoint->date,
$datePoint instanceof DateTimeImmutable => $datePoint,
$datePoint instanceof DateTimeInterface => DateTimeImmutable::createFromInterface($datePoint),
default => DatePoint::fromDateString($datePoint)->date,
};
}

Expand Down Expand Up @@ -215,7 +221,7 @@ public static function after(

/**
* Creates new instance where the given duration is simultaneously
* subtracted from and added to the given datepoint.
* subtracted from and added to the given date endpoint.
*/
public static function around(
DatePoint|DateTimeInterface|string $midpoint,
Expand All @@ -229,7 +235,7 @@ public static function around(
}

/**
* Creates new instance from a ending date endpoint and a duration.
* Creates new instance from an ending date endpoint and a duration.
*/
public static function before(
DatePoint|DateTimeInterface|string $endDate,
Expand Down Expand Up @@ -474,10 +480,10 @@ public function isBefore(Period|DatePoint|DateTimeInterface|string $timeSlot): b
return $this->endDate <= $timeSlot->startDate;
}

$datepoint = self::filterDatePoint($timeSlot);
$datePoint = self::filterDatePoint($timeSlot);

return $this->endDate < $datepoint
|| ($this->endDate == $datepoint && !$this->bounds->isEndIncluded());
return $this->endDate < $datePoint
|| ($this->endDate == $datePoint && !$this->bounds->isEndIncluded());
}

/**
Expand Down Expand Up @@ -506,7 +512,7 @@ public function meetsOnStart(self $timeSlot): bool
}

/**
* Tells whether two intervals share the same start datepoint
* Tells whether two intervals share the same start date endpoint
* and the same starting boundary type.
*
* [----------)
Expand Down Expand Up @@ -578,22 +584,22 @@ private function containsInterval(self $timeSlot): bool
}

/**
* Tells whether an instance contains a datepoint.
* Tells whether an instance contains a date endpoint.
*
* [------|------------)
*/
private function containsDatePoint(DateTimeInterface $datepoint, Bounds $bounds): bool
private function containsDatePoint(DateTimeInterface $datePoint, Bounds $bounds): bool
{
return match ($bounds) {
Bounds::ExcludeAll => $datepoint > $this->startDate && $datepoint < $this->endDate,
Bounds::IncludeAll => $datepoint >= $this->startDate && $datepoint <= $this->endDate,
Bounds::ExcludeStartIncludeEnd => $datepoint > $this->startDate && $datepoint <= $this->endDate,
Bounds::IncludeStartExcludeEnd => $datepoint >= $this->startDate && $datepoint < $this->endDate,
Bounds::ExcludeAll => $datePoint > $this->startDate && $datePoint < $this->endDate,
Bounds::IncludeAll => $datePoint >= $this->startDate && $datePoint <= $this->endDate,
Bounds::ExcludeStartIncludeEnd => $datePoint > $this->startDate && $datePoint <= $this->endDate,
Bounds::IncludeStartExcludeEnd => $datePoint >= $this->startDate && $datePoint < $this->endDate,
};
}

/**
* Tells whether two intervals share the same datepoints.
* Tells whether two intervals share the same date endpoints.
*
* [--------------------)
* [--------------------)
Expand All @@ -606,7 +612,7 @@ public function equals(self $timeSlot): bool
}

/**
* Tells whether two intervals share the same end datepoint
* Tells whether two intervals share the same end date endpoint
* and the same ending boundary type.
*
* [----------)
Expand Down Expand Up @@ -790,13 +796,14 @@ public function dateRangeBackwards(Period|Duration|DateInterval|string $timeDelt
public function splitForward(Period|Duration|DateInterval|string $duration): Generator
{
$duration = self::filterDuration($duration);
/** @var DateTimeImmutable $startDate */
foreach ($this->dateRangeForward($duration) as $startDate) {
$endDate = $startDate->add($duration);
if ($endDate > $this->endDate) {
$endDate = $this->endDate;
}

yield new self($startDate, $endDate, $this->bounds);
yield self::fromDate($startDate, $endDate, $this->bounds);
}
}

Expand Down Expand Up @@ -836,12 +843,12 @@ public function splitBackwards(Period|Duration|DateInterval|string $duration): G
* Returns the computed difference between two overlapping instances as
* an array containing Period objects or the null value.
*
* The array will always contains 2 elements:
* The array will always contain 2 elements:
*
* <ul>
* <li>an NULL filled array if both objects have the same datepoints</li>
* <li>one Period object and NULL if both objects share one datepoint</li>
* <li>two Period objects if both objects share no datepoint</li>
* <li>an NULL filled array if both objects have the same date endpoints</li>
* <li>one Period object and NULL if both objects share one date endpoint</li>
* <li>two Period objects if both objects share no date endpoint</li>
* </ul>
*
* [--------------------)
Expand Down Expand Up @@ -932,7 +939,7 @@ public function subtract(self ...$periods): Sequence
* =
* [----)
*
* @throws UnprocessableInterval If both objects do not overlaps
* @throws UnprocessableInterval If both objects do not overlap
*/
public function intersect(self ...$periods): self
{
Expand Down Expand Up @@ -977,7 +984,7 @@ public function union(self ...$periods): Sequence
* The resulting instance represents the largest duration possible.
*
* This method MUST retain the state of the current instance, and return
* an instance that contains the specified new datepoints.
* an instance that contains the specified new date endpoints.
*
* [--------------------)
* +
Expand Down

0 comments on commit 99bcedb

Please sign in to comment.