Angles are a bit special, they differ from Distances and Currents in that Angles might need to exist within a specific, wrapping domain. If you’ve studied the unit circle for trigonometry, you might be familiar with this idea.

If not, don’t worry too much, the idea isn’t that complicated.

Lets say we start measuring at 0 degrees (makes sense.). Basically, as a circle wraps around past a full rotation (360 degrees), and we reach 361 degrees, this is equivalent to going back to 1 degree!

Dairy has three ways of configuring this, referred to as Wrapping modes:

1. Linear: no domain bounds, no wrapping
2. Wrapping: domain bounds of [0, 360) degrees
3. Relative: domain bounds of [-180, 180) degrees

Wrapping and Relative are functionally equivalent, but sometimes it might be nicer to use Relative rather than Wrapping.

Relative always represents the closest value to 0. While Wrapping always represents the same value as a positive number.

new Angle(AngleUnits.DEGREE, Wrapping.LINEAR, 370);

// OR

Angle linear = Angles.linearDeg(370); // 370
Angle wrapping = Angles.wrappedDeg(370); // 10
Angle relative = Angles.relativeDeg(370); // -170
// this helper will auto assign the `Wrapping` type of the angle
// first it will see if it fits into the bounds of `Wrapping`
// second it will see if it fits into the bounds of `Relative`
// last it will default to `Linear`
// this one will be `Linear`, as the value is out of the bounds of the other two
Angle guess = Angles.deg(370);

Angles have some special extra behaviours, due to Wrapping:

1. The majority of operations will return an Angle with Wrapping of Linear if either side of the operation has Wrapping of Linear. This is because otherwise the operation would lose information.
2. Angles have utilities to convert between Wrappings like AngleUnits.
3. Angles have a special version of findError.

Converting between Wrappings:

Wrapping wrapping = linear.getWrapping(); // we can get the `Wrapping`

linear.into(Wrapping.WRAPPING); // 10
linear.intoLinear(); // no-op
linear.intoWrapping(); // 10
linear.intoRelative(); // -170

Finding the error:

// `findError` will instead return a result solely based on the `Wrapping` of
// the target

// if the target has `Wrapping` `Linear`, the result will have `Wrapping`
// `Linear`, which acts like standard findError

// otherwise, the result will have `Wrapping` `Relative`, with a value that
// represents the shortest distance between the state (self / this) and the
// target

// this will return 0.0 (10 - 10)
linear.findError(wrapping);

// this will return 360 (370 - 10)
wrapping.findError(linear);