formatting

developer_docs/IdLists_Entities_and_Remap.txt

@@ -1,17 +1,49 @@
 Some notes about Entities, Entity IDs and the IdList structure
 ==============================================================
-Sketch entities in SolveSpace are all of the same type without use of language support for polymorphism. The entity class is defined in sketch.h. That class contains an enum for each entity to define its type (line, arc, etc...) and some other members that can be used to store different things depending on the entity type. This means all entities are the same size, so some data may be reference by pointers from the entity (font, extra points, etc...)
+Sketch entities in SolveSpace are all of the same type without use of language
+support for polymorphism. The entity class is defined in sketch.h. That class
+contains an enum for each entity to define its type (line, arc, etc...) and some
+other members that can be used to store different things depending on the entity
+type. This means all entities are the same size, so some data may be reference
+by pointers from the entity (font, extra points, etc...)
 
-Entities in a sketch are kept in a global array (IdList) referenced by a unique Id (handle) and can be looked up by Id in log(n) time via binary search. In order to use binary seach the array must be kept in order sorted by Id. One problem is that insertion takes O(n) time because half the list (on average) must be shifted to make room for a new item.
+Entities in a sketch are kept in a global array (IdList) referenced by a unique
+Id (handle) and can be looked up by Id in log(n) time via binary search. In
+order to use binary seach the array must be kept in order sorted by Id. One
+problem is that insertion takes O(n) time because half the list (on average)
+must be shifted to make room for a new item.
 
 The IdList class is a template and is used for more than entites.
 
 EntityMap:
 ==========
-Another important structure is the EntityMap and EntityKey defined in sketch.h  This is what allows SovleSpace to update groups when earlier groups in the sketch are changed. If a rectangle is extruded to a box and items are constrained to entites on that box, the user can go back to the sketch and modify it. Entites can be added, modified an even deleted. So long as the entites that are later used to build upon are kept the later extrude group will pick up the changes from the 2D sketch and anything build on it will remain.
+Another important structure is the EntityMap and EntityKey defined in sketch.h
+This is what allows SovleSpace to update groups when earlier groups in the
+sketch are changed. If a rectangle is extruded to a box and items are
+constrained to entites on that box, the user can go back to the sketch and
+modify it. Entites can be added, modified an even deleted. So long as the
+entites that are later used to build upon are kept the later extrude group will
+pick up the changes from the 2D sketch and anything build on it will remain.
 
-The way this works is that each group has a member called remap, which is one of these maps. This is where my understanding is fuzzy. At the end of Group.cpp is a function called Group::CopyEntity() which is used to make new sketch entites when a group is created. These are generally copies of entities in the previous group, but there are exceptions. A point will be used to generate a line when extruding a 2D sketch. A point will also be "copied" to a circle for a Lathe group. For this reason, the entity key is derived by combining its previous key with something often called the CopyNumber or just remap (unfortunate).
+The way this works is that each group has a member called remap, which is one of
+these maps. This is where my understanding is fuzzy. At the end of Group.cpp is
+a function called Group::CopyEntity() which is used to make new sketch entites
+when a group is created. These are generally copies of entities in the previous
+group, but there are exceptions. A point will be used to generate a line when
+extruding a 2D sketch. A point will also be "copied" to a circle for a Lathe
+group. For this reason, the entity key is derived by combining its previous key
+with something often called the CopyNumber or just remap (unfortunate).
 
-When a group is regenerated (the first time, or after a previous one is modified) entites are copied from the old group to the new one. For Step Translating and Rotating there may be many copies, and the copy number is literally N for the Nth copy except for the last one which gets an enum - it is common to constrain the last item, so it gets a large unique number so that constraints still refer to it if the number of copies changes. When an entity is copied like this a new handle is created unless there is already an entity in Remap that was created the same way. This is how constructions are preserved across underlying changes.
+When a group is regenerated (the first time, or after a previous one is
+modified) entites are copied from the old group to the new one. For Step
+Translating and Rotating there may be many copies, and the copy number is
+literally N for the Nth copy except for the last one which gets an enum - it is
+common to constrain the last item, so it gets a large unique number so that
+constraints still refer to it if the number of copies changes. When an entity is
+copied like this a new handle is created unless there is already an entity in
+Remap that was created the same way. This is how constructions are preserved
+across underlying changes.
+
+There are some hard limits used in the hash table for the remap mechanism which
+limit the number of entites in a group (but not the global sketch).
 
-There are some hard limits used in the hash table for the remap mechanism which limit the number of entites in a group (but not the global sketch).