#include "term.h"

This page has information from files term.h and term.c.

Contents


Public Routines in File term.c

Index

all_args_varsfree_termnat_to_termsubst_term
arg_positionget_rigid_termnatural_constantsubst_var_term
biggest_variableget_rigid_term_dangerouslyoccurrencessymbol_count
build_binary_termget_rigid_term_likeoccurs_interm_ident
build_unary_termget_variable_termp_termterm_set_variables
copy_termgreatest_symnum_in_termp_term_memupward_term_links
fprint_termgreatest_variableset_variablezap_term
fprint_term_memground_termsprint_term

Details


BOOL all_args_vars(Term t);
This Boolean routine checks if all argumets of Term t are VARIABLEs. (It is true also if t is a VARIABLE.)
int arg_position(Term parent, Term child);
If the given terms are in a parent-child relatioship, return the argument position (index) of the child. Otherwise, return -1.
int biggest_variable(Term t);
This routine returns the greatest variable index of any variable int the given term t. If t is ground, -1 is returned.
Term build_binary_term(int sn, Term a1, Term a2);
Build and return a binary term with SYMNUM sn, first term a1, and second term a2.

WARNING: if sn is not a binary symbol, bad things will happen!


Term build_unary_term(int sn, Term a);
Build and return a unary term with SYMNUM sn and argument term a.

WARNING: if sn is not a unary symbol, bad things will happen!


Term copy_term(Term t);
This routine copies a term. Only the symbols and structure are copied---any extra fields such as bits or u are NOT copied.
void fprint_term(FILE *fp, Term t);
This routine prints (to FILE *fp) a term. A newline is NOT printed.
void fprint_term_mem(FILE *fp, BOOL heading);
This routine prints (to FILE *fp) memory usage statistics for Terms. The Boolean argument heading tells whether to print a heading on the table.
void free_term(Term p);
This routine frees a term node only. If you wish to recursively free all of the subterms as well, call zap_term(t) instead.
Term get_rigid_term(char *sym, int arity);
This routine allocates and returns a term node with the given symbol and arity. If you already have a similar term node, say t, (containing the symbol and arity you need) call get_rigid_term_like(t) instead.
Term get_rigid_term_dangerously(int symnum, int arity);
This routine can be used to allocate a term node if all you have is the symbol ID and arity. If the arity is not correct for the symbol ID, terrible things will happen!

If you have a similar term, use get_rigid_term_like() instead. If you can afford the time to access the symbol table, use sn_to_str() and get_rigid_term() instead.


Term get_rigid_term_like(Term t);
This routine allocates and returns a term node with the same symbol and arity as the given Term t.
Term get_variable_term(int var_num);
This routine allocates and returns a term of type VARIABLE. The index of the variable is set to var_num, which should be an integer >= 0.
int greatest_symnum_in_term(Term t);
This function returns the greatest SYMNUM (of a CONSTANT or COMPLEX term) in the given Term t. If the term is a VARIABLE, return -1.
int greatest_variable(Term t);
This routine returns the greatest variable index in a term. If the term is ground, -1 is returned.
BOOL ground_term(Term t);
This function checks if a term is ground, that is, has no variables.
Term nat_to_term(int n);
This routine takes a nonnegative integer and returns a constant Term with the string representation of the integer as the constant symbol.
int natural_constant(Term t);
This routine takes a term, and if the term represents an nonnegative integer, that integer is returned; otherwise, -1 is returned.
int occurrences(Term t, Term target);
This function returns the number of occurrences of Term target in Term t. The checks are made with term_ident().
BOOL occurs_in(Term t1, Term t2);
This function checks if Term t2 is identical to a subterm of Term t1, including the case term_ident(t1,t2). All identity checks are done with term_ident(), so extra fields such as bits or u are not checked.
void p_term(Term t);
This routine prints a term, followed by '\n' and fflush, to stdout. If you don't want the newline, use fprint_term() instead. If you want the term put into a string, use sprint_term() instead.
void p_term_mem(void);
This routine prints memory usage statistics for Terms to stdout.
void set_variable(Term t, int var_num);
This routine takes a VARIABLE Term and sets the index to var_num, which should be an integer >= 0.
void sprint_term(String_buf sb, Term t);
This (recursive) routine appends the string representation of a term to a String_buf. A newline is not included.
Term subst_term(Term t, Term target, Term replacement);
In term t, replace all occurrences of Term target with copies of Term replacement. Free all of the replaced terms;
Term subst_var_term(Term t, int symnum, int varnum);
In Term t, replace all CONSTANT terms containing SYMNUM symnum with a variable containing VARNUM varnum. Free the replaced constants and return the result.
int symbol_count(Term t);
This routine returns the total number of symbols (i.e., the number of nodes) in the given term t.
BOOL term_ident(Term t1, Term t2);
This function checks if two terms are identical. Only the structure and symbols are checked---any extra fields such as bits or u are NOT checked.
BOOL term_set_variables(Term t, int max_vars);
This routine traverses a term and changes the constants that should be variables, into variables. On input, the term should have no variables. The new variables are numbered 0, 1, 2 ... according the the first occurrence, reading from the left.

