1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
|
<!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.08">
<LINK rel="stylesheet" type="text/css" href="gprolog.css">
<TITLE>
Global variables
</TITLE>
</HEAD>
<BODY TEXT=black BGCOLOR=white>
<A HREF="gprolog043.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="gprolog023.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="gprolog045.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>
<H3 CLASS="subsection"><A NAME="htoc213">7.21</A> Global variables</H3><UL>
<LI><A HREF="gprolog044.html#toc171">Introduction</A>
<LI><A HREF="gprolog044.html#toc172"><TT>g_assign/2</TT>,
<TT>g_assignb/2</TT>,
<TT>g_link/2</TT></A>
<LI><A HREF="gprolog044.html#toc173"><TT>g_read/2</TT></A>
<LI><A HREF="gprolog044.html#toc174"><TT>g_array_size/2</TT></A>
<LI><A HREF="gprolog044.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="gprolog044.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="gprolog044.html#toc177">Examples</A>
</UL>
<A NAME="toc171"></A>
<H4 CLASS="subsubsection"><A NAME="htoc214">7.21.1</A> Introduction</H4>
<A NAME="Global-variables"></A>
GNU Prolog provides a simple and powerful way to assign and read global
variables. A global variable is associated with each atom, its initial value is
the integer 0. A global variable can store 3 kinds of objects:
<UL CLASS="itemize"><LI CLASS="li-itemize">a copy of a term (the assignment can be made backtrackable or not).<BR>
<BR>
<LI CLASS="li-itemize">a link to a term (the assignment is always backtrackable).<BR>
<BR>
<LI CLASS="li-itemize">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 with 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 with 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="gprolog037.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 CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list">
<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 with <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 with <TT>t</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>t(k)</TT></TD>
<TD ALIGN=left NOWRAP>if the value associated with <TT>k</TT> is I, the Ith element of the array associated with <TT>t</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>a-1-2</TT></TD>
<TD ALIGN=left NOWRAP>if the value associated with <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 with 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 CLASS="itemize"><LI CLASS="li-itemize"><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 CLASS="li-itemize"><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 CLASS="li-itemize"><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 CLASS="itemize"><LI CLASS="li-itemize"><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 CLASS="li-itemize"><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 CLASS="li-itemize"><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>
<H4 CLASS="subsubsection"><A NAME="htoc215">7.21.2</A> <TT>g_assign/2</TT>,
<TT>g_assignb/2</TT>,
<TT>g_link/2</TT></H4>
<A NAME="g-assign/2"></A>
<B>Templates</B>
<DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list"><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>
<H4 CLASS="subsubsection"><A NAME="htoc216">7.21.3</A> <TT>g_read/2</TT></H4>
<B>Templates</B>
<DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list"><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>
<H4 CLASS="subsubsection"><A NAME="htoc217">7.21.4</A> <TT>g_array_size/2</TT></H4>
<B>Templates</B>
<DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list"><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>
<H4 CLASS="subsubsection"><A NAME="htoc218">7.21.5</A> <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></H4>
<B>Templates</B>
<DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list"><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>
<H4 CLASS="subsubsection"><A NAME="htoc219">7.21.6</A> <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></H4>
<B>Templates</B>
<DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list"><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>
<H4 CLASS="subsubsection"><A NAME="htoc220">7.21.7</A> Examples</H4>
<A NAME="Examples"></A>
<B>Simulating <TT>g_inc/3</TT></B>: this predicate behaves like:
global variable:
<DL CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list">
<PRE CLASS="verbatim">
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 CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list"><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 CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list"><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 CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list">
<PRE CLASS="verbatim">
| ?- 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 CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list">
<PRE CLASS="verbatim">
| ?- 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 CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list">
<PRE CLASS="verbatim">
| ?- 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 CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list">
<PRE CLASS="verbatim">
| ?- 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 CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list">
<PRE CLASS="verbatim">
| ?- 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 CLASS="list" COMPACT="compact"><DT CLASS="dt-list"><DD CLASS="dd-list">
<PRE CLASS="verbatim">
| ?- 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-2007 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="gprolog043.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="gprolog023.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="gprolog045.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
|
