<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.06-7 of 2001-11-14">
<TITLE>
Global variables
</TITLE>
</HEAD>
<BODY TEXT=black BGCOLOR=white>
<A HREF="manual043.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual023.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="manual045.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>
<TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#66dbff"><DIV ALIGN=center><TABLE>
<TR><TD><FONT SIZE=4><B><A NAME="htoc213">7.21</A></B></FONT></TD>
<TD WIDTH="100%" ALIGN=center><FONT SIZE=4><B>Global variables</B></FONT></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><UL>
<LI><A HREF="manual044.html#toc171"> Introduction</A>
<LI><A HREF="manual044.html#toc172"> <TT>g_assign/2</TT>,
<TT>g_assignb/2</TT>,
<TT>g_link/2</TT></A>
<LI><A HREF="manual044.html#toc173"> <TT>g_read/2</TT></A>
<LI><A HREF="manual044.html#toc174"> <TT>g_array_size/2</TT></A>
<LI><A HREF="manual044.html#toc175"> <TT>g_inc/3</TT>,
<TT>g_inc/2</TT>,
<TT>g_inco/2</TT>,
<TT>g_inc/1</TT>,
<TT>g_dec/3</TT>,
<TT>g_dec/2</TT>,
<TT>g_deco/2</TT>,
<TT>g_dec/1</TT></A>
<LI><A HREF="manual044.html#toc176"> <TT>g_set_bit/2</TT>,
<TT>g_reset_bit/2</TT>,
<TT>g_test_set_bit/2</TT>,
<TT>g_test_reset_bit/2</TT></A>
<LI><A HREF="manual044.html#toc177"> Examples</A>
</UL>
<BR>
<A NAME="toc171"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc214">7.21.1</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>Introduction</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<A NAME="Global-variables"></A><BR>
GNU Prolog provides a simple and powerful way to assign and read global
variables. A global variable is associated to each atom, its initial value is
the integer 0. A global variable can store 3 kinds of objects:
<UL><LI>a copy of a term (the assignment can be made backtrackable or not).<BR>
<BR>
<LI>a link to a term (the assignment is always backtrackable).<BR>
<BR>
<LI>an array of objects (recursively).</UL>
The space necessary for copies and arrays is dynamically allocated and
recovered as soon as possible. For instance, when an atom is associated to a
global variable whose current value is an array, the space for this array is
recovered (unless the assignment is to be undone when backtracking occurs).<BR>
<BR>
When a link to a term is associated to a global variable, the reference to
this term is stored and thus the original term is returned when the content
of the variable is read.<BR>
<BR>
<B>Global variable naming convention</B>: a global variable is referenced
by an atom. <BR>
<BR>
If the variable contains an array, an index (ranging from 0) can be provided
using a compound term whose principal functor is the correponding atom and
the argument is the index. In case of a multi-dimensional array, each index
is given as the arguments of the compound term.<BR>
<BR>
If the variable contains a term (link or copy), it is possible to only
reference a sub-term by giving its argument number (also called argument
selector). Such a sub-term is specified using a compound term whose
principal functor is <TT>-/2</TT> and whose first argument is a global
variable name and the second argument is the argument number (from 1). This
can be applied recursively to specify a sub-term of any depth. In case of a
list, a argument number I represents the Ith element of the list. In the
rest of this section we use the operator notation since <TT>-</TT> is a
predefined infix operator (section <A HREF="manual037.html#op/3:(Term-input/output)">7.14.10</A>).<BR>
<BR>
In the following, <I><TT>GVarName</TT></I> represents a reference to a global
variable and its syntax is as follows:
<DL COMPACT=compact><DT><DD>
<TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD ALIGN=left NOWRAP><I><TT>GVarName</TT></I></TD>
<TD ALIGN=left NOWRAP>::=</TD>
<TD ALIGN=left NOWRAP><I><TT>atom</TT></I></TD>
<TD ALIGN=left NOWRAP>whole content of a variable</TD>
</TR>
<TR><TD ALIGN=left NOWRAP> </TD>
<TD ALIGN=left NOWRAP> </TD>
<TD ALIGN=left NOWRAP><TT><I>atom</I>(<I>Integer</I>,</TT>...<TT>,<I>Integer</I>)</TT></TD>
<TD ALIGN=left NOWRAP>element of an array</TD>
</TR>
<TR><TD ALIGN=left NOWRAP> </TD>
<TD ALIGN=left NOWRAP> </TD>
<TD ALIGN=left NOWRAP><TT><I>GVarName</I>-<I>Integer</I></TT></TD>
<TD ALIGN=left NOWRAP>sub-term selection</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><I><TT>Integer</TT></I></TD>
<TD ALIGN=left NOWRAP>::=</TD>
<TD ALIGN=left NOWRAP><I><TT>integer</TT></I></TD>
<TD ALIGN=left NOWRAP>immediate value</TD>
</TR>
<TR><TD ALIGN=left NOWRAP> </TD>
<TD ALIGN=left NOWRAP> </TD>
<TD ALIGN=left NOWRAP><I><TT>GVarName</TT></I></TD>
<TD ALIGN=left NOWRAP>indirect value</TD>
</TR></TABLE>
</DL>
When a <I><TT>GVarName</TT></I> is used as an index or an argument number
(i.e. indirection), the value of this variable must be an integer.<BR>
<BR>
Here are some examples of the naming convention:<BR>
<TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD ALIGN=left NOWRAP><TT>a</TT></TD>
<TD ALIGN=left NOWRAP>the content of variable associated to <TT>a</TT> (any kind)</TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>t(1)</TT></TD>
<TD ALIGN=left NOWRAP>the 2nd element of the array associated to <TT>t</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>t(k)</TT></TD>
<TD ALIGN=left NOWRAP>if the value associated to <TT>k</TT> is I, the Ith element of the array associated to <TT>t</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>a-1-2</TT></TD>
<TD ALIGN=left NOWRAP>if the value associated to <TT>a</TT> is <TT>f(g(a,b,c),2)</TT>, the sub-term <TT>b</TT></TD>
</TR></TABLE><BR>
Here are the errors associated to global variable names and common to all
predicates.<BR>
<TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>GVarName</TT> is a variable</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>instantiation_error</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>GVarName</TT> is neither a variable nor a callable term</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>type_error(callable, GVarName)</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>GVarName</TT> contains an invalid argument number
(or <TT>GVarName</TT> is an array)</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>domain_error(g_argument_selector, GVarName)</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>GVarName</TT> contains an invalid index
(or <TT>GVarName</TT> is not an array)</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>domain_error(g_array_index, GVarName)</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>GVarName</TT> is used as an indirect index or argument selector
and is not an integer</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>type_error(integer, GVarName)</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR></TABLE><BR>
<B>Arrays</B>: the predicates <TT>g_assign/2</TT>, <TT>g_assignb/2</TT>
and <TT>g_link/2</TT> (section <A HREF="#g-assign/2">7.21.2</A>) can be used to create an
array. They recognize some terms as values. For instance, a compound term
with principal functor <TT>g_array</TT> is used to define an array of fixed
size. There are 3 forms for the term <TT>g_array</TT>:
<UL><LI><TT>g_array(Size)</TT>: if <TT>Size</TT> is an integer > 0 then
defines an array of <TT>Size</TT> elements which are all initialized with
the integer <TT>0</TT>.<BR>
<BR>
<LI><TT>g_array(Size, Initial)</TT>: as above but the elements are
initialized with the term <TT>Initial</TT> instead of 0. <TT>Initial</TT>
can contain other array definitions allowing thus for multi-dimensional
arrays.<BR>
<BR>
<LI><TT>g_array(List)</TT>: as above if <TT>List</TT> is a list of length
<TT>Size</TT> except that the elements of the array are initialized
according to the elements of <TT>List</TT> (which can contain other array
definitions). </UL>
An array can be extended explicitely using a compound term with principal
functor <TT>g_array_extend</TT> which accept the same 3 forms detailed
above. In that case, the existing elements of the array are not
initialized. If <TT>g_array_extend</TT> is used with an object which is not
an array it is similar to <TT>g_array</TT>.<BR>
<BR>
Finally, an array can be <I>automatically</I> expanded when needed. The
programmer does not need to explicitely control the expansion of an automatic
array. An array is expanded as soon as an index is outside the current size
of this array. Such an array is defined using a compound term with principal
functor <TT>g_array_auto</TT>:
<UL><LI><TT>g_array_auto(Size)</TT>: if <TT>Size</TT> is an integer > 0
then defines an automatic array whose initial size is <TT>Size</TT>. All
elements are initialized with the integer <TT>0</TT>. Elements
created during implicit expansions will be initialized with <TT>0</TT>.<BR>
<BR>
<LI><TT>g_array_auto(Size, Initial)</TT>: as above but the elements are
initialized with the term <TT>Initial</TT> instead of 0. <TT>Initial</TT> can
contain other array definitions allowing thus for multi-dimensional
arrays. Elements created during implicit expansions will be initialized with
<TT>Initial</TT>.<BR>
<BR>
<LI><TT>g_array_auto(List)</TT>: as above if <TT>List</TT> is a list of
length <TT>Size</TT> except that the elements of the array are initialized
according to the elements of <TT>List</TT> (which can contain other array
definitions). Elements created during implicit expansions will be initialized
with <TT>0</TT>.</UL>
In any case, when an array is read, a term of the form
<TT>g_array([Elem0,..., ElemSize-1])</TT> is returned.<BR>
<BR>
Some examples using global variables are presented later (section <A HREF="#Examples">7.21.7</A>).<BR>
<BR>
<A NAME="toc172"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc215">7.21.2</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B><TT>g_assign/2</TT>,
<TT>g_assignb/2</TT>,
<TT>g_link/2</TT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<A NAME="g-assign/2"></A>
<BR>
<B>Templates</B>
<DL COMPACT=compact><DT><DD><TT>
g_assign(+callable_term, ?term)<BR>
g_assignb(+callable_term, ?term)<BR>
g_link(+callable_term, ?term)</TT></DL>
<B>Description</B><BR>
<BR>
<TT>g_assign(GVarName, Value)</TT> assigns a copy of the term
<TT>Value</TT> to <TT>GVarName</TT>. This assignment is not undone when
backtracking occurs.<BR>
<BR>
<TT>g_assignb/2</TT> is similar to <TT>g_assign/2</TT> but the assignment
is undone at backtracking.<BR>
<BR>
<TT>g_link(GVarName, Value)</TT> makes a link between <TT>GVarName</TT> to
the term <TT>Value</TT>. This allows the user to give a name to any Prolog
term (in particular non-ground terms). Such an assignment is always undone
when backtracking occurs (since the term may no longer exist). If
<TT>Value</TT> is an atom or an integer, <TT>g_link/2</TT> and
<TT>g_assignb/2</TT> have the same behavior. Since <TT>g_link/2</TT> only
handles links to existing terms it does not require extra memory space and
is not expensive in terms of execution time.<BR>
<BR>
NB: argument selectors can only be used with g_assign/2 (i.e. when using
an argument selector inside an assignment, this one must not be
backtrackable).<BR>
<BR>
<B>Errors</B><BR>
<BR>
See common errors detailed in the introduction (section <A HREF="#Global-variables">7.21.1</A>)<BR>
<TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>GVarName</TT> contains an argument selector and the assignment
is backtrackable</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>domain_error(g_argument_selector, GVarName)</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR></TABLE><BR>
<B>Portability</B><BR>
<BR>
GNU Prolog predicates.<BR>
<BR>
<A NAME="toc173"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc216">7.21.3</A></B></TD>
<TD WIDTH="100%" ALIGN=center><TT><B>g_read/2</B></TT></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<BR>
<B>Templates</B>
<DL COMPACT=compact><DT><DD><TT>
g_read(+callable_term, ?term)</TT></DL>
<B>Description</B><BR>
<BR>
<TT>g_read(GVarName, Value)</TT> unifies <TT>Value</TT> with the term
assigned to <TT>GVarName</TT>.<BR>
<BR>
<B>Errors</B><BR>
<BR>
See common errors detailed in the introduction (section <A HREF="#Global-variables">7.21.1</A>)<BR>
<BR>
<B>Portability</B><BR>
<BR>
GNU Prolog predicate.<BR>
<BR>
<A NAME="toc174"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc217">7.21.4</A></B></TD>
<TD WIDTH="100%" ALIGN=center><TT><B>g_array_size/2</B></TT></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<BR>
<B>Templates</B>
<DL COMPACT=compact><DT><DD><TT>
g_array_size(+callable_term, ?integer)</TT></DL>
<B>Description</B><BR>
<BR>
<TT>g_array_size(GVarName, Value)</TT> unifies <TT>Size</TT> with the
dimension (an integer > 0) of the array assigned to <TT>GVarName</TT>.
Fails if <TT>GVarName</TT> is not an array.<BR>
<BR>
<B>Errors</B><BR>
<BR>
See common errors detailed in the introduction (section <A HREF="#Global-variables">7.21.1</A>)<BR>
<TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>Size</TT> is neither a variable nor an integer</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>type_error(integer, Size)</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR></TABLE><BR>
<B>Portability</B><BR>
<BR>
GNU Prolog predicate.<BR>
<BR>
<A NAME="toc175"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc218">7.21.5</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B><TT>g_inc/3</TT>,
<TT>g_inc/2</TT>,
<TT>g_inco/2</TT>,
<TT>g_inc/1</TT>,
<TT>g_dec/3</TT>,
<TT>g_dec/2</TT>,
<TT>g_deco/2</TT>,
<TT>g_dec/1</TT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
<BR>
<B>Templates</B>
<DL COMPACT=compact><DT><DD><TT>
g_inc(+callable_term, ?integer, ?integer)<BR>
g_inc(+callable_term, ?integer)<BR>
g_inco(+callable_term, ?integer)<BR>
g_inc(+callable_term)<BR>
g_dec(+callable_term, ?integer, ?integer)<BR>
g_dec(+callable_term, ?integer)<BR>
g_deco(+callable_term, ?integer)<BR>
g_dec(+callable_term)</TT></DL>
<B>Description</B><BR>
<BR>
<TT>g_inc(GVarName, Old, New)</TT> unifies <TT>Old</TT> with the
integer assigned to <TT>GVarName</TT>, increments <TT>GVarName</TT> and
then unifies <TT>New</TT> with the incremented value.<BR>
<BR>
<TT>g_inc(GVarName, New)</TT> is equivalent to
<TT>g_inc(GVarName, _, New)</TT>.<BR>
<BR>
<TT>g_inco(GVarName, Old)</TT> is equivalent to
<TT>g_inc(GVarName, Old, _)</TT>.<BR>
<BR>
<TT>g_inc(GVarName)</TT> is equivalent to <TT>g_inc(GVarName, _, _)</TT>.<BR>
<BR>
Predicates <TT>g_dec</TT> are similar but decrement the content of
<TT>GVarName</TT> instead.<BR>
<BR>
<B>Errors</B><BR>
<BR>
See common errors detailed in the introduction (section <A HREF="#Global-variables">7.21.1</A>)<BR>
<TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>Old</TT> is neither a variable nor an integer</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>type_error(integer, Old)</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>New</TT> is neither a variable nor an integer</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>type_error(integer, New)</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>GVarName</TT> stores an array</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>type_error(integer, g_array)</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>GVarName</TT> stores a term <TT>T</TT> which is not an integer</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>type_error(integer, T)</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR></TABLE><BR>
<B>Portability</B><BR>
<BR>
GNU Prolog predicates.<BR>
<BR>
<A NAME="toc176"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc219">7.21.6</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B><TT>g_set_bit/2</TT>,
<TT>g_reset_bit/2</TT>,
<TT>g_test_set_bit/2</TT>,
<TT>g_test_reset_bit/2</TT></B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE><BR>
<BR>
<B>Templates</B>
<DL COMPACT=compact><DT><DD><TT>
g_set_bit(+callable_term, +integer)<BR>
g_reset_bit(+callable_term, +integer)<BR>
g_test_set_bit(+callable_term, +integer)<BR>
g_test_reset_bit(+callable_term, +integer)</TT></DL>
<B>Description</B><BR>
<BR>
<TT>g_set_bit(GVarName, Bit)</TT> sets to 1 the bit number specified by
<TT>Bit</TT> of the integer assigned to <TT>GVarName</TT> to 1. Bit numbers
range from 0 to the maximum number allowed for integers (this is architecture dependent). If <TT>Bit</TT> is greater than this limit,
the modulo with this limit is taken.<BR>
<BR>
<TT>g_reset_bit(GVarName, Bit)</TT> is similar to <TT>g_set_bit/2</TT> but
sets the specified bit to 0.<BR>
<BR>
<TT>g_test_set_bit/2</TT> succeeds if the specified bit is set to 1.<BR>
<BR>
<TT>g_test_reset_bit/2</TT> succeeds if the specified bit is set to 0.<BR>
<BR>
<B>Errors</B><BR>
<BR>
See common errors detailed in the introduction (section <A HREF="#Global-variables">7.21.1</A>)<BR>
<TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>Bit</TT> is a variable</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>instantiation_error</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>Bit</TT> is neither a variable nor an integer</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>type_error(integer, Bit)</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>Bit</TT> is an integer < 0</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>domain_error(not_less_than_zero, Bit)</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>GVarName</TT> stores an array</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>type_error(integer, g_array)</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT>GVarName</TT> stores a term <TT>T</TT> which is not an integer</TD>
<TD VALIGN=top ALIGN=center NOWRAP> </TD>
<TD VALIGN=top ALIGN=left><TT>type_error(integer, T)</TT></TD>
</TR>
<TR><TD BGCOLOR=black COLSPAN=3><TABLE BORDER=0 WIDTH="100%" CELLSPACING=0 CELLPADDING=1><TR><TD></TD></TR></TABLE></TD>
</TR></TABLE><BR>
<B>Portability</B><BR>
<BR>
GNU Prolog predicates.<BR>
<BR>
<A NAME="toc177"></A><TABLE CELLPADDING=0 CELLSPACING=0 WIDTH="100%">
<TR><TD BGCOLOR="#98e7ff"><DIV ALIGN=center><TABLE>
<TR><TD><B><A NAME="htoc220">7.21.7</A></B></TD>
<TD WIDTH="100%" ALIGN=center><B>Examples</B></TD>
</TR></TABLE></DIV></TD>
</TR></TABLE>
<A NAME="Examples"></A><BR>
<B>Simulating <TT>g_inc/3</TT></B>: this predicate behaves like:
global variable:
<DL COMPACT=compact><DT><DD>
<PRE>
my_g_inc(Var, Old, New) :-
g_read(Var, Old),
N is Value + 1,
g_assign(Var, X),
New = N.
</PRE></DL>
The query: <TT>my_g_inc(c, X, _)</TT> will succeed unifying <TT>X</TT> with
<TT>0</TT>, another call to <TT>my_g_inc(a, Y, _)</TT> will then unify
<TT>Y</TT> with <TT>1</TT>, and so on.<BR>
<BR>
<B>Difference between <TT>g_assign/2</TT> and <TT>g_assignb/2</TT></B>:
<TT>g_assign/2</TT> does not undo its assignment when backtracking occurs
whereas <TT>g_assignb/2</TT> undoes it.
<DL COMPACT=compact><DT><DD><TT>
</TT><TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD VALIGN=top ALIGN=left><TT>test(Old) :-</TT></TD>
<TD VALIGN=top ALIGN=center NOWRAP><TT> </TT></TD>
<TD VALIGN=top ALIGN=left NOWRAP><TT>testb(Old) :-</TT></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT> g_assign(x,1),</TT></TD>
<TD VALIGN=top ALIGN=center NOWRAP><TT> </TT></TD>
<TD VALIGN=top ALIGN=left NOWRAP><TT> g_assign(x,1),</TT></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT> ( g_read(x, Old),</TT></TD>
<TD VALIGN=top ALIGN=center NOWRAP><TT> </TT></TD>
<TD VALIGN=top ALIGN=left NOWRAP><TT> ( g_read(x, Old),</TT></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT> <I>g_assign</I>(x, 2)</TT></TD>
<TD VALIGN=top ALIGN=center NOWRAP><TT> </TT></TD>
<TD VALIGN=top ALIGN=left NOWRAP><TT> <I>g_assignb</I>(x, 2)</TT></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT> ; g_read(x, Old),</TT></TD>
<TD VALIGN=top ALIGN=center NOWRAP><TT> </TT></TD>
<TD VALIGN=top ALIGN=left NOWRAP><TT> ; g_read(x, Old),</TT></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT> g_assign(x, 3)</TT></TD>
<TD VALIGN=top ALIGN=center NOWRAP><TT> </TT></TD>
<TD VALIGN=top ALIGN=left NOWRAP><TT> g_assign(x, 3)</TT></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT> ).</TT></TD>
<TD VALIGN=top ALIGN=center NOWRAP><TT> </TT></TD>
<TD VALIGN=top ALIGN=left NOWRAP><TT> ).</TT></TD>
</TR></TABLE><TT>
</TT></DL>
The query <TT>test(Old)</TT> will succeed unifying <TT>Old</TT> with
<TT>1</TT> and on backtracking with <TT>2</TT> (i.e. the assignment of the
value <TT>2</TT> has not been undone). The query <TT>testb(Old)</TT> will
succeed unifying <TT>Old</TT> with <TT>1</TT> and on backtracking with
<TT>1</TT> (i.e. the assignment of the value <TT>2</TT> has been undone). <BR>
<BR>
<B>Difference between <TT>g_assign/2</TT> and <TT>g_link/2</TT></B>:
<TT>g_assign/2</TT> (and <TT>g_assignb/2</TT>) creates a copy of the term
whereas <TT>g_link/2</TT> does not. <TT>g_link/2</TT> can be used to avoid
passing big data structures (e.g. dictionaries,...) as arguments to
predicates.
<DL COMPACT=compact><DT><DD><TT>
</TT><TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD VALIGN=top ALIGN=left><TT>test(B) :-</TT></TD>
<TD VALIGN=top ALIGN=center NOWRAP><TT> </TT></TD>
<TD VALIGN=top ALIGN=left NOWRAP><TT>test(B) :-</TT></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT> <I>g_assign</I>(b, f(X)),</TT></TD>
<TD VALIGN=top ALIGN=center NOWRAP><TT> </TT></TD>
<TD VALIGN=top ALIGN=left NOWRAP><TT> <I>g_link</I>(b, f(X)),</TT></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT> X = 12,</TT></TD>
<TD VALIGN=top ALIGN=center NOWRAP><TT> </TT></TD>
<TD VALIGN=top ALIGN=left NOWRAP><TT> X = 12,</TT></TD>
</TR>
<TR><TD VALIGN=top ALIGN=left><TT> g_read(b, B).</TT></TD>
<TD VALIGN=top ALIGN=center NOWRAP><TT> </TT></TD>
<TD VALIGN=top ALIGN=left NOWRAP><TT> g_read(b, B).</TT></TD>
</TR></TABLE><TT>
</TT></DL>
The query <TT>test(B)</TT> will succeed unifying <TT>B</TT> with
<TT>f(_)</TT> (<TT>g_assign/2</TT> assigns a copy of the value). The query
<TT>testl(B)</TT> will succeed unifying <TT>B</TT> with <TT>f(12)</TT>
(<TT>g_link/2</TT> assigns a pointer to the term). <BR>
<BR>
<B>Simple array definition</B>: here are some queries to show how arrays
can be handled:
<DL COMPACT=compact><DT><DD>
<PRE>
| ?- g_assign(w, g_array(3)), g_read(w, X).
X = g_array([0,0,0])
| ?- g_assign(w(0), 16), g_assign(w(1), 32), g_assign(w(2), 64), g_read(w, X).
X = g_array([16,32,64])
</PRE></DL>
this is equivalent to:
<DL COMPACT=compact><DT><DD>
<PRE>
| ?- g_assign(k, g_array([16,32,64])), g_read(k, X).
X = g_array([16,32,64])
| ?- g_assign(k, g_array(3,null)), g_read(k, X), g_array_size(k, S).
S = 3
X = g_array([null,null,null])
</PRE></DL>
<B>2-D array definition</B>:
<DL COMPACT=compact><DT><DD>
<PRE>
| ?- g_assign(w, g_array(2, g_array(3))), g_read(w, X).
X = g_array([g_array([0,0,0]),g_array([0,0,0])])
| ?- ( for(I,0,1), for(J,0,2), K is I*3+J, g_assign(w(I,J), K),
fail
; g_read(w, X)
).
X = g_array([g_array([0,1,2]),g_array([3,4,5])])
| ?- g_read(w(1),X).
X = g_array([3,4,5])
</PRE></DL>
<B>Hybrid array</B>:
<DL COMPACT=compact><DT><DD>
<PRE>
| ?- g_assign(w,g_array([1,2,g_array([a,b,c]), g_array(2,z),5])), g_read(w, X).
X = g_array([1,2,g_array([a,b,c]), g_array([z,z]),5])
| ?- g_read(w(1), X), g_read(w(2,1), Y), g_read(w(3,1), Z).
X = 2
Y = b
Z = z
| ?- g_read(w(1,2),X).
uncaught exception: error(domain_error(g_array_index,w(1,2)),g_read/2)
</PRE></DL>
<B>Array extension</B>:
<DL COMPACT=compact><DT><DD>
<PRE>
| ?- g_assign(a, g_array([10,20,30])), g_read(a, X).
X = g_array([10,20,30])
| ?- g_assign(a, g_array_extend(5,null)), g_read(a, X).
X = g_array([10,20,30,null,null])
| ?- g_assign(a, g_array([10,20,30])), g_read(a, X).
X = g_array([10,20,30])
| ?- g_assign(a, g_array_extend([1,2,3,4,5,6])), g_read(a, X).
X = g_array([10,20,30,4,5,6])
</PRE></DL>
<B>Automatic array</B>:
<DL COMPACT=compact><DT><DD>
<PRE>
| ?- g_assign(t, g_array_auto(3)), g_assign(t(1), foo), g_read(t,X).
X = g_array([0,foo,0])
| ?- g_assign(t(5), bar), g_read(t,X).
X = g_array([0,foo,0,0,0,bar,0,0])
| ?- g_assign(t, g_array_auto(2, g_array(2))), g_assign(t(1,1), foo),
g_read(t,X).
X = g_array([g_array([0,0]),g_array([0,foo])])
| ?- g_assign(t(3,0), bar), g_read(t,X).
X = g_array([g_array([0,0]),g_array([0,foo]),g_array([0,0]),g_array([bar,0])])
| ?- g_assign(t(3,4), bar), g_read(t,X).
uncaught exception: error(domain_error(g_array_index,t(3,4)),g_assign/2)
| ?- g_assign(t, g_array_auto(2, g_array_auto(2))), g_assign(t(1,1), foo),
g_read(t,X).
X = g_array([g_array([0,0]),g_array([0,foo])])
| ?- g_assign(t(3,3), bar), g_read(t,X).
X = g_array([g_array([0,0]),g_array([0,foo]),g_array([0,0]),
g_array([0,0,0,bar])])
| ?- g_assign(t, g_array_auto(2, g_array_auto(2, null))), g_read(t(2,3), U),
g_read(t, X).
U = null
X = g_array([g_array([null,null]),g_array([null,null]),
g_array([null,null,null,null]),g_array([null,null])])
</PRE></DL>
<HR SIZE=2>
Copyright (C) 1999-2002 Daniel Diaz
<BR>
<BR>
Verbatim copying and distribution of this entire article is permitted in any
medium, provided this notice is preserved. <BR>
<BR>
<A HREF="index.html#copyright">More about the copyright</A>
<HR>
<A HREF="manual043.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual023.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="manual045.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
