CVS difference for ai05s/ai05-0136-1.txt

Differences between 1.3 and version 1.4
Log of other versions for file ai05s/ai05-0136-1.txt

--- ai05s/ai05-0136-1.txt	2009/05/30 05:13:20	1.3
+++ ai05s/ai05-0136-1.txt	2009/06/02 06:22:37	1.4
@@ -71,18 +71,18 @@
 the children of each child node, and so on.
 
 The nodes of a subtree could be visited in several different orders. For a
-*depth-first order*, the last step of visiting a node is to visit the nodes of its
-child list in order, recursively.
+*depth-first order*, the last step of visiting a node is to visit the nodes of
+its child list in order, recursively.
 
-AARM Ramification: For the depth-first order, when each child node is visited, the
-child list of the child node is visited before the next sibling of the child node
-is visited.
-
-[Editor's note: I didn't define a breadth-first order. Such an order requires two
-trips through the child list (one to visit the child nodes, and once to to visit the
-children of those nodes. It also doesn't make sense for debugging/output applications,
-so it wasn't clear that it was very useful. Thus I didn't use it in any of the defined
-operations.]
+AARM Ramification: For the depth-first order, when each child node is visited,
+the child list of the child node is visited before the next sibling of the child
+node is visited.
+
+[Editor's note: I didn't define a breadth-first order. Such an order requires
+two trips through the child list (one to visit the child nodes, and once to to
+visit the children of those nodes. It also doesn't make sense for
+debugging/output applications, so it wasn't clear that it was very useful. Thus
+I didn't use it in any of the defined operations.]
 
 Static Semantics
 
@@ -298,45 +298,47 @@
    ... -- not specified by the language
 end Ada.Containers.Multiway_Trees;
 
-The actual function for the generic formal function "=" on Element_Type values is
-expected to define a reflexive and symmetric relationship and return the same result
-value each time it is called with a particular pair of values. If it behaves in some
-other manner, the functions Find, Reverse_Find, Equal_Subtrees, and "=" on tree values
-return an unspecified value. The exact arguments and number of calls of this generic
-formal function by the functions Find, Reverse_Find, Equal_Subtrees, and "=" on tree
-values are unspecified.
-
-The type Tree is used to represent trees. The type List needs finalization (see 7.6).
-
-Empty_Tree represents the empty Tree object. It contains no nodes (Count (Empty_Tree)
-returns 0). If an object of type Tree is not otherwise initialized, it is initialized
-to the same value as Empty_Tree.
+The actual function for the generic formal function "=" on Element_Type values
+is expected to define a reflexive and symmetric relationship and return the same
+result value each time it is called with a particular pair of values. If it
+behaves in some other manner, the functions Find, Reverse_Find, Equal_Subtrees,
+and "=" on tree values return an unspecified value. The exact arguments and
+number of calls of this generic formal function by the functions Find,
+Reverse_Find, Equal_Subtrees, and "=" on tree values are unspecified.
+
+The type Tree is used to represent trees. The type List needs finalization (see
+7.6).
+
+Empty_Tree represents the empty Tree object. It contains no nodes (Count
+(Empty_Tree) returns 0). If an object of type Tree is not otherwise initialized,
+it is initialized to the same value as Empty_Tree.
+
+No_Element represents a cursor that designates no element. If an object of type
+Cursor is not otherwise initialized, it is initialized to the same value as
+No_Element.
 
-No_Element represents a cursor that designates no element. If an object of type Cursor
-is not otherwise initialized, it is initialized to the same value as No_Element.
-
 No_Parent represents a cursor that represents the parent of an orphan element.
 
-The predefined "=" operator for type Cursor returns True if both cursors are No_Element,
-or designate the same element in the same container.
+The predefined "=" operator for type Cursor returns True if both cursors are
+No_Element, or designate the same element in the same container.
 
-Execution of the default implementation of the Input, Output, Read, or Write attribute
-of type Cursor raises Program_Error.
+Execution of the default implementation of the Input, Output, Read, or Write
+attribute of type Cursor raises Program_Error.
 
 Some operations of this generic package have access-to-subprogram parameters. To
-ensure such operations are well-defined, they guard against certain actions by the
-designated subprogram. In particular, some operations check for "tampering with cursors"
-of a container because they depend on the set of elements of the container remaining
-constant, and others check for "tampering with elements" of a container because they
-depend on elements of the container not being replaced.
+ensure such operations are well-defined, they guard against certain actions by
+the designated subprogram. In particular, some operations check for "tampering
+with cursors" of a container because they depend on the set of elements of the
+container remaining constant, and others check for "tampering with elements" of
+a container because they depend on elements of the container not being replaced.
 
 A subprogram is said to tamper with cursors of a tree object T if:
-* it inserts or deletes elements of T, that is, it calls the Clear, Delete, 
+* it inserts or deletes elements of T, that is, it calls the Clear, Delete,
   Insert_Child, or Delete_Child procedures with T as a parameter; or
 
-AARM To be honest: Operations which are defined to be equivalent to a call on one of
-these operations also are included. Similarly, operations which call one of these as
-part of their definition are included. 
+AARM To be honest: Operations which are defined to be equivalent to a call on
+one of these operations also are included. Similarly, operations which call one
+of these as part of their definition are included.
 
 * it reorders the elements of T, that is, it calls the Splice or Splice_Children
   procedures; or
@@ -345,10 +347,10 @@
 
 * it calls Assign with T as the Target parameter; or
 
-* it calls the Move procedure with T as a parameter. 
+* it calls the Move procedure with T as a parameter.
 
-AARM Reason: Swap copies elements rather than reordering them, so it doesn't tamper
-with cursors.
+AARM Reason: Swap copies elements rather than reordering them, so it doesn't
+tamper with cursors.
 
 A subprogram is said to tamper with elements of a tree object T if:
 
@@ -357,103 +359,116 @@
 * it replaces one or more elements of T, that is, it calls the Replace_Element or Swap
   procedures with T as a parameter.
 
-AARM Reason: Complete replacement of an element can cause its memory to be deallocated
-while another operation is holding onto a reference to it. That can't be allowed.
-However, a simple modification of (part of) an element is not a problem, so Update_Element
-does not cause a problem. 
+AARM Reason: Complete replacement of an element can cause its memory to be
+deallocated while another operation is holding onto a reference to it. That
+can't be allowed. However, a simple modification of (part of) an element is not
+a problem, so Update_Element does not cause a problem.
 
    function Equal_Subtree (Left_Position : Cursor;
                            Right_Position: Cursor) return Boolean;
-      If Left_Position or Right_Position equals No_Element, raises Constraint_Error.
-      If the number of child nodes of the element designated by Left_Position is
-      different than the number of child modes of the element designated by
-      Right_Position, the function returns False. If comparing the element designated
-      by Left_Position with the element designated by Right_Position using the
-      generic formal equality operator returns False, the function returns False.
-      Otherwise, it calls Equal_Subtree on a cursor designating each child element
-      of the element designated by Left_Position and a cursor designated the corresponding
-      child element of the element deisgnated by Right_Position. If any such call
-      returns False, the function returns False; otherwise it returns True. Any
-      exception raised during the evaluation of element equality is propagated.
-
-      [Editor's note: I needed this to define "=" on Trees. We don't support comparing
-      No_Element here, as that doesn't represent a "particular node" and doing so would
-      require passing two container parameters as well. If you need want to compare the
-      entire active tree of a container to some other subtree, pass Root.]
-
-      AARM Ramification: Left_Position and Right_Position do not need to be from the same
-      container.
-
-      AARM Implementation Note: This wording describes the canonical semantics. However,
-      the order and number of calls on the formal equality function is unspecified for
-      all of the operations that use it in this package, so an implementation can call
-      it as many or as few times as it needs to get the correct answer. Similarly, a global
-      rule (see the introduction of Annex A) says that language-defined routines are not
-      affected by overriding of other language-defined routines. This means that no
-      reasonable program can tell how many times Equal_Subtrees is called, and thus an
-      implementation can call it as many or as few times as it needs to get the correct
-      answer. Specifically, there is no requirement to call the formal equality or
-      Equal_Subtrees additional times once the answer has been determined. 
+
+      If Left_Position or Right_Position equals No_Element, raises
+      Constraint_Error. If the number of child nodes of the element designated
+      by Left_Position is different than the number of child modes of the
+      element designated by Right_Position, the function returns False. If
+      comparing the element designated by Left_Position with the element
+      designated by Right_Position using the generic formal equality operator
+      returns False, the function returns False. Otherwise, it calls
+      Equal_Subtree on a cursor designating each child element of the element
+      designated by Left_Position and a cursor designated the corresponding
+      child element of the element deisgnated by Right_Position. If any such
+      call returns False, the function returns False; otherwise it returns True.
+      Any exception raised during the evaluation of element equality is
+      propagated.
+
+      [Editor's note: I needed this to define "=" on Trees. We don't support
+      comparing No_Element here, as that doesn't represent a "particular node"
+      and doing so would require passing two container parameters as well. If
+      you need want to compare the entire active tree of a container to some
+      other subtree, pass Root.]
+
+      AARM Ramification: Left_Position and Right_Position do not need to be from
+      the same container.
+
+      AARM Implementation Note: This wording describes the canonical semantics.
+      However, the order and number of calls on the formal equality function is
+      unspecified for all of the operations that use it in this package, so an
+      implementation can call it as many or as few times as it needs to get the
+      correct answer. Similarly, a global rule (see the introduction of Annex A)
+      says that language-defined routines are not affected by overriding of
+      other language-defined routines. This means that no reasonable program can
+      tell how many times Equal_Subtrees is called, and thus an implementation
+      can call it as many or as few times as it needs to get the correct answer.
+      Specifically, there is no requirement to call the formal equality or
+      Equal_Subtrees additional times once the answer has been determined.
 
    function "=" (Left, Right : Tree) return Boolean;
 
-      If Left and Right denote the same tree object, then the function returns True. If
-      Child_Count (Left, No_Element) does not equal Child_Count (Right, No_Element), then
-      the function returns False. If Left has a designated root element and Right does not,
-      or vice versa, the function returns False. Otherwise, it calls Equal_Subtree with a cursor
-      designating each orphan element of Left and a cursor designating the corresponding
-      orphan element of Right. If any such call returns False, the function returns False;
-      otherwise it returns True. Any exception raised during the evaluation of element
-      equality is propagated.
-
-      AARM Discussion: We test that the number of orphan elements is the same in each container.
-      We also check that either both or neither of the trees has a designated root.
-      Otherwise, we recursively test that all of the orphan subtrees are equivalent. We
-      don't need to explicitly check the contents of the roots, since a designated root
-      (if present) is always the first orphan node.
+      If Left and Right denote the same tree object, then the function returns
+      True. If Child_Count (Left, No_Element) does not equal Child_Count (Right,
+      No_Element), then the function returns False. If Left has a designated
+      root element and Right does not, or vice versa, the function returns
+      False. Otherwise, it calls Equal_Subtree with a cursor designating each
+      orphan element of Left and a cursor designating the corresponding orphan
+      element of Right. If any such call returns False, the function returns
+      False; otherwise it returns True. Any exception raised during the
+      evaluation of element equality is propagated.
+
+      AARM Discussion: We test that the number of orphan elements is the same in
+      each container. We also check that either both or neither of the trees has
+      a designated root. Otherwise, we recursively test that all of the orphan
+      subtrees are equivalent. We don't need to explicitly check the contents of
+      the roots, since a designated root (if present) is always the first orphan
+      node.
 
-      AARM Implementation Note: Similar considerations apply here as apply to Equal_Subtrees.
-      The actual number of calls performed is unspecified.
+      AARM Implementation Note: Similar considerations apply here as apply to
+      Equal_Subtrees. The actual number of calls performed is unspecified.
 
    function Count (Container : Tree) return Count_Type;
-      If there is no designated root element of Container, Count returns 0; otherwise
-      Count returns the number of elements in the active subtree of Container. 
+
+      If there is no designated root element of Container, Count returns 0;
+      otherwise Count returns the number of elements in the active subtree of
+      Container.
 
    function Overall_Count (Container : Tree) return Count_Type;
+
       Overall_Count returns the number of elements in the entire tree Container,
       including orphan elements and their children.
 
    function Subtree_Count (Container : Tree; Position : Cursor) return Count_Type;
+
       If Position equals No_Parent, and there is no designated root element,
-      Subtree_Count returns 0; otherwise Subtree_Count returns the number
-      of elements in the subtree rooted by the designated root element of Container.
-      If Position is not No_Parent, Subtree_Count returns the number of elements in
-      the subtree that is rooted by Position. 
+      Subtree_Count returns 0; otherwise Subtree_Count returns the number of
+      elements in the subtree rooted by the designated root element of
+      Container. If Position is not No_Parent, Subtree_Count returns the number
+      of elements in the subtree that is rooted by Position.
 
    function Is_Empty (Container : Tree) return Boolean;
 
       Equivalent to Overall_Count (Container) = 0.
 
-      AARM Discussion: We use Overall_Count to ensure that all elements are counted;
-      Count (Container) only counts the active subtree. This routine, of course,
-      should be implemented a O(1), while Overall_Count is probably O(N).
+      AARM Discussion: We use Overall_Count to ensure that all elements are
+      counted; Count (Container) only counts the active subtree. This routine,
+      of course, should be implemented a O(1), while Overall_Count is probably
+      O(N).
 
    function Depth (Position : Cursor) return Count_Type;
 
       If Position equals No_Element, Depth returns 0; otherwise Depth returns
-      the number of ancestor nodes of the element at Position (including the element
-      itself). 
+      the number of ancestor nodes of the element at Position (including the
+      element itself).
 
       [Editor's note: Matt suggests that we have this function as well as
-      Child_Depth because this is the most common case. We can't usefully default
-      the Parent parameter in Child_Depth because it is first; putting the parameters
-      in the other order would be inconsistent with all other routines (where the
-      parent comes first) and thus would be confusing in positional calls.]
+      Child_Depth because this is the most common case. We can't usefully
+      default the Parent parameter in Child_Depth because it is first; putting
+      the parameters in the other order would be inconsistent with all other
+      routines (where the parent comes first) and thus would be confusing in
+      positional calls.]
 
    function Is_Root (Position : Cursor) return Boolean;
 
-      Is_Root returns True if the Position designates the element that is designated
-      as the root of the tree; and returns False otherwise.
+      Is_Root returns True if the Position designates the element that is
+      designated as the root of the tree; and returns False otherwise.
 
    function Is_Orphan (Position : Cursor) return Boolean;
 
@@ -473,18 +488,18 @@
 
    function Root (Container : Tree) return Cursor;
 
-      Root returns a cursor that designates the element that is the designated root
-      element of Container; it returns No_Element if there is no designated root
-      element of Container.
+      Root returns a cursor that designates the element that is the designated
+      root element of Container; it returns No_Element if there is no designated
+      root element of Container.
 
    procedure Set_Root (Container : in out Tree;
                        Position  : in     Cursor);
 
       If Position equals No_Element, then Container is set to have no designated
-      root element. If Is_Orphan (Position) is False, Constraint_Error is propagated.
-      Otherwise, the element designated by Position is set as the designated root
-      element designated of Container. The newly designated element becomes the
-      first orphan element of Container.
+      root element. If Is_Orphan (Position) is False, Constraint_Error is
+      propagated. Otherwise, the element designated by Position is set as the
+      designated root element designated of Container. The newly designated
+      element becomes the first orphan element of Container.
 
       AARM Ramification: If Root (Container) /= No_Element, then
       First_Child (Container, No_Parent) = Root (Container).
@@ -496,26 +511,27 @@
    function Element (Position : Cursor)
       return Element_Type;
 
-      If Position equals No_Element, then Constraint_Error is propagated. Otherwise,
-      Element returns the element designated by Position.
+      If Position equals No_Element, then Constraint_Error is propagated.
+      Otherwise, Element returns the element designated by Position.
 
    procedure Replace_Element (Container : in out Tree;
                               Position  : in     Cursor;
                               New_Item  : in     Element_Type);
 
-      If Position equals No_Element, then Constraint_Error is propagated; if Position
-      does not designate an element in Container, then Program_Error is propagated.
-      Otherwise Replace_Element assigns the value New_Item to the element designated
-      by Position.
+      If Position equals No_Element, then Constraint_Error is propagated; if
+      Position does not designate an element in Container, then Program_Error is
+      propagated. Otherwise Replace_Element assigns the value New_Item to the
+      element designated by Position.
 
    procedure Query_Element
      (Position : in Cursor;
       Process  : not null access procedure (Element : in Element_Type));
 
-      If Position equals No_Element, then Constraint_Error is propagated. Otherwise,
-      Query_Element calls Process.all with the element designated by Position as the
-      argument. Program_Error is propagated if Process.all tampers with the elements
-      of Container. Any exception raised by Process.all is propagated.
+      If Position equals No_Element, then Constraint_Error is propagated.
+      Otherwise, Query_Element calls Process.all with the element designated by
+      Position as the argument. Program_Error is propagated if Process.all
+      tampers with the elements of Container. Any exception raised by
+      Process.all is propagated.
 
    procedure Update_Element
      (Container : in out Tree;
@@ -523,14 +539,15 @@
       Process   : not null access procedure
                       (Element : in out Element_Type));
 
-      If Position equals No_Element, then Constraint_Error is propagated; if Position
-      does not designate an element in Container, then Program_Error is propagated.
-      Otherwise Update_Element calls Process.all with the element designated by Position
-      as the argument. Program_Error is propagated if Process.all tampers with the
-      elements of Container. Any exception raised by Process.all is propagated.
+      If Position equals No_Element, then Constraint_Error is propagated; if
+      Position does not designate an element in Container, then Program_Error is
+      propagated. Otherwise Update_Element calls Process.all with the element
+      designated by Position as the argument. Program_Error is propagated if
+      Process.all tampers with the elements of Container. Any exception raised
+      by Process.all is propagated.
 
-      If Element_Type is unconstrained and definite, then the actual Element parameter of
-      Process.all shall be unconstrained.
+      If Element_Type is unconstrained and definite, then the actual Element
+      parameter of Process.all shall be unconstrained.
 
    procedure Assign (Target : in out Tree; Source : Tree);
 
@@ -538,102 +555,114 @@
       effect. Otherwise, it clears Target, and then each element of Source is
       assigned to a corresponding element in Target.
 
-      AARM To Be Honest: The "corresponding element in Target" has a parent element
-      that corresponds to the parent element of the Source element, and has child
-      elements that correspond to the child elements of the Source element.
+      AARM To Be Honest: The "corresponding element in Target" has a parent
+      element that corresponds to the parent element of the Source element, and
+      has child elements that correspond to the child elements of the Source
+      element.
 
    function Copy (Source : Tree) return Tree;
 
-      Returns a tree with the same structure as Source and whose elements are initialized
-      from the corresponding elements of Source.
+      Returns a tree with the same structure as Source and whose elements are
+      initialized from the corresponding elements of Source.
 
    procedure Move (Target : in out Tree;
                    Source : in out Tree);
 
-      If Target denotes the same object as Source, then Move has no effect. Otherwise, Move
-      first calls Clear (Target). Then, the nodes in Source are moved to Target (in the same
-      positions). After Move completes, Overall_Count(Target) is the number of nodes originally
-      in Source, and Overall_Count(Source) is 0.
+      If Target denotes the same object as Source, then Move has no effect.
+      Otherwise, Move first calls Clear (Target). Then, the nodes in Source are
+      moved to Target (in the same positions). After Move completes,
+      Overall_Count(Target) is the number of nodes originally in Source, and
+      Overall_Count(Source) is 0.
 
    procedure Delete (Container : in out Tree;
                      Position  : in out Cursor);
 
-      If Position equals No_Element, then Constraint_Error is propagated. If Position does not
-      designate an element in Container, then Program_Error is propagated. If the element
-      designated by position has any child elements, then Constraint_Error is propagated.
-      Otherwise Delete removes (from Container) the element designated by Position. Finally,
-      Position is set to No_Element.
-
-      AARM Ramification: The check on Position checks that the cursor does not belong to some
-      other Container. This check implies that a reference to the container is included in the
-      cursor value. This wording is not meant to require detection of dangling cursors; such
-      cursors are defined to be invalid, which means that execution is erroneous, and any result
-      is allowed (including not raising an exception). 
+      If Position equals No_Element, then Constraint_Error is propagated. If
+      Position does not designate an element in Container, then Program_Error is
+      propagated. If the element designated by position has any child elements,
+      then Constraint_Error is propagated. Otherwise Delete removes (from
+      Container) the element designated by Position. Finally, Position is set to
+      No_Element.
+
+      AARM Ramification: The check on Position checks that the cursor does not
+      belong to some other Container. This check implies that a reference to the
+      container is included in the cursor value. This wording is not meant to
+      require detection of dangling cursors; such cursors are defined to be
+      invalid, which means that execution is erroneous, and any result is
+      allowed (including not raising an exception).
 
    procedure Delete_Subtree (Container : in out Tree;
                              Position  : in out Cursor);
 
-      If Position equals No_Element, then Constraint_Error is propagated. If Position does not
-      designate an element in Container, then Program_Error is propagated. Otherwise Delete
-      removes (from Container) the subtree designated by Position - that is, the element
-      designated by Position along with all of the descendant elements of that element.
-      Finally, Position is set to No_Element.
+      If Position equals No_Element, then Constraint_Error is propagated. If
+      Position does not designate an element in Container, then Program_Error is
+      propagated. Otherwise Delete removes (from Container) the subtree
+      designated by Position - that is, the element designated by Position along
+      with all of the descendant elements of that element. Finally, Position is
+      set to No_Element.
 
    procedure Swap (Container : in out Tree;
                    I, J      : in     Cursor);
-
-      If either I or J is No_Element, then Constraint_Error is propagated. If either I or J do
-      not designate an element in Container, then Program_Error is propagated. Otherwise, Swap
-      exchanges the values of the elements designated by I and J.
-
-      AARM Ramification: After a call to Swap, I designates the element value previously
-      designated by J, and J designates the element value previously designated by I. The elements
-      position do not change; for instance, the parent node and the first child node of I are
-      unchanged by the operation.
 
-      AARM To be honest: The implementation is not required to actually copy the elements if it
-      can do the swap some other way. But it is allowed to copy the elements if needed. 
+      If either I or J is No_Element, then Constraint_Error is propagated. If
+      either I or J do not designate an element in Container, then Program_Error
+      is propagated. Otherwise, Swap exchanges the values of the elements
+      designated by I and J.
+
+      AARM Ramification: After a call to Swap, I designates the element value
+      previously designated by J, and J designates the element value previously
+      designated by I. The elements position do not change; for instance, the
+      parent node and the first child node of I are unchanged by the operation.
+
+      AARM To be honest: The implementation is not required to actually copy the
+      elements if it can do the swap some other way. But it is allowed to copy
+      the elements if needed.
 
    function Find (Container : Tree;
                   Item      : Element_Type;
                   Position  : Cursor := No_Element)
       return Cursor;
 
-      If Position is not No_Element, and does not designate an element in Container, then
-      Program_Error is propagated. Find searches a subtree of the elements of Container
-      for an element equal to Item (using the generic formal equality operator). The search
-      starts at the element designated by Position, or at the designated root element if Position
-      equals No_Element. The search checks the subtree rooted by Position in a depth-first
-      order. If no equal element is found, then Find returns No_Element. Otherwise, it
+      If Position is not No_Element, and does not designate an element in
+      Container, then Program_Error is propagated. Find searches a subtree of
+      the elements of Container for an element equal to Item (using the generic
+      formal equality operator). The search starts at the element designated by
+      Position, or at the designated root element if Position equals No_Element.
+      The search checks the subtree rooted by Position in a depth-first order.
+      If no equal element is found, then Find returns No_Element. Otherwise, it
       returns a cursor designating the first equal element encountered.
 
-      AARM Ramification: Find does not check any siblings of the element designated by Position.
+      AARM Ramification: Find does not check any siblings of the element
+      designated by Position.
 
-      [Editor's note: This would naturally be called "Find_Subtree", but that is a misleading
-      name, as what this does is Find *in* subtree (not finding a subtree). So we stick with
-      plain "Find".]
+      [Editor's note: This would naturally be called "Find_Subtree", but that is
+      a misleading name, as what this does is Find *in* subtree (not finding a
+      subtree). So we stick with plain "Find".]
 
    function Overall_Find (Container : Tree;
                           Item      : Element_Type)
       return Cursor;
 
-      Overall_Find searches all of the elements of Container for an element equal to Item (using
-      the generic formal equality operator). The search starts at the first orphan element. The
-      search checks each orphan subtree (including the active subtree, if any) in a depth-first order.
-      If no equal element is found, then Overall_Find returns No_Element. Otherwise, it returns
-      a cursor designating the first equal element encountered.
+      Overall_Find searches all of the elements of Container for an element
+      equal to Item (using the generic formal equality operator). The search
+      starts at the first orphan element. The search checks each orphan subtree
+      (including the active subtree, if any) in a depth-first order. If no equal
+      element is found, then Overall_Find returns No_Element. Otherwise, it
+      returns a cursor designating the first equal element encountered.
 
    function Ancestor_Find (Container : Tree;
                            Item      : Element_Type;
                            Position  : Cursor)
       return Cursor;
 
-      If Position is No_Element, then Constraint_Error is propagated. If Position does not designate
-      an element in Container, then Program_Error is propagated. Otherwise, Ancestor_Find searches
-      for an element equal to Item (using the generic formal equality operator). The search starts
-      at the element designated by Position, and checks each ancestor proceeding toward the root
-      of the subtree. If no equal element is found, then Ancestor_Find returns No_Element.
-      Otherwise, it returns a cursor designating the first equal element encountered.
+      If Position is No_Element, then Constraint_Error is propagated. If
+      Position does not designate an element in Container, then Program_Error is
+      propagated. Otherwise, Ancestor_Find searches for an element equal to Item
+      (using the generic formal equality operator). The search starts at the
+      element designated by Position, and checks each ancestor proceeding toward
+      the root of the subtree. If no equal element is found, then Ancestor_Find
+      returns No_Element. Otherwise, it returns a cursor designating the first
+      equal element encountered.
 
    function Contains (Container : Tree;
                       Item      : Element_Type) return Boolean;
@@ -647,61 +676,69 @@
 
    function Has_Element (Position : Cursor) return Boolean;
 
-      Returns True if Position designates an element, and returns False otherwise.
+      Returns True if Position designates an element, and returns False
+      otherwise.
 
-      AARM To be honest: This function may not detect cursors that designate deleted
-      elements; such cursors are invalid (see below) and the result of Has_Element for
-      an invalid cursor is unspecified (but not erroneous). 
+      AARM To be honest: This function may not detect cursors that designate
+      deleted elements; such cursors are invalid (see below) and the result of
+      Has_Element for an invalid cursor is unspecified (but not erroneous).
 
    procedure Iterate
      (Container : in Tree;
       Process   : not null access procedure (Position : in Cursor));
-
-      Iterate calls Process.all with a cursor that designates each node in the active portion
-      of Container, starting with the designated root node and proceeding in a depth-first
-      order. Program_Error is propagated if Process.all tampers with the cursors of
-      Container. Any exception raised by Process.all is propagated.
 
-      AARM Ramification: If there is no designated root node, Iterate does nothing;
-      Process.all will not be called at all.
-
-      AARM Implementation Note: The purpose of the tamper with cursors check is to prevent
-      erroneous execution from the Position parameter of Process.all becoming invalid. This
-      check takes place when the operations that tamper with the cursors of the container are
-      called. The check cannot be made later (say in the body of Iterate), because that could
-      cause the Position cursor to be invalid and potentially cause execution to become erroneous
+      Iterate calls Process.all with a cursor that designates each node in the
+      active portion of Container, starting with the designated root node and
+      proceeding in a depth-first order. Program_Error is propagated if
+      Process.all tampers with the cursors of Container. Any exception raised by
+      Process.all is propagated.
+
+      AARM Ramification: If there is no designated root node, Iterate does
+      nothing; Process.all will not be called at all.
+
+      AARM Implementation Note: The purpose of the tamper with cursors check is
+      to prevent erroneous execution from the Position parameter of Process.all
+      becoming invalid. This check takes place when the operations that tamper
+      with the cursors of the container are called. The check cannot be made
+      later (say in the body of Iterate), because that could cause the Position
+      cursor to be invalid and potentially cause execution to become erroneous
       -- defeating the purpose of the check.
 
-      See Iterate for vectors (A.18.2) for a suggested implementation of the check. 
+      See Iterate for vectors (A.18.2) for a suggested implementation of the
+      check.
       End AARM Implementation Note.
 
    procedure Overall_Iterate
      (Container : in Tree;
       Process   : not null access procedure (Position : in Cursor));
 
-      Iterate calls Process.all with a cursor that designates each node in the Container
-      of Container, starting with the first orphan node and proceeding in a depth-first
-      order, visiting each orphan subtree (including the active subtree, if any) in order.
-      Program_Error is propagated if Process.all tampers with the cursors of Container.
-      Any exception raised by Process.all is propagated.
+      Iterate calls Process.all with a cursor that designates each node in the
+      Container of Container, starting with the first orphan node and proceeding
+      in a depth-first order, visiting each orphan subtree (including the active
+      subtree, if any) in order. Program_Error is propagated if Process.all
+      tampers with the cursors of Container. Any exception raised by Process.all
+      is propagated.
 
    function Child_Count (Container : Tree; Parent : Cursor) return Count_Type;
 
-      If Parent is not equal to No_Parent, and does not designate an element in Container, then
-      Program_Error is propagated. If Parent is equal to No_Parent, then Child_Count
-      returns the number of orphan elements in Container (including the designated root
-      element, if any). Otherwise, Child_Count returns the number of child elements of
-      the element designated by Parent.
+      If Parent is not equal to No_Parent, and does not designate an element in
+      Container, then Program_Error is propagated. If Parent is equal to
+      No_Parent, then Child_Count returns the number of orphan elements in
+      Container (including the designated root element, if any). Otherwise,
+      Child_Count returns the number of child elements of the element designated
+      by Parent.
 
    function Child_Depth (Parent, Child : Cursor) return Count_Type;
 
-      If Child is equal to No_Element, then Constraint_Error is propagated. If Child does not
-      designate and element in Container, then Program_Error is propagated. If Parent is not
-      equal to No_Parent, and does not designate an element in Container, then Program_Error
-      is propagated. If Parent is equal to No_Parent, Child_Depth returns the number of
-      ancestor nodes of Child (including Child itself). Otherwise, Child_Depth returns the
-      number of ancestor nodes of Child (including Child itself), up to but not including
-      Parent; in this case Program_Error is propagated if Parent is not an ancestor of Child.
+      If Child is equal to No_Element, then Constraint_Error is propagated. If
+      Child does not designate and element in Container, then Program_Error is
+      propagated. If Parent is not equal to No_Parent, and does not designate an
+      element in Container, then Program_Error is propagated. If Parent is equal
+      to No_Parent, Child_Depth returns the number of ancestor nodes of Child
+      (including Child itself). Otherwise, Child_Depth returns the number of
+      ancestor nodes of Child (including Child itself), up to but not including
+      Parent; in this case Program_Error is propagated if Parent is not an
+      ancestor of Child.
 
    procedure Insert_Child (Container : in out Tree;
                            Parent    : in     Cursor;
@@ -709,17 +746,19 @@
                            New_Item  : in     Element_Type;
                            Count     : in     Count_Type := 1);
 
-      If Parent is not equal to No_Parent, and does not designate an element in Container, then
-      Program_Error is propagated. If Before is not equal to No_Element, and does not designate
-      an element in Container, then Program_Error is propagated. If Before is not equal to
-      No_Element, and Container.Parent (Before) is not equal to Parent, then Constraint_Error
-      is raised. If Parent is equal to No_Parent, Insert_Child inserts Count orphan copies of
-      New_Item prior to the (orphan) element designated by Before. If Before equals No_Element,
-      the new elements are inserted after the last orphan node (if any). Otherwise, Insert_Child
-      inserts Count copies of New_Item as children of Parent prior to the element designated
-      by Before. If Before equals No_Element, the new elements are inserted after the last child
-      node of Parent (if any). Any exception raised during allocation of internal storage is
-      propagated, and Container is not modified.
+      If Parent is not equal to No_Parent, and does not designate an element in
+      Container, then Program_Error is propagated. If Before is not equal to
+      No_Element, and does not designate an element in Container, then
+      Program_Error is propagated. If Before is not equal to No_Element, and
+      Container.Parent (Before) is not equal to Parent, then Constraint_Error is
+      raised. If Parent is equal to No_Parent, Insert_Child inserts Count orphan
+      copies of New_Item prior to the (orphan) element designated by Before. If
+      Before equals No_Element, the new elements are inserted after the last
+      orphan node (if any). Otherwise, Insert_Child inserts Count copies of
+      New_Item as children of Parent prior to the element designated by Before.
+      If Before equals No_Element, the new elements are inserted after the last
+      child node of Parent (if any). Any exception raised during allocation of
+      internal storage is propagated, and Container is not modified.
 
    procedure Insert_Child (Container : in out Tree;
                            Parent    : in     Cursor;
@@ -728,18 +767,20 @@
                            Position  :    out Cursor;
                            Count     : in     Count_Type := 1);
 
-      If Parent is not equal to No_Parent, and does not designate an element in Container, then
-      Program_Error is propagated. If Before is not equal to No_Element, and does not designate
-      an element in Container, then Program_Error is propagated. If Before is not equal to
-      No_Element, and Container.Parent (Before) is not equal to Parent, then Constraint_Error
-      is raised. If Parent is equal to No_Parent, Insert_Child inserts Count orphan copies of
-      New_Item prior to the (orphan) element designated by Before. If Before equals No_Element,
-      the new elements are inserted after the last orphan node (if any). Otherwise, Insert_Child
-      inserts Count copies of New_Item as children of Parent prior to the element designated
-      by Before. If Before equals No_Element, the new elements are inserted after the last child
-      node of Parent (if any). Position designated the first newly-inserted element. Any
-      exception raised during allocation of internal storage is propagated, and Container is
-      not modified.
+      If Parent is not equal to No_Parent, and does not designate an element in
+      Container, then Program_Error is propagated. If Before is not equal to
+      No_Element, and does not designate an element in Container, then
+      Program_Error is propagated. If Before is not equal to No_Element, and
+      Container.Parent (Before) is not equal to Parent, then Constraint_Error is
+      raised. If Parent is equal to No_Parent, Insert_Child inserts Count orphan
+      copies of New_Item prior to the (orphan) element designated by Before. If
+      Before equals No_Element, the new elements are inserted after the last
+      orphan node (if any). Otherwise, Insert_Child inserts Count copies of
+      New_Item as children of Parent prior to the element designated by Before.
+      If Before equals No_Element, the new elements are inserted after the last
+      child node of Parent (if any). Position designated the first
+      newly-inserted element. Any exception raised during allocation of internal
+      storage is propagated, and Container is not modified.
 
    procedure Insert_Child (Container : in out Tree;
                            Parent    : in     Cursor;
@@ -765,60 +806,74 @@
                             New_Item  : in     Element_Type;
                             Count     : in     Count_Type := 1);
 
-      Equivalent to Insert_Child (Container, Parent, First_Child (Container, Parent), New_Item, Count).
+      Equivalent to Insert_Child (Container, Parent, First_Child (Container,
+      Parent), New_Item, Count).
 
    procedure Append_Child (Container : in out Tree;
                            Parent    : in     Cursor;
                            New_Item  : in     Element_Type;
                            Count     : in     Count_Type := 1);
 
-      Equivalent to Insert_Child (Container, Parent, Last_Child (Container, Parent), New_Item, Count).
+      Equivalent to Insert_Child (Container, Parent, Last_Child (Container,
+      Parent), New_Item, Count).
 
    procedure Delete_Child_Subtree (Container : in out Tree;
                                    Parent    : in     Cursor;
                                    Position  : in out Cursor;
                                    Count     : in     Count_Type := 1);
+
+      If Position equals No_Element, then Constraint_Error is propagated. If
+      Position does not designate an element in Container, then Program_Error is
+      propagated. If Parent is not equal to No_Parent, and does not designate an
+      element in Container, then Program_Error is propagated. If Position is not
+      equal to No_Element, and Container.Parent (Position) is not equal to
+      Parent, then Constraint_Error is raised. Otherwise Delete removes (from
+      Container) Count elements and their dependent elements starting at the
+      element designated by Position (or all of the elements starting at
+      Position if there are fewer than Count elements starting at Position).
+      Finally, Position is set to No_Element.
 
-      If Position equals No_Element, then Constraint_Error is propagated. If Position does not
-      designate an element in Container, then Program_Error is propagated. If Parent is not equal
-      to No_Parent, and does not designate an element in Container, then Program_Error is propagated.
-      If Position is not equal to No_Element, and Container.Parent (Position) is not equal to
-      Parent, then Constraint_Error is raised. Otherwise Delete removes (from Container) Count
-      elements and their dependent elements starting at the element designated by Position (or
-      all of the elements starting at Position if there are fewer than Count elements starting at
-      Position). Finally, Position is set to No_Element.
-
-      [Editor's note: The primary difference of this routine is providing of a Count. This allows
-      the deletion of all of the children of a node without having to write a loop with repeated
-      tests. Container.Delete_Child_Subtree (My_Parent, Position => Container.First_Child (My_Parent),
-      Count => 10000); will delete all of the child nodes.
-
-      We don't provide a Delete_Child that only deletes leaf nodes (as we do for the entire
-      container), as that would require pretesting the nodes to verify that they are leaves
-      before doing any deletions, eliminating any performance advantage.]
+      [Editor's note: The primary difference of this routine is providing of a
+      Count. This allows the deletion of all of the children of a node without
+      having to write a loop with repeated tests. Container.Delete_Child_Subtree
+      (My_Parent, Position => Container.First_Child (My_Parent), Count =>
+      10000); will delete all of the child nodes.
+
+      We don't provide a Delete_Child that only deletes leaf nodes (as we do for
+      the entire container), as that would require pretesting the nodes to
+      verify that they are leaves before doing any deletions, eliminating any
+      performance advantage.]
 
    procedure Splice_Subtree (Target   : in out Tree;
                              Parent   : in     Cursor;
                              Before   : in     Cursor;
                              Source   : in out Tree);
 
