The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Time-Ago-1.00
River stage zero No dependents
3 ++
/ Time::Ago

NAME

Time::Ago - Approximate duration in words

VERSION

version 1.00

SYNOPSIS

  use Time::Ago;

  print Time::Ago->in_words(0), "\n";
  # prints "less than a minute"

  print Time::Ago->in_words(3600 * 4.6), "\n";
  # prints "about 5 hours"
  
  print Time::Ago->in_words(86400 * 360 * 2), "\n";
  # prints "almost 2 years"
  
  print Time::Ago->in_words(86400 * 365 * 11.3), "\n";
  # prints "over 11 years"

DESCRIPTION

Given a duration, in seconds, returns a readable approximation. This a Perl port of the time_ago_in_words() helper from Rails.

From Rails' docs:

  0 <-> 29 secs
    less than a minute

  30 secs <-> 1 min, 29 secs
    1 minute

  1 min, 30 secs <-> 44 mins, 29 secs
    [2..44] minutes

  44 mins, 30 secs <-> 89 mins, 29 secs
    about 1 hour

  89 mins, 30 secs <-> 23 hrs, 59 mins, 29 secs
    about [2..24] hours

  23 hrs, 59 mins, 30 secs <-> 41 hrs, 59 mins, 29 secs
    1 day

  41 hrs, 59 mins, 30 secs <-> 29 days, 23 hrs, 59 mins, 29 secs
    [2..29] days

  29 days, 23 hrs, 59 mins, 30 secs <-> 44 days, 23 hrs, 59 mins, 29 secs
    about 1 month

  44 days, 23 hrs, 59 mins, 30 secs <-> 59 days, 23 hrs, 59 mins, 29 secs
    about 2 months

  59 days, 23 hrs, 59 mins, 30 secs <-> 1 yr minus 1 sec
    [2..12] months

  1 yr <-> 1 yr, 3 months
    about 1 year

  1 yr, 3 months <-> 1 yr, 9 months
    over 1 year

  1 yr, 9 months <-> 2 yr minus 1 sec
    almost 2 years

  2 yrs <-> max time or date
    (same rules as 1 yr)

METHODS

in_words
  Time::Ago->in_words(30); # returns "1 minute"
  Time::Ago->in_words(3600 * 24 * 365 * 10); # returns "about 10 years"

Given a duration, in seconds, returns a readable approximation in words.

If an include_seconds parameter is supplied, durations under one minute generate more granular phrases:

  foreach (4, 9, 19, 39, 59) {
    print Time::Ago->in_words($_, include_seconds => 1), "\n";
  }

  # less than 5 seconds
  # less than 10 seconds
  # less than 20 seconds
  # half a minute
  # less than a minute

As a convenience, if the duration is an object with an epoch() interface (as provided by Time::Piece or DateTime), the current time minus the object's epoch() seconds is used.

Passing the duration as a DateTime::Duration instance is also supported.

LOCALIZATION

Locale::TextDomain is used for localization.

Currently Arabic, Dutch, English, French, German, Italian, Japanese, Russian, and Spanish translations are available. Contact me if you need another language.

See Locale::TextDomain for how to specify a language.

  #!/usr/bin/env perl
  
  use strict;
  use warnings;
  use open qw/ :std :utf8 /;
  use POSIX ':locale_h';
  use Time::Ago;
  
  my $secs = 86400 * 365 * 10.4;
  
  foreach (qw/ en fr de it ja ru es /) {
    setlocale(LC_ALL, '');
    $ENV{LANGUAGE} = $_;
    print Time::Ago->in_words($secs), "\n";
  }

Output:

  over 10 years
  plus de 10 ans
  vor mehr als 10 Jahren
  oltre 10 anni
  10年以上
  больше 10 лет
  más de 10 años

BUGS

The rails' implementation includes some logic for leap years that is not implemented here.

CREDITS

Ruby on Rails DateHelper http://apidock.com/rails/v4.2.1/ActionView/Helpers/DateHelper/distance_of_time_in_words

Ruby i18n library https://github.com/svenfuchs/i18n

SEE ALSO

Github repository https://github.com/mla/time-ago

Time::Duration, DateTime::Format::Human::Duration, Locale::TextDomain

AUTHOR

Maurice Aubrey <maurice.aubrey@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Maurice Aubrey.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.