[Freeciv-Dev] Re: normalize_map_pos and invalid map positions

[Jason Short <jdorje@xxxxxxxxxxxxxxxxxxxxx>]

Per I. Mathisen wrote:
> On Fri, 9 Aug 2002, Jason Short wrote:
> > Using (-1,-1) as an "illegal" map position is already done: for
> > instance, vnotify_conn_ex() takes (-1,-1) as the position indicating
> > that a given event has no valid position. This can be made to work so
> > long as (-1,-1) is not a *normal* map position.Soon it will be a
> > *real* map position, but as long as all valid coordinates used are
> > *normal* we can tell (-1,-1) from a valid position.
>
> Ok, I've been skipping my homework. Care to clue me in to the difference
> between *real* and *normal* map positions?
This explanation leaves room for improvement, but it's something.

I wouldn't necessarily say this patch should be applied (it overlaps 
with other explanations below), but I do think after some discussion the 
"map" portion of HACKING should be updated/rewritten to explain things 
better.
jason

Index: doc/HACKING
===================================================================
RCS file: /home/freeciv/CVS/freeciv/doc/HACKING,v
retrieving revision 1.3
diff -u -r1.3 HACKING
--- doc/HACKING 2002/07/13 16:07:45     1.3
+++ doc/HACKING 2002/08/10 01:33:58
@@ -324,6 +324,21 @@
 to find a pointer to a specific tile.
 A tile has various fields; see the struct in common/map.h
 
+A map position (x, y) may be "real" or "unreal".  An unreal position is
+one that is not on the map at all; it does not refer to any valid tile.
+A real position does refer to a location on the map - but it may not be
+a unique reference.  For instance, with a 100x80 map that wraps in the
+X direction, the positions (0,0), (100,0) and (-2000,0) are all real
+positions - they refer to the same tile.  We also have the concept of a
+"normal" position, which is a real position that is in its canonical
+form.  In the above example, the set of normal positions would be all
+map positions such that 0 <= x < 100 and 0 <= y < 80.  Clearly, any
+normal position must also be real.  Passing a position to
+normalize_map_pos will normalize the position if it is real, and return
+FALSE if it is unreal.  Treating all positions in a consistent manner
+becomes more important when it is possible to have different topologies,
+such as unwrapping or torus worlds.
+
 When operating on tiles you normally iterate over x and y and maybe use
 map_get_tile() to get the tile struct.
 When fx iterating in a square around a map position (x,y) the naive method