## org.apache.lucene.facet.taxonomy
Class CategoryPath

    java.lang.Object
      org.apache.lucene.facet.taxonomy.CategoryPath

All Implemented Interfaces:
  Serializable, Cloneable, Comparable<CategoryPath>

    public class CategoryPath

extends Object
implements Serializable, Cloneable, Comparable<CategoryPath>

A CategoryPath holds a sequence of string components, specifying the hierarchical name of a category.

CategoryPath is designed to reduce the number of object allocations, in two ways: First, it keeps the components internally in two arrays, rather than keeping individual strings. Second, it allows reusing the same CategoryPath object (which can be clear()ed and new components add()ed again) and of add()'s parameter (which can be a reusable object, not just a string).

See Also:
  Serialized Form
WARNING: This API is experimental and might change in incompatible ways in the next release.

Field Summary
`protected char[]` `chars`
`protected short[]` `ends`
`protected short` `ncomponents`

Constructor Summary
`CategoryPath()` Create an empty CategoryPath object.
`CategoryPath(CategoryPath existing)` Construct a new CategoryPath object, copying the path given in an existing CategoryPath object.
`CategoryPath(CategoryPath existing, int prefixLen)` Construct a new CategoryPath object, copying a prefix with the given number of components of the path given in an existing CategoryPath object.
`CategoryPath(CharSequence... components)` Construct a new CategoryPath object, copying an existing path given as an array of strings.
`CategoryPath(int capacityChars, int capacityComponents)` Construct a new empty CategoryPath object.
`CategoryPath(String pathString, char delimiter)` Construct a new CategoryPath object, given a single string with components separated by a given delimiter character.