-      If Parent is not equal to No_Parent, and does not designate an element in Target, then
-      Program_Error is propagated. If Before is not equal to No_Element, and does not designate
-      an element in Target, then Program_Error is propagated. If Before is not equal to
-      No_Element, and Target.Parent (Before) is not equal to Parent, then Constraint_Error
-      is raised. Otherwise, if Source denotes the same object as Target, or if there is no active
-      subtree in Source, the operation has no effect. Otherwise, Splice_Subtree reorders elements
-      such that the active subtree is removed from Source and moved to Target. The subtree is
-      inserted as a child of Parent (or, if Parent is equal to No_Parent, as an orphan subtree)
-      prior to the element designated by Before. If Before equals No_Element, the subtree is
-      inserted after the last child node of Parent (if any), or if Parent is equal to No_Parent,
-      after the last orphan node (if any). The overall count of Target is incremented by
-      Count (Source), and Source is set to have no designated root element.
-
-      AARM Ramification: If Source contains non-root orphan nodes, Overall_Count (Source) may
-      not be zero after this operation, as they are not moved. However, the sum of the
-      overall counts for the source and target before Splice_Subtree will be the same as
-      the sum of the overall counts afterwards.
+      If Parent is not equal to No_Parent, and does not designate an element in
+      Target, then Program_Error is propagated. If Before is not equal to
+      No_Element, and does not designate an element in Target, then
+      Program_Error is propagated. If Before is not equal to No_Element, and
+      Target.Parent (Before) is not equal to Parent, then Constraint_Error is
+      raised. Otherwise, if Source denotes the same object as Target, or if
+      there is no active subtree in Source, the operation has no effect.
+      Otherwise, Splice_Subtree reorders elements such that the active subtree
+      is removed from Source and moved to Target. The subtree is inserted as a
+      child of Parent (or, if Parent is equal to No_Parent, as an orphan
+      subtree) prior to the element designated by Before. If Before equals
+      No_Element, the subtree is inserted after the last child node of Parent
+      (if any), or if Parent is equal to No_Parent, after the last orphan node
+      (if any). The overall count of Target is incremented by Count (Source),
+      and Source is set to have no designated root element.
+
+      AARM Ramification: If Source contains non-root orphan nodes, Overall_Count
+      (Source) may not be zero after this operation, as they are not moved.
+      However, the sum of the overall counts for the source and target before
+      Splice_Subtree will be the same as the sum of the overall counts
+      afterwards.
+
+      [Editor's note: This would naturally be called "Splice_Child", but that
+      name is misleading. I originally used just "Splice", but Matt suggested
+      that "Splice_Subtree" is more evokative of what it does.]
 
    procedure Splice_Subtree (Target   : in out Tree;
                              Parent   : in     Cursor;
@@ -826,47 +881,54 @@
                              Source   : in out Tree;
                              Position : in out Cursor);
 
