.Do() and .Wrap() are no longer aliases. .Do() returns a mostly-pristine
copy of the error with the passed in value set to its upstream error
chain. .Wrap() now includes and retains other values such as the
error's associated code and metadata. As a consequence, .Wrap() obviates
some use cases such as remembering whether to call .Do() first when
using .Add() (which often leads to unexpected results if the opposite is
ever done instead).
GuaranteeError now calls .Copy().Wrap() instead of .Do().
New() and Errorf() are no longer aliases to their respective functions
in the errors and fmt packages; instead, they return an Error as an
error interface.
1) Public API now actually publishes DeepEqual. This was omitted for a
long enough period so as to be embarrassing.
2) Wrap() is now part of the public API and will be deprecating the more
confusingly-named Do().
3) Actually test UnfurlOn to see if it works as the documentation
claimed. It didn't, so we fixed it.
top level type.
Previously, the intent was for SetCode to be used in circumstances where
an error was replicated with .Do. However, there may be cases where this
isn't possible. This ensures that only copies are modified.
1) Comments have been clarified where they weren't entirely clear.
2) Guarantee will now return &nilError{} when passed a nil value.
3) Other Guarantee* functions are now documented as per their intended
purpose.
4) A new IsNil function has been added to determine if the Error under
scrutiny is, in fact, a nilError, nil, or otherwise.
5) Error.Equal and Error.Is now call the top level functions internally
to minimize code footprint.
sensibilities:
1) Errors track their clone state to determine if they're a top-level
error.
2) Top-level Clone(Error) function now calls .Clone() on the argument
it's passed rather than vice-versa.
3) Added Copy() function which acts in accordance with the intended
purpose that Clone() sufficed. Clone() has been retained for API
compatibility.
4) Calling Add() on a top-level error, directly, will create a copy and
return the copy with the specified metadata values attached. Add() will
never change the metadata associated with a top-level error type. Use
Attach() instead.
5) Attach() has been added as a separate method for working with
metadata values on top-level error types.
6) GetString, GetInt, GetFloat, and GetError have been added for
extricating typed metadata values for convenience.
Unwrap acts analogously to the standard library errors.Unwrap.
UnfurlOn acts similarly to Unfurl with the exception that it accepts a
function against which every error in the chain will be applied.
Contains returns true if the parent error type contains the specified
error.
