The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

EAI::DateUtil - Date and Time helper functions for EAI::Wrap

SYNOPSIS

 monthsToInt ($mmm, $locale)
 intToMonths ($m, $locale)
 addLocaleMonths ($locale, $monthsArray)
 get_curdate ()
 get_curdatetime ()
 get_curdate_dot ()
 formatDate ($y, $m, $d, [$template])
 formatDateFromYYYYMMDD($date, [$template])
 get_curdate_gen ([$template])
 get_curdate_dash ()
 get_curdate_dash_plus_X_years ($years)
 get_curtime ()
 get_curtime_HHMM ()
 get_lastdateYYYYMMDD ()
 get_lastdateDDMMYYYY ()
 is_first_day_of_month ($date YYYYMMDD)
 is_last_day_of_month ($date YYYYMMDD, [$cal])
 get_last_day_of_month ($date YYYYMMDD)
 weekday ($date YYYYMMDD)
 is_weekend ($date YYYYMMDD)
 is_holiday ($cal, $date YYYYMMDD)
 is_easter ($cal, $date YYYYMMDD)
 addCalendar ($cal, $fixedHol hash, $easterHol .. hash, $specialFunction)
 first_week ($d,$m,$y,$day,[$month])
 first_weekYYYYMMDD ($date,$day,[$month])
 last_week ($d,$m,$y,$day,[$month])
 last_weekYYYYMMDD ($date,$day,[$month])
 convertDate ($date YYYY.MM.DD or YYYY/MM/DD)
 convertDateFromMMM ($inDate dd-mmm-yyyy, out $day, out $mon, out $year)
 convertDateToMMM ($day, $mon, $year)
 convertToDDMMYYYY ($date YYYYMMDD)
 addDays ($day, $mon, $year, $dayDiff)
 addDaysHol ($date, $days, [$template, $cal])
 addDatePart ($date, $count, $datepart, [$template])
 subtractDays ($date, $days)
 subtractDaysHol ($date, $days, [$template, $cal])
 convertcomma ($number, $divideBy)
 convertToThousendDecimal($value, $ignoreDecimal)
 get_dateseries
 parseFromDDMMYYYY ($dateStr)
 parseFromYYYYMMDD ($dateStr)
 convertEpochToYYYYMMDD ($epoch)

DESCRIPTION

EAI::DateUtil contains all date/time related API-calls.

API

monthsToInt

convert from english/german/custom locale short months -> numbers, monthsToInt("Oct","EN") equals 10, monthsToInt("mär","GE") equals 3. months and locale are case insensitive.

intToMonths

convert from int to english/german/custom locale months -> numbers, intToMonths(10,"EN") equals "Oct", intToMonths(3,"GE") equals "Mär". locale is case insensitive, month is returned with uppercase beginnen resp. as it was added (see below).

addLocaleMonths

adds custom locale $locale with ref to array $monthsArray to above conversion functions. locale is case insensitive.

Example:

 addLocaleMonths("FR",["Jan","Fév","Mars","Mai","Juin","Juil","Août","Sept","Oct","Nov","Déc"]);
get_curdate

gets current date in format YYYYMMDD

get_curdatetime

gets current datetime in format YYYYMMDD_HHMMSS

get_curdate_dot

gets current date in format DD.MM.YYYY

formatDate

formats passed date (given in arguments $y,$m,$d) into format as defined in $template

 $y .. year part
 $m .. month part
 $d .. day part
 $template .. optional, date template with D for day, M for month and Y for year (e.g. D.M.Y for 01.02.2016),
              D and M is always 2 digit, Y always 4 digit; if empty/nonexistent defaults to "YMD"
              special formats are MMM und mmm als monthpart, here three letter month abbreviations in english (MMM) or german (mmm) are returned as month
              additionally a locale can be passed in brackets with MMM and mmm, resulting in conversion to locale dependent months.
              e.g. formatDate(2002,6,1,"Y-MMM-D[fr]") would yield 2002-Juin-01 for the addLocaleMonths given above.
