NAME

Time::P - Parse times from strings.

VERSION

version 0.024

SYNOPSIS

  use Time::P; # strptime() automatically exported.
  use Time::C;

  # "2016-10-30T16:07:34Z"
  my $t = Time::C->mktime(strptime("sön okt 30 16:07:34 UTC 2016", "%a %b %d %T %Z %Y", locale => "sv_SE"));

DESCRIPTION

Parses a string to get a time out of it using "Format Specifiers" reminiscent of C's scanf and indeed strptime functions.

FUNCTIONS

strptime

  my %struct = strptime($str, $fmt);
  my %struct = strptime($str, $fmt, locale => $locale, strict => $strict, struct => \%struct);

strptime takes a string and a format which it parses the string with, and returns key-value pairs of the parsed bits of time.

$str

$str is the string to parse.

$fmt

$fmt is the format specifier used to parse the $str. If it can't match $str it will throw an exception. See "Format Specifiers" for details on the supported format specifiers.

locale => $locale

$locale is an optional parameter which defaults to C. It is used to determine how the format specifiers %a, %A, %b, %B, %c, %p, and %r match. See "Format Specifiers" for more details.

strict => $strict

$strict is an optional boolean flag which defaults to true. If it is a true value, the $fmt must describe the string entirely. If it is false, the $fmt may describe only part of the string, and any extra bits, either before or after, are discarded.

struct => \%struct

If passed a reference to a hash %struct, that hash will be updated with the bits that were parsed from the string. The hash will also be equal to the key-value pairs being returned. If it is not supplied, a reference to an empty hash will be used in its stead.

If the format reads in a timezone that isn't well-defined, it will be silently ignored, and any offset that is parsed will be used instead.

See "mktime" in Time::C for making a Time::C object out of the returned structure. Or see "strptime" in Time::C for a constructor that will do it for you.

Format Specifiers

The format specifiers work in a format to parse distinct portions of a string. Any part of the format that isn't a format specifier will be matched verbatim. All format specifiers start with a % character. Some implementations of strptime will support some of them, and other implementations will support others.

Some format specifiers can have a - inserted between the % and the letter, and if so they will no longer need any leading whitespace or 0 to be matched. The ones which support this are: %-C, %-d, %-e, %-G, %-g, %-H, %-I, %-j, %-k, %-l, %-M, %-m, %-S, %-U, %-V, %-W, %-Y, and %-y.

This implementation will support the ones described below:

%A

Full weekday, depending on the locale, e.g. söndag.

%a

Abbreviated weekday, depending on the locale, e.g. sön.

%B

Full month name, depending on the locale, e.g. oktober.

%b

Abbreviated month name, depending on the locale, e.g. okt.

%C

2 digit century, e.g. 20 - 20 actually means the 21st century.

If you specify %-C, it will be 1 or 2 digits if the century is low enough.

%c

The date and time representation for the current locale, e.g. sön okt 30 16:07:34 UTC 2016.

%D

Equivalent to %m/%d/%y, e.g. 10/30/16 - this is used mostly in the US. Internationally %F is much preferred.

%d

2 digit day of month, e.g. 30.

If you specify %-d, it will be 1 or 2 digits if the day of the month is low enough.

%E*

The %E* format specifiers that are supported are:

%Ec

Similar to %c, but using an alternate way of displaying the year. See %EY, %EC, and %Ey.

%EC

Similarly to %C, it (usually) describes a period longer than 1 year, depending on the locale. There are only a few locales that define this: ja_JP, lo_LA, and th_TH; in other locales it functions like %C.

Taking the ja_JP locale as an example, it defines a number of periods, ostensibly relating to when they got a new emperor, and these periods are what the %EC represents rather than centuries like %C.

%EX

Similar to %x, but using an alternate way of displaying the time. There are only a few locales that define this: lo_LA, and th_TH; in other locales it functions like %X.

%Ex

Similar to %X, but using an alternate way of displaying the year. There are only a few locales that define this: ja_JP, lo_LA, and th_TH; in other locales it functions like %x. See %EY, %EC, and %Ey for details on how the year is displayed.

%EY

Similarly to %Y, it describes a year fully, but depends on the %EC and possibly the %Ey of the locale. There are only a few locales that define this: ja_JP, lo_LA, and th_TH; in other locales it functions like %Y.

%Ey

Similarly to %y, it describes the number of years since the period, only %y's period is %C, while %Ey's period is %EC. There are only a few locales that define this: ja_JP, lo_LA, and th_TH; in other locales it functions like %y.

%e

1/2 digit day of month, space padded, e.g. 30.

If you specify %-e, it will not be space padded if it is low enough.

%F

Equivalent to %Y-%m-%d, e.g. 2016-10-30.

%G

Year, 4 digits, representing the week-based year since year 0, e.g. 2016 - i.e. if the date being represented has a week that overlaps with the previous or next year, the year for any date in that week will count as the year that has 4 or more days of the week in it, counting from Monday til Sunday. Should be combined with a %V week specifier (a %W or %U week specifier will not work).

