⧼vector-jumptocontent⧽

API:EPrints/Time: Difference between revisions

From EPrints Documentation
← Older edit
Cjg (talk | contribs)
483 edits
No edit summary
No edit summary
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<!-- Pod2Wiki=_preamble_  
<!-- Pod2Wiki=_preamble_  
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
  -->
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/Time.pm|package_name=EPrints::Time}}[[Category:API|TIME]][[Category:API:EPrints/Time|TIME]]<div><!-- Edit below this comment -->
__NOTOC__
{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/Time.pm|package_name=EPrints::Time}}[[Category:API|Time]]<div><!-- Edit below this comment -->




<!-- Pod2Wiki=head_name --></div>
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
==NAME==
==NAME==
'''EPrints::Time''' - Time and Date-related functions  
'''EPrints::Time''' - Time and Date-related functions  


<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki=head_synopsis --></div>
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_synopsis -->
==SYNOPSIS==
==SYNOPSIS==
  EPrints::Time::render_date( $handle, "2001-01-12T00:00:00Z" )
<source lang="perl">($year) = EPrints::Time::utc_datetime()
  # returns XML containing 12 January 2001 00:00
# 2010
 
  EPrints::Time::render_short_date( $handle, "2001-01-12T00:00:00Z" )  
  # returns XML containing 12 Jan 2001 00:00
 
  EPrints::Time::get_iso_timestamp( );
  # returns NOW in the form YYYY-MM-DDTHH:MM:SSZ
 
  EPrints::Time::human_delay( 28 );
  # returns "1 day"
 
  EPrints::Time::get_month_label( $handle, 11 )
  # returns November
 
  EPrints::Time::get_month_label_short( $handle, 11 )
  # returns Nov
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
<!-- Edit below this comment -->


($year,$month) = EPrints::Time::local_datetime()
# 2010, 6


<!-- Pod2Wiki=head_description --></div>
EPrints::Time::iso_datetime();
==DESCRIPTION==
# 2008-05-15T14:40:24Z
This package contains functions related to time/date functionality.


EPrints::Time::iso_date()
# 2010-06-23


EPrints::Time::month_label( $repo, 11 )
# returns "November"


<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
EPrints::Time::short_month_label( $repo, 11 )
<h4><span style='display:none'>User Comments</span></h4>
# returns "Nov"
<!-- Edit below this comment -->


EPrints::Time::render_date( $repo, "2001-01-12T00:00:00Z" )
# returns XML containing 12 January 2001 00:00


<!-- Pod2Wiki=item_render_date --></div>
EPrints::Time::render_short_date( $repo, "2001-01-12T00:00:00Z" )  
===$xhtml = EPrints::Time::render_date( $handle, $datevalue )===
# returns XML containing 12 Jan 2001 00:00</source>


Render the given date or date and time as a chunk of XHTML.
<!-- Edit below this comment -->


$datevalue is given in a UTC timestamp of the form YYYY-MM-DDTHH:MM:SSZ but it will be rendered in the local offset.


e.g EPrints::Time::render_date( $handle, "2001-01-12T00:00:00Z" ) #returns XML containing 12 January 2001 00:00
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_description -->
==DESCRIPTION==
This package contains functions related to time/date functionality.


<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki=item_render_short_date --></div>
<!-- Pod2Wiki= -->
===$xhtml = EPrints::Time::render_short_date( $handle, $datevalue )===
<!-- Pod2Wiki=head_formats_used_in_eprints -->
==FORMATS USED IN EPRINTS==
<!-- Edit below this comment -->


Renders a short version of the given date or date and time as a chunk of XHTML.


$datevalue is given in UTC timestamp of the form YYYY-MM-DDTHH:MM:SSZ but it will be rendered in the local offset.
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_internal_format -->
===Internal format===
Time zone: UTC (database), server local time (embargoes)


e.g EPrints::Time::render_short_date( $handle, "2001-01-12T00:00:00Z" ) #returns XML containing 12 Jan 2001 00:00
Format: YYYY or YYYY-MM or YYYY-MM-DD or "YYYY-MM-DD hh" or "YYYY-MM-DD hh:mm" or "YYYY-MM-DD hh:mm:ss"
 
