Pentagon and grid navigation error codes

[ajfriend]

I wanted to make sure we were in agreement around an offline discussion of #619. I think I'll abandon the changes in that PR and just start a new one, once we reach agreement in this issue.

The thinking, as I recall, was to add a few new error codes:

• E_UNREACHABLE_CELL: when an algorithm was unable to reach a desired cell. these situations may relate to pentagon distortion or cells being too far apart. this situation might be overcome with a "safe" version of the function or with future algorithm improvements (check the function documentation)
• E_PENTAGON_DOMAIN: when attempting to access the deleted subsequence of a pentagon
• E_UNEXPECTED_CODE_PATH: for when we reach a situation which we expect to be impossible. users should let us know whenever they see this, as this indicates an implementation bug

We would also remove E_PENTAGON, and use either E_UNREACHABLE_CELL or E_PENTAGON_DOMAIN in its place.

We would not add E_TOO_FAR, as that would be covered by E_UNREACHABLE_CELL.

We would also not add E_RETRY_WITH_SAFE, as that information will can be given in the specific function documentation.

One alternative

We could potentially split E_UNREACHABLE_CELL into two different errors:

• E_TOO_FAR
• E_PENTAGON_DISTORTION

And E_PENTAGON_DOMAIN would remain. My thinking is that it is distinct from E_PENTAGON_DISTORTION. Folks agree?

Or is all this more detail than the user needs?

[dfellis]

I like the proposed solution over the alternative.

[isaacbrodsky]

This is OK with me.

I might suggest E_ASSERTION_FAILURE as the name for E_UNEXPECTED_CODE_PATH.