If you specify %-G, it will be 1, 2, 3, or 4 digits if the year is low enough.

%g

Like %G but without century, and which will be interpreted as being within 50 years of the current year, whether that means adding 1900 or 2000 to it, e.g. 16.

If you specify %-g, it will be 1 or 2 digits if the year is low enough.

%H

2 digit hour in 24-hour time, e.g. 16.

If you specify %-H, it will be 1 or 2 digits if the hour is low enough.

%h

Equivalent to %b, e.g. okt.

%I

2 digit hour in 12-hour time, e.g. 04.

If you specify %-I, it will be 1 or 2 digits if the hour is low enough.

%j

3 digit day of the year, e.g. 304.

If you specify %-j, it will be 1, 2, or 3 digits if the day of the year is low enough.

%k

1/2 digit hour in 24-hour time, space padded, e.g. 16.

If you specify %-k, it will not be space padded if it is low enough.

%l

1/2 digit hour in 12-hour time, space padded, e.g. 4.

If you specify %-l, it will not be space padded if it is low enough.

%M

2 digit minute, e.g. 07.

If you specify %-M, it will be 1 or 2 digits if the minute is low enough.

%m

2 digit month, e.g. 10.

If you specify %-m, it will be 1 or 2 digits if the month is low enough.

%n

Arbitrary whitespace, like m/\s+/ - if used as a formatting specifier rather than a parsing specifier, it will result in a \n (i.e. a newline).

%O*

The %O* format specifiers work like their non-O counterparts, except they use an alternate set of digits for representing the number depending on the locale. Not all %O* specifiers are actually supported by all locales, as some only define numbers up to a certain point. Some don't specify an alternate set of digits at all, in which case they should work exactly like their non-O counterparts.

The %O* format specifiers that are supported are:

%OC

%Od

%Oe

%OH

%OI

%OM

%Om

%OS

%OU

%Ou

%OV

%OW

%Ow

%Oy

%p

Matches the locale version of a.m. or p.m., if the locale has that. Otherwise matches the empty string.

%X

The time representation for the current locale, e.g. 16:07:34.

%x

The date representation for the current locale, e.g. 2016-10-30.

%R

Equivalent to %H:%M, e.g. 16:07.

%r

The time representation with am/pm for the current locale. For example in the POSIX locale, it is equivalent to %I:%M:%S %p.

%S

2 digit second, e.g. 34.

If you specify %-S, it will be 1 or 2 digits if the second is low enough.

%s

The epoch, i.e. the number of seconds since 1970-01-01T00:00:00Z.

%T

Equivalent to %H:%M:%S, e.g. 16:07:34.

%t

Arbitrary whitespace, like m/\s+/ - if used as a formatting specifier rather than a parsing specifier, it will result in a \t (i.e. a tab).

%U

2 digit week number of the year, Sunday-based week, e.g. 44.

If you specify %-U, it will be 1 or 2 digits if the week is low enough.

%u

1 digit weekday, Monday-based week, e.g. 7.

%V

2 digit week number of the year, Monday-based week, e.g. 43, where week 1 is the first week of the year that has 4 days or more. Any preceding days will belong to the last week of the prior year, see %G.

If you specify %-V, it will be 1 or 2 digits if the week is low enough.

%v

Equivalent to %e-%b-%Y, which depends on the locale, e.g. 30-okt-2016.

%W

2 digit week number of the year, Monday-based week, e.g. 43.

If you specify %-W, it will be 1 or 2 digits if the week is low enough.

%w

1 digit weekday, Sunday-based week, e.g. 0.

%Y

Year, 4 digits, representing the full year since year 0, e.g. 2016.

If you specify %-Y, it will be from 1 to 4 digits if the year is low enough.

%y

2 digit year without century, which will be interpreted as being within 50 years of the current year, whether that means adding 1900 or 2000 to it, e.g. 16.

If you specify %-y, it will be 1 or 2 digits if the year is low enough.

%Z

Time zone name, e.g. CET, or Europe/Stockholm.

%z

Offset from UTC in hours and minutes, or just hours, e.g. +0100.

%%

A literal % sign.

SEE ALSO

Time::C

The companion to this module, which can create an actual time representation from the structure we parsed.

Time::Piece

Also provides a strptime(), but it doesn't deal well with timezones or offsets.

POSIX::strptime

Also provides a strptime(), but it also doesn't deal well with timezones or offsets.

Time::Strptime

Also provides a strptime(), but it doesn't handle %c, %x, or %X format specifiers at all, only supports a POSIX version of %r, and is arguably buggy with %a, %A, %b, %B, and %p.

DateTime::Format::Strptime

Provides an OO-interface for strptime, but it has the same issues as Time::Strptime.

AUTHOR

Andreas Guldstrand <andreas.guldstrand@gmail.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016 by Andreas Guldstrand.

This is free software, licensed under:

  The MIT (X11) License