Compound
Date: 2018-01-12

org.jpl7

## Class Compound

- java.lang.Object
- - org.jpl7.Term
  - - org.jpl7.Compound

-     public class Compound
      extends Term

  A Compound represents a structured term, comprising a functor and one or more arguments (Terms). Direct instances of Compound must have one or more arguments (it is an error to attempt to construct a Compound with zero args; a JPLException will be thrown). For example, this Java expression yields a representation of the term f(a):

       new Compound("f", new Term[] { new Atom("a") })

  Note the use of the "anonymous array" notation to denote the arguments (an anonymous array of Term).
  Alternatively, construct the Term from Prolog source syntax:

       Util.textToTerm("f(a)")

  The arity of a Compound is the quantity of its arguments. Once constructed, neither the name nor the arity of a Compound can be altered. An argument of a Compound can be replaced with the setArg() method.

  Copyright (C) 2004 Paul Singleton

  Copyright (C) 1998 Fred Dushin

  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

  See Also:
    `Term`, `Atom`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Compound(java.lang.String name)` Creates a Compound with name and no args (which in SWI Prolog V7 is distinct from a text atom of the same name).
    `Compound(java.lang.String name, Term[] args)` Creates a Compound with name and (zero or more) args.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Term` | `arg(int i)` Returns the ith argument (counting from 1) of this Compound.
    `Term[]` | `args()` Returns the arguments of this Compound as a Term[0..arity-1] array.
    `int` | `arity()` Returns the arity (0+) of this Compound.
    `boolean` | `equals(java.lang.Object obj)` Two Compounds are equal if they are identical (same object) or their names and arities are equal and their respective arguments are equal.
    `boolean` | `hasFunctor(java.lang.String name, int arity)` Tests whether this Compound's functor has (String) 'name' and 'arity'.
    `boolean` | `isJFalse()` whether this Term is a 'jboolean' structure denoting Java's false, i.e.
    `boolean` | `isJNull()` whether this Term is a 'jnull' structure, i.e.
    `boolean` | `isJTrue()` whether this Term is a 'jboolean' structure denoting Java's true, i.e.
    `boolean` | `isJVoid()` whether this Term is a 'jvoid' structure, i.e.
    `boolean` | `isListPair()` whether this Term denotes (syntax-specifically) a list cell
    `java.lang.Object` | `jrefToObject()` returns null iff this Compound represents @(null)
    `java.lang.String` | `name()` the name (unquoted) of this Compound
    `void` | `setArg(int i, Term arg)` Sets the i-th (from 1) arg of this Compound to the given Term instance.
    `java.lang.String` | `toString()` a prefix functional representation of a Compound of the form name(arg1,...), where 'name' is quoted iff necessary (to be valid Prolog soutce text) and each argument is represented according to its toString() method.
    `int` | `type()` the type of this term, as jpl.fli.Prolog.COMPOUND
    `java.lang.String` | `typeName()` the name of the type of this term, as "Compound"

    - ### Methods inherited from class org.jpl7.Term

      `atomType, bigValue, doubleValue, floatValue, hasFunctor, hasFunctor, hasFunctor, intValue, isAtom, isBig, isBigInteger, isCompound, isFloat, isInteger, isJRef, isListNil, isVariable, listLength, longValue, object, objectToJRef, putParams, putTerm, ref, toString, toTermArray`

    - ### Methods inherited from class java.lang.Object

      `getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Compound

          public Compound(java.lang.String name)

      Creates a Compound with name and no args (which in SWI Prolog V7 is distinct from a text atom of the same name).
      Parameters:
        `name` - the name of this Compound
      Throws:
        `JPLException` - if name is null

    - #### Compound

          public Compound(java.lang.String name,
                          Term[] args)

      Creates a Compound with name and (zero or more) args.
      Parameters:
        `name` - the name of this Compound
        `args` - the (zero or more) arguments of this Compound
      Throws:
        `JPLException` - if name is null or args is null

  - ### Method Detail

    - #### arg

          public final Term arg(int i)

      Returns the ith argument (counting from 1) of this Compound.
      Overrides:
        `arg` in class `Term`
      Parameters:
        `i` - the ordinal number of the required arg (1 denotes the first arg etc.)
      Returns:
        the ith argument (counting from 1) of this Compound
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if i is inappropriate

    - #### args

          public final Term[] args()

      Returns the arguments of this Compound as a Term[0..arity-1] array.
      Overrides:
        `args` in class `Term`
      Returns:
        the arguments of this Compound as a Term[0..arity-1] array.

    - #### arity

          public final int arity()

      Returns the arity (0+) of this Compound.
      Overrides:
        `arity` in class `Term`
      Returns:
        the arity (0+) of this Compound

    - #### equals

          public final boolean equals(java.lang.Object obj)

      Two Compounds are equal if they are identical (same object) or their names and arities are equal and their respective arguments are equal.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `obj` - the Object to compare (not necessarily another Compound)
      Returns:
        true if the Object satisfies the above condition

    - #### hasFunctor

          public final boolean hasFunctor(java.lang.String name,
                                          int arity)

      Tests whether this Compound's functor has (String) 'name' and 'arity'.
      Overrides:
        `hasFunctor` in class `Term`
      Parameters:
        `name` - a possible name for the functor of a term
        `arity` - an arity 0+
      Returns:
        whether this Compound's functor has (String) 'name' and 'arity'

    - #### isJFalse

          public boolean isJFalse()

      whether this Term is a 'jboolean' structure denoting Java's false, i.e. @(false)
      Overrides:
        `isJFalse` in class `Term`
      Returns:
        whether this Term is a 'jboolean' structure denoting Java's false, i.e. @(false)

    - #### isJNull

          public boolean isJNull()

      whether this Term is a 'jnull' structure, i.e. @(null)
      Overrides:
        `isJNull` in class `Term`
      Returns:
        whether this Term is a 'jnull' structure, i.e. @(null)

    - #### isJTrue

          public boolean isJTrue()

      whether this Term is a 'jboolean' structure denoting Java's true, i.e. @(true)
      Overrides:
        `isJTrue` in class `Term`
      Returns:
        whether this Term is a 'jboolean' structure denoting Java's true, i.e. @(true)

    - #### isJVoid

          public boolean isJVoid()

      whether this Term is a 'jvoid' structure, i.e. @(void)
      Overrides:
        `isJVoid` in class `Term`
      Returns:
        whether this Term is a 'jvoid' structure, i.e. @(void)

    - #### isListPair

          public final boolean isListPair()

      whether this Term denotes (syntax-specifically) a list cell
      Overrides:
        `isListPair` in class `Term`
      Returns:
        whether this Term denotes (syntax-specifically) a list cell

    - #### jrefToObject

          public java.lang.Object jrefToObject()

      returns null iff this Compound represents @(null)
      Overrides:
        `jrefToObject` in class `Term`
      Returns:
        the Object which this JRef references
      See Also:
        `Term.jrefToObject()`, `Term.jrefToObject()`

    - #### name

          public final java.lang.String name()

      the name (unquoted) of this Compound
      Overrides:
        `name` in class `Term`
      Returns:
        the name (unquoted) of this Compound

    - #### setArg

          public void setArg(int i,
                             Term arg)

      Sets the i-th (from 1) arg of this Compound to the given Term instance. This method, along with the Compound(name,arity) constructor, serves the new, native Prolog-term-to-Java-term routine, and is public only so as to be accessible via JNI: it is not intended for general use.
      Parameters:
        `i` - the index (1+) of the arg to be set
        `arg` - the Term which is to become the i-th (from 1) arg of this Compound

    - #### toString

          public java.lang.String toString()

      a prefix functional representation of a Compound of the form name(arg1,...), where 'name' is quoted iff necessary (to be valid Prolog soutce text) and each argument is represented according to its toString() method.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        string representation of an Compound

    - #### type

          public int type()

      the type of this term, as jpl.fli.Prolog.COMPOUND
      Specified by:
        `type` in class `Term`
      Returns:
        the type of this term, as jpl.fli.Prolog.COMPOUND

    - #### typeName

          public java.lang.String typeName()

      the name of the type of this term, as "Compound"
      Specified by:
        `typeName` in class `Term`
      Returns:
        the name of the type of this term, as "Compound"