These are used in the database and when setting and getting values. They can contain any fractional part of a date time.


<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki=item_datestring_to_timet --></div>
<!-- Pod2Wiki= -->
===$xhtml = EPrints::Time::datestring_to_timet( $handle, $datevalue )===
<!-- Pod2Wiki=head_iso_8601_style_date_times -->
===ISO 8601-style date/times===
Time zone: UTC


Returns an interger number of seconds since 1970-01-01:00:00
Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ssZ


$datevalue - in the format YYYY-MM-DDTHH:MM:SSZ
These are primarily used in XML output where times that conform to the standard XSD date/time are required.


<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki=item_gmt_off --></div>
<!-- Pod2Wiki= -->
===$xhtml = EPrints::Time::gmt_off()===
<!-- Pod2Wiki=head_epoch_time -->
===Epoch time===
Time zone: UTC
 
Format: integer


Render the current time offset in seconds. This just diffs gmtime and localtime.
Time in seconds since system epoch. Used in the login tickets table and when performing date calculations.


<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki=item_get_month_label --></div>
<!-- Pod2Wiki= -->
===$label = EPrints::Time::get_month_label( $handle, $monthid )===
<!-- Pod2Wiki=head_methods -->
==METHODS==
<!-- Edit below this comment -->
 


Return a UTF-8 string describing the month, in the current lanugage.
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_parsing -->
===Parsing===
@t = split_value( $value )
Splits internal or ISO format $value into years, months, days, hours, minutes, seconds.


$monthid is an integer from 1 to 12.
$time = datetime_local( @t )
Returns local time @t as the number of seconds since epoch, where @t is years, months etc.


e.g EPrints::Time::get_month_label( $handle, 11 ) # returns November
$time = datetime_utc( @t )
Returns UTC time @t as the number of seconds since epoch, where @t is years, months etc.


<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki=item_get_month_label_short --></div>
<!-- Pod2Wiki= -->
===$label = EPrints::Time::get_month_label_short( $handle, $monthid )===
<!-- Pod2Wiki=head_formatting -->
===Formatting===
$datetime = EPrints::Time::join_value( @t )
Return a time @t in internal format.


Return a UTF-8 string of a short representation in  month, in the current lanugage.
Returns undef if no parts are defined.


$monthid is an integer from 1 to 12.
($year,$mon,$day,$hour,$min,$sec) = EPrints::Time::local_datetime( [ $seconds ] )
Returns the local date-time as an array, see {{API:PodLink|file=perlfunc|package_name=perlfunc|section=localtime|text=perlfunc/localtime}}.
 
$seconds is seconds since epoch or now if not given.


e.g EPrints::Time::get_month_label_short( $handle, 11 ) # returns Nov
($year,$mon,$day,$hour,$min,$sec) = EPrints::Time::utc_datetime( [ $seconds ] )
Returns the UTC date-time as an array, see {{API:PodLink|file=perlfunc|package_name=perlfunc|section=gmtime|text=perlfunc/gmtime}}.


<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
$seconds is seconds since epoch or now if not given.
<h4><span style='display:none'>User Comments</span></h4>
<!-- Edit below this comment -->


$date = EPrints::Time::iso_date( [ $seconds ] )
Return a UTC date of the form YYYY-MM-DD.


<!-- Pod2Wiki=item_get_date_array --></div>
$seconds is seconds since epoch or now if not given.
===($year,$month,$day) = EPrints::Time::get_date_array( [$time] )===


Static method that returns the given time (in UNIX time, seconds since 1.1.79) in an array.
$datetime = EPrints::Time::iso_datetime( [ $seconds ] );
Return a UTC date-time of the form YYYY-MM-DDTHH:MM:SSZ


This is the local date not the UTC date.
$seconds is seconds since epoch or now if not given.


<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
$datetime = EPrints::Time::rfc822_datetime( [ $seconds ] )
<h4><span style='display:none'>User Comments</span></h4>
Return the local date-time in RFC 822 format (used by e.g. RSS).
<!-- Edit below this comment -->


