Difference between revisions of "API:EPrints/Time"

From EPrints Documentation
Jump to: navigation, search
(New page: <!-- Pod2Wiki=_preamble_ This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost. -...)
 
 
(14 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- Pod2Wiki=_preamble_  
−
This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' 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.
−
  -->{{Pod2Wiki}}{{API:Source|file=EPrints/Time.pm|package_name=EPrints::Time}}[[Category:API|Time]]<!-- End of Pod2Wiki -->
+
  -->{{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 -->
−
<!-- Pod2Wiki=head_name -->=NAME=
+
 
 +
 
 +
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 +
==NAME==
 
'''EPrints::Time''' - Time and Date-related functions  
 
'''EPrints::Time''' - Time and Date-related functions  
  
−
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
−
<!-- Pod2Wiki=head_description -->=DESCRIPTION=
+
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_synopsis -->
 +
==SYNOPSIS==
 +
<source lang="perl">($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</source>
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_description -->
 +
==DESCRIPTION==
 
This package contains functions related to time/date functionality.  
 
This package contains functions related to time/date functionality.  
  
−
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
−
<!-- Pod2Wiki=item_render_date -->==render_date==
+
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_formats_used_in_eprints -->
 +
==FORMATS USED IN EPRINTS==
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_internal_format -->
 +
===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.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_iso_8601_style_date_times -->
 +
===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.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_epoch_time -->
 +
===Epoch time===
 +
Time zone: UTC
  
−
  $xhtml = EPrints::Time::render_date( $session, $datevalue )
+
Format: integer
  
−
Render the given date or date and time as a chunk of XHTML.
+
Time in seconds since system epoch. Used in the login tickets table and when performing date calculations.
  
−
The date given is in UTC but it will be rendered in the local offset.
+
<!-- Edit below this comment -->
  
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_gmt_off -->==gmt_off==
 
  
−
  $xhtml = EPrints::Time::gmt_off()
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_methods -->
 +
==METHODS==
 +
<!-- Edit below this comment -->
  
−
Render the current time offset in seconds. This just diffs gmtime and localtime.
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=item_get_month_label -->==get_month_label==
+
<!-- Pod2Wiki=head_parsing -->
 +
===Parsing===
 +
@t = split_value( $value )
 +
Splits internal or ISO format $value into years, months, days, hours, minutes, seconds.
  
−
  $label = EPrints::Time::get_month_label( $session, $monthid )
+
$time = datetime_local( @t )
 +
Returns local time @t as the number of seconds since epoch, where @t is years, months etc.
  
−
Return a UTF-8 string describing the month, in the current lanugage.
+
$time = datetime_utc( @t )
 +
Returns UTC time @t as the number of seconds since epoch, where @t is years, months etc.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_formatting -->
 +
===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 {{API:PodLink|file=perlfunc|package_name=perlfunc|section=localtime|text=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 {{API:PodLink|file=perlfunc|package_name=perlfunc|section=gmtime|text=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 {{API:PodLink|file=perlfunc|package_name=perlfunc|section=localtime|text=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.
  
−
$monthid is an integer from 1 to 12.
+
<!-- Edit below this comment -->
  
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_get_date_array -->==get_date_array==
 
  
−
  ($year,$month,$day) = EPrints::Time::get_date_array( [$time] )
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_phrases -->
 +
===Phrases===
 +
$label = EPrints::Time::month_label( $repo, $monthid )
 +
Return a UTF-8 string describing the month, in the current lanugage.
  
−
Static method that returns the given time (in UNIX time, seconds  since 1.1.79) in an array.
+
$monthid is an integer from 1 to 12.
  
−
This is the local date not the UTC date.
+
$label = EPrints::Time::short_month_label( $repo, $monthid )
 +
Return a UTF-8 string of a short representation in month, in the current lanugage.
  
−
<!-- End of Pod2Wiki -->
+
$monthid is an integer from 1 to 12.
−
<!-- Pod2Wiki=item_get_iso_date -->==get_iso_date==
 
  
−
  $datestamp = EPrints::Time::get_iso_date( [$time] )
+
<!-- Edit below this comment -->
  
−
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).
 
  
−
This is the localtime date, not UTC.
+
<!-- Pod2Wiki= -->
 +
<!-- 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.
  
−
<!-- End of Pod2Wiki -->
+
Month names are taken from the current repository language.
−
<!-- Pod2Wiki=item_human_time -->==human_time==
 
  
−
  $timestamp = EPrints::Time::human_time( [$time] )
+
E.g.
  
−
Return a string describing the current local date and time in the current locale's format (see Perl's 'localtime).
+
<pre>  5 June 2010 10:35:12 +02:00
 +
  12 December 1912 # no time
 +
  1954 # no month/day</pre>
  
−
<!-- End of Pod2Wiki -->
+
$xhtml = EPrints::Time::render_short_date( $repo, $value )
−
<!-- Pod2Wiki=item_get_iso_timestamp -->==get_iso_timestamp==
+
Render a shorter form of [[API:EPrints/Time#render_date|render_date]].
  
−
  $timestamp = EPrints::Time::get_iso_timestamp( [$time] );
+
E.g.
  
−
Return a UTC timestamp of the form YYYY-MM-DDTHH:MM:SSZ
+
<pre>  05 Jun 2010 10:35:12
 +
  12 Dec 1912 # no time
 +
  1954 # no month/day</pre>
  
−
e.g. 2005-02-12T09:23:33Z
+
<!-- Pod2Wiki=head_copyright -->
 +
==COPYRIGHT==
 +
: Copyright 2000-2011 University of Southampton.
  
−
$time in seconds from 1970. If not defined then assume current time.
+
: This file is part of EPrints http://www.eprints.org/.
  
−
<!-- End of Pod2Wiki -->
+
: 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.
−
<!-- Pod2Wiki=head_undocumented_methods -->=UNDOCUMENTED METHODS=
 
−
{{API:Undocumented Methods}}<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_datestring_to_timet -->==datestring_to_timet==
 
  
−
<!-- End of Pod2Wiki -->
+
: 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.
−
<!-- Pod2Wiki=item_get_date -->==get_date==
 
  
−
<!-- End of Pod2Wiki -->
+
: You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.
−
<!-- Pod2Wiki=item_get_month_label_short -->==get_month_label_short==
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
−
<!-- Pod2Wiki=item_human_delay -->==human_delay==
 
  
−
<!-- End of Pod2Wiki -->
 
−
<!-- Pod2Wiki=item_render_short_date -->==render_short_date==
 
  
−
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=_postamble_ -->
 +
<!-- Edit below this comment -->

Latest revision as of 09:56, 22 January 2013

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects

API: Core API

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.eprints.org/w/index.php?title=API:EPrints/Time&oldid=10678’