Atom
Date: 2020-06-16

org.jpl7

## Class Atom

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

-     public class Atom
      extends Term

  Atom is a specialised Term, representing a Prolog atom with the same name. An Atom is constructed with a String parameter (its name, unquoted), which cannot thereafter be changed.

       Atom a = new Atom("hello");

  An Atom can be used (and re-used) as an argument of Compound Terms. Two Atom instances are equal (by equals()) iff they are of the same type and have equal values.

  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`, `Compound`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.lang.String` | `name` the name of this Atom
    `protected java.lang.String` | `type` the type of this Atom (e.g.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Atom(java.lang.String name)` This constructs a "text" Atom, and is equivalent to
    `Atom(java.lang.String name, java.lang.String type)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Term[]` | `args()` The arguments of this Term.
    `java.lang.String` | `atomType()`
    `boolean` | `equals(java.lang.Object o)` Two Atoms are equal if they are identical (same object) or their respective names and blobTypes are equal
    `boolean` | `hasFunctor(java.lang.String name, int arity)` Tests whether this Compound's functor has (String) 'name' and 'arity'.
    `int` | `hashCode()`
    `protected boolean` | `isAtomOfNameType(java.lang.String name, java.lang.String type)` for internal use only
    `boolean` | `isListNil()` whether this Term denotes (syntax-specifically) an empty list
    `java.lang.String` | `name()` the name (unquoted) of this Compound
    `protected void` | `put(java.util.Map<java.lang.String,term_t> varnames_to_vars, term_t term)` To put an Atom in a term, we create a sequence of term_t references from the Term.terms_to_term_ts() method, and then use the Prolog.cons_functor_v() method to create a Prolog compound term.
    `java.lang.String` | `toString()` an Atom's name is quoted if it is not a simple identifier.
    `int` | `type()` returns the type of this term, as "Prolog.ATOM"
    `java.lang.String` | `typeName()` returns the name of the type of this term, as "Atom"

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

      `arg, arity, atomListToStringArray, bigValue, doubleValue, floatValue, getSubst, getSubsts, getTerm, getTerm, hasFunctor, hasFunctor, hasFunctor, intArrayArrayToList, intArrayToList, intValue, isAtom, isBig, isBigInteger, isCompound, isFloat, isInteger, isJFalse, isJNull, isJRef, isJTrue, isJVoid, isList, isList, isListPair, isVariable, jrefToObject, listLength, listLength, listToTermArray, listToTermArray, longValue, object, objectToJRef, put, putParams, putParams, putParams1, putParams2, putTerm, putTerms, ref, setName, stringArrayToList, termArrayToList, textParamsToTerm, textToTerm, toString, toTermArray`

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

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

- - ### Field Detail

    - #### name

          protected final java.lang.String name

      the name of this Atom

    - #### type

          protected final java.lang.String type

      the type of this Atom (e.g. "text", "string", "reserved_symbol")

  - ### Constructor Detail

    - #### Atom

          public Atom(java.lang.String name)

      This constructs a "text" Atom, and is equivalent to

      `new Atom(name, "text")`

      Parameters:
        `name` - the Atom's name (unquoted)
      Throws:
        `JPLException` - if name is null

    - #### Atom

          public Atom(java.lang.String name,
                      java.lang.String type)

      Parameters:
        `name` - the Atom's name (unquoted)
        `type` - the required Atom type, e.g. "text" or "string"
      Throws:
        `JPLException` - if name or type is null, or if type is "jref"

  - ### Method Detail

    - #### args

          public Term[] args()

      Description copied from class: `Term`
      The arguments of this Term.

      Note that a SWI Prolog 7.x compound term can have zero arguments.

      This method returns an empty Term[] from an Atom, Float, Integer or JRef, approximating the behaviour of SWI Prolog's =../2

      Overrides:
        `args` in class `Term`
      Returns:
        the arguments of a Compound

    - #### atomType

          public final java.lang.String atomType()

      Overrides:
        `atomType` in class `Term`
      Returns:
        the type ("text", "string", "reserved_symbol", "jref" etc.) of an Atom

    - #### equals

          public boolean equals(java.lang.Object o)

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

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

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

    - #### isAtomOfNameType

          protected final boolean isAtomOfNameType(java.lang.String name,
                                                   java.lang.String type)

      for internal use only
      Overrides:
        `isAtomOfNameType` in class `Term`
      Parameters:
        `name` - an Atom name
        `type` - an Atom (blob) type, e.g. "text", "reserved_symbol"
      Returns:
        whether this Term instance is an Atom with name and type

    - #### isListNil

          public final boolean isListNil()

      whether this Term denotes (syntax-specifically) an empty list
      Overrides:
        `isListNil` in class `Term`
      Returns:
        whether this Term denotes an empty list within the current syntax ("traditional" or "modern").
      See Also:
        `JPL.getSyntax()`

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

    - #### put

          protected void put(java.util.Map<java.lang.String,term_t> varnames_to_vars,
                             term_t term)

      To put an Atom in a term, we create a sequence of term_t references from the Term.terms_to_term_ts() method, and then use the Prolog.cons_functor_v() method to create a Prolog compound term.
      Specified by:
        `put` in class `Term`
      Parameters:
        `varnames_to_vars` - A Map from variable names to Prolog variables
        `term` - A (previously created) term_t which is to be set to a Prolog term corresponding to the Term subtype (Atom, Variable, Compound, etc.) on which the method is invoked.

    - #### toString

          public java.lang.String toString()

      an Atom's name is quoted if it is not a simple identifier.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        string representation of an Atom

    - #### type

          public final int type()

      returns the type of this term, as "Prolog.ATOM"
      Specified by:
        `type` in class `Term`
      Returns:
        the type of this term, as "Prolog.ATOM"

    - #### typeName

          public java.lang.String typeName()

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