$seconds is seconds since epoch or now if not given.


<!-- Pod2Wiki=item_get_iso_date --></div>
$timestamp = EPrints::Time::human_time( [$time] )
===$datestamp = EPrints::Time::get_iso_date( [$time] )===
Return a string describing the current local date and time in the current locale's format, see {{API:PodLink|file=perlfunc|package_name=perlfunc|section=localtime|text=perlfunc/localtime}}.


Method that returns the given time (in UNIX time, seconds since 1.1.79) in the format used by EPrints and MySQL (YYYY-MM-DD).
  $timestamp = EPrints::Time::human_delay( $hours );
Returns a human readable amount of time.  


This is the localtime date, not UTC.
$hours the number of hours representing the time you want to be human readable.


<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki=item_human_time --></div>
<!-- Pod2Wiki= -->
===$timestamp = EPrints::Time::human_time( [$time] )===
<!-- Pod2Wiki=head_phrases -->
===Phrases===
$label = EPrints::Time::month_label( $repo, $monthid )
Return a UTF-8 string describing the month, in the current lanugage.
 
$monthid is an integer from 1 to 12.
 
$label = EPrints::Time::short_month_label( $repo, $monthid )
Return a UTF-8 string of a short representation in month, in the current lanugage.


Return a string describing the current local date and time in the current locale's format (see Perl's 'localtime).
$monthid is an integer from 1 to 12.


<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki=item_get_iso_timestamp --></div>
<!-- Pod2Wiki= -->
===$timestamp = EPrints::Time::get_iso_timestamp( [$time] );===
<!-- Pod2Wiki=head_rendering -->
===Rendering===
$xhtml = EPrints::Time::render_date( $repo, $value )
Renders a [[API:EPrints/MetaField/Date|EPrints::MetaField::Date]] or [[API:EPrints/MetaField/Time|EPrints::MetaField::Time]] value in a human-friendly form in the current locale's time zone.


Return a UTC timestamp of the form YYYY-MM-DDTHH:MM:SSZ
Month names are taken from the current repository language.


e.g. 2005-02-12T09:23:33Z
E.g.


$time in seconds from 1970. If not defined then assume current time.
<pre>  5 June 2010 10:35:12 +02:00
  12 December 1912 # no time
  1954 # no month/day</pre>


