Image::ExifTool::Shift(3pm)

1Image::ExifTool::Shift(U3s)er Contributed Perl DocumentatIimoange::ExifTool::Shift(3)
2
3
4

NAME

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

DESCRIPTION

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

DETAILS

13       Time shifts are applied to standard EXIF-formatted date/time values
14       (ie.  "2005:03:14 18:55:00").  Date-only and time-only values may also
15       be shifted, and an optional timezone (ie. "-05:00") is also supported.
16       Here are some general rules and examples to explain how shift strings
17       are interpreted:
18
19       Date-only values are shifted using the following formats:
20
21           'Y:M:D'     - shift date by 'Y' years, 'M' months and 'D' days
22           'M:D'       - shift months and days only
23           'D'         - shift specified number of days
24
25       Time-only values are shifted using the following formats:
26
27           'h:m:s'     - shift time by 'h' hours, 'm' minutes and 's' seconds
28           'h:m'       - shift hours and minutes only
29           'h'         - shift specified number of hours
30
31       Timezone shifts are specified in the following formats:
32
33           '+h:m'      - shift timezone by 'h' hours and 'm' minutes
34           '-h:m'      - negative shift of timezone hours and minutes
35           '+h'        - shift timezone hours only
36           '-h'        - negative shift of timezone hours only
37
38       A valid shift value consists of one or two arguments, separated by a
39       space.  If only one is provided, it is assumed to be a time shift when
40       applied to a time-only or a date/time value, or a date shift when
41       applied to a date-only value.  For example:
42
43           '7'         - shift by 1 hour if applied to a time or date/time
44                         value, or by one day if applied to a date value
45           '2:0'       - shift 2 hours (time, date/time), or 2 months (date)
46           '5:0:0'     - shift 5 hours (time, date/time), or 5 years (date)
47           '0:0:1'     - shift 1 s (time, date/time), or 1 day (date)
48
49       If two arguments are given, the date shift is first, followed by the
50       time shift:
51
52           '3:0:0 0'         - shift date by 3 years
53           '0 15:30'         - shift time by 15 hours and 30 minutes
54           '1:0:0 0:0:0+5:0' - shift date by 1 year and timezone by 5 hours
55
56       A date shift is simply ignored if applied to a time value or visa
57       versa.
58
59       Numbers specified in shift fields may contain a decimal point:
60
61           '1.5'       - 1 hour 30 minutes (time, date/time), or 1 day (date)
62           '2.5 0'     - 2 days 12 hours (date/time), 12 hours (time) or
63                         2 days (date)
64
65       And to save typing, a zero is assumed for any missing numbers:
66
67           '1::'       - shift by 1 hour (time, date/time) or 1 year (date)
68           '26:: 0'    - shift date by 26 years
69           '+:30       - shift timezone by 30 minutes
70
71       Below are some specific examples applied to real date and/or time
72       values ('Dir' is the applied shift direction: '+' is positive, '-' is
73       negative):
74
75            Original Value         Shift   Dir    Shifted Value
76           ---------------------  -------  ---  ---------------------
77           '20:30:00'             '5'       +   '01:30:00'
78           '2005:01:27'           '5'       +   '2005:02:01'
79           '11:54:00'             '2.5 0'   -   '23:54:00'
80           '2005:11:02'           '2.5 0'   -   '2005:10:31'
81           '2005:11:02 11:54:00'  '2.5 0'   -   '2005:10:30 23:54:00'
82           '2004:02:28 08:00:00'  '1 1.3'   +   '2004:02:29 09:18:00'
83           '07:00:00'             '-5'      +   '07:00:00'
84           '07:00:00+01:00'       '-5'      +   '07:00:00-04:00'
85           '07:00:00Z'            '+2:30'   -   '07:00:00-02:30'
86           '1970:01:01'           '35::'    +   '2005:01:01'
87           '2005:01:01'           '400'     +   '2006:02:05'
88           '10:00:00.00'          '::1.33'  +   '09:59:58.67'
89

NOTES

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

TRICKY

99       This module is perhaps more complicated than it needs to be because it
100       is designed to be very flexible in the way time shifts are specified
101       and applied...
102
103       The ability to shift dates by Y years, M months, etc, is somewhat
104       contradictory to the goal of maintaining a constant shift for all time
105       values when applying a batch shift.  This is because shifting by 1
106       month can be equivalent to anything from 28 to 31 days, and 1 year can
107       be 365 or 366 days, depending on the starting date.
108
109       The inconsistency is handled by shifting the first tag found with the
110       actual specified shift, then calculating the equivalent time difference
111       in seconds for this shift and applying this difference to subsequent
112       tags in a batch conversion.  So if it works as designed, the behaviour
113       should be both intuitive and mathematically correct, and the user
114       shouldn't have to worry about details such as this (in keeping with
115       Perl's "do the right thing" philosophy).
116

BUGS

118       This feature uses the standard time library functions, which typically
119       are limited to dates in the range 1970 to 2038.
120

AUTHOR

122       Copyright 2003-2011, Phil Harvey (phil at owl.phy.queensu.ca)
123
124       This library is free software; you can redistribute it and/or modify it
125       under the same terms as Perl itself.
126