-      If Position is equal to No_Element then Constraint_Error is propagated. If Parent is not equal
-      to No_Parent, and does not designate an element in Target, then Program_Error is propagated.
-      If Before is not equal to No_Element, and does not designate an element in Target, then
-      Program_Error is propagated. If Position does not equal No_Element, and does not designate
-      a node in Source, then Program_Error is propagated. If Before is not equal to
-      No_Element, and Target.Parent (Before) is not equal to Parent, then Constraint_Error
-      is raised. If Source denotes the same object as Target, then there is no effect if
-      Position equals Before, else the subtree rooted by the element designated by Position is
-      moved immediately prior to Before, or, if Before equals No_Element, after the last child
-      node of Parent (if any) or if Parent is equal to No_Parent, after the last orphan node. In
-      each of these cases, Position and the overall count of Target are unchanged, and the parent
-      of the element designated by Position is set to Parent. 
-
-      Otherwise, the subtree designated by Position is removed from Source and moved to Target.
-      The subtree is inserted as a child of Parent (or, if Parent is equal to No_Parent, as an
-      orphan subtree) prior to the element designated by Before. If Before equals No_Element,
-      the subtree is inserted after the last child node of Parent (if any), or if Parent is equal
-      to No_Parent, after the last orphan node (if any). In each of these cases, the overall
-      count of Target is incremented by Subtree_Count (Position), and overall count of Source is
-      decremented by Subtree_Count (Position), Position is updated to represent an element
-      in Target.
-
-      AARM Ramification: If Source is the same as Target, and Position = Before, or
-      Next_Sibling(Position) = Before, Splice has no effect, as the subtree does not have to move
-      to meet the postcondition. 
+      If Position is equal to No_Element then Constraint_Error is propagated. If
+      Parent is not equal to No_Parent, and does not designate an element in
+      Target, then Program_Error is propagated. If Before is not equal to
+      No_Element, and does not designate an element in Target, then
+      Program_Error is propagated. If Position does not equal No_Element, and
+      does not designate a node in Source, then Program_Error is propagated. If
+      Before is not equal to No_Element, and Target.Parent (Before) is not equal
+      to Parent, then Constraint_Error is raised. If Source denotes the same
+      object as Target, then there is no effect if Position equals Before, else
+      the subtree rooted by the element designated by Position is moved
+      immediately prior to Before, or, if Before equals No_Element, after the
+      last child node of Parent (if any) or if Parent is equal to No_Parent,
+      after the last orphan node. In each of these cases, Position and the
+      overall count of Target are unchanged, and the parent of the element
+      designated by Position is set to Parent.
+
+      Otherwise, the subtree designated by Position is removed from Source and
+      moved to Target. The subtree is inserted as a child of Parent (or, if
+      Parent is equal to No_Parent, as an orphan subtree) prior to the element
+      designated by Before. If Before equals No_Element, the subtree is inserted
+      after the last child node of Parent (if any), or if Parent is equal to
+      No_Parent, after the last orphan node (if any). In each of these cases,
+      the overall count of Target is incremented by Subtree_Count (Position),
+      and overall count of Source is decremented by Subtree_Count (Position),
+      Position is updated to represent an element in Target.
+
+      AARM Ramification: If Source is the same as Target, and Position = Before,
+      or Next_Sibling(Position) = Before, Splice has no effect, as the subtree
+      does not have to move to meet the postcondition.
 
    procedure Splice_Subtree (Container: in out Tree;
                              Parent   : in     Cursor;
                              Before   : in     Cursor;
                              Position : in     Cursor);
 
