2.10.10 The class PlTerm_tail (version 2)

The class PlTerm_tail^{28This was named PlTail in version 1 of the API.} is both for analysing and constructing lists. It is called PlTerm_tail as enumeration-steps make the term-reference follow the “tail” of the list.

PlTerm_tail :: PlTerm_tail(PlTerm list)

A PlTerm_tail is created by making a new term-reference pointing to the same object. As PlTerm_tail is used to enumerate or build a Prolog list, the initial list term-reference keeps pointing to the head of the list.

int PlTerm_tail::append(const PlTerm &element)

Appends element to the list and make the PlTerm_tail reference point to the new variable tail. If A is a variable, and this function is called on it using the argument "gnat", a list of the form [gnat|B] is created and the PlTerm_tail object now points to the new variable B.

This function returns true if the unification succeeded and false otherwise. No exceptions are generated.

The example below translates the main() argument vector to Prolog and calls the prolog predicate entry/1 with it.

int
main(int argc, char **argv)
{ PlEngine e(argv[0]);
  PlTermv av(1);
  PlTerm_tail l(av[0]);

  for(int i=0; i<argc; i++)
    PlCheckFail(l.append(argv[i]));
  PlCheckFail(l.close());

  PlQuery q("entry", av);
  return q.next_solution() ? 0 : 1;
}

int PlTerm_tail::close()

Unifies the term with [] and returns the result of the unification.

int PlTerm_tail::next(PlTerm &)

Bind t to the next element of the list PlTerm_tail and advance PlTerm_tail. Returns true on success and false if PlTerm_tail represents the empty list. If PlTerm_tail is neither a list nor the empty list, a type_error is thrown. The example below prints the elements of a list.

PREDICATE(write_list, 1)
{ PlTerm_tail tail(A1);
  PlTerm_var e;

  while(tail.next(e))
    cout << e.as_string() << endl;

  return tail.close();
}