Module java.desktop
Package javax.print.attribute

## Class SetOfIntegerSyntax

- java.lang.Object
- - javax.print.attribute.SetOfIntegerSyntax

- All Implemented Interfaces:
    `Serializable`, `Cloneable`
  Direct Known Subclasses:
    `CopiesSupported`, `JobImpressionsSupported`, `JobKOctetsSupported`, `JobMediaSheetsSupported`, `NumberUpSupported`, `PageRanges`

      public abstract class SetOfIntegerSyntax
      extends Object
      implements Serializable, Cloneable

  Class `SetOfIntegerSyntax` is an abstract base class providing the common implementation of all attributes whose value is a set of nonnegative integers. This includes attributes whose value is a single range of integers and attributes whose value is a set of ranges of integers.

  You can construct an instance of `SetOfIntegerSyntax` by giving it in "string form." The string consists of zero or more comma-separated integer groups. Each integer group consists of either one integer, two integers separated by a hyphen (`-`), or two integers separated by a colon (`:`). Each integer consists of one or more decimal digits (`0` through `9`). Whitespace characters cannot appear within an integer but are otherwise ignored. For example: `""`, `"1"`, `"5-10"`, `"1:2, 4"`.

  You can also construct an instance of `SetOfIntegerSyntax` by giving it in "array form." Array form consists of an array of zero or more integer groups where each integer group is a length-1 or length-2 array of `int`s; for example, `int[0][]`, `int[][]{{1}}`, `int[][]{{5,10}}`, `int[][]{{1,2},{4}}`.

  In both string form and array form, each successive integer group gives a range of integers to be included in the set. The first integer in each group gives the lower bound of the range; the second integer in each group gives the upper bound of the range; if there is only one integer in the group, the upper bound is the same as the lower bound. If the upper bound is less than the lower bound, it denotes a `null` range (no values). If the upper bound is equal to the lower bound, it denotes a range consisting of a single value. If the upper bound is greater than the lower bound, it denotes a range consisting of more than one value. The ranges may appear in any order and are allowed to overlap. The union of all the ranges gives the set's contents. Once a `SetOfIntegerSyntax` instance is constructed, its value is immutable.

  The `SetOfIntegerSyntax` object's value is actually stored in "canonical array form." This is the same as array form, except there are no `null` ranges; the members of the set are represented in as few ranges as possible (i.e., overlapping ranges are coalesced); the ranges appear in ascending order; and each range is always represented as a length-two array of `int`s in the form {lower bound, upper bound}. An empty set is represented as a zero-length array.

  Class `SetOfIntegerSyntax` has operations to return the set's members in canonical array form, to test whether a given integer is a member of the set, and to iterate through the members of the set.

  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `SetOfIntegerSyntax​(int member)` | Construct a new set-of-integer attribute containing a single integer.
    `protected` | `SetOfIntegerSyntax​(int[][] members)` | Construct a new set-of-integer attribute with the given members in array form.
    `protected` | `SetOfIntegerSyntax​(int lowerBound, int upperBound)` | Construct a new set-of-integer attribute containing a single range of integers.
    `protected` | `SetOfIntegerSyntax​(String members)` | Construct a new set-of-integer attribute with the given members in string form.

  - ### Method Summary

    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `contains​(int x)` | Determine if this set-of-integer attribute contains the given value.
    `boolean` | `contains​(IntegerSyntax attribute)` | Determine if this set-of-integer attribute contains the given integer attribute's value.
    `boolean` | `equals​(Object object)` | Returns whether this set-of-integer attribute is equivalent to the passed in object.
    `int[][]` | `getMembers()` | Obtain this set-of-integer attribute's members in canonical array form.
    `int` | `hashCode()` | Returns a hash code value for this set-of-integer attribute.
    `int` | `next​(int x)` | Determine the smallest integer in this set-of-integer attribute that is greater than the given value.
    `String` | `toString()` | Returns a string value corresponding to this set-of-integer attribute.

    - ### Methods declared in class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### SetOfIntegerSyntax

          protected SetOfIntegerSyntax​(String members)

      Construct a new set-of-integer attribute with the given members in string form.
      Parameters:
        `members` - set members in string form. If `null`, an empty set is constructed.
      Throws:
        `IllegalArgumentException` - if `members` does not obey the proper syntax

    - #### SetOfIntegerSyntax

          protected SetOfIntegerSyntax​(int[][] members)

      Construct a new set-of-integer attribute with the given members in array form.
      Parameters:
        `members` - set members in array form. If `null`, an empty set is constructed.
      Throws:
        `NullPointerException` - if any element of `members` is `null`
        `IllegalArgumentException` - if any element of `members` is not a length-one or length-two array or if any `non-null` range in `members` has a lower bound less than zero

    - #### SetOfIntegerSyntax

          protected SetOfIntegerSyntax​(int member)

      Construct a new set-of-integer attribute containing a single integer.
      Parameters:
        `member` - set member
      Throws:
        `IllegalArgumentException` - if `member` is negative

    - #### SetOfIntegerSyntax

          protected SetOfIntegerSyntax​(int lowerBound,
                                       int upperBound)

      Construct a new set-of-integer attribute containing a single range of integers. If the lower bound is greater than the upper bound (a null range), an empty set is constructed.
      Parameters:
        `lowerBound` - Lower bound of the range
        `upperBound` - Upper bound of the range
      Throws:
        `IllegalArgumentException` - if the range is `non-null` and `lowerBound` is less than zero

  - ### Method Detail

    - #### getMembers

          public int[][] getMembers()

      Obtain this set-of-integer attribute's members in canonical array form. The returned array is "safe;" the client may alter it without affecting this set-of-integer attribute.
      Returns:
        this set-of-integer attribute's members in canonical array form

    - #### contains

          public boolean contains​(int x)

      Determine if this set-of-integer attribute contains the given value.
      Parameters:
        `x` - the Integer value
      Returns:
        `true` if this set-of-integer attribute contains the value `x`, `false` otherwise

    - #### contains

          public boolean contains​(IntegerSyntax attribute)

      Determine if this set-of-integer attribute contains the given integer attribute's value.
      Parameters:
        `attribute` - the Integer attribute
      Returns:
        `true` if this set-of-integer attribute contains `attribute`'s value, `false` otherwise

    - #### next

          public int next​(int x)

      Determine the smallest integer in this set-of-integer attribute that is greater than the given value. If there are no integers in this set-of-integer attribute greater than the given value, `-1` is returned. (Since a set-of-integer attribute can only contain nonnegative values, `-1` will never appear in the set.) You can use the `next()` method to iterate through the integer values in a set-of-integer attribute in ascending order, like this:

               SetOfIntegerSyntax attribute = . . .;
               int i = -1;
               while ((i = attribute.next (i)) != -1)
                   {
                   foo (i);
                   }

      Parameters:
        `x` - the Integer value
      Returns:
        the smallest integer in this set-of-integer attribute that is greater than `x`, or `-1` if no integer in this set-of-integer attribute is greater than `x`.

    - #### equals

          public boolean equals​(Object object)

      Returns whether this set-of-integer attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
      1. `object` is not `null`.
      2. `object` is an instance of class `SetOfIntegerSyntax`.
      3. This set-of-integer attribute's members and `object`'s members are the same.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `object` - `Object` to compare to
      Returns:
        `true` if `object` is equivalent to this set-of-integer attribute, `false` otherwise
      See Also:
        `Object.hashCode()`, `HashMap`

    - #### hashCode

          public int hashCode()

      Returns a hash code value for this set-of-integer attribute. The hash code is the sum of the lower and upper bounds of the ranges in the canonical array form, or 0 for an empty set.
      Overrides:
        `hashCode` in class `Object`
      Returns:
        a hash code value for this object.
      See Also:
        `Object.equals(java.lang.Object)`, `System.identityHashCode(java.lang.Object)`

    - #### toString

          public String toString()

      Returns a string value corresponding to this set-of-integer attribute. The string value is a zero-length string if this set is empty. Otherwise, the string value is a comma-separated list of the ranges in the canonical array form, where each range is represented as `"i"` if the lower bound equals the upper bound or `"i-j"` otherwise.
      Overrides:
        `toString` in class `Object`
      Returns:
        a string representation of the object.