-      If Position is equal to No_Element then Constraint_Error is propagated. If Parent is not equal
-      to No_Parent, and does not designate an element in Container, then Program_Error is propagated.
-      If Before is not equal to No_Element, and does not designate an element in Container, then
-      Program_Error is propagated. If Position does not equal No_Element, and does not designate
-      a node in Container, then Program_Error is propagated. If Before is not equal to
-      No_Element, and Container.Parent (Before) is not equal to Parent, then Constraint_Error
-      is raised. If Position equals Before there is no effect. Otherwise, the subtree rooted by
-      the element designated by Position is moved immediately prior to Before, or, if Before equals
-      No_Element, after the last child node of Parent (if any) or if Parent is equal to No_Parent,
-      after the last orphan node. The parent of the element designated by Position is set to Parent. 
+      If Position is equal to No_Element then Constraint_Error is propagated. If
+      Parent is not equal to No_Parent, and does not designate an element in
+      Container, then Program_Error is propagated. If Before is not equal to
+      No_Element, and does not designate an element in Container, then
+      Program_Error is propagated. If Position does not equal No_Element, and
+      does not designate a node in Container, then Program_Error is propagated.
+      If Before is not equal to No_Element, and Container.Parent (Before) is not
+      equal to Parent, then Constraint_Error is raised. If Position equals
+      Before there is no effect. Otherwise, the subtree rooted by the element
+      designated by Position is moved immediately prior to Before, or, if Before
+      equals No_Element, after the last child node of Parent (if any) or if
+      Parent is equal to No_Parent, after the last orphan node. The parent of
+      the element designated by Position is set to Parent.
 
    procedure Splice_Children (Target          : in out Tree;
                               Target_Parent   : in     Cursor;
@@ -874,41 +936,47 @@
                               Source          : in out Tree;
                               Source_Parent   : in     Cursor);
 