$xhtml = EPrints::Time::render_short_date( $repo, $value )
Render a shorter form of [[API:EPrints/Time#render_date|render_date]].


<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
E.g.
<h4><span style='display:none'>User Comments</span></h4>
<!-- Edit below this comment -->


<pre>  05 Jun 2010 10:35:12
  12 Dec 1912 # no time
  1954 # no month/day</pre>


<!-- Pod2Wiki=item_human_delay --></div>
<!-- Pod2Wiki=head_copyright -->
===$timestamp = EPrints::Time::human_delay( $hours );===
==COPYRIGHT==
: Copyright 2000-2011 University of Southampton.


Returns a human readable amount of time.  
: This file is part of EPrints http://www.eprints.org/.


$hours the number of hours representing the time you want to be human readable.
: EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.


e.g. EPrints::Time::human_delay( 28 ); # returns "1 day"
: EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.


e.g. EPrints::Time::human_delay( 400 ); # returns "2 weeks"
: You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.


<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
<!-- Edit below this comment -->
<!-- Edit below this comment -->




<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=_postamble_ -->
<!-- Edit below this comment -->

Latest revision as of 09:56, 22 January 2013

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki


NAME

EPrints::Time - Time and Date-related functions


SYNOPSIS

($year) = EPrints::Time::utc_datetime()
# 2010

($year,$month) = EPrints::Time::local_datetime()
# 2010, 6

EPrints::Time::iso_datetime(); 
# 2008-05-15T14:40:24Z

EPrints::Time::iso_date()
# 2010-06-23

EPrints::Time::month_label( $repo, 11 ) 
# returns "November"

EPrints::Time::short_month_label( $repo, 11 ) 
# returns "Nov"

EPrints::Time::render_date( $repo, "2001-01-12T00:00:00Z" ) 
# returns XML containing 12 January 2001 00:00

EPrints::Time::render_short_date( $repo, "2001-01-12T00:00:00Z" ) 
# returns XML containing 12 Jan 2001 00:00


DESCRIPTION

This package contains functions related to time/date functionality.


FORMATS USED IN EPRINTS

Internal format

Time zone: UTC (database), server local time (embargoes)

Format: YYYY or YYYY-MM or YYYY-MM-DD or "YYYY-MM-DD hh" or "YYYY-MM-DD hh:mm" or "YYYY-MM-DD hh:mm:ss"

These are used in the database and when setting and getting values. They can contain any fractional part of a date time.


ISO 8601-style date/times

Time zone: UTC

Format: YYYY-MM-DD or YYYY-MM-DDThh:mm:ssZ

These are primarily used in XML output where times that conform to the standard XSD date/time are required.


Epoch time

Time zone: UTC

Format: integer

Time in seconds since system epoch. Used in the login tickets table and when performing date calculations.


METHODS

Parsing

@t = split_value( $value )

Splits internal or ISO format $value into years, months, days, hours, minutes, seconds. 

$time = datetime_local( @t )

Returns local time @t as the number of seconds since epoch, where @t is years, months etc. 

$time = datetime_utc( @t )

Returns UTC time @t as the number of seconds since epoch, where @t is years, months etc.


Formatting

$datetime = EPrints::Time::join_value( @t )

Return a time @t in internal format.

Returns undef if no parts are defined. 

($year,$mon,$day,$hour,$min,$sec) = EPrints::Time::local_datetime( [ $seconds ] )

Returns the local date-time as an array, see perlfunc/localtime.

$seconds is seconds since epoch or now if not given. 

($year,$mon,$day,$hour,$min,$sec) = EPrints::Time::utc_datetime( [ $seconds ] )

Returns the UTC date-time as an array, see perlfunc/gmtime.

$seconds is seconds since epoch or now if not given. 

$date = EPrints::Time::iso_date( [ $seconds ] )

Return a UTC date of the form YYYY-MM-DD.

$seconds is seconds since epoch or now if not given. 

$datetime = EPrints::Time::iso_datetime( [ $seconds ] );

Return a UTC date-time of the form YYYY-MM-DDTHH:MM:SSZ

$seconds is seconds since epoch or now if not given. 

$datetime = EPrints::Time::rfc822_datetime( [ $seconds ] )

Return the local date-time in RFC 822 format (used by e.g. RSS).

$seconds is seconds since epoch or now if not given. 

$timestamp = EPrints::Time::human_time( [$time] )

Return a string describing the current local date and time in the current locale's format, see perlfunc/localtime. 

$timestamp = EPrints::Time::human_delay( $hours );

Returns a human readable amount of time.

$hours the number of hours representing the time you want to be human readable.


Phrases

$label = EPrints::Time::month_label( $repo, $monthid )

Return a UTF-8 string describing the month, in the current lanugage.

$monthid is an integer from 1 to 12. 

$label = EPrints::Time::short_month_label( $repo, $monthid )

Return a UTF-8 string of a short representation in month, in the current lanugage.

$monthid is an integer from 1 to 12.


Rendering

$xhtml = EPrints::Time::render_date( $repo, $value )

Renders a EPrints::MetaField::Date or EPrints::MetaField::Time value in a human-friendly form in the current locale's time zone.

Month names are taken from the current repository language.

E.g. 

  5 June 2010 10:35:12 +02:00
  12 December 1912 # no time
  1954 # no month/day
$xhtml = EPrints::Time::render_short_date( $repo, $value )

Render a shorter form of render_date.

E.g. 

  05 Jun 2010 10:35:12
  12 Dec 1912 # no time
  1954 # no month/day

COPYRIGHT

Copyright 2000-2011 University of Southampton.
This file is part of EPrints http://www.eprints.org/.
EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.



Retrieved from "https://wiki.ext-9.eprints-hosting.org/w/index.php?title=API:EPrints/Time&oldid=10678"