<HTML>
<HEAD>
<!-- Created by texi2html 1.56k + clip patches and <A href="http://www.clip.dia.fi.upm.es/Software">lpdoc</A> from ciao.texi on 28 January 2007 -->
<LINK rel="stylesheet" href="ciao.css" type="text/css">
<TITLE>The Ciao Prolog System - Multiple Argument Indexing</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_95.html">previous</A>, <A HREF="ciao_97.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>.
<P><HR><P>
<H1><A NAME="SEC399" HREF="ciao_toc.html#TOC399">Multiple Argument Indexing</A></H1>
<P>
<A NAME="IDX5255"></A>
<P>
<STRONG>Author(s):</STRONG> Tom Howland (http://home.pacbell.net/tomjdnh/pd.html), derived from work by Anil Nair, F. Bueno (for the Ciao package).
<P>
<STRONG>Version:</STRONG> 1.10#7 (2006/4/26, 19:22:13 CEST)
<P>
<STRONG>Version of last change:</STRONG> 1.9#225 (2003/12/21, 20:20:39 CET)
<P>
This package is an extension of the idea of Prolog indexing, usually performed, in a limited way, on the first argument. This package provides more powerful indexing schemes. It lets you pick different arguments to index on, and provides for different combinations of arguments to index on. E.g., it will let you index on the first and third argument or the second and the third argument of a predicate.
<UL>
<LI><A HREF="ciao_96.html#SEC400">Usage and interface (indexer)</A>
<LI><A HREF="ciao_96.html#SEC401">Documentation on internals (indexer)</A>
</UL>
<H2><A NAME="SEC400" HREF="ciao_toc.html#TOC400">Usage and interface (<CODE>indexer</CODE>)</A></H2>
<div class="cartouche">
<UL>
<LI><STRONG>Library usage:</STRONG>
This facility is used as a package, thus either including
<A NAME="IDX5256"></A>
<CODE>indexer</CODE> in the package list of the module, or by using the
<A NAME="IDX5257"></A>
<CODE>use_package/1</CODE> declaration. The facility predicate
<A NAME="IDX5258"></A>
<CODE>hash_term/2</CODE>, documented here, is defined in library module
<A NAME="IDX5259"></A>
<CODE>hash</CODE>.
<LI><STRONG>Other modules used:</STRONG>
<UL>
<LI><EM>System library modules:</EM>
<A NAME="IDX5260"></A>
<CODE>assertions/native_props</CODE>.
</UL>
</UL>
</div class="cartouche">
<H2><A NAME="SEC401" HREF="ciao_toc.html#TOC401">Documentation on internals (<CODE>indexer</CODE>)</A></H2>
<P>
<A NAME="IDX5261"></A>
<A NAME="IDX5262"></A>
<DL>
<DT><span class="define">DECLARATION:</span> <B>index/1:</B>
<DD><A NAME="IDX5263"></A>
<P>
<STRONG>Usage:</STRONG> :- <CODE>index(IndexSpecs)</CODE>.
<UL>
<LI><EM>Description:</EM> Declares an indexing scheme for a predicate. All specs of <CODE>IndexSpecs</CODE> must be terms for the same predicate. Each spec declares an indexing on a combination of the arguments. Indexing will be performed using any of the specs in <CODE>IndexSpecs</CODE> (being thus interpreted as an or).
You should use a <CODE>*</CODE> in an argument position if you wish to hash on the entire term in that argument. If a <CODE>+</CODE> is used only one level of the term in the argument is used for hashing. An <CODE>i</CODE> is used to indicate that argument is already an integer, and therefore its own value will be used for hashing. The argspec <CODE>?</CODE> simply indicates not to use the argument for indexing.
For example, the index specification:
<PRE>
:- index foo(+,?,*,i), foo(?,?,?,i).
</PRE>
declares indexing for <CODE>foo/4</CODE> either on a combination of the first, third, and fourht arguments, or only on the last argument, which is an integer. In the first case, only the principal functor of the first argument will be used for hashing; the third argument will be used in its entirety.
The argspec <CODE>n</CODE> is a pragmatic extension and can not be used in conjunction with the other specifiers aside from <CODE>?</CODE>. It stands for "nonvar" and implies that the argument will not be used for hashing, since only ground terms can effectively be used in hashing. Thus, it can not be used in combination with other specifiers within a particular index specification. It is often the fastest thing to use.
<LI><EM>The following properties should hold upon exit:</EM>
<CODE>IndexSpecs</CODE> is an index specification.
(<CODE>indexer_doc:indexspecs/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX5264"></A>
<A NAME="IDX5265"></A>
<DL>
<DT><span class="define">REGTYPE:</span> <B>indexspecs/1:</B>
<DD><A NAME="IDX5266"></A>
<P>
An index specification is defined as follows:
<PRE>
indexspecs(Spec) :-
indexspec(Spec).
indexspecs((Spec,Specs)) :-
indexspec(Spec),
indexspecs(Specs).
</PRE>
<PRE>
indexspec(Spec) :-
Spec=..[_F|Args],
list(Args,argspec).
</PRE>
<P>
<STRONG>Usage:</STRONG> <CODE>indexspecs(IndexSpecs)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>IndexSpecs</CODE> is an index specification.
</UL>
</DL>
<P>
<A NAME="IDX5267"></A>
<A NAME="IDX5268"></A>
<DL>
<DT><span class="define">REGTYPE:</span> <B>argspec/1:</B>
<DD><A NAME="IDX5269"></A>
<P>
An argument hash specification is defined as follows:
<PRE>
argspec(+).
argspec(*).
argspec(i).
argspec(n).
argspec(?).
</PRE>
<P>
<STRONG>Usage:</STRONG> <CODE>argspec(Spec)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>Spec</CODE> is an argument hash specification.
</UL>
</DL>
<P>
<A NAME="IDX5270"></A>
<A NAME="IDX5271"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>hash_term/2:</B>
<DD><A NAME="IDX5272"></A>
<P>
<CODE>hash_term(Term, HashValue)</CODE>
<P>
Provides an efficient way to calculate an integer <CODE>HashValue</CODE> for a ground <CODE>Term</CODE>.
<P>
<STRONG>Usage 1:</STRONG> <CODE>hash_term(T, N)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>N</CODE> is a hashing index for <CODE>T</CODE>.
<LI><EM>The following properties should hold at call time:</EM>
<CODE>T</CODE> is currently ground (it contains no variables).
(<CODE>term_typing:ground/1</CODE>)
<CODE>N</CODE> is a free variable.
(<CODE>term_typing:var/1</CODE>)
<LI><EM>The following properties should hold upon exit:</EM>
<CODE>N</CODE> is an integer.
(<CODE>basic_props:int/1</CODE>)
</UL>
<P>
<STRONG>Usage 2:</STRONG> <CODE>hash_term(T, N)</CODE>
<UL>
<LI><EM>The following properties should hold at call time:</EM>
<CODE><CODE>T</CODE></CODE> is not ground.
(<CODE>native_props:nonground/1</CODE>)
<CODE>N</CODE> is a free variable.
(<CODE>term_typing:var/1</CODE>)
<LI><EM>The following properties should hold upon exit:</EM>
<CODE>N</CODE> is a free variable.
(<CODE>term_typing:var/1</CODE>)
</UL>
</DL>
<P><HR><P>
Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_95.html">previous</A>, <A HREF="ciao_97.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>.
</BODY>
</HTML>
