.. java:import:: java.util Arrays

Tuple
=====

.. java:package:: com.ampl
   :noindex:

.. java:type:: public final class Tuple

   An immutable tuple. All methods of this class throw a \ ``NullPointerException``\  if a null object reference is passed in any parameter.

Constructors
------------

.. java:constructor:: public Tuple(Object... elements)
   :outertype: Tuple

   Constructs a new \ ``Tuple``\  from the specified elements.

   The elements in a Tuple can be numbers or strings.

   All basic Java numeric types are converted to double, as AMPL supports only one numeric type.

Methods
-------

.. java:method:: @Override public Tuple clone()
   :outertype: Tuple

   Clone the tuple

.. java:method:: public Object[] elements()
   :outertype: Tuple

   Returns a new array containing the tuple elements.

.. java:method:: @Override public boolean equals(Object other)
   :outertype: Tuple

   Checks for deep equality

.. java:method:: public Object get(int index)
   :outertype: Tuple

   Returns the element at the specified position in this tuple.

.. java:method:: @Override public int hashCode()
   :outertype: Tuple

   Hash code of all elements

.. java:method:: public void insert(Object[] array, int index)
   :outertype: Tuple

   Inserts the elements of this tuple into the specified array starting from the specified index.

.. java:method:: public static Tuple join(Object... elements)
   :outertype: Tuple

   Constructs a new \ ``Tuple``\  joining the specified elements.

   The elements in a Tuple can be numbers, strings, tuples or arrays.

   Use this function to construct a tuple for accessing instances of AMPL entities indexed over 2 or more index sets at least one of which is two-dimensional.

   For example, accessing the AMPL entity:

   .. parsed-literal::

      var x{{(1,2)}, {'a'}};

   can be achieved either via:

   .. parsed-literal::

      Variable x = ampl.getVariable("x");
      x.get(1, 2, "a");

   or, using this function, as:

   .. parsed-literal::

      Variable x = ampl.getVariable("x");
      Tuple t = new Tuple(1,2);
      x.get(Tuple.join(t, "a"));

   The very same way, the elements of the tuple created by:

   .. parsed-literal::

      t = Tuple.join(new Object[] { 2, 3 }, 4, "b";);

   will be equivalent to

   .. parsed-literal::

      t = new Tuple(2, 3, 4, "b").

   or, by joining tuples:

   .. parsed-literal::

      Tuple A = new Tuple(2, 3);
      Tuple B = Tuple.join(A, A);

   is equivalent to:

   .. parsed-literal::

      Tuple B = new Tuple(2, 3, 2, 3);

   Note that to conform with the AMPL type system all basic Java numeric types are converted to double, as AMPL supports only one numeric type (see :java:ref:`Tuple.Tuple` for more information).

.. java:method:: public int size()
   :outertype: Tuple

   Returns the number of elements in this tuple.

.. java:method:: public Tuple subtuple(int from, int to)
   :outertype: Tuple

   Returns a tuple containing the specified range of elements from this tuple.

   :param from: - the initial index of the range to be copied, inclusive
   :param to: - the final index of the range to be copied, exclusive. (This index may be equal to size.)
   :throws ArrayIndexOutOfBoundsException: - if \ ``from < 0``\  or \ ``to > size()``\
   :throws IllegalArgumentException: - if \ ``from > to``\

.. java:method:: @Override public String toString()
   :outertype: Tuple

   Returns a string of the form ``(t1,t2,t3)`` where t1, t2, t3 are the elements of the tuple