---
name: "Badger::Duration"
section: "3pm"
platform: "linux"
package: "libbadger-perl"
version: "0.16-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Badger::Duration"
---

# Badger::Duration(3pm)

simple class for representing durations

## NAME

Badger::Duration - simple class for representing durations

## SYNOPSIS

```
    use Badger::Duration 'Duration';
    my $d = Duration('7 days 4 hours 20 minutes');
    print "$d is ", $d->seconds, " seconds\n";
```

## DESCRIPTION

This is a simple module for parsing durations.

It is ideally suited for things like the calculation of expiry times (e.g.  for cookies, items in a cache, etc) allowing them to be specified in  human-friendly format, e.g. "4 minutes 20 seconds" (or various alternatives).

## EXPORTABLE SUBROUTINES

### DURATION

This is a shortcut alias to `"Badger::Duration"`.

```
    use Badger::Duration 'DURATION';

    my $duration = DURATION->new(
        hours   => 4,
        minutes => 20,
    );              # same as Badger::Duration->new(...);
```

### Duration()

This subroutine returns the name of the `"Badger::Duration"` class when called without arguments. Thus it can be used as an alias for `"Badger::Duration"` as per DURATION.

```
    use Badger::Duration 'Duration';

    my $duration = Duration->new(...);  # same as Badger::Duration->new(...);
```

When called with arguments, it creates a new `"Badger::Duration"` object.

```
    my $duration = Duration(...);       # same as Badger::Duration->new(...);
```

## METHODS

The following methods are defined in addition to those inherited from the Badger::Comparable and Badger::Base base classes.

### new()

Constructor method to create a new `"Badger::Duration"` object.  The duration can be specified as a single `"duration"` parameter.

```
    my $d = Badger::Duration->new(
        duration => '4 minutes 20 seconds'
    );
```

The duration string can contain any number of  "\<number\> \<duration\>" sequences separate by whitespace,  commas or the word `"and"`.  The following  are all valid:

```
    4 minutes 20 seconds
    4 minutes,20 seconds
    4 minutes, 20 seconds
    4 minutes and 20 seconds
```

The canonical names for durations are: `"year"`, `"month"`, `"day"`, `"hour"`,  `"minute"` and `"second"`.  The following aliases may be used:

- second

  ```
      s sec secs seconds
  ```

- minute

  ```
      m min mins minutes
  ```

- hour

  ```
      h hr hrs hours
  ```

- day

  ```
      d days
  ```

- week

  ```
      w wk weeks
  ```

- month

  ```
      M mon mons months
  ```

- year

  ```
      y yr yrs years
  ```

A duration can also be specified using named parameters:

```
    my $d = Badger::Duration->new(
        minutes => 4,
        seconds => 20,
    );
```

Or by reference to a hash array:

```
    my $d = Badger::Duration->new({
        minutes => 4,
        seconds => 20,
    });
```

This can also be specified as an explicit `"duration"` option if you prefer:

```
    my $d = Badger::Duration->new(
        duration => {
            minutes => 4,
            seconds => 20,
        }
    );
```

In all cases, any of the valid aliases for durations may be used, e.g.

```
    my $d = Badger::Duration->new(
        h => 1,
        m => 4,
        s => 20,
    );
```

### duration()

Returns a reference to a hash array containing the canonical values of  the duration.

```
    my $d = Badger::Duration->new(
        duration => '4 hours 20 minutes'
    );
    my $h = $d->duration;
    print $h->{ hour   };     # 4
    print $h->{ minute };     # 20
```

### seconds()

Returns the total number of seconds for the duration.

```
    my $d = Badger::Duration->new(
        duration => '4 hours 20 minutes'
    );
    print $d->seconds;      # 15600
```

### compare($that)

This method is defined to enable the functionality provided by the  Badger::Comparable base class.

```
    use Badger::Duration 'Duration';
    my $d1 = Duration('4 hours 20 minutes');
    my $d2 = Duration('270 minutes');
    if ($d1 < $d2) {
        # ...do something...
    }
```

### text()

Returns a canonical text representation of the duration.

```
    use Badger::Duration 'Duration';
    my $d1 = Duration('4 hrs 20 mins');
    print $d1->text;            # 4 hours 20 minutes
```

Note that the units will be pluralised appropriately.  e.g.

```
    1 hour 1 minute 1 second
    2 hours 2 minutes 2 seconds
```

This method is bound to the auto-stringification operation which is a fancy way of saying it gets called automatically when you simply print a  `"Badger::Duration"` object.

```
    print $d1;                  # 4 hours 20 minutes
```

## INTERNAL METHODS

### init($config)

Object initialisation method called automatically by the  **new()** constructor method inherited from the  Badger::Base base class.

### parse\_text($text)

Internal method to parse a text string and return a hash reference of canonical values.

### parse\_hash($hash)

Internal method to parse a hash reference and return another hash reference of  canonical values (e.g. after mapping aliases to canonical names).

### count\_seconds($hash)

Counts the total number of seconds in a duration passed by reference to a hash array.

## AUTHOR

Andy Wardley \<http://wardley.org\>

## COPYRIGHT

Copyright (C) 2013 Andy Wardley.  All Rights Reserved.

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