Add order consideration for appending

The existing append method assumes that the order of the existing legend
entries has not been permuted from the plot order of the axes' Children,
and vice-versa. Because of this assumption, the order of the legend
strings can diverge from the axes' Children plot order for reasons that
are not clear to the user. A union of the two object arrays is taken in
order to account for the permutation potential.

A stable union of the legend's PlotChildren and the parent Axes'
Children will return the object handles existing in the legend, in the
order they appear in the legend, followed by the object handles not in
the legend, in the order they are rendered in the parent Axes.

Add warning when more strings are passed to append than there are legend
entries. This warning is consistent with the behavior of legend.

See: #11

Author: sco1

legtools.m

@@ -54,7 +54,24 @@ function append(lh, newStrings)
 
             % Update legend with line object handles & new string array
             newlegendstr = [lh.String newStrings];  % Need to generate this before adding new plot objects
-            lh.PlotChildren = plothandles;
+            
+            % Use the union of the parent axes' Children and the legend
+            % handle's PlotChildren to properly order the legend strings.
+            % Union(A, B, 'Sorted') will return A concatenated with the
+            % values of B not in A, so we have the handles associated with
+            % the existing entries and then the remaining handles in the
+            % order they are plotted.
+            lh.PlotChildren = union(lh.PlotChildren, plothandles, 'stable');
+            
+            if numel(newlegendstr) > numel(lh.PlotChildren)
+                % MATLAB automatically throws out the extra legend entries
+                % if the number of strings to be added is larger than the
+                % number of supported graphics objects that are children of
+                % the parent axes. legend throws a warning in this case and
+                % we should too
+                warning('legtools:append:IgnoringExtraEntries', ...
+                        'Ignoring extra legend entries');
+            end
             lh.String = newlegendstr;
         end