Shift.html 7.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173
  1. <?xml version="1.0" ?>
  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  3. <html xmlns="http://www.w3.org/1999/xhtml">
  4. <head>
  5. <title>ExifTool Date/Time Shift Module</title>
  6. <meta http-equiv="content-type" content="text/html; charset=utf-8" />
  7. <link rev="made" href="mailto:_securityagent@gamma.local" />
  8. </head>
  9. <body style="background-color: white">
  10. <table border="0" width="100%" cellspacing="0" cellpadding="3">
  11. <tr><td class="block" style="background-color: #cccccc" valign="middle">
  12. <big><strong><span class="block">&nbsp;ExifTool Date/Time Shift Module</span></strong></big>
  13. </td></tr>
  14. </table>
  15. <!-- INDEX BEGIN -->
  16. <div name="index">
  17. <p><a name="__index__"></a></p>
  18. <ul>
  19. <li><a href="#name">NAME</a></li>
  20. <li><a href="#description">DESCRIPTION</a></li>
  21. <li><a href="#details">DETAILS</a></li>
  22. <li><a href="#notes">NOTES</a></li>
  23. <li><a href="#tricky">TRICKY</a></li>
  24. <li><a href="#bugs">BUGS</a></li>
  25. <li><a href="#author">AUTHOR</a></li>
  26. <li><a href="#see_also">SEE ALSO</a></li>
  27. </ul>
  28. <hr name="index" />
  29. </div>
  30. <!-- INDEX END -->
  31. <p>
  32. </p>
  33. <h1><a name="name">NAME</a></h1>
  34. <p>Image::ExifTool::Shift.pl - ExifTool time shifting routines</p>
  35. <p>
  36. </p>
  37. <hr />
  38. <h1><a name="description">DESCRIPTION</a></h1>
  39. <p>This module contains routines used by ExifTool to shift date and time
  40. values.</p>
  41. <p>
  42. </p>
  43. <hr />
  44. <h1><a name="details">DETAILS</a></h1>
  45. <p>Time shifts are applied to standard EXIF-formatted date/time values (eg.
  46. <code>2005:03:14 18:55:00</code>). Date-only and time-only values may also be
  47. shifted, and an optional timezone (eg. <code>-05:00</code>) is also supported. Here
  48. are some general rules and examples to explain how shift strings are
  49. interpreted:</p>
  50. <p>Date-only values are shifted using the following formats:</p>
  51. <pre>
  52. 'Y:M:D' - shift date by 'Y' years, 'M' months and 'D' days
  53. 'M:D' - shift months and days only
  54. 'D' - shift specified number of days</pre>
  55. <p>Time-only values are shifted using the following formats:</p>
  56. <pre>
  57. 'h:m:s' - shift time by 'h' hours, 'm' minutes and 's' seconds
  58. 'h:m' - shift hours and minutes only
  59. 'h' - shift specified number of hours</pre>
  60. <p>Timezone shifts are specified in the following formats:</p>
  61. <pre>
  62. '+h:m' - shift timezone by 'h' hours and 'm' minutes
  63. '-h:m' - negative shift of timezone hours and minutes
  64. '+h' - shift timezone hours only
  65. '-h' - negative shift of timezone hours only</pre>
  66. <p>A valid shift value consists of one or two arguments, separated by a space.
  67. If only one is provided, it is assumed to be a time shift when applied to a
  68. time-only or a date/time value, or a date shift when applied to a date-only
  69. value. For example:</p>
  70. <pre>
  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)</pre>
  76. <p>If two arguments are given, the date shift is first, followed by the time
  77. shift:</p>
  78. <pre>
  79. '3:0:0 0' - shift date by 3 years
  80. '0 15:30' - shift time by 15 hours and 30 minutes
  81. '1:0:0 0:0:0+5:0' - shift date by 1 year and timezone by 5 hours</pre>
  82. <p>A date shift is simply ignored if applied to a time value or visa versa.</p>
  83. <p>Numbers specified in shift fields may contain a decimal point:</p>
  84. <pre>
  85. '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)</pre>
  88. <p>And to save typing, a zero is assumed for any missing numbers:</p>
  89. <pre>
  90. '1::' - shift by 1 hour (time, date/time) or 1 year (date)
  91. '26:: 0' - shift date by 26 years
  92. '+:30 - shift timezone by 30 minutes</pre>
  93. <p>Below are some specific examples applied to real date and/or time values
  94. ('Dir' is the applied shift direction: '+' is positive, '-' is negative):</p>
  95. <pre>
  96. Original Value Shift Dir Shifted Value
  97. --------------------- ------- --- ---------------------
  98. '20:30:00' '5' + '01:30:00'
  99. '2005:01:27' '5' + '2005:02:01'
  100. '2005:01:27 20:30:00' '5' + '2005:01:28 01:30:00'
  101. '11:54:00' '2.5 0' - '23:54:00'
  102. '2005:11:02' '2.5 0' - '2005:10:31'
  103. '2005:11:02 11:54:00' '2.5 0' - '2005:10:30 23:54:00'
  104. '2004:02:28 08:00:00' '1 1.3' + '2004:02:29 09:18:00'
  105. '07:00:00' '-5' + '07:00:00'
  106. '07:00:00+01:00' '-5' + '07:00:00-04:00'
  107. '07:00:00Z' '+2:30' - '07:00:00-02:30'
  108. '1970:01:01' '35::' + '2005:01:01'
  109. '2005:01:01' '400' + '2006:02:05'
  110. '10:00:00.00' '::1.33' - '09:59:58.67'</pre>
  111. <p>
  112. </p>
  113. <hr />
  114. <h1><a name="notes">NOTES</a></h1>
  115. <p>The format of the original date/time value is not changed when the time
  116. shift is applied. This means that the length of the date/time string will
  117. not change, and only the numbers in the string will be modified. The only
  118. exception to this rule is that a 'Z' timezone is changed to '+00:00'
  119. notation if a timezone shift is applied. A timezone will not be added to
  120. the date/time string.</p>
  121. <p>
  122. </p>
  123. <hr />
  124. <h1><a name="tricky">TRICKY</a></h1>
  125. <p>This module is perhaps more complicated than it needs to be because it is
  126. designed to be very flexible in the way time shifts are specified and
  127. applied...</p>
  128. <p>The ability to shift dates by Y years, M months, etc, conflicts with the
  129. design goal of maintaining a constant shift for all time values when
  130. applying a batch shift. This is because shifting by 1 month can be
  131. equivalent to anything from 28 to 31 days, and 1 year can be 365 or 366
  132. days, depending on the starting date.</p>
  133. <p>The inconsistency is handled by shifting the first tag found with the actual
  134. specified shift, then calculating the equivalent time difference in seconds
  135. for this shift and applying this difference to subsequent tags in a batch
  136. conversion. So if it works as designed, the behaviour should be both
  137. intuitive and mathematically correct, and the user shouldn't have to worry
  138. about details such as this (in keeping with Perl's &quot;do the right thing&quot;
  139. philosophy).</p>
  140. <p>
  141. </p>
  142. <hr />
  143. <h1><a name="bugs">BUGS</a></h1>
  144. <p>Due to the use of the standard time library functions, dates are typically
  145. limited to the range 1970 to 2038 on 32-bit systems.</p>
  146. <p>
  147. </p>
  148. <hr />
  149. <h1><a name="author">AUTHOR</a></h1>
  150. <p>Copyright 2003-2016, Phil Harvey (phil at owl.phy.queensu.ca)</p>
  151. <p>This library is free software; you can redistribute it and/or modify it
  152. under the same terms as Perl itself.</p>
  153. <p>
  154. </p>
  155. <hr />
  156. <h1><a name="see_also">SEE ALSO</a></h1>
  157. <p><a href="ExifTool.html">Image::ExifTool(3pm)</a></p>
  158. <table border="0" width="100%" cellspacing="0" cellpadding="3">
  159. <tr><td class="block" style="background-color: #cccccc" valign="middle">
  160. <big><strong><span class="block">&nbsp;ExifTool Date/Time Shift Module</span></strong></big>
  161. </td></tr>
  162. </table>
  163. </body>
  164. </html>