formatDateFromYYYYMMDD

formats passed date (given in argument $date) in format as defined in $template

 $date .. date in format YYYYMMDD
 $template .. same as in formatDate
get_curdate_gen

returns current date in format as defined in $template

 $template .. same as in formatDate
get_curdate_dash

returns current date in format DD-MM-YYYY

get_curdate_dash_plus_X_years: date + X years in format DD-MM-YYYY
 $y .. years to be added to the current or given date
 $year,$mon,$day .. optional date to which X years should be added (if not given current date is taken instead).
 $daysToSubtract .. days that should be subtracted from the result
get_curtime

returns current time in format HH:MM:SS (or as given in formatstring $format, however ordering of format is always hour, minute and second)

 $format .. optional sprintf format string (e.g. %02d:%02d:%02d) for hour, minute and second
get_curtime_HHMM

returns current time in format HHMM

is_first_day_of_month

returns 1 if first day of months, 0 else

 $date .. date in format YYYYMMDD
is_last_day_of_month

returns 1 if last day of month, 0 else

 $date .. date in format YYYYMMDD
 $cal .. optional, calendar for holidays used to get the last of month
get_last_day_of_month

returns last day of month of passed date

 $date .. date in format YYYYMMDD
weekday

returns 1..sunday to 7..saturday

 $date .. date in format YYYYMMDD
is_weekend

returns 1 if saturday or sunday

 $date .. date in format YYYYMMDD
is_holiday

returns 1 if weekend or holiday

 $cal .. holiday calendar; currently supported: AT (Austria), TG (Target), UK (see is_holiday) and WE (for only weekends).
         throws warning if calendar not supported (fixed lookups or additionally added). To add a calendar use addCalendar.
 $date .. date in format YYYYMMDD
is_easter

returns 1 if date is an easter holiday for that calendar

 $cal .. holiday calendar;
 $date .. date in format YYYYMMDD
addCalendar

add an additional calendar for calendar holiday dependent calculations

 $cal .. name of holiday calendar to be added, warns if already existing (builtin)
 $fixedHol .. hash of fixed holiday dates for that calendar (e.g. {"0105"=>1,"2512"=>1} for may day and christmas day)
 $easterHol .. hash of easter holidays for that calendar (possible: {"GF"=>1,"EM"=>1,"ES"=>1,"AS"=>1,"WM"=>1,"CC"=>1}) = good friday,easter monday, easter sunday, ascension day, whitmonday, corpus christi day
 $specialFunction .. pass ref to sub used for additional calculations; this sub should receive a date (YYYYMMDD) and return 1 for holiday, 0 otherwise.

Example:

 sub testCalSpecial {
   my ($y,$m,$d) = $_[0] =~ /(.{4})(..)(..)/;
   return 1 if $y eq "2002" and $m eq "09" and $d eq "08";
   return 0;
 }
 addCalendar("TC",{"0101"=>1,"0105"=>1,"2512"=>1,"2612"=>1},{"EM"=>1,"GF"=>1},\&testCalSpecial);
last_week

returns 1 if given date ($d,$m,$y) is the last given weekday ($day: 0 - 6, sunday==0) in given month ($month), if $month is not passed, then it is taken from passed date.

 $d .. day part
 $m .. month part
 $y .. year part
 $day .. given weekday
 $month .. optional, given month
last_weekYYYYMMDD

returns 1 if given date ($date in Format YYYYMMDD) is the last given weekday ($day: 0 - 6, sunday==0) in given month ($month), if $month is not passed, then it is taken from passed date.

 $date .. given date
 $day .. given weekday
 $month .. optional, given month
 
first_week

returns 1 if given date ($d,$m,$y) is the first given weekday ($day: 0 - 6, sunday==0) in given month ($month), if $month is not passed, then it is taken from passed date.

 $d .. day part
 $m .. month part
 $y .. year part
 $day .. given weekday
 $month .. optional, given month
