/ 
Time-Str-0.50
/ Time::Str::Token

NAME

Time::Str::Token - Convert captured date/time tokens to semantic values

SYNOPSIS

use Time::Str::Token qw( parse_day parse_month parse_day_name
                         parse_meridiem parse_tz_offset );

DESCRIPTION

This module provides functions for converting individual captured date/time tokens into their numeric equivalents. Each function accepts a single string and returns an integer, croaking on invalid input.

These functions are intended for use with captures from Time::Str::Regexp when building custom parsers.

FUNCTIONS

All functions are exportable on request. Use :all to import everything.

parse_day

my $day = parse_day($string);

Converts a day-of-month string to an integer (1-31). Accepts numeric values with or without leading zero, and ordinal suffixes.

parse_day('3')     # 3
parse_day('03')    # 3
parse_day('3rd')   # 3
parse_day('24th')  # 24
parse_day('31st')  # 31

Croaks with Unable to parse: day is invalid on failure.

parse_month

my $month = parse_month($string);

Converts a month string to an integer (1-12). Accepts numeric values with or without leading zero, abbreviated names, full names, and Roman numerals. Case-insensitive.

parse_month('1')         # 1
parse_month('01')        # 1
parse_month('Jan')       # 1
parse_month('january')   # 1
parse_month('IX')        # 9
parse_month('sept')      # 9

Croaks with Unable to parse: month is invalid on failure.

parse_day_name

my $dow = parse_day_name($string);

Converts a day name to an integer (1=Monday .. 7=Sunday). Accepts abbreviated and full names. Case-insensitive.

parse_day_name('Mon')       # 1
parse_day_name('monday')    # 1
parse_day_name('Tues')      # 2
parse_day_name('Thu')       # 4
parse_day_name('Thurs')     # 4
parse_day_name('Sunday')    # 7

Croaks with Unable to parse: day name is invalid on failure.

parse_meridiem

my $offset = parse_meridiem($string);

Converts an AM/PM indicator to an hour offset (0 for AM, 12 for PM). Accepts AM, PM, A.M., and P.M.. Case-insensitive.

parse_meridiem('am')    # 0
parse_meridiem('PM')    # 12
parse_meridiem('a.m.')  # 0
parse_meridiem('P.M.')  # 12

Croaks with Unable to parse: meridiem is invalid on failure.

parse_tz_offset

my $minutes = parse_tz_offset($string);

Converts a timezone offset string to a signed offset in minutes. Accepts multiple formats.

parse_tz_offset('+0100')   #  60
parse_tz_offset('-05:00')  # -300
parse_tz_offset('+05')     #  300
parse_tz_offset('+0530')   #  330
parse_tz_offset('+5')      #  300
parse_tz_offset('+5:30')   #  330
parse_tz_offset('+00:00')  #  0

Croaks with Unable to parse: timezone offset is invalid on failure.

SEE ALSO

Time::Str, Time::Str::Regexp, Time::Str::Calendar

AUTHOR

Christian Hansen

COPYRIGHT AND LICENSE

Copyright (C) 2026 by Christian Hansen

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.