Using Calends in PHP
Calends exposes a very small handful of things for use outside the library
itself. One is the Calends
class, documented here, which should be
the only interface users of the library ever need to touch.
Another thing Calends exposes is the TAITime
class, used to store
and manipulate the instants of time which make up a Calends
instance. The rest are interfaces for extending the library's functionality.
These are covered in the Custom Calendars in PHP
section.
Ghi chú
Calends
objects are immutable - all methods return a new
Calends
object where they might otherwise alter the current one.
This has the side effect of using more memory to perform manipulations than
updating values on an existing object would. It makes many operations safer,
though, than mutable objects would allow.
- class Calends\Calends
The main entry point to Calends and its functionality.
Calends
objects can only be created with theCalends\Calends::create
function, and not directly.Calends
does implement theSerializable
interface, though, so it's safe toserialize
/unserialize
instances if you want.
Create
- static Calends\Calends::create($value, $calendar, $format)
- Tham số
$value (
mixed
) -- The value to parse the date(s)/time(s) from.$calendar (
string
) -- The calendar system to parse the date(s)/time(s) with.$format (
string
) -- The format the date(s)/time(s) is/are expected to use.
- Trả về
A new
Calends
object- Kiểu trả về
- Ném
CalendsException
-- when an error occurs
Creates a new
Calends
object, using$calendar
to select a calendar system, and$format
to parse the contents of$value
into theCalends
object's internal instants. The type of$value
can vary based on the calendar system itself, but generally speaking can always be a string.In any case, the value can always be an associative array, where the keys are any two of
start
,end
, andduration
. If all three are provided,duration
is ignored in favor of calculating it directly.The calendar system then converts
$value
to aTAITime
instant, which theCalends
object sets to the appropriate internal value.
Read
- Calends\Calends::date($calendar, $format)
- Tham số
$calendar (
string
) -- The calendar system to format the date/time with.$format (
string
) -- The format the date/time is expected to be in.- Trả về
The start date of the
Calends
object- Kiểu trả về
string
- Ném
CalendsException
-- when an error occursRetrieves the start date of the
Calends
object as a string. The value is generated by the calendar system given in$calendar
, according to the format string in$format
.
- Calends\Calends::endDate($calendar, $format)
- Tham số
$calendar (
string
) -- The calendar system to format the date/time with.$format (
string
) -- The format the date/time is expected to be in.- Trả về
The end date of the
Calends
object- Kiểu trả về
string
- Ném
CalendsException
-- when an error occursRetrieves the end date of the
Calends
object as a string. The value is generated by the calendar system given in$calendar
, according to the format string in$format
.
Update
- Calends\Calends::withDate($value, $calendar, $format)
- Tham số
$value (
mixed
) -- The value to parse the date/time from.$calendar (
string
) -- The calendar system to parse the date/time with.$format (
string
) -- The format the date/time is expected to use.- Trả về
A new
Calends
object- Kiểu trả về
- Ném
CalendsException
-- when an error occursReturns a
Calends
object with a start date based on the currentCalends
object's value. The inputs are the same as forCalends\Calends::create
, above, except the string → value map option isn't available, since you're already specifically setting the start value explicitly.
- Calends\Calends::withEndDate($value, $calendar, $format)
- Tham số
$value (
mixed
) -- The value to parse the date/time from.$calendar (
string
) -- The calendar system to parse the date/time with.$format (
string
) -- The format the date/time is expected to use.- Trả về
A new
Calends
object- Kiểu trả về
- Ném
CalendsException
-- when an error occursReturns a
Calends
object with an end date based on the currentCalends
object's value. The inputs are the same as forCalends\Calends::create
, above, except the string → value map option isn't available, since you're already specifically setting the end value explicitly.
- Calends\Calends::withDuration($duration, $calendar)
- Tham số
$duration (
string
) -- The value to parse the new duration from.$calendar (
string
) -- The calendar system to parse the date/time with.- Trả về
A new
Calends
object- Kiểu trả về
- Ném
CalendsException
-- when an error occursReturns a
Calends
object with a duration set by adjusting the currentCalends
object's end point, and using its start point as an anchor. The$duration
value is interpreted by the calendar system given in$calendar
, so is subject to any of its rules.
- Calends\Calends::withDurationFromEnd($duration, $calendar)
- Tham số
$duration (
string
) -- The value to parse the new duration from.$calendar (
string
) -- The calendar system to parse the date/time with.- Trả về
A new
Calends
object- Kiểu trả về
- Ném
CalendsException
-- when an error occursReturns a
Calends
object with a duration set by adjusting the currentCalends
object's start point, and using its end point as an anchor. The$duration
value is interpreted by the calendar system given in$calendar
, so is subject to any of its rules.
Manipulate
- Calends\Calends::add($offset, $calendar)
- Tham số
$offset (
string
) -- The value to parse the offset from.$calendar (
string
) -- The calendar system to parse the date/time with.- Trả về
A new
Calends
object- Kiểu trả về
- Ném
CalendsException
-- when an error occursIncreases the end date of the
Calends
object's current value by$offset
, as interpreted by the calendar system given in$calendar
, and returns a newCalends
object with the result.
- Calends\Calends::addFromEnd($offset, $calendar)
- Tham số
$offset (
string
) -- The value to parse the offset from.$calendar (
string
) -- The calendar system to parse the date/time with.- Trả về
A new
Calends
object- Kiểu trả về
- Ném
CalendsException
-- when an error occursIncreases the start date of the
Calends
object's current value by$offset
, as interpreted by the calendar system given in$calendar
, and returns a newCalends
object with the result.
- Calends\Calends::subtract($offset, $calendar)
- Tham số
$offset (
string
) -- The value to parse the offset from.$calendar (
string
) -- The calendar system to parse the date/time with.- Trả về
A new
Calends
object- Kiểu trả về
- Ném
CalendsException
-- when an error occursWorks the same as
add
, except it decreases the start date, rather than increasing it.
- Calends\Calends::subtractFromEnd($offset, $calendar)
- Tham số
$offset (
string
) -- The value to parse the offset from.$calendar (
string
) -- The calendar system to parse the date/time with.- Trả về
A new
Calends
object- Kiểu trả về
- Ném
CalendsException
-- when an error occursWorks the same as
addFromEnd
, except it decreases the end date, rather than increasing it.
- Calends\Calends::next($offset, $calendar)
- Tham số
$offset (
string
) -- The value to parse the offset from.$calendar (
string
) -- The calendar system to parse the date/time with.- Trả về
A new
Calends
object- Kiểu trả về
- Ném
CalendsException
-- when an error occursReturns a
Calends
object of$offset
duration (as interpreted by the calendar system given in$calendar
), which abuts the currentCalends
object's value. If$offset
is empty,$calendar
is ignored, and the current object's duration is used instead.
- Calends\Calends::previous($offset, $calendar)
- Tham số
$offset (
string
) -- The value to parse the offset from.$calendar (
string
) -- The calendar system to parse the date/time with.- Trả về
A new
Calends
object- Kiểu trả về
- Ném
CalendsException
-- when an error occursReturns a
Calends
object of$offset
duration (as interpreted by the calendar system given in$calendar
), which abuts the currentCalends
object's value. If$offset
is empty,$calendar
is ignored, and the current object's duration is used instead.
Combine
- Calends\Calends::merge($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to merge.- Trả về
A new
Calends
object- Kiểu trả về
- Ném
CalendsException
-- when an error occursReturns a
Calends
object spanning from the earliest start date to the latest end date between the currentCalends
object and$c2
.
- Calends\Calends::intersect($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to intersect.- Trả về
A new
Calends
object- Kiểu trả về
- Ném
CalendsException
-- when an error occursReturns a
Calends
object spanning the overlap between the currentCalends
object and$c2
. If the current object and$c2
don't overlap, throws an error.
- Calends\Calends::gap($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to gap.- Trả về
A new
Calends
object- Kiểu trả về
- Ném
CalendsException
-- when an error occursReturns a
Calends
object spanning the gap between the currentCalends
object and$c2
. If the current object and$c2
overlap (and there is, therefore, no gap to return), throws an error.
Compare
- Calends\Calends::difference($c2, $mode)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.$mode (
string
) -- The comparison mode.- Trả về
The difference, as a decimal string
- Kiểu trả về
string
Returns the difference of the current
Calends
object minus$c2
, using$mode
to select which values to use in the calculation. Valid$mode
s include:
start
- use the start date of both the current object and$c2
duration
- use the duration of both the current object and$c2
end
- use the end date of both the current object and$c2
start-end
- use the start of the current object, and the end of$c2
end-start
- use the end of the current object, and the start of$c2
- Calends\Calends::compare($c2, $mode)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.$mode (
string
) -- The comparison mode.- Trả về
A standard comparison result
- Kiểu trả về
int
Returns
-1
if the currentCalends
object is less than$c2
,0
if they are equal, and1
if the current object is greater than$c2
, using$mode
to select which values to use in the comparison. Valid$mode
s are the same as forCalends\Calends::difference
, above.
- Calends\Calends::contains($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Checks whether the current
Calends
object contains all of$c2
.
- Calends\Calends::overlaps($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Checks whether the current
Calends
object overlaps with$c2
.
- Calends\Calends::abuts($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Checks whether the current
Calends
object abuts$c2
(that is, whether one begins at the same instant the other ends).
- Calends\Calends::isSame($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Checks whether the current
Calends
object covers the same span of time as$c2
.
- Calends\Calends::isShorter($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Compares the duration of the current
Calends
object and$c2
.
- Calends\Calends::isSameDuration($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Compares the duration of the current
Calends
object and$c2
.
- Calends\Calends::isLonger($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Compares the duration of the current
Calends
object and$c2
.
- Calends\Calends::isBefore($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Compares the entirety of the current
Calends
object with the start date of$c2
.
- Calends\Calends::startsBefore($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Compares the start date of the current
Calends
object with the start date of$c2
.
- Calends\Calends::endsBefore($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Compares the end date of the current
Calends
object with the start date of$c2
.
- Calends\Calends::isDuring($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Checks whether the entirety of the current
Calends
object lies between the start and end dates of$c2
.
- Calends\Calends::startsDuring($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Checks whether the start date of the current
Calends
object lies between the start and end dates of$c2
.
- Calends\Calends::endsDuring($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Checks whether the end date of the current
Calends
object lies between the start and end dates of$c2
.
- Calends\Calends::isAfter($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Compares the entirety of the current
Calends
object with the end date of$c2
.
- Calends\Calends::startsAfter($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Compares the start date of the current
Calends
object with the end date of$c2
.
- Calends\Calends::endsAfter($c2)
- Tham số
$c2 (
Calends\Calends
) -- TheCalends
object to compare.- Trả về
The result of the comparison
- Kiểu trả về
bool
Compares the end date of the current
Calends
object with the end date of$c2
.
Export
It's possible to export Calends
values in a couple of ways. It
implements Serializable
and JsonSerializable
, as well
as the __toString
method, so the regular mechanisms for each of
those are readily available and usable. In addition, it also offers support for
JSON-decoding values directly:
- static Calends\Calends::jsonUnserialize($encoded)
- Tham số
$encoded (
string
) -- The JSON-encoded value to import.- Trả về
A new
Calends
object- Kiểu trả về
- Ném
CalendsException
-- when an error occurs
Error Handling
- class Calends\CalendsException
A very simple exception class, directly extending
Exception
. It is thrown by the library for all encountered errors.