first_weekYYYYMMDD

returns 1 if given date ($date in Format YYYYMMDD) is the first given weekday ($day: 0 - 6, sunday==0) in given month ($month), if $month is not passed, then it is taken from passed date.

 $date .. given date
 $day .. given weekday
 $month .. optional, given month
 
convertDate

converts given date to format YYYYMMDD

 $date .. date in format YYYY.MM.DD or YYYY/MM/DD
convertDateFromMMM

converts date from format dd-mmm-yyyy (01-Oct-05, english !), returns date in format DD.MM.YYYY ($day, $mon, $year are returned by ref as well)

 $inDate .. date to be converted
 $day .. ref for day part
 $mon .. ref for month part
 $year ..  ref for year part
convertDateToMMM

converts date into ($day, $mon, $year) from format dd-mmm-yyyy (01-Oct-05, english !)

 $day .. day part
 $mon .. month part
 $year .. year part
convertToDDMMYYYY

converts date into $datestring (dd.mm.yyyy) from format YYYYMMDD

 $date .. date in format YYYYMMDD
addDays

adds $dayDiff to date ($day, $mon, $year) and returns in format dd-mmm-yyyy (01-Oct-05, english !), arguments $day, $mon, $year are returned by ref as well if not passed as literal

 $day .. day part
 $mon .. month part
 $year .. year part
 $dayDiff .. days to be added
subtractDays

subtracts $days actual calendar days from $date

 $date .. date in format YYYYMMDD
 $days .. calendar days to subtract
subtractDaysHol

subtracts $days days from $date and regards weekends and holidays of passed calendar

 $date .. date in format YYYYMMDD
 $days .. calendar days to subtract
 $template .. as in formatDate
 $cal .. holiday calendar; currently supported: NO (no holidays  = default if not given), rest as in is_holiday
addDaysHol

adds $days days to $date and regards weekends and holidays of passed calendar

 $date .. date in format YYYYMMDD
 $days .. calendar days to add
 $template .. as in formatDate
 $cal .. holiday calendar; currently supported: NO (no holidays = default if not given), rest as in is_holiday
 
addDatePart

adds $count dateparts to $date. when adding to months ends (>28 in february, >29 or >30 else), if the month end is not available in the target month, then date is moved into following month

 $date .. date in format YYYYMMDD
 $count .. count of dateparts to add
 $datepart .. can be "d" or "day" for days, "m"/"mon"/"month" for months and "y" or "year" for years
 $template .. as in formatDate
get_lastdateYYYYMMDD

returns last business day (only weekends, no holiday here !) in format YYYYMMDD

get_lastdateDDMMYYYY

returns last business day (only weekends, no holiday here !) in format DDMMYYYY

convertcomma

converts decimal point in $number to comma, also dividing by $divideBy before if $divideBy is set

 $number ..  number to be converted
 $divideBy .. number to be divided by
convertToThousendDecimal

converts $value into thousand separated decimal (german format) ignoring decimal places if wanted

 $value .. number to be converted
 $ignoreDecimal .. return number without decimal places (truncate)
get_dateseries

returns date values (format YYYYMMMDD) starting at $fromDate until $toDate, if a holiday calendar is set in $cal (optional), these holidays (incl. weekends) are regarded as well.

 $fromDate .. start date
 $toDate .. end date
 $cal .. holiday calendar
parseFromDDMMYYYY

returns time epoch from datestring (dd.mm.yyyy)

 $dateStr .. datestring
parseFromYYYYMMDD

returns time epoch from datestring (yyyymmdd)

 $dateStr .. datestring
convertEpochToYYYYMMDD

returns datestring (yyyymmdd) from epoch/Time::piece

 $arg .. date either as epoch (seconds since 1.1.1970) or as Time::piece object

COPYRIGHT

Copyright (c) 2023 Roland Kapl

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.