-      If Target_Parent is not equal to No_Parent, and does not designate an element in Target, then
-      Program_Error is propagated. If Before is not equal to No_Element, and does not
-      designate an element in Target, then Program_Error is propagated. If Source_Parent is not equal
-      to No_Parent, and does not designate an element in Source, then Program_Error is propagated.
-      If Before is not equal to No_Element, and Target.Parent (Before) is not equal to Target_Parent,
-      then Constraint_Error is raised.
+      If Target_Parent is not equal to No_Parent, and does not designate an
+      element in Target, then Program_Error is propagated. If Before is not
+      equal to No_Element, and does not designate an element in Target, then
+      Program_Error is propagated. If Source_Parent is not equal to No_Parent,
+      and does not designate an element in Source, then Program_Error is
+      propagated. If Before is not equal to No_Element, and Target.Parent
+      (Before) is not equal to Target_Parent, then Constraint_Error is raised.
 
       If Source denotes the same object as Target, then:
         * if Target_Parent equals Source_Parent there is no effect; else
-        * if Source_Parent is equal to No_Parent or Source_Parent is an ancestor of Target_Parent,
-          then Constraint_Error is propagated; else
-        * the child elements (and their descendants) of Source_Parent are moved to be child elements
-          of Target_Parent immediately prior to Before, or, if Before equals No_Element, after the
-          last child node of Target_Parent (if any) or if Target_Parent is equal to No_Parent, after
-          the last orphan node. The parent of each moved child element is set to Target_Parent.
-
-      AARM Reason: We can't allow moving the children of Source_Parent to an descendant node, as
-      the descendant node will be part of one of the subtrees being moved.
-
-      Otherwise (if Source does not denote the same object as Target), the child elements (and their
-      descendants) of Source_Parent are removed from Source and moved to Target. If Source_Parent
-      is equal to No_Parent, all of the orphan elements of Source are moved.
-      The child (or orphan) elements are inserted as children of Target_Parent (or, if Target_Parent
-      is equal to No_Parent, as an orphan subtree) prior to the element designated by Before. If
-      Before equals No_Element, the child (or orphan) elements are inserted after the last child
-      node of Target_Parent (if any), or if Parent is equal to No_Parent, after the last orphan
-      node (if any). In each of these cases, the overall count of Target is incremented by
-      Subtree_Count (Source_Parent)-1, and overall count of Source is decremented by
+        * if Source_Parent is equal to No_Parent or Source_Parent is an ancestor
+	  of Target_Parent, then Constraint_Error is propagated; else
+        * the child elements (and their descendants) of Source_Parent are moved
+	  to be child elements of Target_Parent immediately prior to Before, or,
+	  if Before equals No_Element, after the last child node of
+	  Target_Parent (if any) or if Target_Parent is equal to No_Parent,
+	  after the last orphan node. The parent of each moved child element is
+	  set to Target_Parent.
+
+      AARM Reason: We can't allow moving the children of Source_Parent to an
+      descendant node, as the descendant node will be part of one of the
+      subtrees being moved.
+
+      Otherwise (if Source does not denote the same object as Target), the child
+      elements (and their descendants) of Source_Parent are removed from Source
+      and moved to Target. If Source_Parent is equal to No_Parent, all of the
+      orphan elements of Source are moved. The child (or orphan) elements are
+      inserted as children of Target_Parent (or, if Target_Parent is equal to
+      No_Parent, as an orphan subtree) prior to the element designated by
+      Before. If Before equals No_Element, the child (or orphan) elements are
+      inserted after the last child node of Target_Parent (if any), or if Parent
+      is equal to No_Parent, after the last orphan node (if any). In each of
+      these cases, the overall count of Target is incremented by Subtree_Count
+      (Source_Parent)-1, and overall count of Source is decremented by
       Subtree_Count (Source_Parent)-1.
 
