Sort.html

`Sort.java`

    // FILE. . . . . /home/hak/hlt/src/hlt/osf/base/Sort.java
    // EDIT BY . . . Hassan Ait-Kaci
    // ON MACHINE. . Hp-Dv7
    // STARTED ON. . Mon Nov 05 18:19:15 2012

This is the class of sorts as explained in the specification.
Author: |  | Hassan Aït-Kaci
Copyright: |  | © by the author
Version: |  | Last modified on Sat Jan 19 12:48:43 2013 by hak

    package hlt.osf.base;

    import java.util.HashSet;

    import hlt.osf.util.BitCode;
    import hlt.osf.exec.Context;
    import hlt.osf.exec.Taxonomy;
    import hlt.osf.exec.LockedCodeArrayException;

    import hlt.language.util.Comparable;

    public class Sort implements Comparable
      {
        /* ************************************************************************ */

The index of this Sort (not necessarily its index in the sort code array).

        public int index;

The name of this Sort.

        public String name;

The bit vector code of this Sort.

        public BitCode code;

        /* ************************************************************************ */

Constructs a Sort object with the specified index and name.

        Sort (int index, String name)
        {
          this.index = index;
          this.name = name.intern();
        }

Constructs a Sort object with the specified index, name, and bit code.

        public Sort (int index, String name, BitCode code)
        {
          this.index = index;
          this.name = name.intern();
          this.code = code;
        }

Sets the index of this Sort object to the specified index, and returns this sort.

        public Sort setIndex (int index)
        {
          this.index = index;
          return this;
        }

        /* ************************************************************************ */

Sets the bit code of this Sort object to the specified bit code, and returns this sort.

        public Sort setCode (BitCode code)
        {
          this.code = code;
          return this;
        }

        /* ************************************************************************ */

Returns true iff this sort is a subsort of the specified sort.

        public boolean isSubsortOf (Sort sort)
        {
          return this.code.isContainedIn(sort.code);
        }

Returns true iff this sort is a strict subsort of the specified sort.

        public boolean isStrictSubsortOf (Sort sort)
        {
          return this.code.isStrictlyContainedIn(sort.code);
        }

Returns true iff this sort is unrelated to the specified sort.

        public boolean isUnrelatedTo (Sort sort)
        {
          return this.code.isUnrelatedTo(sort.code);
        }

        /* ************************************************************************ */

        private Context _context;

        public Context context ()
        {
          return _context;
        }

        public Sort setContext (Context context)
        {
          _context = context;
          return this;
        }

        /* ************************************************************************ */

This defines the sort code size for all Boolean computations on, and printing of, sort codes. This is necessary for consistency since only bits within this code size do matter. It is set in the `Taxonomy` class upon locking the defined sorts' code array. This constant is taken into account in Boolean operations (essentially by 'not') and code printing methods defined the `BitCode` class. For all sort codes, all bits of index greater than or equal to this constant are always false. This is also the index of top when it is initialized and installed in the sort code array upon locking it.

        private static int _CODESIZE;

Returns the sort code size for an encoded taxonomy. Raises a LockedCodeArrayException if the sort code array is not locked.

        public static int codeSize () throws LockedCodeArrayException
        {
          if (!Taxonomy.isLocked())
    	throw new LockedCodeArrayException("Attempt to access code size for a non-encoded taxonomy");

          return _CODESIZE;
        }

Sets the sort code size for an encoded taxonomy. Raises a LockedCodeArrayException if the sort code array is locked.

        public static void setCodeSize (int size) throws LockedCodeArrayException
        {
          if (Taxonomy.isLocked())
    	throw new LockedCodeArrayException("Cannot change the sort code size for an encoded taxonomy");

          _CODESIZE = size;
        }

        /* ************************************************************************ */

This defines top as a static constant. Note that the index is set to 0. But this is temporary, as it will updated to its final index when initialized and be stored in the sort code array. It final index will then be the value of _CODESIZE.

        private static Sort _TOP = new Sort(0,"@",new BitCode().lock());

Returns the top sort as a static constant. This is safe only if the taxonomy this is relative to has been encoded. Raises a LockedCodeArrayException if the sort code array is locked. This is because its correct code size is only dtermined after the sorts have been all encoded.

        public static Sort top () // throws LockedCodeArrayException
        {
          // if (!Taxonomy.isLocked())
          // 	throw new LockedCodeArrayException("Attempt to access unsafe top sort for a non-encoded taxonomy");

          return _TOP;
        }

Return true iff this sort is top.

        public boolean isTop ()
        {
          return name == "@";
        }

        /* ************************************************************************ */

This defines bottom as a static constant. Note that the index is set to -1. This is because it is not stored in the sort code array and therefore, its index is irrelevant. It is the only sort not stored in the code array and whose height is always 0.

        private static Sort _BOTTOM = new Sort(-1,"{}",new BitCode().lock()).setHeight(0);

Returns the bottom sort as a static constant.

        public static Sort bottom ()
        {
          if (!Taxonomy.isLocked())
    	throw new LockedCodeArrayException("Attempt to access unsafe bottom sort for a non-encoded taxonomy");

          return _BOTTOM;
        }

Return true iff this sort is bottom.

        public boolean isBottom ()
        {
          return name == "{}";
        }

        /* ************************************************************************ */

This is a bucket used to register is-a declarations (it is the set of names of this sort's declared immediate supersorts). Its purpose is essentially for detecting redundant such declarations. It is the erased (reset to null) by the context upon committing this sort.

        private HashSet _isaDeclarations;

Adds the specified name to the set of names of immediate supersorts of this sort, and returns true if it was not there (ie., declared so) before.

        public boolean addIsaDeclaration (String name)
        {
          if (_isaDeclarations == null)
    	_isaDeclarations = new HashSet();

          return _isaDeclarations.add(name);
        }

Cleans up this sort by resetting its is-a declarations to null.

        public void clearIsaDeclarations ()
        {
          _isaDeclarations = null;
        }

        /* ************************************************************************ */

This is the set of sorts that are immediate upper bounds of this sort.

        private BitCode _parents;

Returns this sort's parents (that is, its minimal upper bounds) as a set of sorts. Note that this set be empty - in which case this sort must be the top sort. This assumes that the sorts have been encoded.

        public BitCode getParents ()
        {
          if (_parents != null && _parents.isLocked())
    	return _parents;

          if (_parents == null)
    	_parents = new BitCode();

          return _parents = _context.taxonomy().minUpperBounds(code,_parents);
        }

Erases this sort's parents.

        public Sort resetParents ()
        {
          if (_parents != null)
    	_parents.unlock().erase();

          return this;
        }

        /* ************************************************************************ */

This is the set of sorts that are immediate lower bounds if this sort.

        private BitCode _children;

Returns this sort's children (that is, its maximal lower bounds) as set of sorts. Note that set array may be empty - in which case this sort must be the bottom sort. This assumes that the sorts have been encoded.

        public BitCode getChildren ()
        {
          if (_children != null && _children.isLocked())
    	return _children;

          if (_children == null)
    	_children = new BitCode();

          return _children = _context.taxonomy().maxLowerBounds(code,_children);
        }

Erases this sort's children.

        public Sort resetChildren ()
        {
          if (_children != null)
    	_children.unlock().erase();

          return this;
        }

        /* ************************************************************************ */

The height of this Sort in its taxonomy. (See the specification.)

        private int _height = -1;

Returns the height of this Sort in its taxonomy. (See the specification.)

        public int height () throws LockedCodeArrayException
        {
          if (!Taxonomy.isLocked())
    	throw new LockedCodeArrayException("Can't compute sort heights in a non-encoded taxonomy");

          if (_height != -1)
    	return _height;

          return _height = _context.taxonomy().computeHeight(this);
        }

        public Sort setHeight (int height)
        {
          _height = height;
          return this;
        }

        public void resetHeight ()
        {
          _height = -1;
        }

        /* ************************************************************************ */

Returns the number of subsorts of this sort (not including itself).

        public int numberOfDescendants ()
        {
          return this.code.cardinality()-1;
        }

The set of descendants of this Sort in its taxonomy. (See the specification.)

        private BitCode _descendants;

Returns the set of descendants of this sort as a BitCode. (See the specification.)

        public BitCode descendants () throws LockedCodeArrayException
        {
          if (!Taxonomy.isLocked())
    	throw new LockedCodeArrayException("Attempt to perform an operation requiring prior sort encoding");

          if (_descendants != null)
    	return _descendants;

          if (isBottom())
    	return _descendants = _BOTTOM.code;

          return _descendants = _context.taxonomy().computeDescendants(this);
        }

        /* ************************************************************************ */

Returns the number of supersorts of this sort (not including itself).

        int numberOfAncestors (Sort sort)
        {
          return ancestors().cardinality();
        }

The set of ancestors of this Sort in its taxonomy. (See the specification.)

        private BitCode _ancestors;

Returns the set of ancestors of this sort as a BitCode. (See the specification.)

        public BitCode ancestors () throws LockedCodeArrayException
        {
          if (!Taxonomy.isLocked())
    	throw new LockedCodeArrayException("Attempt to perform an operation requiring prior sort encoding");

          if (_ancestors != null)
    	return _ancestors;

          return _ancestors = _context.taxonomy().computeAncestors(this);
        }

        /* ************************************************************************ */

Returns true iff this is a strict lower sort of the specified sort. This is used by the `hlt.language.tools.Misc.sort` method used in class `Taxonomy` to sort the declared sorts.

        public boolean lessThan (Comparable sort)
        {
          return precedes((Sort)sort);
        }

This defines the "precedes" ordering as described in the specification. This is a topological ordering that respects the is-a ordering to ease the detection of potential cycles. A cycle is a set of sorts with equal codes after transitive closure has been performed. Using this "precedes" comparison to reorder the array will make all elements in a cycle be contiguous.

        public boolean precedes (Sort sort)
        {
          if (this.code.isStrictlyContainedIn(sort.code))	// this is a proper subsort of sort
    	return true;

          if (this.code.equals(sort.code))	// respect the index ordering for equal codes
    	return this.index < sort.index;

          if (!sort.code.isContainedIn(this.code))	// for unrelated sorts
    	if (this.code.cardinality() == sort.code.cardinality())
    	  return this.index < sort.index;	// respect the index order for same cardinality
            else	// respect smaller cardinality
    	  return (this.code.cardinality() < sort.code.cardinality());

          return false;
        }

Returns true iff this sort's name is equal to the specified one's.

        public boolean equals (Sort sort)
        {
          return name == sort.name;
        }

Locks this sort's bit code - which means that its code will not be modified by the 3 Boolean static bit code operations 'not', 'and', and 'or'.

        public Sort lock ()
        {
          code.lock();
          return this;
        }

Unlocks this sort's bit code - which means that its code may be modified by the 3 Boolean static bit code operations 'not', 'and', and 'or'.

        public Sort unlock ()
        {
          code.unlock();
          return this;
        }

Returns true iff this sort's bit code is locked - which means that its bit code will not be modified by the 3 Boolean static operations 'not', 'and', and 'or'.

        public boolean isLocked ()
        {
          return code.isLocked();
        }

Returns a string form of this Sort object. This string is its name.

        public String toString ()
        {
          return name;
        }

      }

This file was generated on Wed Jan 30 13:26:29 CET 2013 from file `Sort.java`
by the `hlt.language.tools.Hilite` Java tool written by Hassan Aït-Kaci