The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

MusicRoom::Date - Handle dates in the MusicRoom

DESCRIPTION

This package handles dates for the MusicRoom catalogue. Dates associated with music files have a number of strange attributes, for example a song is normally dated accurate to a year, the birth date of a classical composer may be known only to the nearest decade. So the handling of dates has to be special and cannot rely on standard modules (which would break down for dates before the 17th Century anyway.

OVERVIEW

The package creates objects that hold dates, these have three attributes:

  • j_day - The "Julian Day"

  • gmt_sec - The second within the day

  • accuracy - How accurately the value has been measured

Julian Day

The "Julian Day" is the number of days since 1 Jan 4711BC. This is a standard date used by astronomers to ensure that all dates for reasonable historical events have positive numbers. The calculations to convert various calendars to and from Julian days are quite well documented.

When handling dates associated with music some dates come from before 1752 (which is when the UK and US switched to the Gregorian calendar). So some kind of special handling is required.

There is one aspect of "real" Julian days that this module ignores. Astronomers start days at midday (that simplifies calculation for a discipline that mostly works at night). This module totally ignores timezones and assumes a day that starts at midnight.

GMT Seconds

For MusicRoom purposes the time zone is not very important, so long as all times are measured in the same one. So the date structure just includes a value for the number of seconds since midnight.

If you have parts of you music collection in different timezones you will either have to live with the minor issues this causes or organise to convert times (for example on files) when data moves.

Accuracy

All dates have an associated accuracy that modifies how they are presented. The accuracy values (and example default date renditions) are:

  • second - " 8 Mar 1993 05:20:27"

  • minute - " 8 Mar 1993 05:20"

  • hour - " 8 Mar 1993 5am"

  • day - " 8 Mar 1993"

  • week - "Week 14 1993"

  • month - "Mar 1993"

  • quarter - "Q1 1993",

  • year - "1993"

  • decade - "1990s"

  • century - "20th Century"

Conversion Routines

There are a number of routines in the package that convert between various types of information. These do not generally take date objects and all have names of the form convert_from2to

The formats implied by these functions are:

  • mrd - A MusicRoom::Date object

  • mrdfields - The three fields in a MusicRoom::Date

  • jday - A Julian day

  • gmtsec - The number of seconds since midnight

  • hms - The time as hour, minute and second

  • accint - The accuracy as an integer

  • accuracy - The accuracy as a string

  • gdate - A Gregorian year, month and day

  • jdate - A Julian year, month and day

  • unix - An integer giving the unix time value

  • text - A string suitable for using as a date

  • rcal - A year, month and date in a regular calendar (such as "gregorian")

mrd

A standard MusicRoom::Date object. These routines all have equivalent methods. For example:

    $mrd = MusicRoom::Date->new();
    ...
    $mrd->convert_mrd2unix();
    # ...is the same as...
    $mrd->unix();

mrdfields

The three fields that make up a MusicRoom::Date object. For example:

    my($jday,$gmtsec,$accuracy) = $mrd->mrdfields();

jday

The Julian day represented by the date object.

    my $jday = $mrd->jday();

gmtsec

The number of seconds since midnight the date represents.

    my $gmtsec = $mrd->gmtsec();

hms

The time of day as hours, minutes and seconds.

    my($hour,$minute,$sec) = $mrd->hms();

accint

The accuracy of the time as an integer. Normally it would be better to use the accuracy.

    # Integer: 0 is seconds, 1 is minutes etc
    my $accint = $mrd->accint();

accuracy

The accuracy as a string

    my $accuracy = $mrd->accuracy();

gdate

The Gregorian date. For most purposes this is the date you should use.

    my($year,$month,$day) = $mrd->gdate();

jdate

The Julian date. Only really usefull for dates before 1752 (or possibly 1588)

    my($year,$month,$day) = $mrd->jdate();

unix

The UNIX time, this is seconds since 1 Jan 1970. So the UNIX time only works for dates after 1969. Dates associated with files (like the file creation date) should normally be OK, but "real" track dates (like release date) will probably not work.

    my $unixtime = $mrd->unix();

text

The date represented as a text string. Normally this takes into account the accuracy.

    my $text = $mrd->text();

rcal

Dates in a "regular calendar". This could potentially be expanded to cover all sorts of strange calendars (anyone want to implement Islamic?). Currently only Julian and Gregorian are supported.

    my($year,$month,$day) = $mrd->rcal("gregorian");

FUNCTIONS

language($lang)

Change the language that the module uses. Mainly used to set the names of months and days of the week. At the moment only "en" is defined, so this function is quite useless.

new()

Create a new MusicRoom::Date object. Here are some examples:

    # The current time with an accuracy of seconds
    my $mrd = MusicRoom::Date->new();

    # A set time to the nearest second
    my $mrd = MusicRoom::Date->new("12 Jan 2007 3:42:08");

    # Some time in the 60s
    my $mrd = MusicRoom::Date->new("1960s");

    # Set the fields
    my $mrd = MusicRoom::Date->new(j_day => "27 Nov 1960",
                           gmt_sec => 0, accuracy => "day");

    # Attach to a given unixtime
    my $mrd = MusicRoom::Date->new(unixtime => $filedate);

dow()

Return the day of the week as a number in the range 0..6. There are hardly any good reasons for needing this but, it's easy to do.

    my $dow = $mrd->dow();

convert_mrd2mrdfields()

Return the fields of the date. Equivalent to the mrdfields() function.

    my($jday,$gmtsec,$accuracy) = $mrd->convert_mrd2mrdfields();

convert_jday2gdate

Converts a Julian day to a ($year,$month,$day) of Gregorian dates