-      AARM Ramification: The node designated by Source_Parent is not moved, thus we never need to
-      update Source_Parent.
+      AARM Ramification: The node designated by Source_Parent is not moved, thus
+      we never need to update Source_Parent.
 
-      Move (Target, Source) could be written Splice_Children (Target, No_Parent, No_Element,
-      Source, No_Parent);
+      Move (Target, Source) could be written Splice_Children (Target, No_Parent,
+      No_Element, Source, No_Parent);
       End AARM Ramification.
 
    procedure Splice_Children (Container       : in out Tree;
@@ -916,32 +984,38 @@
                               Before          : in     Cursor;
                               Source_Parent   : in     Cursor);
 
-      If Target_Parent is not equal to No_Parent, and does not designate an element in Container, then
-      Program_Error is propagated. If Before is not equal to No_Element, and does not
-      designate an element in Container, then Program_Error is propagated. If Source_Parent is not equal
-      to No_Parent, and does not designate an element in Container, then Program_Error is propagated.
-      If Before is not equal to No_Element, and Container.Parent (Before) is not equal to Target_Parent,
-      then Constraint_Error is raised. If Target_Parent equals Source_Parent there is no effect.
-      If Source_Parent is equal to No_Parent or Source_Parent is an ancestor of Target_Parent,
-      then Constraint_Error is propagated. Otherwise the child elements (and their descendants) of
-      Source_Parent are moved to be child elements of Target_Parent immediately prior to Before, or,
-      if Before equals No_Element, after the last child node of Target_Parent (if any) or if
-      Target_Parent is equal to No_Parent, after the last orphan node. The parent of each moved child
-      element is set to Target_Parent.
+      If Target_Parent is not equal to No_Parent, and does not designate an
+      element in Container, then Program_Error is propagated. If Before is not
+      equal to No_Element, and does not designate an element in Container, then
+      Program_Error is propagated. If Source_Parent is not equal to No_Parent,
+      and does not designate an element in Container, then Program_Error is
+      propagated. If Before is not equal to No_Element, and Container.Parent
+      (Before) is not equal to Target_Parent, then Constraint_Error is raised.
+      If Target_Parent equals Source_Parent there is no effect. If Source_Parent
+      is equal to No_Parent or Source_Parent is an ancestor of Target_Parent,
+      then Constraint_Error is propagated. Otherwise the child elements (and
+      their descendants) of Source_Parent are moved to be child elements of
+      Target_Parent immediately prior to Before, or, if Before equals
+      No_Element, after the last child node of Target_Parent (if any) or if
+      Target_Parent is equal to No_Parent, after the last orphan node. The
+      parent of each moved child element is set to Target_Parent.
 
    function Parent (Position : Cursor) return Cursor;
 
-      If Position is equal to No_Element then Constraint_Error is propagated. If the element designated
-      by Position is an orphan element, No_Parent is returned. Otherwise, a cursor designating the
-      parent element of the element designated by Position is returned.
+      If Position is equal to No_Element then Constraint_Error is propagated. If
+      the element designated by Position is an orphan element, No_Parent is
+      returned. Otherwise, a cursor designating the parent element of the
+      element designated by Position is returned.
 
    function First_Child (Container : Tree; Parent : Cursor) return Cursor;
 
-      If Parent is not equal to No_Parent, and does not designate an element in Container, then
-      Program_Error is propagated. If Parent is equal to No_Parent, First_Child returns a cursor
-      designating the first orphan element in Container; if there is no such element, No_Element is
-      returned. Otherwise, First_Child returns a cursor designating the first child element of the
-      element designated by Parent; if ther is no such element, No_Element is returned.
+      If Parent is not equal to No_Parent, and does not designate an element in
+      Container, then Program_Error is propagated. If Parent is equal to
+      No_Parent, First_Child returns a cursor designating the first orphan
+      element in Container; if there is no such element, No_Element is returned.
+      Otherwise, First_Child returns a cursor designating the first child
+      element of the element designated by Parent; if ther is no such element,
+      No_Element is returned.
 
    function First_Child_Element (Container : Tree; Parent : Cursor)
       return Element_Type;
@@ -950,11 +1024,13 @@
 
    function Last_Child (Container : Tree; Parent : Cursor) return Cursor;
 
-      If Parent is not equal to No_Parent, and does not designate an element in Container, then
-      Program_Error is propagated. If Parent is equal to No_Parent, Last_Child returns a cursor
-      designating the last orphan element in Container; if there is no such element, No_Element is
-      returned. Otherwise, Last_Child returns a cursor designating the last child element of the
-      element designated by Parent; if there is no such element, No_Element is returned.
+      If Parent is not equal to No_Parent, and does not designate an element in
+      Container, then Program_Error is propagated. If Parent is equal to
+      No_Parent, Last_Child returns a cursor designating the last orphan element
+      in Container; if there is no such element, No_Element is returned.
+      Otherwise, Last_Child returns a cursor designating the last child element
+      of the element designated by Parent; if there is no such element,
+      No_Element is returned.
 
    function Last_Child_Element (Container : Tree; Parent : Cursor)
       return Element_Type;
@@ -963,15 +1039,17 @@
 
    function Next_Sibling (Position : Cursor) return Cursor;
 
-      If Position equals No_Element or designates the last child element of its parent, then
-      Next_Sibling returns the value No_Element. Otherwise, it returns a cursor that designates
-      the successor (with the same parent) of the element designated by Position.
+      If Position equals No_Element or designates the last child element of its
+      parent, then Next_Sibling returns the value No_Element. Otherwise, it
+      returns a cursor that designates the successor (with the same parent) of
+      the element designated by Position.
 
    function Previous_Sibling (Position : Cursor) return Cursor;
 
