# allsopp/p6-Operator-dB

Operator to support decibel (dB) arithmetic
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
doc/Operator
lib/Operator
t
.gitignore
.travis.yml
META6.json

# NAME

Operator::dB - Operator to support decibel (dB) arithmetic.

# SYNOPSIS

``````use Operator::dB;

put 100 + 3dB;
# 199.52623149688796

put 100 - 3dB;
# 50.11872336272723

put 10dB + 20dB;
# 20.413927dB``````

# DESCRIPTION

The interface tries to be intuitive while avoiding ambiguity. For example, the following makes sense (adding 3dB is approximately equivalent to doubling).

``````10 + 3dB
# 19.952623149688794``````

But the following doesn't make sense. It could represent either `13dB`, or `10.8dB` (i.e. `3dB + 10dB`).

``3dB + 10 # DOESN'T WORK!``

All supported operations are discussed in the following subsections.

## Addition and subtraction on numbers

Adding or subtracting decibel values to and from numbers (of `Numeric` type) scales the number by the corresponding decibel gain:

``````put 100 + 3dB;
# 199.52623149688796

put 100 - 3dB;
# 50.11872336272723``````

## Addition and subtraction on decibels

Decibels can be added to, or subtracted from, each other.

This type of operation returns an `Operator::dB::Decibel` wrapper object:

``````my \$foo = 3dB + 2dB - 1dB;
# Operator::dB::Decibel.new(x => 10, y => 0.365...)``````

You can get the decibel value itself with `.dB`:

``````\$foo.dB;
# 3.6571819272302735``````

Or by stringification:

``````"The gain is: \$foo";
# The gain is: 3.657182dB``````

Or by defining your own format with `.fmt`:

``````\$foo.fmt("%.1f dB(A)");
# 3.7 dB(A)``````

# CAVEATS

This package exports overloads to built-in operators, which is potentially reckless. But the operator signatures all contain at least one `Operator::dB::Decibel` object (which is not built-in), so it should be fine!

The `Num` method is not implemented on the wrapper class, so many built-in numerical operations don't work, e.g. `1dB * 1`. This is a necessary limitation because decibel arithmetic is only semantically valid for addition and subtraction AFAIK.