The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Image-ExifTool-5.77
River stage two • 29 direct dependents • 30 total dependents
41 ++
/ Image::ExifTool::Shift.pl

NAME

Image::ExifTool::Shift.pl - ExifTool time shifting routines

DESCRIPTION

This module contains routines used by ExifTool to shift date and time values.

DETAILS

Time shifts are applied to standard EXIF-formatted date, time or date/time values. Here are some general rules and examples to explain how shift strings are interpreted:

Date shifts are specified in the following formats:

    'Y:M:D'     - shift date by 'Y' years, 'M' months and 'D' days
    'M:D'       - shift months and days only
    'D'         - shift specified number of days

Time shifts are specified in the following formats:

    'h:m:s'     - shift time by 'h' hours, 'm' minutes and 's' seconds
    'h:m'       - shift hours and minutes only
    'h'         - shift specified number of hours

Timezone shifts are specified in the following formats:

    '+h:m'      - shift timezone by 'h' hours and 'm' minutes
    '-h:m'      - negative shift of timezone hours and minutes
    '+h'        - shift timezone hours only
    '-h'        - negative shift of timezone hours only

Date and time fields have the same format, so if only one is given it is assumed to be a time shift if applied to a time or a date/time value, or a date shift if applied to a date value. For example:

    '7'         - shift by 1 hour if applied to a time or date/time
                  value, or by one day if applied to a date value
    '2:0'       - shift 2 hours (time, date/time), or 2 months (date)
    '0:0:1'     - shift 1 sec (time, date/time), or 1 day (date)

Shifts may combine any or all of these fields into a single string. The date field comes first, separated by a space, then the time and timezone fields. ie:

    '0 15:30'         - shift time by 15 hours and 30 minutes
    '1:0:0 0:0:0+5:0' - shift date by 1 year and timezone by 5 hours

A date shift is simply ignored if applied to a time value or visa versa.

Numbers specified in shift fields may contain a decimal point:

    '1.5'       - 1 hour 30 minutes (time, date/time), or 1 day (date)
    '2.5 0'     - 2 days 12 hours (date/time), 12 hours (time) or
                  2 days (date)

And finally, a zero is assumed for any missing numbers:

    '1::'       - shift by 1 hour (time, date/time) or 1 year (date)
    '+:30       - shift timezone by 30 minutes

Below are some sample shifts and their results ('Dir' is the applied shift direction: '+' is positive, '-' is negative):

     Original Date/Time     Shift   Dir    Shifted Date/Time
    ---------------------  -------  ---  ---------------------
    '20:30:00'             '5'       +   '01:30:00'
    '2005:01:27'           '5'       +   '2005:02:01'
    '11:54:00'             '2.5 0'   -   '23:54:00'
    '2005:11:02'           '2.5 0'   -   '2005:10:31'
    '2005:11:02 11:54:00'  '2.5 0'   -   '2005:10:30 23:54:00'
    '2004:02:28 08:00:00'  '1 1.3'   +   '2004:02:29 09:18:00'
    '07:00:00'             '-5'      +   '07:00:00'
    '07:00:00+01:00'       '-5'      +   '07:00:00-04:00'
    '07:00:00Z'            '+2:30'   -   '07:00:00-02:30'
    '1970:01:01'           '35::'    +   '2005:01:01'
    '2005:01:01'           '400'     +   '2006:02:05'
    '10:00:00.00'          '::1.33'  +   '09:59:58.67'

NOTES

The format of the original date/time value is not changed when the time shift is applied. This means that the length of the date/time string will not change, and only the numbers in the string will be modified. The only exception to this rule is that a 'Z' timezone is changed to '+00:00' notation if a timezone shift is applied. A timezone will not be added to the date/time string.

TRICKY

This module is perhaps more complicated than it needs to be because it is designed to be very flexible in the way time shifts are specified and applied...

The ability to shift dates by Y years, M months, etc, is somewhat contradictory with the goal of maintaining a constant shift for all time values when applying a batch shift. This is because shifting by 1 month can be equivalent to anything from 28 to 31 days, and 1 year can be 365 or 366 days, depending on the starting date.

The inconsistency is handled by shifting the first tag found with the actual specified shift, then calculating the equivalent time difference in seconds for this shift and applying this difference to subsequent tags in a batch conversion. So if it works as designed, the behaviour should be both intuitive and mathematically correct, and the user shouldn't have to worry about details such as this (in keeping with the Perl "do the right thing" philosophy).

AUTHOR

Copyright 2003-2005, Phil Harvey (phil at owl.phy.queensu.ca)

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

SEE ALSO

Image::ExifTool(3pm)