-      If Position equals No_Element or designates the last child element of its parent, then
-      Next_Sibling returns the value No_Element. Otherwise, it returns a cursor that designates
-      the predecessor (with the same parent) of the element designated by Position.
+      If Position equals No_Element or designates the last child element of its
+      parent, then Next_Sibling returns the value No_Element. Otherwise, it
+      returns a cursor that designates the predecessor (with the same parent) of
+      the element designated by Position.
 
    procedure Next_Sibling (Position : in out Cursor);
 
@@ -986,121 +1064,138 @@
       Parent    : in     Cursor;
       Process   : not null access procedure (Position : in Cursor));
 
-     If Parent is not equal to No_Parent, and does not designate an element in Container, then
-     Program_Error is propagated. 
+      If Parent is not equal to No_Parent, and does not designate an element in
+      Container, then Program_Error is propagated.
 
-     If Parent is equal to No_Parent, Iterate_Children calls Process.all with a cursor that
-     designates each orphan node in Container, starting with the first orphan node and moving
-     the cursor as per the Next_Sibling function. Otherwise, Iterate_Children calls Process.all
-     with a cursor that designates each child node of Parent, starting with the first child node
-     and moving the cursor as per the Next_Sibling function. 
+      If Parent is equal to No_Parent, Iterate_Children calls Process.all with a
+      cursor that designates each orphan node in Container, starting with the
+      first orphan node and moving the cursor as per the Next_Sibling function.
+      Otherwise, Iterate_Children calls Process.all with a cursor that
+      designates each child node of Parent, starting with the first child node
+      and moving the cursor as per the Next_Sibling function.
 
-     Program_Error is propagated if Process.all tampers with the cursors of Container. Any
-     exception raised by Process.all is propagated.
+      Program_Error is propagated if Process.all tampers with the cursors of
+      Container. Any exception raised by Process.all is propagated.
 
    procedure Reverse_Iterate_Children
      (Container : in Tree;
       Parent    : in     Cursor;
       Process   : not null access procedure (Position : in Cursor));
 
-     If Parent is not equal to No_Parent, and does not designate an element in Container, then
-     Program_Error is propagated. 
+      If Parent is not equal to No_Parent, and does not designate an element in
+      Container, then Program_Error is propagated.
 
-     If Parent is equal to No_Parent, Iterate_Children calls Process.all with a cursor that
-     designates each orphan node in Container, starting with the last orphan node and moving
-     the cursor as per the Previous_Sibling function. Otherwise, Iterate_Children calls Process.all
-     with a cursor that designates each child node of Parent, starting with the last child node
-     and moving the cursor as per the Previous_Sibling function. 
+      If Parent is equal to No_Parent, Iterate_Children calls Process.all with a
+      cursor that designates each orphan node in Container, starting with the
+      last orphan node and moving the cursor as per the Previous_Sibling
+      function. Otherwise, Iterate_Children calls Process.all with a cursor that
+      designates each child node of Parent, starting with the last child node
+      and moving the cursor as per the Previous_Sibling function.
 
-     Program_Error is propagated if Process.all tampers with the cursors of Container. Any
-     exception raised by Process.all is propagated.
+      Program_Error is propagated if Process.all tampers with the cursors of
+      Container. Any exception raised by Process.all is propagated.
 
 Bounded (Run-Time) Errors
 
-It is a bounded error for the actual function associated with a generic formal subprogram,
-when called as part of an operation of this package, to tamper with elements of any Tree parameter
-to the operation. Either Program_Error is raised, or the operation works as defined on the value
-of the Tree either prior to, or subsequent to, some or all of the modifications to the Tree.
-
-It is a bounded error to call any subprogram declared in the visible part of Containers.Multiway_Trees
-when the associated container has been finalized. If the operation takes Container as an in out
-parameter, then it raises Constraint_Error or Program_Error. Otherwise, the operation either proceeds
-as it would for an empty container, or it raises Constraint_Error or Program_Error. 
+It is a bounded error for the actual function associated with a generic formal
+subprogram, when called as part of an operation of this package, to tamper with
+elements of any Tree parameter to the operation. Either Program_Error is raised,
+or the operation works as defined on the value of the Tree either prior to, or
+subsequent to, some or all of the modifications to the Tree.
+
+It is a bounded error to call any subprogram declared in the visible part of
+Containers.Multiway_Trees when the associated container has been finalized. If
+the operation takes Container as an in out parameter, then it raises
+Constraint_Error or Program_Error. Otherwise, the operation either proceeds as
+it would for an empty container, or it raises Constraint_Error or Program_Error.
 
+
 Erroneous Execution
 
 A Cursor value is invalid if any of the following have occurred since it was created:
 * The tree that contains the element it designates has been finalized;
 * The tree that contains the element it designates has been used as the Source or Target of a call to Move;
-* A subtree that contains the element it designated has been moved to a different tree by a call to
-  Splice_Children or Splice_Subtree; or 
+* A subtree that contains the element it designated has been moved to a
+  different tree by a call to Splice_Children or Splice_Subtree; or
 * The element it designates has been deleted.
 
-[Editor's note: We have to include moving a subtree to a different container as a cause of invalidating
-a cursor. It appears that the case of a full list splice is missing from the list of A.18.3(153-156),
-as it should invalidate cursors that point into the source list.]
-
-The result of "=" or Has_Element is unspecified if it is called with an invalid cursor parameter.
-Execution is erroneous if any other subprogram declared in Containers.Multiway_Trees is called with an invalid
-cursor parameter.
-
-AARM Discussion: The list above is intended to be exhaustive. In other cases, a cursor value continues
-to designate its original element. For instance, cursor values survive the insertion and deletion of other nodes.
-
-While it is possible to check for these cases, in many cases the overhead necessary to make the check
-is substantial in time or space. Implementations are encouraged to check for as many of these cases as
-possible and raise Program_Error if detected. 
+[Editor's note: We have to include moving a subtree to a different container as
+a cause of invalidating a cursor. It appears that the case of a full list splice
+is missing from the list of A.18.3(153-156), as it should invalidate cursors
+that point into the source list.]
+
+The result of "=" or Has_Element is unspecified if it is called with an invalid
+cursor parameter. Execution is erroneous if any other subprogram declared in
+Containers.Multiway_Trees is called with an invalid cursor parameter.
+
+AARM Discussion: The list above is intended to be exhaustive. In other cases, a
+cursor value continues to designate its original element. For instance, cursor
+values survive the insertion and deletion of other nodes.
+
+While it is possible to check for these cases, in many cases the overhead
+necessary to make the check is substantial in time or space. Implementations are
+encouraged to check for as many of these cases as possible and raise
+Program_Error if detected.
 
 Implementation Requirements
 
-No storage associated with a multiway tree object shall be lost upon assignment or scope exit.
+No storage associated with a multiway tree object shall be lost upon assignment
+or scope exit.
 
-The execution of an assignment_statement for a list shall have the effect of copying the elements from the
-source tree object to the target tree object.
+The execution of an assignment_statement for a list shall have the effect of
+copying the elements from the source tree object to the target tree object.
 
-AARM Implementation Note: An assignment of a Tree is a “deep” copy; that is the elements are copied as well
-as the data structures. We say “effect of” in order to allow the implementation to avoid copying elements
-immediately if it wishes. For instance, an implementation that avoided copying until one of the containers
+AARM Implementation Note: An assignment of a Tree is a "deep" copy; that is the
+elements are copied as well as the data structures. We say "effect of" in order
+to allow the implementation to avoid copying elements immediately if it wishes.
+For instance, an implementation that avoided copying until one of the containers
 is modified would be allowed.
 
 Implementation Advice
-
-Containers.Multiway_Trees should be implemented similarly to a multiway tree. In particular, if N is the
-overall number of nodes for a particular tree, then the worst-case time complexity of Element, Parent,
-First_Child, Last_Child, Insert_Child with Count=1, and Delete should be O(log N).
-
-AARM Reason: We do not mean to overly constrain implementation strategies here. However, it is important for
-portability that the performance of large containers has roughly the same factors on different implementations.
-If a program is moved to an implementation that takes O(N) time to access elements, that program could be
-unusable when the trees are large. We allow O(log N) access because the proportionality constant and
-caching effects are likely to be larger than the log factor, and we don't want to discourage innovative
-implementations. 
-
-Move should not copy elements, and should minimize copying of internal data structures. 
-
-AARM Implementation Note: Usually that can be accomplished simply by moving the pointer(s) to the internal
-data structures from the Source container to the Target container. 
-
-If an exception is propagated from a tree operation, no storage should be lost, nor any elements removed
-from a tree unless specified by the operation. 
 
