FoldUtilities


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  
20  package org.netbeans.api.editor.fold;
21  
22  import java.util.ArrayList  ;
23  import java.util.Collection  ;
24  import java.util.Collections  ;
25  import java.util.Iterator  ;
26  import java.util.List  ;
27  import org.netbeans.modules.editor.fold.FoldUtilitiesImpl;
28  
29  /**
30   * Various utility methods for dealing with the folds.
31   *
32   * <p>
33   * <b>Note:</b> Until explicitly noted all the utility methods
34   * require a lock to be held on the {@link FoldHierarchy}
35   * during execution of the methods.
36   *
37   * @author Miloslav Metelka
38   * @version 1.00
39   */
40  
41  public final class FoldUtilities {
42  
43      private FoldUtilities() {
44          // No instances
45      }
46      
47      /**
48       * Is the given fold a root fold?
49       *
50       * @param fold non-null fold which is either root fold or a regular fold.
51       * @return true if the given fold is root fold or false otherwise.
52       */
53      public static boolean isRootFold(Fold fold) {
54          return fold.isRootFold();
55      }
56      
57      /**
58       * Find index of the child of the given fold that 
59       * starts right at or below the given offset.
60       *
61       * <p>
62       * This method uses binary search and has log2(n) performance
63       * where n is number of children of the given fold.
64       * <br>
65       * The efficiency may drop to linear if there would be many empty folds
66       * at the given offset.
67       *
68       * @param fold fold which children will be inspected.
69       * @param offset &gt;=0 offset in the document for which the representing
70       *  child will be searched.
71       * @return index of the child fold that represents the given offset.
72       *  <br>
73       *  An <code>index</code> is returned
74       *    if <code>offset &gt;= getFold(index).getStartOffset()</code>
75       *    and <code>offset &lt;= getFold(index + 1).getStartOffset()</code>.
76       *  <br>
77       *  <code>-1</code> is returned
78       *    if <code>offset &lt; getFold(0).getStartOffset()</code>
79       *    and in case the fold does not have any children.
80       */
81       public static int findFoldStartIndex(Fold fold, int offset) {
82           // The empty folds should be removed immediately (prior to notification
83           // to managers) so the "first" param should not matter
84           return FoldUtilitiesImpl.findFoldStartIndex(fold, offset, true);
85       }
86       
87      /**
88       * Find index of the first child of the given fold that ends
89       * above the given offset ("contains" the offset).
90       *
91       * <p>
92       * This method uses binary search and has log2(n) performance
93       * where n is number of children of the given fold.
94       * <br>
95       * The efficiency may drop to linear if there would be many empty folds
96       * at the given offset.
97       *
98       * @param fold fold which children will be inspected.
99       * @param offset &gt;=0 offset in the document for which the representing
100      *  child will be searched.
101      * @return index of the child fold that contains or is above the given offset.
102      *  <br>
103      *  A highest <code>index</code> is returned for which
104      *    <code>offset &lt; getFold(index).getEndOffset()</code>
105      *  <br>
106      *  or <code>fold.getFoldCount()</code> in case there is no such fold.
107      */
108      public static int findFoldEndIndex(Fold fold, int offset) {
109          return FoldUtilitiesImpl.findFoldEndIndex(fold, offset);
110      }
111      
112      /**
113       * Check whether the starting offset of the fold is the same like
114       * its ending offset.
115       *
116       * @param fold fold that should be checked whether it's empty.
117       * @return true if the fold is empty or false otherwise.
118       */
119      public static boolean isEmpty(Fold fold) {
120          return (fold.getStartOffset() == fold.getEndOffset());
121      }
122     
123     /**
124      * Collapse all folds in the hierarchy.
125      * <br>
126      * This method does the necessary locking of the document and hierarchy.
127      * 
128      * @param hierarchy hierarchy under which all folds should be collapsed.
129      */
130     public static void collapseAll(FoldHierarchy hierarchy) {
131         collapse(hierarchy, (Collection  )null);
132     }
133 
134     /**
135      * Collapse all folds of the given type.
136      * <br>
137      * This method does the necessary locking of the document and hierarchy.
138      * 
139      * @param hierarchy hierarchy under which the folds should be collapsed.
140      * @param type folds with this type will be collapsed.
141      */
142     public static void collapse(FoldHierarchy hierarchy, FoldType type) {
143         collapse(hierarchy, Collections.singleton(type));
144     }
145 
146     /**
147      * Collapse all folds that having any
148      * of the fold types in the given collection.
149      * <br>
150      * This method does the necessary locking of the document and hierarchy.
151      * 
152      * @param hierarchy hierarchy under which the folds should be collapsed.
153      * @param foldTypes collection of fold types to search for.
154      */
155     public static void collapse(FoldHierarchy hierarchy, Collection   foldTypes) {
156         FoldUtilitiesImpl.collapseOrExpand(hierarchy, foldTypes, true);
157     }
158 
159     /**
160      * Expand all folds in the hierarchy.
161      * <br>
162      * This method does the necessary locking of the document and hierarchy.
163      * 
164      * @param hierarchy hierarchy under which all folds should be expanded.
165      */
166     public static void expandAll(FoldHierarchy hierarchy) {
167         expand(hierarchy, (Collection  )null);
168     }
169 
170     /**
171      * Expand all folds of the given type.
172      * <br>
173      * This method does the necessary locking of the document and hierarchy.
174      * 
175      * @param hierarchy hierarchy under which the folds should be expanded.
176      * @param type folds with this type will be expanded.
177      */
178     public static void expand(FoldHierarchy hierarchy, FoldType type) {
179         expand(hierarchy, Collections.singleton(type));
180     }
181 
182     /**
183      * Expand all folds of the given type (or all folds if the type is null)
184      * found in the whole fold hierarchy.
185      * <br>
186      * This method does the necessary locking of the document and hierarchy.
187      * 
188      * @param hierarchy hierarchy under which the folds should be expanded.
189      * @param foldTypes collection of fold types to search for.
190      */
191     public static void expand(FoldHierarchy hierarchy, Collection   foldTypes) {
192         FoldUtilitiesImpl.collapseOrExpand(hierarchy, foldTypes, false);
193     }
194 
195     /**
196      * Check whether fold contains the given offset.
197      *
198      * @param fold fold to be tested for containing the given offset
199      * @param offset that will be tested for being contained in the given fold.
200      * @return true if <code>offset &gt;= fold.getStartOffset()
201      *  &amp;&amp; offset &lt; fold.getEndOffset()</code>
202      */
203     public static boolean containsOffset(Fold fold, int offset) {
204         return (offset < fold.getEndOffset() && offset >= fold.getStartOffset());
205     }
206     
207     /**
208      * Return children of the given fold as array.
209      *
210      * @param fold fold which children will be returned.
211      * @return non-null array of all child folds.
212      */
213     public static Fold[] childrenToArray(Fold fold) {
214         return childrenToArray(fold, 0, fold.getFoldCount());
215     }
216 
217     /**
218      * Return children of the given fold as array.
219      *
220      * @param fold fold which children will be returned.
221      * @param index &gt;=0 index of the first child to be returned.
222      * @param count &gt;=0 number of children to be returned.
223      *  <code>index + count &lt;= {@link Fold#getFoldCount()}</code>.
224      * @return non-null array of selected child folds.
225      */
226     public static Fold[] childrenToArray(Fold fold, int index, int count) {
227         return fold.foldsToArray(index, count);
228     }
229     
230     /**
231      * Return children of the given fold as modifiable list.
232      * <br>
233      * {@link #findRecursive(Fold)} can be used
234      * to collect children recursively.
235      *
236      * @param fold fold which children will be returned.
237      * @return non-null modifiable list of all child folds.
238      */
239     public static List   childrenAsList(Fold fold) {
240         return childrenAsList(fold, 0, fold.getFoldCount());
241     }
242     
243     /**
244      * Return children of the given fold as list.
245      *
246      * @param fold fold which children will be returned.
247      * @param index &gt;=0 index of the first child to be returned.
248      * @param count &gt;=0 number of children to be returned.
249      *  <code>index + count &lt;= {@link Fold#getFoldCount()}</code>.
250      * @return non-null list of selected child folds.
251      *  <br>
252      *  The list can potentially be further modified by the caller without
253      *  any effect on the fold hierarchy.
254      */
255     public static List   childrenAsList(Fold fold, int index, int count) {
256         return FoldUtilitiesImpl.childrenAsList(fold, index, count);
257     }
258     
259     /**
260      * Find direct subfolds of the given fold having certain type.
261      * <br>
262      * Complexity corresponds to number of direct child folds under the given fold.
263      *
264      * @param fold direct children of this fold will be searched.
265      *  The search is *not* recursive in grandchildren etc.
266      * @param foldType non-null fold type to search for.
267      * @return non-null list of folds matching the criteria.
268      *  <br>
269      *  The list can potentially be further modified by the caller without
270      *  any effect on the fold hierarchy.
271      */
272     public static List   find(Fold fold, FoldType foldType) {
273         return find(fold, Collections.singletonList(foldType));
274     }
275     
276     /**
277      * Find direct subfolds of the given fold having any
278      * of the fold types in the given collection.
279      * <br>
280      * Complexity corresponds to number of direct child folds under the given fold.
281      *
282      * @param fold direct children of this fold will be searched.
283      *  The search is *not* recursive in grandchildren etc.
284      * @param foldTypes collection of fold types to search for.
285      * @return non-null list of folds matching the criteria.
286      *  <br>
287      *  The list can potentially be further modified by the caller without
288      *  any effect on the fold hierarchy.
289      */
290     public static List   find(Fold fold, Collection   foldTypes) {
291         return FoldUtilitiesImpl.find(fold, foldTypes);
292     }
293     
294     /**
295      * Collect all children of the given fold recursively.
296      * <br>
297      * Complexity corresponds to number of all child folds
298      * (including grandchildren etc.) under the given fold.
299      *
300      * @param fold all children of this fold will be collected.
301      * @return non-null list of folds matching the criteria.
302      *  <br>
303      *  The list can potentially be further modified by the caller without
304      *  any effect on the fold hierarchy.
305      */
306     public static List   findRecursive(Fold fold) {
307         return findRecursive(fold, (Collection  )null);
308     }
309     
310     /**
311      * Recursively find any subfolds of the given fold having certain type.
312      * <br>
313      * Complexity corresponds to number of all child folds
314      * (including grandchildren etc.) under the given fold.
315      *
316      * @param fold all children of this fold will be searched.
317      *  The search is recursive into grandchildren etc.
318      * @param foldType non-null fold type to search for.
319      * @return non-null list of folds matching the criteria.
320      *  <br>
321      *  The list can potentially be further modified by the caller without
322      *  any effect on the fold hierarchy.
323      */
324     public static List   findRecursive(Fold fold, FoldType foldType) {
325         return findRecursive(fold, Collections.singletonList(foldType));
326     }
327     
328     /**
329      * Recursively find any subfolds of the given fold having any
330      * of the fold types in the given collection.
331      * <br>
332      * Complexity corresponds to number of all child folds
333      * (including grandchildren etc.) under the given fold.
334      *
335      * @param fold all children of this fold will be searched.
336      *  The search is recursive into grandchildren etc.
337      * @param foldTypes collection of fold types to search for.
338      * @return non-null list of folds matching the criteria.
339      *  <br>
340      *  The list can potentially be further modified by the caller without
341      *  any effect on the fold hierarchy.
342      */
343     public static List   findRecursive(Fold fold, Collection   foldTypes) {
344         return FoldUtilitiesImpl.findRecursive(null, fold, foldTypes);
345     }
346     
347     /**
348      * Find nearest fold that either starts right at or follows
349      * the given offset.
350      * <br>
351      * The search deep-dives into hierarchy.
352      * 
353      * @param offset &gt=0 offset in a document.
354      * @return fold in the hierarchy that starts directly at the offset or follows it.
355      *  The most important is the lowest distance of the start of the fold
356      *  to the given offset. If there would be a nearest fold having a first child that
357      *  starts at the same position like the parent
358      *  then the parent would be returned.
359      */
360     public static Fold findNearestFold(FoldHierarchy hierarchy, int offset) {
361         return FoldUtilitiesImpl.findNearestFold(hierarchy, offset, Integer.MAX_VALUE);
362     }
363     
364     /** 
365      * Find a deepest fold in the hierarchy which contains the offset
366      * or has it as one of its boundaries.
367      * <br>
368      * The search deep-dives into hierarchy.
369      *
370      * @param offset &gt=0 offset in a document.
371      * @return deepset fold in the hierarchy satisfying
372      *  <code>fold.getStartOffset() >= offset && offset <= fold.getEndOffset()</code>
373      *  or null if there is no such fold (except the root fold) satisfying the condition.
374      *  <br>
375      *  For two consecutive folds (one ending at the offset and the next one
376      *  starting at the offset) the latter fold would be returned.
377      */
378     public static Fold findOffsetFold(FoldHierarchy hierarchy, int offset) {
379         return FoldUtilitiesImpl.findOffsetFold(hierarchy, offset);
380     }
381 
382     /**
383      * Find the first collapsed fold (deep-diving into the hierarchy)
384      * in the requested boundaries.
385      *
386      * @param hierarchy hierarchy in which to search.
387      * @param startOffset &gt;=0 only fold ending above it will be returned.
388      * @param endOffset &gt;=0 only fold starting below it will be returned.
389      * @return collapsed fold satisfying
390      *  <code>fold.getEndOffset() > startOffset and fold.getStartOffset() < endOffset</code>
391      *  or null if such fold does not exist.
392      */
393     public static Fold findCollapsedFold(FoldHierarchy hierarchy,
394     int startOffset, int endOffset) {
395 
396         return FoldUtilitiesImpl.findFirstCollapsedFold(hierarchy, startOffset, endOffset);
397     }
398 
399     /**
400      * Get iterator over the collapsed folds.
401      *
402      * @param hierarchy hierarchy in which to search.
403      * @param startOffset &gt;=0 only folds ending above it will be returned.
404      * @param endOffset &gt;=0 only folds starting before it will be returned.
405      * @return iterator over collapsed folds satisfying
406      *  <code>fold.getEndOffset() > startOffset and fold.getStartOffset() < endOffset</code>
407      *  <br>
408      *  If a particular collapsed fold gets returned then its children
409      *  are not deep-dived for collapsed folds. Instead the search continues
410      *  by a following sibling.
411      */
412     public static Iterator   collapsedFoldIterator(FoldHierarchy hierarchy,
413     int startOffset, int endOffset) {
414 
415         return FoldUtilitiesImpl.collapsedFoldIterator(hierarchy, startOffset, endOffset);
416     }
417     
418 }
419
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags