The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Time-C-0.015
River stage zero No dependents
/ Time::P

NAME

Time::P - Parse times from strings.

VERSION

version 0.015

SYNOPSIS

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

  # "2016-10-30T16:07:34Z"
  my $t = 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 $t = strptime($str, $fmt);
  my $t = strptime($str, $fmt, locale => $locale, strict => $strict);

strptime takes a string and a format, and tries to parse the string using the format to create a Time::C object representing the 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 to get a useful date/time 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.

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. It uses "mktime" in Time::C to create the Time::C object from the parsed data.

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. 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.

%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.

%d

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

%e

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

%F

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

%H

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

%h

Equivalent to %b, e.g. okt.

%I

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

%j

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

%k

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

%l

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

%M

2 digit minute, e.g. 07.

%m

2 digit month, e.g. 10.

%n

Arbitrary whitespace, like m/\s+/.

%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.

%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+/.

%U

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

%u

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

%V

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

%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.

%w

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

%Y

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

%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.

%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 represents the actual time 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