-AARM Reason: This is important so that programs can recover from errors. But we don't want to require
-heroic efforts, so we just require documentation of cases where this can't be accomplished. 
+Containers.Multiway_Trees should be implemented similarly to a multiway tree. In
+particular, if N is the overall number of nodes for a particular tree, then the
+worst-case time complexity of Element, Parent, First_Child, Last_Child,
+Insert_Child with Count=1, and Delete should be O(log N).
+
+AARM Reason: We do not mean to overly constrain implementation strategies here.
+However, it is important for portability that the performance of large
+containers has roughly the same factors on different implementations. If a
+program is moved to an implementation that takes O(N) time to access elements,
+that program could be unusable when the trees are large. We allow O(log N)
+access because the proportionality constant and caching effects are likely to be
+larger than the log factor, and we don't want to discourage innovative
+implementations.
+
+Move should not copy elements, and should minimize copying of internal data structures.
+
+AARM Implementation Note: Usually that can be accomplished simply by moving the
+pointer(s) to the internal data structures from the Source container to the
+Target container.
+
+If an exception is propagated from a tree operation, no storage should be lost,
+nor any elements removed from a tree unless specified by the operation.
+
+AARM Reason: This is important so that programs can recover from errors. But we
+don't want to require heroic efforts, so we just require documentation of cases
+where this can't be accomplished.
 
 A.18.YY The Package Containers.Indefinite_Multiway_Trees
 
-The language-defined generic package Containers.Indefinite_Multiway_Trees provides private types Tree and
-Cursor, and a set of operations for each type. It provides the same operations and semantics as the
-package Containers.Multiway_Trees (see A.18.xx), with the difference that the generic formal Element_Type
-is indefinite. 
+The language-defined generic package Containers.Indefinite_Multiway_Trees
+provides private types Tree and Cursor, and a set of operations for each type.
+It provides the same operations and semantics as the package
+Containers.Multiway_Trees (see A.18.xx), with the difference that the generic
+formal Element_Type is indefinite.
 
 Static Semantics
 
-The declaration of the generic library package Containers.Indefinite_Multiway_Trees has the same contents as
+The declaration of the generic library package
+Containers.Indefinite_Multiway_Trees has the same contents as
 Containers.Multiway_Trees except:
 
 * The generic formal Element_Type is indefinite.
-* The procedure with the profile: 
+* The procedure with the profile:
    procedure Insert_Child (Container : in out Tree;
                            Parent    : in     Cursor;
                            Before    : in     Cursor;
@@ -1108,14 +1203,16 @@
                            Count     : in     Count_Type := 1);
    is omitted.
 
-AARM Discussion: This procedure is omitted because there is no way to create a default-initialized object
-of an indefinite type. We considered having this routine insert an empty element similar to the empty elements
-of a vector, but rejected this possibility because the semantics are fairly complex and very different
-from the existing case. That would make it more error-prone to convert a container from a definite type to
-an indefinite type; by omitting the routine completely, any problems will be diagnosed by the compiler.
+AARM Discussion: This procedure is omitted because there is no way to create a
+default-initialized object of an indefinite type. We considered having this
+routine insert an empty element similar to the empty elements of a vector, but
+rejected this possibility because the semantics are fairly complex and very
+different from the existing case. That would make it more error-prone to convert
+a container from a definite type to an indefinite type; by omitting the routine
+completely, any problems will be diagnosed by the compiler.
 
-The actual Element parameter of access subprogram Process of Update_Element may be constrained even if
-Element_Type is unconstrained. 
+The actual Element parameter of access subprogram Process of Update_Element may
+be constrained even if Element_Type is unconstrained.
 
 [** TBD** We need to define a bounded form similarly to the ones in AI05-0001-1. Copy the linked list
 to the extent possible.]
@@ -1144,46 +1241,46 @@
 believe that First always represents the first node of the root of the tree.
 
 Having "_Child" as part of the names also opens up the possibility of operations
-not having the "_Child" suffix. These would naturally operate on the entire tree.
-We're taken advantage of this to define operations like Find and Iterate over the
-entire tree.
+not having the "_Child" suffix. These would naturally operate on the entire
+tree. We're taken advantage of this to define operations like Find and Iterate
+over the entire tree.
 
 We've added the suffix "_Subtree" to a few operations to make it clear that they
 operate on entire subtrees, as opposed to a single element. While this isn't
 strictly necessary, it should enhance readability of code.
 
-Elements are stored in internal nodes (as in the linked list container). Nodes which
-do not have parents are called "orphan elements" (or possibly "orphan nodes", if
-we need that terminology in the actual wording. These also form a list of elements,
-and the normal "child" operations can be used on the list of orphan elements. One
-of the orphan elements can be designated the "root" of the tree. Some operations
-operate on the tree that starts at the root, but ignore other orphan elements
-and their children.
-
-Orphan elements allow bottom-up tree creation where subtrees are stashed as orphan
-elements until their parent is created (at which time Slice_Children or Slice_Subtree
-would be used to make it a subtree of the appropriate parent). Without this capability,
-bottom up tree creation would require the creation of many container objects (each
-with overhead) and potentially would require copying of the subtrees and elements
-from one container to another with each step (this is certainly the case for a
-bounded tree container).
+Elements are stored in internal nodes (as in the linked list container). Nodes
+which do not have parents are called "orphan elements" (or possibly "orphan
+nodes", if we need that terminology in the actual wording. These also form a
+list of elements, and the normal "child" operations can be used on the list of
+orphan elements. One of the orphan elements can be designated the "root" of the
+tree. Some operations operate on the tree that starts at the root, but ignore
+other orphan elements and their children.
+
+Orphan elements allow bottom-up tree creation where subtrees are stashed as
+orphan elements until their parent is created (at which time Slice_Children or
+Slice_Subtree would be used to make it a subtree of the appropriate parent).
+Without this capability, bottom up tree creation would require the creation of
+many container objects (each with overhead) and potentially would require
+copying of the subtrees and elements from one container to another with each
+step (this is certainly the case for a bounded tree container).
 
 We considered making the tree multirooted rather than designating a particular
 root node. Some reviewers considered this too weird, in addition, designating a
 particular root node allows elements to be in the container without being in the
 primary tree, which can be useful in some circumstances.
 
-Most operations that act on the entire tree container only act on the active portion
-of the tree (that is the subtree rooted by the designated root element); those
-usually have a counter-part that has the prefix "Overall_" that act on the entire
-container including all orphan subtrees.
+Most operations that act on the entire tree container only act on the active
+portion of the tree (that is the subtree rooted by the designated root element);
+those usually have a counter-part that has the prefix "Overall_" that act on the
+entire container including all orphan subtrees.
 
 Note that we added the Assign and Copy routines here as proposed in AI05-0001-1.
 If we decide not to do that for the other containers, they should be removed
 here as well.
 
-Similarly, we define a bounded form here; in the unlikely event that we decide not
-to adopt AI05-0001-1, it should be removed here.
+Similarly, we define a bounded form here; in the unlikely event that we decide
+not to adopt AI05-0001-1, it should be removed here.
 
 For all of the subprograms that take a Parent parameter, if the parameter is
 No_Element, the node is inserted at the root of the tree. This is consistent
@@ -1194,14 +1291,16 @@
   * Delete_First and Delete_Last: These seem unlikely to occur in the context of
     a tree (as opposed to a sequence like a list), and they're very easy to
     write yourself if necessary. [Editor's Note: Dropping these are all Matt's
-    idea. :-) Since the names aren't the same anyway (they'd be Delete_First_Child
-    and Delete_Last_Child) the consistency argument doesn't seem to hold much water.]
+    idea. :-) Since the names aren't the same anyway (they'd be
+    Delete_First_Child and Delete_Last_Child) the consistency argument doesn't
+    seem to hold much water.]
   * Swap_Links: Swapping within a single sibling list doesn't seem very useful.
-    Swapping such that the parents get changed on the nodes can be a nightmare to
-    describe and implement correctly: consider swapping two nodes where one is the
-    parent of the other, and additional children are also involved. Exactly which
-    elements end up where?? We do provide Swap, which just swaps the elements and
-    leaves the nodes alone; that doesn't have definitional issues.
+    Swapping such that the parents get changed on the nodes can be a nightmare
+    to describe and implement correctly: consider swapping two nodes where one
+    is the parent of the other, and additional children are also involved.
+    Exactly which elements end up where?? We do provide Swap, which just swaps
+    the elements and leaves the nodes alone; that doesn't have definitional
+    issues.
   * Reverse_Find: This is a strange operation, which would be hard to define
     sensibly. Rather, we provide Ancestor_Find, which has a clear definition.
   * Reverse_Elements: This seems like a strange operation operating on a single
@@ -1212,13 +1311,13 @@
 
 
 Note that we left the Container parameter in routines like First_Child, because
-the Parent parameter can be No_Element to represent no parent (an orphan element,
-including the root), and we need to know in which container to look for that
-orphan element. An alternative design would be to have a separate set of routines
-for accessing orphan elements (including the designated root), but that would
-clutter the package and complicate use (a lot of insertion code would have to
-explicitly check to see if it is inserting at the root: a scourge of hand-written
-code that we don't want to duplicate in the containers!).
+the Parent parameter can be No_Element to represent no parent (an orphan
+element, including the root), and we need to know in which container to look for
+that orphan element. An alternative design would be to have a separate set of
+routines for accessing orphan elements (including the designated root), but that
+would clutter the package and complicate use (a lot of insertion code would have
+to explicitly check to see if it is inserting at the root: a scourge of
+hand-written code that we don't want to duplicate in the containers!).
 
 
 More on the orphan/root model:
@@ -1252,9 +1351,9 @@
 specially. This could be very annoying in programs that do bottom-up tree
 construction.
 
-With either model, (individual) operations directly on elements or that
-involve the relationships between elements do not care whether they are operating
-on an orphan subtree or on
+With either model, (individual) operations directly on elements or that involve
+the relationships between elements do not care whether they are operating on an
+orphan subtree or on
 
 
 With the model we selected, most operations do not care if they are working on

Questions? Ask the ACAA Technical Agent