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

METHODS

13   ShiftTime
14       Shift date/time value
15
16           use Image::ExifTool;
17           $err = Image::ExifTool::ShiftTime($dateTime, $shift);
18
19       Inputs:
20           0) Date/time string in EXIF format (eg. "2016:01:30 11:45:00").
21
22           1) Shift string (see below) with optional leading sign for shift
23           direction.
24
25           2) [optional] Direction of shift (-1 or +1), or 0 or undef to use
26           the sign from the shift string.
27
28           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
32           or
33
34           0) Shift string (and $_ contains the input date/time string).
35
36       Return value:
37           Error string, or undef on success and the input date/time string is
38           shifted by the specified amount.
39

SHIFT STRING

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

NOTES

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

TRICKY

128       This module is perhaps more complicated than it needs to be because it
129       is designed to be very flexible in the way time shifts are specified
130       and applied...
131
132       The ability to shift dates by Y years, M months, etc, conflicts with
133       the design goal of maintaining a constant shift for all time values
134       when applying a batch shift.  This is because shifting by 1 month can
135       be equivalent to anything from 28 to 31 days, and 1 year can be 365 or
136       366 days, depending on the starting date.
137
138       The inconsistency is handled by shifting the first tag found with the
139       actual specified shift, then calculating the equivalent time difference
140       in seconds for this shift and applying this difference to subsequent
141       tags in a batch conversion.  So if it works as designed, the behaviour
142       should be both intuitive and mathematically correct, and the user
143       shouldn't have to worry about details such as this (in keeping with
144       Perl's "do the right thing" philosophy).
145

BUGS

147       Due to the use of the standard time library functions, dates are
148       typically limited to the range 1970 to 2038 on 32-bit systems.
149

AUTHOR

151       Copyright 2003-2021, Phil Harvey (philharvey66 at gmail.com)
152
153       This library is free software; you can redistribute it and/or modify it
154       under the same terms as Perl itself.
155

SEE ALSO

157       Image::ExifTool(3pm)
158
159
160
161perl v5.34.0                      2021-08-24         Image::ExifTool::Shift(3)
Impressum