1Image::ExifTool::Shift(U3s)er Contributed Perl DocumentatIimoange::ExifTool::Shift(3)
2
6 Image::ExifTool::Shift.pl - ExifTool time shifting routines
7
9 This module contains routines used by ExifTool to shift date and time
10 values.
11
13 ShiftTime
14 Shift date/time value
15 use Image::ExifTool;
17 $err = Image::ExifTool::ShiftTime($dateTime, $shift);
18 Inputs:
20 0) Date/time string in EXIF format (eg. "2016:01:30 11:45:00").
21 1) Shift string (see below) with optional leading sign for shift
23 direction.
24 2) [optional] Direction of shift (-1 or +1), or 0 or undef to use
26 the sign from the shift string.
27 3) [optional] Reference to time-shift hash -- filled in by first
29 call to ShiftTime, and used in subsequent calls to shift date/time
30 values by the same relative amount (see "TRICKY" section below).
31 Return value:
33 Error string, or undef on success and the input date/time string is
34 shifted by the specified amount.
35
37 Time shifts are applied to standard EXIF-formatted date/time values
38 (eg. "2005:03:14 18:55:00"). Date-only and time-only values may also
39 be shifted, and an optional timezone (eg. "-05:00") is also supported.
40 Here are some general rules and examples to explain how shift strings
41 are interpreted:
42 Date-only values are shifted using the following formats:
44 'Y:M:D' - shift date by 'Y' years, 'M' months and 'D' days
46 'M:D' - shift months and days only
47 'D' - shift specified number of days
48 Time-only values are shifted using the following formats:
50 'h:m:s' - shift time by 'h' hours, 'm' minutes and 's' seconds
52 'h:m' - shift hours and minutes only
53 'h' - shift specified number of hours
54 Timezone shifts are specified in the following formats:
56 '+h:m' - shift timezone by 'h' hours and 'm' minutes
58 '-h:m' - negative shift of timezone hours and minutes
59 '+h' - shift timezone hours only
60 '-h' - negative shift of timezone hours only
61 A valid shift value consists of one or two arguments, separated by a
63 space. If only one is provided, it is assumed to be a time shift when
64 applied to a time-only or a date/time value, or a date shift when
65 applied to a date-only value. For example:
66 '1' - shift by 1 hour if applied to a time or date/time
68 value, or by one day if applied to a date value
69 '2:0' - shift 2 hours (time, date/time), or 2 months (date)
70 '5:0:0' - shift 5 hours (time, date/time), or 5 years (date)
71 '0:0:1' - shift 1 s (time, date/time), or 1 day (date)
72 If two arguments are given, the date shift is first, followed by the
74 time shift:
75 '3:0:0 0' - shift date by 3 years
77 '0 15:30' - shift time by 15 hours and 30 minutes
78 '1:0:0 0:0:0+5:0' - shift date by 1 year and timezone by 5 hours
79 A date shift is simply ignored if applied to a time value or visa
81 versa.
82 Numbers specified in shift fields may contain a decimal point:
84 '1.5' - 1 hour 30 minutes (time, date/time), or 1 day (date)
86 '2.5 0' - 2 days 12 hours (date/time), 12 hours (time) or
87 2 days (date)
88 And to save typing, a zero is assumed for any missing numbers:
90 '1::' - shift by 1 hour (time, date/time) or 1 year (date)
92 '26:: 0' - shift date by 26 years
93 '+:30' - shift timezone by 30 minutes
94 Below are some specific examples applied to real date and/or time
96 values ('Dir' is the applied shift direction: '+' is positive, '-' is
97 negative):
98 Original Value Shift Dir Shifted Value
100 --------------------- ------- --- ---------------------
101 '20:30:00' '5' + '01:30:00'
102 '2005:01:27' '5' + '2005:02:01'
103 '2005:01:27 20:30:00' '5' + '2005:01:28 01:30:00'
104 '11:54:00' '2.5 0' - '23:54:00'
105 '2005:11:02' '2.5 0' - '2005:10:31'
106 '2005:11:02 11:54:00' '2.5 0' - '2005:10:30 23:54:00'
107 '2004:02:28 08:00:00' '1 1.3' + '2004:02:29 09:18:00'
108 '07:00:00' '-5' + '07:00:00'
109 '07:00:00+01:00' '-5' + '07:00:00-04:00'
110 '07:00:00Z' '+2:30' - '07:00:00-02:30'
111 '1970:01:01' '35::' + '2005:01:01'
112 '2005:01:01' '400' + '2006:02:05'
113 '10:00:00.00' '::1.33' - '09:59:58.67'
114
116 The format of the original date/time value is not changed when the time
117 shift is applied. This means that the length of the date/time string
118 will not change, and only the numbers in the string will be modified.
119 The only exception to this rule is that a 'Z' timezone is changed to
120 '+00:00' notation if a timezone shift is applied. A timezone will not
121 be added to the date/time string.
122
124 This module is perhaps more complicated than it needs to be because it
125 is designed to be very flexible in the way time shifts are specified
126 and applied...
127 The ability to shift dates by Y years, M months, etc, conflicts with
129 the design goal of maintaining a constant shift for all time values
130 when applying a batch shift. This is because shifting by 1 month can
131 be equivalent to anything from 28 to 31 days, and 1 year can be 365 or
132 366 days, depending on the starting date.
133 The inconsistency is handled by shifting the first tag found with the
135 actual specified shift, then calculating the equivalent time difference
136 in seconds for this shift and applying this difference to subsequent
137 tags in a batch conversion. So if it works as designed, the behaviour
138 should be both intuitive and mathematically correct, and the user
139 shouldn't have to worry about details such as this (in keeping with
140 Perl's "do the right thing" philosophy).
141
143 Due to the use of the standard time library functions, dates are
144 typically limited to the range 1970 to 2038 on 32-bit systems.
145
147 Copyright 2003-2019, Phil Harvey (phil at owl.phy.queensu.ca)
148 This library is free software; you can redistribute it and/or modify it
150 under the same terms as Perl itself.
151
153 Image::ExifTool(3pm)
154perl v5.28.1 2019-01-10 Image::ExifTool::Shift(3)