If there are not more than max_vars distinct variables, 1 is returned; if there are more than max_vars variables, the transformation is not completed, and 0 is returned.

If you are dealing with clauses, use clause_set_variables() instead.


void upward_term_links(Term t, void *p);
In the given Term t, make the "container" field of t and each subterm point to (void *) p.
void zap_term(Term t);
This routine frees a term t and all of its subterms. You should not refer to t after calling zap_term(t).

Public Definitions in File term.h

#define MAX_VARS  100  /* max number of (distinct) variables per term */

#define MAX_VAR   SHRT_MAX      /* maximum ID of any variable symbol */
#define MAX_SYM   (-SHRT_MIN)   /* maximum ID of any rigid symbol */
#define MAX_ARITY UCHAR_MAX     /* maximum arity of any term */

#define FLAGS_TYPE unsigned char  /* for private_flags field of Term */

typedef struct term * Term;     /* Term is a pointer to a term struct */

struct term {
  short         private_symbol; /* const/func/pred/var symbol ID */
  unsigned char arity;          /* number of auguments */
  FLAGS_TYPE    private_flags;  /* for marking terms in various ways */
  Term          *args;          /* array (of size arity) of pointers to args */
  void          *container;     /* an object that contains the term */
  union {                       /* this field is used for various things */
    void        *p;
    unsigned    i;
  } u;
};

/* to check type of term */
#define VARIABLE(t) ((t)->private_symbol >= 0)
#define CONSTANT(t) ((t)->private_symbol < 0 && (t)->arity == 0)
#define COMPLEX(t)  ((t)->private_symbol < 0 && (t)->arity > 0)

/* to get symbol ID from a CONSTANT or COMPLEX term */
#define SYMNUM(t)   ((t)->private_symbol >= 0 ? -1 : -((t)->private_symbol))
#define VARNUM(t)   ((t)->private_symbol < 0 ? -1 : (t)->private_symbol)

/* to get the arity of a term (VARIABLE terms have arity 0) */
#define ARITY(t)    ((t)->arity)
/* to get the i-th argument of a term (make sure i is in [0..arity-1]) */
#define ARG(t,i)    ((t)->args[i])


Introduction

The Term data structure is designed mainly to represent first-order untyped terms. It is generally used for atoms as well, because the indexing and unification methods don't care whether an object is a term or an atom.

No term structure sharing is supported at this level of abstraction. (Higher-level packagers can build terms with shared structure if they wish.) Because we envision applications with tens of millions of terms, small size for the individual nodes is important. So we have some overloaded fields, and macros are provided to get some of the information from from term nodes.

There are three types of term, and the Boolean macros VARIABLE(t), CONSTANT(t), and COMPLEX(t) should be used to find out what type a term is. If you have a CONSTANT or COMPLEX term t, you can get its symbol id with SYMNUM(t) (from which you can get other information about the symbol such as the print string and any special properties). If you have a variable t, you can get its index with VARNUM(t), which is a signed integral type in the range [0..MAX_VAR]. Warning: MAX_VAR is a big number---a higher-level unification package will typically have a much smaller MAX_VARS defined for array sizes, because it does array indexing with VARNUM(t).

The macro ARITY(t) gets the arity of a term (constants and variables have arity 0), and ARG(t,i) gets the i-th argument (counting from 0) of a term. When using ARG(t,i), make sure that i is in range [0..ARITY(t)-1], because ARG does not check.

Here is an example of recursing through a term.

void print_term(Term t)
{
  if (VARIABLE(t))
    printf("v%d", VARNUM(t));
  else {
    printf("%s", sn_to_str(SYMNUM(t)));
    if (COMPLEX(t)) {
      int i;
      printf("(");
      for (i = 0; i < ARITY(t); i++) {
	print_term(ARG(t,i));
	if (i < ARITY(t)-1)
	  printf(",");
      }
      printf(")");
    }
  }
}

These activities are projects of the Mathematics and Computer Science Division of Argonne National Laboratory.