DateTi...mplete(3pm)

📦
version 0.08 · 5 versions
, in debian bookworm, ubuntu jammy

💖 DateTime::Incomplete — the manual, but make it cute 💖

okay so welcome to DateTime::Incomplete, a Perl module from the User Contributed Perl Documentation section (that's DateTi...mplete(3pm) if you're looking it up by hand, bestie 🫶).

✨ NAME ✨

DateTime::Incomplete — an incomplete datetime, like literally just January 5 and nothing else. it's giving "we know some things but not everything" 💅

🌸 SYNOPSIS 🌸

my $dti = DateTime::Incomplete->new( year => 2003 );
# 2003-xx-xx
$dti->set( month => 12 );
# 2003-12-xx
$dt = $dti->to_datetime( base => DateTime->now );
# 2003-12-19T16:54:33

see how it fills in the blanks with xx until you actually know the tea? iconic behavior honestly ✨

🦋 DESCRIPTION 🦋

DateTime::Incomplete is a class for representing partial dates and times. no cap.

and like, these show up way more than you'd think. for example? a birthday is commonly given as a month and day, without a year. like yeah we know you're a libra but when were you born?? 😭 the vibe check passed but the data didn't.

💀 ERROR HANDLING 💀

Constructor and mutator methods (so like new and set) will die if there's an attempt to set the datetime to an invalid value. dramatic? yes. correct? also yes.

how do they even know it's invalid? they detect it by setting the appropriate fields of a "base" datetime object. go look at the set_base method if you wanna know more 👀

Accessor methods (like day()) are chill tho — they'll return either a value or undef, but they will never die. they're not gonna yell at you, they're just gonna shrug. soft launch energy 🫶

👑 THE "BASE" DATETIME 👑

A DateTime::Incomplete object can have a base DateTime.pm object. this base object is used as a default datetime in the to_datetime() method, and it's also used to validate inputs to the set() method. it's doing double duty, main character energy fr fr 💅

The base object must use the year/month/day system. most calendars use this system, including Gregorian (DateTime) and Julian. but lowkey — this module has not been well tested with base objects from classes other than DateTime.pm class. so like, tread carefully bestie 🙈

By default, newly created DateTime::Incomplete objects have no base. they're free. they're unbothered. they're ✨independent✨.

🌈 DATETIME-LIKE METHODS 🌈

Most methods provided by this class are designed to emulate the behavior of DateTime.pm whenever possible. we're being a good little sibling, basically 🎀

  • new()

Creates a new incomplete date:

my $dti = DateTime::Incomplete->new( year => 2003 );
# 2003-xx-xx

This class method accepts parameters for each date and time component: year, month, day, hour, minute, second, nanosecond. Additionally, it accepts time_zone, locale, and base parameters.

Any parameters not given default to undef. (yes, they just ghost you. it's fine. it's fine 😭)

Calling the new() method without parameters creates a completely undefined datetime:

my $dti = DateTime::Incomplete->new();
  • from_day_of_year( ... )

This constructor takes the same arguments as can be given to the new() method, except that it does not accept a month or day argument. Instead, it requires both year and day_of_year. The day of year must be between 1 and 366, and 366 is only allowed for leap years. 👑

It creates a DateTime::Incomplete object with all date fields defined, but with the time fields (hour, minute, etc.) set to undef. so the date is fully known, the time is a mystery 🕵️‍♀️

  • from_object( object => $object, ... )

This class method can be used to construct a new DateTime::Incomplete object from any object that implements the utc_rd_values() method. All DateTime::Calendar modules must implement this method in order to provide cross-calendar compatibility. This method accepts a locale parameter.

If the object passed to this method has a time_zone() method, that is used to set the time zone. Otherwise UTC is used.

It creates a DateTime::Incomplete object with all fields defined. full send ✨

  • from_epoch( ... )

This class method can be used to construct a new DateTime::Incomplete object from an epoch time instead of components. Just as with the new() method, it accepts time_zone and locale parameters.

If the epoch value is not an integer, the part after the decimal will be converted to nanoseconds. This is done in order to be compatible with Time::HiRes. precision queen 💅

It creates a DateTime::Incomplete object with all fields defined.

  • now( ... )

This class method is equivalent to DateTime->now.

It creates a new DateTime::Incomplete object with all fields defined.

  • today( ... )

This class method is equivalent to now(), but it leaves hour, minute, second and nanosecond undefined. it knows the day but not the moment. it's giving "we'll get there when we get there" 🦋

  • clone

Creates a new object with the same information as the object this method is called on. a little twin. a copy. slay ✨

