NAME

SYNOPSIS

$path =
tildehome($path);

$dt =
validate($dt);

$bool =
nonexdate($dt);

$tim =
dticalunix($dt, $tzone);

$dt =
dtunixical($tim, $tzone);

$dt =
tzconvert($dt, $tzfrom, $tzto);

$n =
daysinyr($yyyy);

$n =
daysinmo($yyyy, $mn);

$date =
daydate($yyyy, $mn, $n);

$n =
weekno($yyyy, $mn, $dd, $wkstart);

$s =
prettydate($dt);

$dt =
ytterpdate($s);

$order =
ymdf();

$bool =
dark_color($color);

$witem =
wrap75item($item);

$w =
wrap75str($s);

$item =
unwrap75item($witem);

$bitem =
bsencodeitem($item);

$b =
bsencode($s);

$item =
bsdecodeitem($bitem);

$s =
bsdecode($b);

$n =
nlencode($s);

$s =
nldecode($n);

$h =
hexencode($s, $t);

$s =
hexdecode($h);

upd($file, $count);

$evlist =
tmsinsert($evlist, $tms);

$evlist =
tmsremove($evlist, $tms);

DESCRIPTION

In these functions, all $dt arguments and return values have the form of a string containing either an 8 character date ‘yyyymndd’ or a 14 character date-time ‘yyyymnddhhmmss’.

tildehome() takes a path possibly containing a ‘~’ character and returns the path with the first such character replaced by the user's HOME directory.

validate() takes a date-time string and forms it into a valid 8 character date string or a 14 character date-time string. The input may contain the human-readable date-time separation characters from the set: ‘[/:\s-]’ as well as the standards-imposed ‘[TZ]’ separators all of which are removed from the input before any missing components are added. Specifically, input strings after removal of the above characters are interpreted as follows:

Input of any other length will result in a return value of ‘undef’. The validate() function does not verify that individual values fall within suitable ranges.

nonexdate() returns a boolean value to signify whether or not the input date is a valid date. Dates such as Feb 30th or Sept 31st would be examples of invalid dates.

dticalunix() converts a $dt date-time string to a decimal $tim value which is generally the number of seconds since the system's time Epoch. Negative values are supported allowing calendars and events on dates/times earlier than the system time Epoch. $dt is interpreted according to timezone $tzone. $tim is returned as a UTC value.

dtunixical() converts a decimal UTC $tim value to a $dt date-time string in the timezone specified by $tzone. The returned string is always a 14 character date-time string.

tzconvert() converts a $dt date-time string from timezone $tzfrom to another date-time string in timezone $tzto.

daysinyr() returns the number of days in the month given by $yyyy. It knows about leap-years but it does not know about historical months with calendar discontinuities when countries adopted the Gregorian calendar.

daysinmo() returns the number of days in the month given by $yyyy, $mn. It knows about leap-years but it does not know about historical months with calendar discontinuities when countries adopted the Gregorian calendar.

daydate() returns an 8 character $dt string with the date of the $n'th day of the year or month. If $mn is 0, the return value will be the day of the year, else the day of that month.

weekno() returns the week number of the given date, based on the week starting on the day given by $wkstart. ISO8601 defines week number 1 of the year as being the week containing the first Thursday of the year starting from your week start day. It should be noted, therefore, that week numbers have regional or cultural interpretation based on which day is typically thought of as the start of the week.

prettydate() returns a string formated as a human-readable date-time in the order defined by the user's locale conventions. E.g., the date-time ‘20130818164500’ would be displayed as ‘18/08/2013 16:45’ in France and as ‘08/18/2013  4:45PM’ in the United States.

ytterpdate() attempts to parse a locale-specific input date format and returns an 8 or 14 character $dt value. It is the reverse of prettydate(). ytterpdate() understands the locale's year-month-day order and does its best to handle time input in both 24-hour and 12-hour formats based on the locale's ‘am’ and ‘pm’ designators. Time can always be entered as a 24-hour value even in locales that normally use 12-hour format.

ymdf() returns a string of the form ‘"yyyy/mn/dd"’, ‘"mn/dd/yyyy"’ or ‘"dd/mn/yyyy"’ containing the actual characters ‘yyyy’, ‘mn’ and ‘dd’ ordered according to the locale's date order.

The wrap75xxxx() functions wrap input to the 75 character line length mandated by RFC5545. Longer lines are broken into 75 character segments separated by a ‘\n’ character with the second and subsequent segments indented by one space. wrap75str() wraps a single string in this way. wrap75item() accepts an entire VEVENT (or other) item and wraps each record in this way. Both functions return the wrapped input.

unwrap75item() performs the opposite action, concatenating records with continuation lines starting with a space into one long record. There is no unwrap75str() function; a single record can also be unwrapped by unwrap75item().

The bsencode() and bsencodeitem() functions perform backslash encoding of their input data as mandated by RFC5545. Input characters ‘\,;’ are escaped using a preceding backslash. bsencode() encodes a single string in this way. bsencodeitem() accepts an entire VEVENT (or other) item and encodes the SUMMARY and DESCRIPTION records in this way. Both functions return the encoded input.

bsdecode() and bsdecodeitem() perform the opposite action, removing the escaping backslashes from their input.

The nlencode() function encodes newline characters in the data to ‘\n’ sequences.

nldecode() performs the opposite action, decoding ‘\n’ and ‘\N’ sequences to newline characters.

The hexencode() function performs hexencoding, also known as percent-encoding, on the input data. It takes the string $s, looks for all instances of all characers in $t within $s and converts them to ‘%xx’ where ‘xx’ represents the hexadecimal ASCII code of the character. The character ‘%’ itself is always silently appended to $t, if it was not included.

hexdecode() performs the opposite action, converting all sequences of ‘%xx’ to the character with that ASCII code.

upd() performs a sequence of file rename calls. Starting with the file with $count "o"s, files are renamed:

This is used in log file rotation. If the original $file name does not contain a ‘.ext’, the extenstion ‘.ld’ is assumed (resulting in the orignal file being renamed to file.old ). upd() returns the return value of the last rename operation.

tmsinsert() and tmsremove() are functions that manage insertion and removal of event times into an event-list hash. The input $tms is a hashref of event times, with ‘{start}’, ‘{finish}’ and ‘{duration}’ fields. These are copied into or removed from the event-list given by $evtlist.

RETURN VALUES

SEE ALSO

ENVIRONMENT

HOME

The path of the user's home directory.

LC_TIME

Format of the user's date-time display.

STANDARDS

HISTORY