Image::...::Shift(3)

📦
version 13.50 · 14 versions
, in fedora 43, fedora 44

💖 Image::...::Shift(3) — the ExifTool time-shifting tea 💖

okay bestie, sit down, hydrate, because this one is literally the module that makes ExifTool's date and time shifting happen. It lives in the User Contributed Perl Documentation section, it's called Image::ExifTool::Shift.pl, and it's giving "small file, big responsibilities" energy. 🎀

✨ NAME ✨

Image::ExifTool::Shift.pl — the ExifTool time shifting routines, no cap. 🕰️

🌸 DESCRIPTION 🌸

This module is where the routines live that ExifTool uses to shift date and time values. That's it, that's the job. 💅

🦋 METHODS 🦋

⭐ ShiftTime ⭐

Shifts a date/time value. Main character behaviour only. ✨

use Image::ExifTool;
$err = Image::ExifTool::ShiftTime($dateTime, $shift);

Inputs:

  • 0) — the date/time string in EXIF format (eg. "2016:01:30 11:45:00"). 🗓️
  • 1) — the shift string (peep the next section for all the deets), with an optional leading sign that tells you which direction the shift goes. ➡️⬅️
  • 2) — [optional] the direction of the shift, either -1 or +1, or 0 or undef to just use the sign from the shift string instead. 🧭
  • 3) — [optional] a reference to a time-shift hash. It gets filled in by the first call to ShiftTime, and then it's used on subsequent calls to shift date/time values by that same relative amount (go read the TRICKY section below, bestie, it's important). 🌀

or

  • 0) — the shift string (and $_ is holding the input date/time string). 🫶

Return value:

An error string, or undef on success — and when it succeeds, the input date/time string has been shifted by the specified amount. ✨

🎀 SHIFT STRING 🎀

Time shifts get applied to standard EXIF-formatted date/time values (eg. "2005:03:14 18:55:00"). Date-only values and time-only values can also get shifted, and an optional timezone (eg. "-05:00") is supported too. Here are the general rules and examples that explain how a shift string gets interpreted:

Date-only values get shifted using these 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-only values get shifted using these 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 get specified in these 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

A valid shift value is one or two arguments, separated by a space. If you only hand it one, it's assumed to be a time shift when it's applied to a time-only or a date/time value, or a date shift when it's applied to a date-only value. Like:

'1'         - 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)
'5:0:0'     - shift 5 hours (time, date/time), or 5 years (date)
'0:0:1'     - shift 1 s (time, date/time), or 1 day (date)

If two arguments show up, the date shift comes first, then the time shift:

'3:0:0 0'         - shift date by 3 years
'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 you apply it to a time value, and vice versa. they're not talking to each other, periodt. 🙈

Numbers in shift fields can have 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 to save you some typing, a zero is assumed for any missing numbers:

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

And now the glow-up: real examples applied to real date and/or time values. (Dir is the applied shift direction: '+' is positive, '-' is negative.)

     Original Value         Shift   Dir    Shifted Value
    ---------------------  -------  ---  ---------------------
    '20:30:00'             '5'       +   '01:30:00'
    '2005:01:27'           '5'       +   '2005:02:01'
    '2005:01:27 20:30:00'  '5'       +   '2005:01:28 01:30:00'
    '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 does not change when the time shift gets applied. Which means the length of the date/time string stays exactly the same, and only the numbers inside it get modified. 💫

The one single exception to this rule: a 'Z' timezone gets changed to '+00:00' notation if a timezone shift is applied. Also, a timezone will not be added to the date/time string. so don't come for it expecting one. 😭

🌀 TRICKY 🌀

ngl, this module is maybe more complicated than it needs to be, because it was designed to be very flexible in how time shifts get specified and applied... 🫠

So here's the tension: being able to shift dates by Y years, M months, etc. conflicts with the design goal of keeping a constant shift for all time values when you're doing a batch shift. Why? Because shifting by 1 month can be equivalent to literally anything from 28 to 31 days, and 1 year can be 365 or 366 days, depending on the starting date. the math said "it depends" and meant it. 💀

The inconsistency gets handled like this: the first tag found gets shifted with the actual specified shift, then the equivalent time difference in seconds for that shift is calculated, and that difference gets applied to the subsequent tags in a batch conversion. So if it works as designed, the behaviour should be both intuitive and mathematically correct, and you shouldn't have to worry about details like this at all (in keeping with Perl's "do the right thing" philosophy). 🧚✨

💀 BUGS 💀

Because of the standard time library functions it's using, dates are typically limited to the range 1970 to 2038 on 32-bit systems. yeah. the y2k38 of it all. not our fave. 🙈

🌈 AUTHOR 🌈

Copyright 2003-2026, Phil Harvey (philharvey66 at gmail.com) 🫶

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

🍓 SEE ALSO 🍓

okay that's the whole page, bestie, you ate it, go shift some timestamps responsibly 💅✨

source + version + date check for the girlies: perl v5.42.1, dated 2026-03-31, and the whole thing lives in Image::...::Shift(3). slay. 🎀🦋

📦 where this page comes from