# perldoc > Date::Manip::Delta

---
type: CommandReference
command: Date::Manip::Delta
mode: perldoc
section: 3
source: perldoc
---

## Quick Reference

- `$delta = new Date::Manip::Delta` — create a new delta object
- `$delta->parse($string, \%opts)` — parse a delta string (compact or expanded notation)
- `$delta->set($field => $val, ...)` — set one or more delta fields
- `$delta->printf($format)` — format delta using printf directives
- `$delta->convert($type)` — convert between exact, semi, approx
- `$delta->cmp($delta2)` — compare two deltas
- `$delta->type($op)` — test if delta is business/standard, exact/semi/approx/estimated
- `$delta->value()` — return delta as string or list of fields

## Name

Methods for working with deltas — an amount of time elapsed with no start/end time.

## Synopsis

perl
use Date::Manip::Delta;
$delta = new Date::Manip::Delta;
## Options (Methods)

### Construction

- `new` — create a new delta object (returns $delta)
- `new_config`, `new_date`, `new_delta`, `new_recur` — see `Date::Manip::Obj`
- `base`, `tz`, `is_date`, `is_delta`, `is_recur`, `config`, `err` — see `Date::Manip::Obj`

### Parsing

- `parse($string, \%opts)` — parse a delta string. Options: `mode` (standard/business), `nonorm` (0/1), `type` (exact/semi/approx/estimated). Returns 0 on success, 1 on error.
  - Compact notation: colon-separated fields (1–7), e.g., `0:0:0:0:4:3:-2`
  - Expanded notation: field names and values, e.g., `+4 hours +3mn -2second`
  - Supports fractional values, `in`/`ago` words, and `business` keyword.

### Setting

- `set(\%opts)` — set one or more fields. Keys: `delta` (array ref), `business`, `standard`, `y`, `M`, `w`, `d`, `h`, `m`, `s`, `nonorm`, `mode`, `type`. Returns error code.
- `set($field, $val, $no_normalize)` — deprecated, use hash form.

### Formatting

- `printf($in)` — format delta using printf directives. Directives: `%%` (literal `%`), `%[+][pad][width]Xv` (single field), `%[+][pad][width][.precision]XYZ` (multiple fields in terms of one), `%[+][pad][width]Dt` (entire delta), `%[+][pad][width]DXY` (range of fields). Pad: `<` (left), `>` (right), `0` (zero-fill). Width: positive integer. Precision: decimal places.

### Conversion

- `convert($to)` — convert delta to `exact`, `semi`, or `approx`. Uses approximate/estimated relationships. Result is normalized. Converting from less exact to more exact is deprecated.
- `type($op)` — test if delta is `business`, `standard`, `exact`, `semi`, `approx`, `estimated`. Returns 1 if true.

### Comparison

- `cmp($delta2)` — compare two deltas using approximate relationships. Returns -1, 0, 1, or undef if invalid or mixed business/standard.

### Other

- `input()` — returns the parsed string.
- `value()` — returns printable string (scalar) or list of fields (list context).

## Examples

perl
use Date::Manip::Delta;

# Create and parse a delta
$delta = new Date::Manip::Delta;
$err = $delta->parse("1:2:3:4:5:6:7");
print $delta->value();   # +1:2:+3:+4:5:6:7

# Parse with options
$delta->parse("4 hours 3 minutes", { mode => "business" });

# Set fields
$delta->set( y => 1, d => 10, nonorm => 1 );

# Format using printf
$delta->printf("|%Dt|");          # |+1:2:+3:+4:5:6:7|
$delta->printf("|%+05dv|");       # |+0004|
$delta->printf("|%.4Myw|");       # |14.6900|

# Convert type
$delta->convert('semi');          # make day/week exact

# Compare
$delta1 = new Date::Manip::Delta;
$delta1->parse("0:0:0:0:44:0:0");
$delta2 = new Date::Manip::Delta;
$delta2->parse("0:0:0:1:20:0:0");
print $delta1->cmp($delta2);      # 0 (equal length)
## See Also

- [Date::Manip](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip/markdown) — main module documentation
- [Date::Manip::Calc](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ACalc/markdown) — delta calculations
- [Date::Manip::Obj](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3AObj/markdown) — base object methods
- [Date::Manip::Lang](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ALang/markdown) — language-specific field names