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 Details

  - ### 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 Details

  - ### 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.