pioneerspacesim/pioneer — pull request #795 by johnbartholomew (2011-11-14 03:52:31+00:00)
Title: Use -1 as an explicitly invalid systemIndex and bodyIndex in SystemPath

SystemPath can, and does, point to a whole sector, or to a system, or to a body within a system. However, this was purely implicit in which values happened to be used. This meant that there was no difference between a SystemPath that had been constructed to point to, say, Sector 0,0,0, and a SystemPath that had been constructed to point to the star, "Sol".

Following the general guideline that invalid data should be trapped as early as possible, this patch series alters SystemPath so that -1 is used as an explicit 'invalid' value for the `systemIndex` and `bodyIndex` fields.

Changes:

* When Lua accesses the `systemIndex` or `bodyIndex` attributes, 'nil' is returned if the field is invalid.
* SystemPath gets an extra constructor that takes just sector X,Y,Z and sets the system and body index fields to -1.
* SystemPath gets an extra set of methods for checking which fields are valid and clearing unwanted fields: `IsSectorPath`, `IsSystemPath`, `IsBodyPath` return a bool indicating whether the SystemPath is of the relevant form (this is an exact test, not a sub-typing test; that is, e.g., `IsSystemPath` returns false if the path contains valid body and system indices). `SectorOnly` and `SystemOnly` return a copy of the SystemPath with the extraneous fields cleared to -1. `IsSameSector` compares for equality against another SystemPath, checking only the sector X,Y,Z fields.
* `SectorOnly`, `SystemOnly` and `IsSameSector` are exposed to Lua.
* The Lua SystemPath type gains a `__tostring` metamethod. This is automatically used by the `print()` and `tostring()` functions.
* Various other bits of code has been updated to work with the new requirements or to use the new SystemPath methods.
* As part of the work for this I had to fix a long-standing bug in the way SectorView is initialised.

Unfortunately, this change is the sort that can easily introduce subtle bugs. It could do with being looked at by fresh eyes.