Method Summary
`void` `add(CharSequence component)` Add the given component to the end of the path.
`void` `add(CharSequence pathString, char delimiter)` Add the given components to the end of the path.
`void` `appendTo(Appendable out, char delimiter)` Build a string representation of the path, with its components separated by the given delimiter character.
`void` `appendTo(Appendable out, char delimiter, int prefixLen)` like `appendTo(Appendable, char)`, but takes only a prefix of the path, rather than the whole path.
`void` `appendTo(Appendable out, char delimiter, int start, int end)` like `appendTo(Appendable, char)`, but takes only a part of the path, rather than the whole path.
`int` `capacityChars()` Returns the current character capacity of the CategoryPath.
`int` `capacityComponents()` Returns the current component capacity of the CategoryPath.
`int` `charsNeededForFullPath()` Returns the number of characters required to represent this entire category path, if written using `copyToCharArray(char[], int, int, char)` or `appendTo(Appendable, char)`.
`void` `clear()` Empty the CategoryPath object, so that it has zero components.
`Object` `clone()`
`int` `compareTo(CategoryPath other)` Compares this CategoryPath with the other CategoryPath for lexicographic order.
`int` `copyToCharArray(char[] outputBuffer, int outputBufferStart, int numberOfComponentsToCopy, char separatorChar)` Copies the specified number of components from this category path to the specified character array, with the components separated by a given delimiter character.
`void` `deserializeFromStreamReader(InputStreamReader isr)` Serializes the content of this CategoryPath to a byte stream, using UTF-8 encoding to convert characters to bytes, and treating the ends as 16-bit characters.
`boolean` `equals(Object obj)` Compare the given CategoryPath to another one.
`boolean` `equalsToSerialized(CharSequence buffer, int offset)` Check whether the current path is identical to the one serialized (with `serializeAppendTo(Appendable)`) in the given buffer, at the given offset.
`boolean` `equalsToSerialized(int prefixLen, CharSequence buffer, int offset)` Just like `equalsToSerialized(CharSequence, int)`, but compare to a prefix of the CategoryPath, instead of the whole CategoryPath.
`String` `getComponent(int i)` Return the i'th component of the path, in a new String object.
`int` `hashCode()` Calculate a hashCode for this path, used when a CategoryPath serves as a hash-table key.
`int` `hashCode(int prefixLen)` Like `hashCode()`, but find the hash function of a prefix with the given number of components, rather than of the entire path.
`static int` `hashCodeOfSerialized(CharSequence buffer, int offset)` This method calculates a hash function of a path that has been written to (using `serializeAppendTo(Appendable)`) a character buffer.
`boolean` `isDescendantOf(CategoryPath other)` Test whether this object is a descendant of another CategoryPath.
`String` `lastComponent()` Return the last component of the path, in a new String object.
`short` `length()` Return the number of components in the facet path.
`long` `longHashCode()` Calculate a 64-bit hash function for this path.
`long` `longHashCode(int prefixLen)` Like `longHashCode()`, but find the hash function of a prefix with the given number of components, rather than of the entire path.
`void` `serializeAppendTo(Appendable out)` Write out a serialized (as a character sequence) representation of the path to a given Appendable (e.g., a StringBuilder, CharBuffer, Writer, or something similar.
`void` `serializeAppendTo(int prefixLen, Appendable out)` Just like `serializeAppendTo(Appendable)`, but writes only a prefix of the CategoryPath.
`void` `serializeToStreamWriter(OutputStreamWriter osw)` Serializes the content of this CategoryPath to a byte stream, using UTF-8 encoding to convert characters to bytes, and treating the ends as 16-bit characters.
`int` `setFromSerialized(CharSequence buffer, int offset)` Set a CategoryPath from a character-sequence representation written by `serializeAppendTo(Appendable)`.
`String` `toString()` This method, an implementation of the `Object.toString()` interface, is to allow simple printing of a CategoryPath, for debugging purposes.
`String` `toString(char delimiter)` Build a string representation of the path, with its components separated by the given delimiter character.
`String` `toString(char delimiter, int prefixLen)` like `toString(char)`, but takes only a prefix with a given number of components, rather than the whole path.
`String` `toString(char delimiter, int start, int end)` like `toString(char)`, but takes only a part of the path, rather than the whole path.
`void` `trim(int nTrim)` Trim the last components from the path.

Methods inherited from class java.lang.Object
`finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### chars

    protected char[] chars

### ends

    protected short[] ends

### ncomponents

    protected short ncomponents

Constructor Detail

### CategoryPath

    public CategoryPath(int capacityChars,
                        int capacityComponents)

  Construct a new empty CategoryPath object. CategoryPath objects are meant to be reused, by add()ing components, and later clear()ing, and add()ing components again. The CategoryPath object is created with a buffer pre-allocated for a given number of characters and components, but the buffer will grow as necessary (see `capacityChars()` and `capacityComponents()`).

### CategoryPath

    public CategoryPath()

  Create an empty CategoryPath object. Equivalent to the constructor `CategoryPath(int, int)` with the two initial-capacity arguments set to zero.

### CategoryPath

    public CategoryPath(String pathString,
                        char delimiter)

  Construct a new CategoryPath object, given a single string with components separated by a given delimiter character.

  The initial capacity of the constructed object will be exactly what is needed to hold the given path. This fact is convenient when creating a temporary object that will not be reused later.

### CategoryPath

    public CategoryPath(CharSequence... components)

  Construct a new CategoryPath object, copying an existing path given as an array of strings.

  The new object occupies exactly the space it needs, without any spare capacity. This is the expected behavior in the typical use case, where this constructor is used to create a temporary object which is never reused.

### CategoryPath

    public CategoryPath(CategoryPath existing)

  Construct a new CategoryPath object, copying the path given in an existing CategoryPath object.

  This copy-constructor is handy when you need to save a reference to a CategoryPath (e.g., when it serves as a key to a hash-table), but cannot save a reference to the original object because its contents can be changed later by the user. Copying the contents into a new object is a solution.

  This constructor does not copy the capacity (spare buffer size) of the existing CategoryPath. Rather, the new object occupies exactly the space it needs, without any spare. This is the expected behavior in the typical use case outlined in the previous paragraph.

### CategoryPath

    public CategoryPath(CategoryPath existing,
                        int prefixLen)

  Construct a new CategoryPath object, copying a prefix with the given number of components of the path given in an existing CategoryPath object.

  If the given length is negative or bigger than the given path's actual length, the full path is taken.

  This constructor is often convenient for creating a temporary object with a path's prefix, but this practice is wasteful, and therefore inadvisable. Rather, the application should be written in a way that allows considering only a prefix of a given path, without needing to make a copy of that path.

Method Detail

### length

    public short length()

  Return the number of components in the facet path. Note that this is not the number of characters, but the number of components.

### trim

    public void trim(int nTrim)

  Trim the last components from the path.

  Parameters:
    `nTrim` - Number of components to trim. If larger than the number of components this path has, the entire path will be cleared.

### capacityChars

    public int capacityChars()

  Returns the current character capacity of the CategoryPath. The character capacity is the size of the internal buffer used to hold the characters of all the path's components. When a component is added and the capacity is not big enough, the buffer is automatically grown, and capacityChars() increases.

### capacityComponents

    public int capacityComponents()

  Returns the current component capacity of the CategoryPath. The component capacity is the maximum number of components that the internal buffer can currently hold. When a component is added beyond this capacity, the buffer is automatically grown, and capacityComponents() increases.

### add

    public void add(CharSequence component)

  Add the given component to the end of the path.

  Note that when a String object is passed to this method, a reference to it is not saved (rather, its content is copied), which will lead to that String object being gc'ed. To reduce the number of garbage objects, you can pass a mutable CharBuffer instead of an immutable String to this method.

### clear

    public void clear()

  Empty the CategoryPath object, so that it has zero components. The capacity of the object (see `capacityChars()` and `capacityComponents()`) is not reduced, so that the object can be reused without frequent reallocations.

### appendTo

    public void appendTo(Appendable out,
                         char delimiter)
                  throws IOException

  Build a string representation of the path, with its components separated by the given delimiter character. The resulting string is appended to a given Appendable, e.g., a StringBuilder, CharBuffer or Writer.

  Note that the two cases of zero components and one component with zero length produce indistinguishable results (both of them append nothing). This is normally not a problem, because components should not normally have zero lengths.

  An IOException can be thrown if the given Appendable's append() throws this exception.

  Throws:
    `IOException`

### appendTo

    public void appendTo(Appendable out,
                         char delimiter,
                         int prefixLen)
                  throws IOException

  like `appendTo(Appendable, char)`, but takes only a prefix of the path, rather than the whole path.

  If the given prefix length is negative or bigger than the path's actual length, the whole path is taken.

  Throws:
    `IOException`

### appendTo

    public void appendTo(Appendable out,
                         char delimiter,
                         int start,
                         int end)
                  throws IOException

  like `appendTo(Appendable, char)`, but takes only a part of the path, rather than the whole path.

  `start` specifies the first component in the subpath, and `end` is one past the last component. If `start` is negative, 0 is assumed, and if `end` is negative or past the end of the path, the path is taken until the end. Otherwise, if `end<=start`, nothing is appended. Nothing is appended also in the case that the path is empty.

  Throws:
    `IOException`

### toString

    public String toString(char delimiter)

  Build a string representation of the path, with its components separated by the given delimiter character. The resulting string is returned as a new String object. To avoid this temporary object creation, consider using `appendTo(Appendable, char)` instead.

  Note that the two cases of zero components and one component with zero length produce indistinguishable results (both of them return an empty string). This is normally not a problem, because components should not normally have zero lengths.

### toString

    public String toString()

  This method, an implementation of the `Object.toString()` interface, is to allow simple printing of a CategoryPath, for debugging purposes. When possible, it recommended to avoid using it it, and rather, if you want to output the path with its components separated by a delimiter character, specify the delimiter explicitly, with `toString(char)`.

  Overrides:
    `toString` in class `Object`

### toString

    public String toString(char delimiter,
                           int prefixLen)

  like `toString(char)`, but takes only a prefix with a given number of components, rather than the whole path.

  If the given length is negative or bigger than the path's actual length, the whole path is taken.

### toString

    public String toString(char delimiter,
                           int start,
                           int end)

  like `toString(char)`, but takes only a part of the path, rather than the whole path.

  `start` specifies the first component in the subpath, and `end` is one past the last component. If `start` is negative, 0 is assumed, and if `end` is negative or past the end of the path, the path is taken until the end. Otherwise, if `end<=start`, an empty string is returned. An emptry string is returned also in the case that the path is empty.

### getComponent

    public String getComponent(int i)

  Return the i'th component of the path, in a new String object. If there is no i'th component, a null is returned.

### lastComponent

    public String lastComponent()

  Return the last component of the path, in a new String object. If the path is empty, a null is returned.

### copyToCharArray

    public int copyToCharArray(char[] outputBuffer,
                               int outputBufferStart,
                               int numberOfComponentsToCopy,
                               char separatorChar)

  Copies the specified number of components from this category path to the specified character array, with the components separated by a given delimiter character. The array must be large enough to hold the components and separators - the amount of needed space can be calculated with `charsNeededForFullPath()`.

  This method returns the number of characters written to the array.

  Parameters:
    `outputBuffer` - The destination character array.
    `outputBufferStart` - The first location to write in the output array.
    `numberOfComponentsToCopy` - The number of path components to write to the destination buffer.
    `separatorChar` - The separator inserted between every pair of path components in the output buffer.
  See Also:
    `charsNeededForFullPath()`

### charsNeededForFullPath

    public int charsNeededForFullPath()

  Returns the number of characters required to represent this entire category path, if written using `copyToCharArray(char[], int, int, char)` or `appendTo(Appendable, char)`. This includes the number of characters in all the components, plus the number of separators between them (each one character in the aforementioned methods).

### add

    public void add(CharSequence pathString,
                    char delimiter)

  Add the given components to the end of the path. The components are given in a single string, separated by a given delimiter character. If the given string is empty, it is assumed to refer to the root (empty) category, and nothing is added to the path (rather than adding a single empty component).

  Note that when a String object is passed to this method, a reference to it is not saved (rather, its content is copied), which will lead to that String object being gc'ed. To reduce the number of garbage objects, you can pass a mutable CharBuffer instead of an immutable String to this method.

### clone

    public Object clone()

  Overrides:
    `clone` in class `Object`

### equals

    public boolean equals(Object obj)

  Compare the given CategoryPath to another one. For two category paths to be considered equal, only the path they contain needs to be identical The unused capacity of the objects is not considered in the comparison.

  Overrides:
    `equals` in class `Object`

### isDescendantOf

    public boolean isDescendantOf(CategoryPath other)

  Test whether this object is a descendant of another CategoryPath. This is true if the other CategoryPath is the prefix of this.

### hashCode

    public int hashCode()

  Calculate a hashCode for this path, used when a CategoryPath serves as a hash-table key. If two objects are equal(), their hashCodes need to be equal, so like in equal(), hashCode does not consider unused portions of the internal buffers in its calculation.

  The hash function used is modeled after Java's String.hashCode() - a simple multiplicative hash function with the multiplier 31. The same hash function also appeared in Kernighan & Ritchie's second edition of "The C Programming Language" (1988).

  Overrides:
    `hashCode` in class `Object`

### hashCode

    public int hashCode(int prefixLen)

  Like `hashCode()`, but find the hash function of a prefix with the given number of components, rather than of the entire path.

### longHashCode

    public long longHashCode()

  Calculate a 64-bit hash function for this path. Unlike `hashCode()`, this method is not part of the Java standard, and is only used if explicitly called by the user.

  If two objects are equal(), their hash codes need to be equal, so like in `equals(Object)`, longHashCode does not consider unused portions of the internal buffers in its calculation.

  The hash function used is a simple multiplicative hash function, with the multiplier 65599. While Java's standard multiplier 31 (used in `hashCode()`) gives a good distribution for ASCII strings, it turns out that for foreign-language strings (with 16-bit characters) it gives too many collisions, and a bigger multiplier produces fewer collisions in this case.

### longHashCode

    public long longHashCode(int prefixLen)

  Like `longHashCode()`, but find the hash function of a prefix with the given number of components, rather than of the entire path.

### serializeAppendTo

    public void serializeAppendTo(Appendable out)
                           throws IOException

  Write out a serialized (as a character sequence) representation of the path to a given Appendable (e.g., a StringBuilder, CharBuffer, Writer, or something similar.

  This method may throw a IOException if the given Appendable threw this exception while appending.

  Throws:
    `IOException`

### serializeAppendTo

    public void serializeAppendTo(int prefixLen,
                                  Appendable out)
                           throws IOException

  Just like `serializeAppendTo(Appendable)`, but writes only a prefix of the CategoryPath.

  Throws:
    `IOException`

### setFromSerialized

    public int setFromSerialized(CharSequence buffer,
                                 int offset)

  Set a CategoryPath from a character-sequence representation written by `serializeAppendTo(Appendable)`.

  Reading starts at the given offset into the given character sequence, and the offset right after the end of this path is returned.

### equalsToSerialized

    public boolean equalsToSerialized(CharSequence buffer,
                                      int offset)

  Check whether the current path is identical to the one serialized (with `serializeAppendTo(Appendable)`) in the given buffer, at the given offset.

### equalsToSerialized

    public boolean equalsToSerialized(int prefixLen,
                                      CharSequence buffer,
                                      int offset)

  Just like `equalsToSerialized(CharSequence, int)`, but compare to a prefix of the CategoryPath, instead of the whole CategoryPath.

### hashCodeOfSerialized

    public static int hashCodeOfSerialized(CharSequence buffer,
                                           int offset)

  This method calculates a hash function of a path that has been written to (using `serializeAppendTo(Appendable)`) a character buffer. It is guaranteed that the value returned is identical to that which `hashCode()` would have produced for the original object before it was serialized.

### serializeToStreamWriter

    public void serializeToStreamWriter(OutputStreamWriter osw)
                                 throws IOException

  Serializes the content of this CategoryPath to a byte stream, using UTF-8 encoding to convert characters to bytes, and treating the ends as 16-bit characters.

  Parameters:
    `osw` - The output byte stream.
  Throws:
    `IOException` - If there are encoding errors.

### deserializeFromStreamReader

    public void deserializeFromStreamReader(InputStreamReader isr)
                                     throws IOException

  Serializes the content of this CategoryPath to a byte stream, using UTF-8 encoding to convert characters to bytes, and treating the ends as 16-bit characters.

  Parameters:
    `isr` - The input stream.
  Throws:
    `IOException` - If there are encoding errors.

### compareTo

    public int compareTo(CategoryPath other)

  Compares this CategoryPath with the other CategoryPath for lexicographic order. Returns a negative integer, zero, or a positive integer as this CategoryPath lexicographically precedes, equals to, or lexicographically follows the other CategoryPath.

  Specified by:
    `compareTo` in interface `Comparable<CategoryPath>`