🎀 "Get" Methods 🎀

  • year
  • month
  • day
  • hour
  • minute
  • second
  • nanosecond
  • time_zone
  • locale

These methods return the field value for the object, or undef. (shrug emoji)

These values can also be accessed using the same alias methods available in DateTime.pm, such as mon(), mday(), etc. so if you learned the nickname version first, you're valid 💖

  • has_year
  • has_month
  • has_day
  • has_hour
  • has_minute
  • has_second
  • has_nanosecond
  • has_time_zone
  • has_locale
  • has_date
  • has_time

Returns a boolean value indicating whether the corresponding component is defined. yes/no. defined/not. vibe check passed or not 💅

has_date tests for year, month, and day.

has_time tests for hour, minute, and second.

  • has
$has_date = $dti->has( 'year', 'month', 'day' );

Returns a boolean value indicating whether all fields in the argument list are defined. it's an all-or-nothing kinda situation 🫶

  • defined_fields
@fields = $dti->defined_fields;   # list of field names

Returns a list containing the names of the fields that are defined.

The list order is: year, month, day, hour, minute, second, nanosecond, time_zone, locale. in that exact order bestie, don't rearrange it 🙈

  • datetime, ymd, date, hms, time, iso8601, mdy, dmy

These are equivalent to DateTime stringification methods with the same name, except that the undefined fields are replaced by 'xx' or 'xxxx' as appropriate. the blanks get filled with x's and honestly it's kind of a look ✨

  • epoch
  • hires_epoch
  • is_dst
  • utc_rd_values
  • utc_rd_as_seconds
my $epoch = $dti->epoch( base => $dt );

These methods are equivalent to the DateTime methods with the same name.

They all accept a base argument to use in order to calculate the method's return values.

If no base argument is given, then today is used. (the default is today, no cap 📅)

  • is_finite, is_infinite

Incomplete dates are always "finite". always. forever. no infinity era for us 💀

  • strftime( $format, ... )

This method implements functionality similar to the strftime() method in C. However, if given multiple format strings, then it will return multiple scalars, one for each format string. buy one get however many you asked for 💅

See the "strftime Specifiers" section in the DateTime.pm documentation for a list of all possible format specifiers.

Undefined fields are replaced by 'xx' or 'xxxx' as appropriate.

The specification %s (epoch) is calculated using today as the base date, unless the object has a base datetime set.

🧚 Computed Values 🧚

All other accessors, such as day_of_week(), or week_year() are computed from the base values for a datetime. When these methods are called, they return the requested information if there is enough data to compute them, otherwise they return undef. it's giving "I'll tell you if I can, but I'm not gonna make stuff up" — respect honestly 🫶

🙈 Unimplemented Methods 🙈

The following DateTime.pm methods are not implemented in DateTime::Incomplete, though some of them may be implemented in future versions (so like... watch this space 👀):

  • add_duration
  • add
  • subtract_duration
  • subtract
  • subtract_datetime
  • subtract_datetime_absolute
  • delta_md
  • delta_days
  • delta_ms
  • compare
  • compare_ignore_floating
  • DefaultLanguage

💜 "Set" Methods 💜

  • set

Use this to set or undefine a datetime field:

$dti->set( month => 12 );
$dti->set( day => 24 );
$dti->set( day => undef );

This method takes the same arguments as the set() method in DateTime.pm, but it can accept undef for any value. you can take it back. you can un-set it. no questions asked 💅

  • set_time_zone

This method accepts either a time zone object or a string that can be passed as the name parameter to DateTime::TimeZone->new().

Unlike with DateTime.pm, if the new time zone's offset is different from the previous time zone, no local time adjustment is made. heads up bestie, that's different from the sibling module 👀

You can remove time zone information by calling this method with the value undef.

  • truncate( to => ... )

This method allows you to reset some of the local time components in the object to their "zero" values. The to parameter is used to specify which values to truncate, and it may be one of year, month, day, hour, minute, or second. For example, if month is specified, then the local day becomes 1, and the hour, minute, and second all become 0. reset era ✨

Note that the to parameter cannot be week. sorry to the week girlies, it's just not happening 😭

✨ "DateTime::Incomplete" METHODS ✨

ok so these are the extra special methods that only DateTime::Incomplete objects have — your regular datetime could never, this is main character exclusive behavior 💅

  • base — hands you back the base datetime value, or undef if your object is out here with none at all 🙈
  • has_base — returns a boolean, like: does this object have a base datetime set or not? yes/no, iconic/hmm.
  • is_undef — returns true when the datetime is completely undefined. like, fully blank. nothing there. ghosted.
  • can_be_datetime — returns true if the datetime has enough info to be converted into a proper DateTime object 🎀

so the deal is: the year field has to be valid, and then it needs a sequence of valid fields after it.

Examples, bestie:

Can be datetime:
2003-xx-xxTxx:xx:xx
2003-10-xxTxx:xx:xx
2003-10-13Txx:xx:xx

Can not be datetime:
2003-10-13Txx:xx:30
xxxx-10-13Txx:xx:30
  • set_base — sets the base datetime object for your DateTime::Incomplete object. The default value for base is undef, which means no validation is made on input (yes, that's a vibe check you're skipping, be aware 👀).
  • to_datetime — takes an optional base parameter and returns a "complete" datetime 💖
$dt = $dti->to_datetime( base => DateTime->now );

$dti->set_base( DateTime->now );
$dt = $dti->to_datetime;

The resulting datetime can land either before or after the given base datetime. No adjustments are made, besides setting the missing fields. no extra editing, just filling in the blanks fr fr.

This method will use today if the object has no base datetime set and none is given as an argument.

⚠️ This method may die if it results in a datetime that doesn't actually exist, like February 30 for example. that date is not real, bestie, and it will not pretend otherwise 😭

The fields in the resulting datetime are set in this order: locale, time_zone, nanosecond, second, minute, hour, day, month, year.

  • to_recurrence — this one generates the set of all possible datetimes that fit into an incomplete datetime definition. obsessed.
$dti = DateTime::Incomplete->new( month => 12, day => 24 );
$dtset1 = $dti->to_recurrence;
# Christmas recurrence, with _seconds_ resolution

$dti->truncate( to => 'day' );
$dtset2 = $dti->to_recurrence;
# Christmas recurrence, with days resolution (hour/min/sec = 00:00:00)

Those recurrences are DateTime::Set objects:

$dt_next_xmas = $dti->to_recurrence->next( DateTime->today );

Incomplete dates that have the year defined will generate finite sets. And heads up: this kind of set can take a LOT of resources (RAM and CPU) 🔥 the following incomplete datetime would generate the set of all seconds in 2003:

2003-xx-xxTxx:xx:xx

Recurrences are generated with up to 1 second resolution. The nanosecond value is ignored. periodt.

  • to_spanset — generates the set of all possible spans that fit into an incomplete datetime definition ✨
$dti = DateTime::Incomplete->new( month => 12, day => 24 );
$dtset1 = $dti->to_spanset;
# Christmas recurrence, from xxxx-12-24T00:00:00
#                         to xxxx-12-25T00:00:00
  • start
  • end
  • to_span

These three methods look at an incomplete datetime as a "time span" 💫

For example, the incomplete datetime 2003-xx-xxTxx:xx:xx starts in 2003-01-01T00:00:00 and ends in 2004-01-01T00:00:00.

The to_span method returns a DateTime::Span object.

An incomplete datetime without a year spans "forever". Start and end datetimes are undef. literally infinite, no cap 🌈

  • contains — returns a true value if the incomplete datetime range contains a given datetime value. does it hold it? is it in there? let's find out.

For example:

2003-xx-xx contains 2003-12-24
2003-xx-xx does not contain 1999-12-14
  • previous / next / closest
$dt2 = $dti->next( $dt );

next() returns the first complete date after or equal to the given datetime.

previous() returns the first complete date before or equal to the given datetime.

closest() returns the closest complete date (previous or next) to the given datetime.

All of these methods return undef if there is no matching complete datetime. no match, no answer, we move on 💀

If no datetime is given, these methods use the base datetime.

📌 Note: the definition of previous() and next() here is different from the methods of the same name in the DateTime::Set class. same name, different personality, don't get them confused bestie.

The datetimes are generated with 1 nanosecond precision. The last time value of a given day is 23:59:59.999999999 (for non leapsecond days).

🫶 SUPPORT

Support for this module is provided via the datetime@perl.org email list. See http://lists.perl.org/ for more details. they're nice, go say hi 💌

👑 AUTHORS

Flavio S. Glock <fglock[at]cpan.org>

With Ben Bennett <fiji[at]ayup.limey.net>, Claus Farber <claus[at]xn--frber-gra.muc.de>, Dave Rolsky <autarch[at]urth.org>, Eugene Van Der Pijll <pijll[at]gmx.net>, Rick Measham <rick[at]isite.net.au>, and the DateTime team. the whole squad, we love to see it 🌸

Copyright (c) 2003 Flavio S. Glock. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

🌈 SEE ALSO

and that's a wrap, bestie 🎀 this page came from perl v5.32.0, dated 2021-01-07, and it's DateTi...mplete(3pm) — go forth and complete your datetimes, you absolute icon 💅✨

📦 where this page comes from