Debian Codegraph @

ipl/packs/loadfuncpp/doc/manual.htm

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2 <HTML>
3
4 <HEAD>
5 <META HTTP-EQUIV="Content-Type" CONTENT="text/html;CHARSET=iso-8859-1">
6 <TITLE>loadfuncpp</TITLE>
7 <LINK REL="stylesheet" TYPE="text/css" HREF="loadfuncpp.css">
8 </HEAD>
9
10 <BODY>
11
12 <CENTER>
13 <P>
14 <TABLE BORDER="0" WIDTH="700">
15 <TR>
16 <TD WIDTH="100%">
17 <H1 ALIGN="CENTER"><BR>
18 Loadfuncpp</H1>
19 <H2 ALIGN="CENTER">How to Write External Functions and Libraries<BR>
20 for <A HREF="http://www.cs.arizona.edu/icon/lb3.htm" target="_blank">The Icon Programming Language</A> in C++</H2>
21 <H3 ALIGN="CENTER">Carl Sturtivant, February 2010, <FONT COLOR="#FF9900">version 0.91alpha</FONT></H3>
22 <BLOCKQUOTE>
23 <H2><A NAME="Contents"></A>Contents</H2>
24 <UL>
25 <LI><A HREF="#Contents">Contents</A>
26 <LI><A HREF="#Summary">Summary</A>
27 <LI><A HREF="#Installation">Installation</A>
28 <UL>
29 <LI><A HREF="#CorrectIconInstallation">Correct Icon Installation</A>
30 <LI><A HREF="#DefaultPlacement">Default Placement of Loadfuncpp Files</A>
31 <LI><A HREF="#AlternativePlacement">Alternative Placement of Loadfuncpp Files</A>
32 <LI><A HREF="#LoadfuncppInstallationTest">Loadfuncpp Installation Test</A>
33 </UL>
34 <LI><A HREF="#Manual">Manual</A>
35 <UL>
36 <LI><A HREF="#Writing">Writing, Loading and Calling an External Function</A>
37 <LI><A HREF="#Working">Working with Icon Values</A>
38 <UL>
39 <LI><A HREF="#Initialization">Assignment &amp; Initialization</A>
40 <LI><A HREF="#Operations">Icon Operations</A>
41 <LI><A HREF="#Functions">Icon Built-in Functions</A>
42 <LI><A HREF="#Keywords">Icon Keywords</A>
43 <LI><A HREF="#Types">Types, Conversions and Errors</A>
44 </UL>
45 <LI><A HREF="#Variadic">Variadic Functions and Dynamic List Construction</A>
46 <LI><A HREF="#Calling">Calling Icon from C++</A>
47 <LI><A HREF="#Generators">Working with Generators</A>
48 <UL>
49 <LI><A HREF="#Generate">Writing External Functions that are Generators</A>
50 <LI><A HREF="#Iterate">Calling Icon Procedures that are Generators in C++</A>
51 <LI><A HREF="#Bang">Iterating over Exploded Structures in C++</A>
52 <LI><A HREF="#Coexpressions">Working with Coexpressions in C++</A>
53 </UL>
54 <LI><A HREF="#Externals">Working with External Values</A>
55 <LI><A HREF="#Records">Using Icon Records as Objects</A>
56 </UL>
57 </UL>
58 <H2><A NAME="Summary"></A>Summary</H2>
59 <P>Since 1996 a new function for Version 9 of <A HREF="http://www.cs.arizona.edu/icon/" target="_blank">Icon</A>
60 could be written in C following a certain <A HREF="http://www.cs.arizona.edu/icon/uguide/cfuncs.htm" target="_blank">interface</A>,
61 and compiled into a shared library, where such is a <A HREF="http://www.ibm.com/developerworks/library/l-shobj/"
62 target="_blank">shared object</A> (.so) under Unix-like operating systems. More recently this has been implemented
63 using dynamically linked libraries (DLLs) under <A HREF="http://www.cs.arizona.edu/icon/uguide/relnotes.htm"
64 target="_blank">cygwin</A>. The library could then be dynamically loaded by an Icon program calling the built-in
65 function <A HREF="http://www.cs.arizona.edu/icon/uguide/cfuncs.htm" target="_blank">loadfunc</A> which is passed
66 the location and name of the library and the name of the C function desired, and which returns an Icon function
67 that can subsequently be called. A suite of useful <A HREF="http://www.cs.arizona.edu/icon/library/fcfuncs.htm"
68 target="_blank">examples</A> of this technique is a part of the distribution of Icon.</P>
69 <P>Writing a significantly complex external function for use by <A HREF="http://www.cs.arizona.edu/icon/uguide/cfuncs.htm"
70 target="_blank">loadfunc</A> is potentially difficult for two reasons. First, an Icon structure (or other value,
71 string, list, set, table, et cetera) referred to solely by variables inside external code could be garbage collected
72 by Icon. Second, working directly with Icon data more complex than numbers, strings and files requires a thorough
73 understanding of the <A HREF="http://www.cs.arizona.edu/icon/ftp/doc/ib1up.pdf" target="_blank">implementation
74 of Icon</A>. The Icon runtime system is implemented in an <A HREF="http://www.cs.arizona.edu/icon/ftp/doc/ipd261.pdf"
75 target="_blank">extension of C</A> that is automatically translated into C. The design of the Icon virtual machine
76 is not object oriented, and contains a great deal of straight-line code. Icon structures are operated upon as combinations
77 of complex linked blocks. Writing code to work directly with such is lengthy, error prone and time consuming.</P>
78 <P>Loadfuncpp is a tool that makes writing external functions for Icon a relatively simple matter, requiring very
79 little understanding of the implementation of the Icon virtual machine. Loadfuncpp exploits the close compatibility
80 of C and C++ to provide a clean abstract interface to Icon. External functions for Icon are declared with C linkage,
81 and the Icon virtual machine requires no modification to use external functions written using loadfuncpp.</P>
82 <P>Beginning C++ programmers with programming experience in other languages should have little difficulty with
83 using loadfuncpp. It is not necessary to use templates, exceptions, or RTTI to use loadfuncpp. Little beyond some
84 C experience plus how to define a simple class with virtual and non-virtual member functions is needed to use loadfuncpp.
85 So C programmers with OOP experience but without C++ experience will also find loadfuncpp not difficult to use.</P>
86 <P>Loadfuncpp makes extensive use of operator overloading and other techniques to provide in C++ essentially the
87 same suite of operations, functions and capabilities that are available to the Icon programmer in Icon. The use
88 of these facilities in C++ is at most an order of magnitude more difficult than the corresponding Icon, and is
89 often much easier than that. These facilities include the ability to write external functions that suspend a sequence
90 of results, and the ability to call an Icon procedure that returns a value, which may in turn call a function that
91 calls Icon recursively in the same fashion.</P>
92 <P>These facilities also include the ability to create, activate and refresh coexpressions, the ability to write
93 external functions that are new string matching or string analysis functions, and the ability to work with all kinds
94 of Icon data as if they were built-in types. Loadfuncpp also provides garbage collection safety as a matter of
95 course, largely transparently to the C++ programmer. Loadfuncpp also provides a simple way to add new datatypes
96 to Icon using the new <A HREF="http://www.cs.arizona.edu/icon/uguide/extlvals.htm" target="_blank">external values</A>
97 added to Icon version 9.5 in 2008. These are used extensively by loadfuncpp, and so loadfuncpp cannot be used with
98 versions of Icon prior to 9.5.</P>
99 <P>Loadfuncpp consists of three shared libraries (iload.so, loadnogpx.so and iloadgpx.so) normally placed in the
100 icon/bin directory (all are actually DLLs under cygwin despite the .so filename extension, and import library called
101 iload.a is used to link to them under cygwin) together with a small amount of Icon in loadfuncpp.icn, compiled
102 into loadfuncpp.u1 and loadfuncpp.u2 (using 'icont -c loadfuncpp.icn') which are normally placed in the icon/lib
103 directory. Loadfuncpp may then be used by an Icon program by adding the line 'link loadfuncpp' which makes the
104 function loadfuncpp available to Icon.</P>
105 <P>The function loadfuncpp is used in place of loadfunc to dynamically load external functions written to use the
106 loadfuncpp interface. The library containing loadfuncpp is itself loaded by an implicit call to loadfunc. The first
107 call to loadfuncpp loads iload.so (and also loads iloadgpx.so if the Icon installation supports graphics and iloadnogpx.so
108 if not) and replaces loadfuncpp by an external function in iload.so of the same name. This sequence of events makes
109 the C++ interface in iload.so available to all libraries subsequently loaded by Icon through calls of loadfuncpp.</P>
110 <H2><A NAME="Installation"></A>Installation</H2>
111 <P>Installation of Loadfuncpp is in three parts. First ensuring a correct Icon installation. Second placing the
112 loadfuncpp files appropriately. And third, ensuring that environment variables are set appropriately if the default
113 locations of loadfuncpp files are not used.</P>
114 <H3><A NAME="CorrectIconInstallation"></A>Correct Icon Installation</H3>
115 <P>You will need to install Icon version 9.5 Loadfuncpp to run. To verify you are running the correct version of
116 Icon, use `<A HREF="http://www.cs.arizona.edu/icon/refernce/icontx.htm#icont" target="_blank">icont</A> -V` and
117 `<A HREF="http://www.cs.arizona.edu/icon/refernce/icontx.htm#iconx" target="_blank">iconx</A> -V`.
118 <H3><A NAME="DefaultPlacement"></A>Default Placement of Loadfuncpp Files</H3>
119 <P>Loadfuncpp consists of the following files. Starting now (2010/2/8) loadfuncpp is available as an <A HREF="loadfuncpp.htm"
120 target="_blank">experimental source distribution.</A> I intend to do no further work on it. Use <I>make</I> and
121 examine the following files.
122 <BLOCKQUOTE>
123 <P>
124 <TABLE BORDER="0" WIDTH="585">
125 <TR>
126 <TD WIDTH="26%">
127 <P>iload.so
128 </TD>
129 <TD WIDTH="74%">
130 <P>C++ part of the loadfuncpp interface to <A HREF="http://www.cs.arizona.edu/icon/refernce/icontx.htm#iconx" target="_blank">iconx</A>
131 </TD>
132 </TR>
133 <TR>
134 <TD WIDTH="26%">
135 <P>loadfuncpp.icn
136 </TD>
137 <TD WIDTH="74%">
138 <P>Icon part of the loadfuncpp interface to <A HREF="http://www.cs.arizona.edu/icon/refernce/icontx.htm#iconx"
139 target="_blank">iconx</A>
140 </TD>
141 </TR>
142 <TR>
143 <TD WIDTH="26%">
144 <P>iloadgpx.so
145 </TD>
146 <TD WIDTH="74%">
147 <P>C++ interface needed with the graphics build of Icon
148 </TD>
149 </TR>
150 <TR>
151 <TD WIDTH="26%">
152 <P>iloadnogpx.so
153 </TD>
154 <TD WIDTH="74%">
155 <P>C++ interface needed with the non-graphics build of Icon
156 </TD>
157 </TR>
158 <TR>
159 <TD WIDTH="26%">
160 <P>loadfuncpp.h
161 </TD>
162 <TD WIDTH="74%">
163 <P>C++ header for writing new external functions
164 </TD>
165 </TR>
166 </TABLE>
167 </P>
168 </BLOCKQUOTE>
169 <P>The default installation of these files is as follows. (Here we assume that the directory containing your Icon
170 installation is called icon.) I recommend that you use these locations unless there is a compelling reason not
171 to.</P>
172 <P>
173 <TABLE BORDER="0" WIDTH="585">
174 <TR>
175 <TD WIDTH="26%">
176 <P>iload.so
177 </TD>
178 <TD WIDTH="74%">
179 <P>icon/bin
180 </TD>
181 </TR>
182 <TR>
183 <TD WIDTH="26%">
184 <P>iload.a
185 </TD>
186 <TD WIDTH="74%">
187 <P>icon/bin (cygwin only)
188 </TD>
189 </TR>
190 <TR>
191 <TD WIDTH="26%">
192 <P>loadfuncpp.u1
193 </TD>
194 <TD WIDTH="74%">
195 <P>icon/lib (from loadfuncpp.icn)
196 </TD>
197 </TR>
198 <TR>
199 <TD WIDTH="26%">
200 <P>loadfuncpp.u2
201 </TD>
202 <TD WIDTH="74%">
203 <P>icon/lib (from loadfuncpp.icn)
204 </TD>
205 </TR>
206 <TR>
207 <TD WIDTH="26%">
208 <P>iloadgpx.so
209 </TD>
210 <TD WIDTH="74%">
211 <P>icon/bin
212 </TD>
213 </TR>
214 <TR>
215 <TD WIDTH="26%">
216 <P>iloadnogpx.so
217 </TD>
218 <TD WIDTH="74%">
219 <P>icon/bin
220 </TD>
221 </TR>
222 <TR>
223 <TD WIDTH="26%">
224 <P>loadfuncpp.h
225 </TD>
226 <TD WIDTH="74%">
227 <P>wherever is convenient to #include in C++ source
228 </TD>
229 </TR>
230 </TABLE>
231 <BR>
232 Under <I>cygwin only</I> there is one additional file used when <A HREF="compile.htm" target="_blank">linking</A>
233 a dynamic library that uses loadfuncpp. This is the windows import library iload.a, and is most naturally placed
234 in the same directory as iload.so, as it contains the information necessary to link against it.
235 <H3><A NAME="AlternativePlacement"></A>Alternative Placement of Loadfuncpp Files</H3>
236 <P>Alternatively, you can place iload.so and iloadgpx.so anywhere you please and set the environment variable FPATH
237 to include the directories containing iload.so and iloadgpx.so. FPATH should be a space or colon separated string
238 of locations. You can compile loadfuncpp.icn using `icont -c loadfuncpp.icn` and place the resulting files (loadfuncpp.u1
239 and loadfuncpp.u2) in any directory and set the environment variable IPATH to include that directory. IPATH should
240 also be a space or colon separated string of locations.
241 <H3><A NAME="LoadfuncppInstallationTest"></A>Loadfuncpp Installation Test</H3>
242 <P>Once loadfuncpp is installed, you may test your installation by creating a small new external function and load
243 and call it from Icon. Here's how.</P>
244 <P>
245 <UL>
246 <LI>Create a new directory, place a copy of loadfuncpp.h in it and work there
247 <LI>Edit a new file called (say) hello.cpp to contain the following code
248 <P>
249 <TABLE BORDER="0" WIDTH="312">
250 <TR>
251 <TD WIDTH="312">
252 <PRE><FONT COLOR="black" FACE="Courier New, Courier">#include &quot;loadfuncpp.h&quot;
253
254 extern &quot;C&quot; int hello(value argv[]) {
255 argv[0] = &quot;Hello World&quot;;
256 return SUCCEEDED;
257 }</FONT></PRE>
258 </TD>
259 </TR>
260 </TABLE>
261
262 <LI>Compile hello.cpp into a shared object hello.so using one of these <A HREF="compile.htm" target="_blank">compiler
263 options</A>
264 <LI>Edit a new file called (say) hello.icn to contain the following code and ensure that hello.so is in the same
265 directory
266 <P>
267 <TABLE BORDER="0" WIDTH="392">
268 <TR>
269 <TD WIDTH="392">
270 <PRE><FONT COLOR="black" FACE="Courier New, Courier">link loadfuncpp
271
272 procedure main()
273 hello := loadfuncpp(&quot;./hello.so&quot;, &quot;hello&quot;, 0)
274 write( hello() )
275 end</FONT></PRE>
276 </TD>
277 </TR>
278 </TABLE>
279
280 <LI>Compile hello.icn by typing `icont hello.icn` and run it by typing `./hello` and you should get the output
281 <FONT COLOR="black">Hello World</FONT> appearing in the console.
282 </UL>
283 </BLOCKQUOTE>
284 <BLOCKQUOTE ALIGN="CENTER">
285 <UL>
286 <P>
287 </UL>
288 <P>
289 </BLOCKQUOTE>
290 <BLOCKQUOTE>
291 <H2><A NAME="Manual"></A>Manual</H2>
292 <P>This manual assumes that you have a <A HREF="#Installation">working installation</A> of Loadfuncpp and Icon
293 as described above. An installation of Icon alone is not sufficient, nor can Loadfuncpp be used with any Icon version
294 prior to 9.5, as it relies upon the presence of <A HREF="http://www.cs.arizona.edu/icon/uguide/extlvals.htm"
295 target="_blank">external values</A> which are first implemented as a part of that version.</P>
296 <H3><A NAME="Writing"></A>Writing, Loading and Calling a new External Function</H3>
297 </BLOCKQUOTE>
298 <BLOCKQUOTE ALIGN="CENTER">
299 <P>A new Icon external function written in C++ takes one of the following forms.
300 </BLOCKQUOTE>
301 <BLOCKQUOTE>
302 <BLOCKQUOTE>
303 <P>
304 <TABLE BORDER="0" WIDTH="432">
305 <TR>
306 <TD WIDTH="432">
307 <PRE><FONT COLOR="black" FACE="Courier New, Courier">#include &quot;loadfuncpp.h&quot;
308
309 extern &quot;C&quot; int fixed_arity(value argv[]) {
310 // ... has a fixed number of arguments
311 return SUCCEEDED; //or FAILED
312 }
313
314 extern &quot;C&quot; int variable_arity(int argc, value argv[]){
315 // ... has a variable number of arguments
316 return SUCCEEDED; //or FAILED
317 }</FONT></PRE>
318 </TD>
319 </TR>
320 </TABLE>
321 </P>
322 </BLOCKQUOTE>
323 <P>The C++ type 'value' is an Icon value (called a <A HREF="http://www.cs.arizona.edu/icon/uguide/cfuncs.htm" target="_blank">descriptor</A>),
324 representing null or an integer, real, string, cset, list, table, set, file, procedure, coexpression, record, <A
325 HREF="http://www.cs.arizona.edu/icon/uguide/extlvals.htm" target="_blank">external value</A> or an Icon <A HREF="#Variable">variable</A>.
326 When such a function is called from Icon, its arguments are passed in the array argv starting from argv[1], and
327 argv[0] is taken to be the value returned to Icon by the function. In the function variable_arity the number of
328 arguments is also passed in argc. So the following is a one argument external function that returns its only argument.
329 <BLOCKQUOTE>
330 <P>
331 <TABLE BORDER="0" WIDTH="432">
332 <TR>
333 <TD WIDTH="432">
334 <PRE><FONT COLOR="black" FACE="Courier New, Courier">#include &quot;loadfuncpp.h&quot;
335
336 extern &quot;C&quot; int ident(value argv[]) {
337 argv[0] = argv[1];
338 return SUCCEEDED;
339 }</FONT></PRE>
340 </TD>
341 </TR>
342 </TABLE>
343 </P>
344 </BLOCKQUOTE>
345 <P>The int returned to C++ is a signal to Icon indicating whether the call succeeded or failed. These are represented
346 by the constants SUCCEEDED and FAILED respectively, defined in loadfuncpp.h. However there is also a simple mechanism
347 in loadfuncpp to write <A HREF="#Generate">external functions that suspend a sequence of values</A> when called
348 in Icon.</P>
349 <P>Functions <A HREF="compile.htm" target="_blank">compiled into a shared object</A> are loaded into Icon by calls
350 of loadfuncpp. Such calls indicate to Icon whether the loaded function has a variable or a fixed number of arguments,
351 and if the latter, how many. For example the preceding functions might be loaded into Icon as follows if the body
352 of fixed_arity was written to use two arguments.
353 <BLOCKQUOTE>
354 <P>
355 <TABLE BORDER="0" WIDTH="464">
356 <TR>
357 <TD WIDTH="464">
358 <PRE><FONT COLOR="black" FACE="Courier New, Courier">link loadfuncpp
359
360 procedure main()
361 fixed := loadfuncpp(&quot;./mylib.so&quot;, &quot;fixed_arity&quot;, 2)
362 variadic := loadfuncpp(&quot;./mylib.so&quot;, &quot;variable_arity&quot;)
363 #fixed and variadic now contain Icon functions
364 #and may be treated like any other such values
365 end</FONT></PRE>
366 </TD>
367 </TR>
368 </TABLE>
369 </P>
370 </BLOCKQUOTE>
371 <P>If the number of arguments is not specified when loading a function of fixed <A HREF="http://en.wikipedia.org/wiki/Arity">arity</A>
372 then calling the result from Icon will lead to a memory violation. (Similar behavior will likely occur if a function
373 of variable arity is loaded with a specific arity specified, or if too small an arity is specified for a fixed
374 arity function.) Beware!<BR>
375 <BR>
376 A relative or absolute path to the shared object may be used as the first argument to loadfuncpp, in which case
377 loadfuncpp will look exactly where specified for it and nowhere else. <B>Alternatively, just the filename of the
378 shared object may be specified, in which case Icon will search FPATH for the file.</B> If FPATH is not set in the
379 environment Icon runs in, then iconx defines FPATH to consist of the current directory followed by the icon/bin
380 directory. If FPATH is set in the environment Icon is run in, then iconx appends the icon/bin directory. In either
381 case FPATH should be a space or colon separated series of directories, with no spaces in their paths. (This restriction
382 will be cleaned up &quot;soon&quot;.)</P>
383 <P>All of the C++ in this manual requires '#include &quot;loadfuncpp.h&quot;' and all of the Icon requires 'link
384 loadfuncpp'. Hereafter this will be assumed implicitly.</P>
385 <P>Here is an external function of no arguments that returns null, represented in C++ by the constant nullvalue.
386 <BLOCKQUOTE>
387 <P>
388 <TABLE BORDER="0" WIDTH="432">
389 <TR>
390 <TD WIDTH="432">
391 <PRE><FONT COLOR="black" FACE="Courier New, Courier">extern &quot;C&quot; int dull(value argv[]){
392 argv[0] = nullvalue;
393 return SUCCEEDED;
394 }</FONT></PRE>
395 </TD>
396 </TR>
397 </TABLE>
398 </P>
399 </BLOCKQUOTE>
400 <P>If this is compiled into the shared object 'dull.so' in the current directory then it might be called by Icon
401 as follows.
402 <BLOCKQUOTE>
403 <P>
404 <TABLE BORDER="0" WIDTH="464">
405 <TR>
406 <TD WIDTH="464">
407 <PRE><FONT COLOR="black" FACE="Courier New, Courier">dull := loadfuncpp(&quot;./dull.so&quot;, &quot;dull&quot;, 0)
408 write(image( dull() ))</FONT></PRE>
409 </TD>
410 </TR>
411 </TABLE>
412 </P>
413 </BLOCKQUOTE>
414 <P>The value of argv[0] when an external function is called is of type procedure, and is the Icon value representing
415 the external function being called. So failure to assign to argv[0] means that Icon loads a function that returns
416 itself.</P>
417 <P>The C++ class <B>value</B> is intended to be used primarily in the interface to Icon. Icon structures in variables
418 of this class are not safe from garbage collection. Icon does guarantee that argv[] is garbage collection safe
419 however.</P>
420 <H3><A NAME="Working"></A>Working with Icon values</H3>
421 <P>Variables of the C++ class <B>safe</B> are intended to hold Icon values with guaranteed garbage collection safety.
422 The interface to Icon is largely available through the class safe. Most computation with Icon values in external
423 functions may be implemented through use of the <A HREF="#Operations">overloaded operators</A> in using this class,
424 along with its member functions that represent <A HREF="#Operations">additional Icon operators</A>. Loadfuncpp
425 also provides the <A HREF="#Keywords">Icon keywords</A> and in the namespace '<A HREF="#Builtin">Icon</A>' provides
426 a C++ variant of each of the <A HREF="#Functions">built-in functions in Icon</A>.</P>
427 <H4><A NAME="Initialization"></A>Assignment and Initialization among safe and value</H4>
428 <P>Assignment of a safe to a safe has the semantics of an Icon assignment. Specifically, if the left operand contains
429 an Icon value that is an <A NAME="Variable"></A>Icon <FONT COLOR="black">variable</FONT> (i.e. an Icon value used
430 to refer to the storage containing another Icon value so that the latter can be modified) then the assignment modifies
431 the value referred to by that Icon variable, not the C++ variable whose value is the Icon variable.</P>
432 <P>Assignment is possible among the classes safe and value, and has simple semantics: even values that are Icon
433 variables are copied. Initialization of variables of the class safe is possible from any of safe and value, with
434 the same simple semantics. In both cases the semantics is the same as Icon assignment, except in the case of an
435 Icon variable, which is merely copied, so that the variable assigned or initialized now contains the same Icon
436 variable. This lack of dereferencing is useful if an external function needs to return an Icon variable, in the
437 same way that an Icon procedure may.</P>
438 </BLOCKQUOTE>
439 <BLOCKQUOTE ALIGN="CENTER">
440 <P>A variable of class safe may also be initialized from an array of values as follows.
441 </BLOCKQUOTE>
442 <BLOCKQUOTE>
443 <BLOCKQUOTE>
444 <P>
445 <TABLE BORDER="0" WIDTH="432">
446 <TR>
447 <TD WIDTH="432">
448 <PRE><FONT COLOR="black" FACE="Courier New, Courier">extern &quot;C&quot; int makelist(int argc, value argv[]){
449 safe arglist(argc, argv);
450 argv[0] = arglist;
451 return SUCCEEDED;
452 }</FONT></PRE>
453 </TD>
454 </TR>
455 </TABLE>
456 </P>
457 </BLOCKQUOTE>
458 <P>Such initialization creates an Icon list containing the values in the array starting from position 1. So the
459 above function called from Icon returns a list of its arguments.</P>
460 <P>A variable of class safe may be initialized by or assigned a C string, which causes an Icon string that is a
461 copy of the original to be created, so that the original can safely be modified or destroyed later. If such copying
462 is unwanted because the C string is a literal or constant, then the two argument value constructor may be used
463 as follows.
464 <BLOCKQUOTE>
465 <P>
466 <TABLE BORDER="0" WIDTH="432">
467 <TR>
468 <TD WIDTH="432">
469 <PRE><FONT COLOR="black" FACE="Courier New, Courier">extern &quot;C&quot; int f(value argv[]){
470 safe text = value(StringLiteral, &quot;Hello&quot;);
471 // ...
472 return SUCCEEDED;
473 }</FONT></PRE>
474 </TD>
475 </TR>
476 </TABLE>
477 </P>
478 </BLOCKQUOTE>
479 <P>A variable of class safe may also be initialized by or assigned a C++ long or int causing the creation of an
480 Icon integer. Similarly initialization or assignment of a double causes the creation of an Icon real.</P>
481 <H4><A NAME="Operations"></A>Icon operations on variables of class safe</H4>
482 <P>Here is a table of the overloaded operators and member functions implementing Icon operators for the class safe.
483 These are listed with their Icon equivalents, and with a note of any restrictions or extensions. The <A HREF="#Bang">unary
484 ! operator</A> in Icon is a generator and is supplied through loadfuncpp by <A HREF="#Bang">other means</A>.</P>
485 </BLOCKQUOTE>
486 <BLOCKQUOTE ALIGN="CENTER">
487 <P>
488 <TABLE BORDER="0" WIDTH="585">
489 <TR>
490 <TH COLSPAN="2">
491 <P><FONT SIZE="2" FACE="Courier New, Courier">functions of safe for Icon operators</FONT>
492 </TH>
493 <TD WIDTH="271">
494 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
495 </TD>
496 </TR>
497 <TR>
498 <TH WIDTH="130">
499 <P><FONT SIZE="2" FACE="Courier New, Courier">unary</FONT>
500 </TH>
501 <TH WIDTH="164">
502 <P><FONT SIZE="2" FACE="Courier New, Courier">Icon equivalent</FONT>
503 </TH>
504 <TD WIDTH="271">
505 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
506 </TD>
507 </TR>
508 <TR>
509 <TD WIDTH="130">
510 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">*x</FONT>
511 </TD>
512 <TD WIDTH="164">
513 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">*x</FONT>
514 </TD>
515 <TD WIDTH="271">
516 <P>&nbsp;
517 </TD>
518 </TR>
519 <TR>
520 <TD WIDTH="130">
521 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">~x</FONT>
522 </TD>
523 <TD WIDTH="164">
524 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">~x</FONT>
525 </TD>
526 <TD WIDTH="271">
527 <P>&nbsp;
528 </TD>
529 </TR>
530 <TR>
531 <TD WIDTH="130">
532 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">-x</FONT>
533 </TD>
534 <TD WIDTH="164">
535 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">-x</FONT>
536 </TD>
537 <TD WIDTH="271">
538 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
539 </TD>
540 </TR>
541 <TR>
542 <TD WIDTH="130">
543 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">++x</FONT>
544 </TD>
545 <TD WIDTH="164">
546 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x +:= 1</FONT>
547 </TD>
548 <TD WIDTH="271">
549 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
550 </TD>
551 </TR>
552 <TR>
553 <TD WIDTH="130">
554 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">--x</FONT>
555 </TD>
556 <TD WIDTH="164">
557 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x -:= 1</FONT>
558 </TD>
559 <TD WIDTH="271">
560 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
561 </TD>
562 </TR>
563 <TR>
564 <TD WIDTH="130">
565 <P ALIGN="CENTER"><B><FONT SIZE="2" FACE="Courier New, Courier">binary</FONT></B>
566 </TD>
567 <TD WIDTH="164">
568 <P ALIGN="CENTER"><B><FONT SIZE="2" FACE="Courier New, Courier">Icon equivalent</FONT></B>
569 </TD>
570 <TD WIDTH="271">
571 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
572 </TD>
573 </TR>
574 <TR>
575 <TD WIDTH="130">
576 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">=</FONT>
577 </TD>
578 <TD WIDTH="164">
579 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">:=</FONT>
580 </TD>
581 <TD WIDTH="271">
582 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
583 </TD>
584 </TR>
585 <TR>
586 <TD WIDTH="130">
587 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">+= -= *=</FONT>
588 </TD>
589 <TD WIDTH="164">
590 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">+:= -:= *:=</FONT>
591 </TD>
592 <TD WIDTH="271">
593 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
594 </TD>
595 </TR>
596 <TR>
597 <TD WIDTH="130">
598 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">/= %= ^=</FONT>
599 </TD>
600 <TD WIDTH="164">
601 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">/:= %:= ^:=</FONT>
602 </TD>
603 <TD WIDTH="271">
604 <P>&nbsp;
605 </TD>
606 </TR>
607 <TR>
608 <TD WIDTH="130">
609 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">+</FONT>
610 </TD>
611 <TD WIDTH="164">
612 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">+</FONT>
613 </TD>
614 <TD WIDTH="271">
615 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
616 </TD>
617 </TR>
618 <TR>
619 <TD WIDTH="130">
620 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">-</FONT>
621 </TD>
622 <TD WIDTH="164">
623 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">-</FONT>
624 </TD>
625 <TD WIDTH="271">
626 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
627 </TD>
628 </TR>
629 <TR>
630 <TD WIDTH="130">
631 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">*</FONT>
632 </TD>
633 <TD WIDTH="164">
634 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">*</FONT>
635 </TD>
636 <TD WIDTH="271">
637 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
638 </TD>
639 </TR>
640 <TR>
641 <TD WIDTH="130">
642 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">/</FONT>
643 </TD>
644 <TD WIDTH="164">
645 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">/</FONT>
646 </TD>
647 <TD WIDTH="271">
648 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
649 </TD>
650 </TR>
651 <TR>
652 <TD WIDTH="130">
653 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">%</FONT>
654 </TD>
655 <TD WIDTH="164">
656 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">%</FONT>
657 </TD>
658 <TD WIDTH="271">
659 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
660 </TD>
661 </TR>
662 <TR>
663 <TD WIDTH="130">
664 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x^y</FONT>
665 </TD>
666 <TD WIDTH="164">
667 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x^y</FONT>
668 </TD>
669 <TD WIDTH="271">
670 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
671 </TD>
672 </TR>
673 <TR>
674 <TD WIDTH="130">
675 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x | y</FONT>
676 </TD>
677 <TD WIDTH="164">
678 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x ++ y</FONT>
679 </TD>
680 <TD WIDTH="271">
681 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
682 </TD>
683 </TR>
684 <TR>
685 <TD WIDTH="130">
686 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x &amp; y</FONT>
687 </TD>
688 <TD WIDTH="164">
689 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x ** y</FONT>
690 </TD>
691 <TD WIDTH="271">
692 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
693 </TD>
694 </TR>
695 <TR>
696 <TD WIDTH="130">
697 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x &amp;&amp; y</FONT>
698 </TD>
699 <TD WIDTH="164">
700 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x -- y</FONT>
701 </TD>
702 <TD WIDTH="271">
703 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
704 </TD>
705 </TR>
706 <TR>
707 <TD WIDTH="130">
708 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x || y</FONT>
709 </TD>
710 <TD WIDTH="164">
711 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x || y</FONT>
712 </TD>
713 <TD WIDTH="271">
714 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
715 </TD>
716 </TR>
717 <TR>
718 <TD WIDTH="130">
719 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">|=</FONT>
720 </TD>
721 <TD WIDTH="164">
722 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">++:=</FONT>
723 </TD>
724 <TD WIDTH="271">
725 <P>&nbsp;
726 </TD>
727 </TR>
728 <TR>
729 <TD WIDTH="130">
730 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">&amp;=</FONT>
731 </TD>
732 <TD WIDTH="164">
733 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">**:=</FONT>
734 </TD>
735 <TD WIDTH="271">
736 <P>&nbsp;
737 </TD>
738 </TR>
739 <TR>
740 <TD WIDTH="130">
741 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">==</FONT>
742 </TD>
743 <TD WIDTH="164">
744 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">===</FONT>
745 </TD>
746 <TD WIDTH="271">
747 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
748 </TD>
749 </TR>
750 <TR>
751 <TD WIDTH="130">
752 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">!=</FONT>
753 </TD>
754 <TD WIDTH="164">
755 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">~===</FONT>
756 </TD>
757 <TD WIDTH="271">
758 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
759 </TD>
760 </TR>
761 <TR>
762 <TD WIDTH="130">
763 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">&lt; &gt; &lt;= &gt;=</FONT>
764 </TD>
765 <TD WIDTH="164">
766 <P ALIGN="CENTER"><B><FONT SIZE="2" FACE="Courier New, Courier">none</FONT></B>
767 </TD>
768 <TD WIDTH="271">
769 <P><A HREF="#Compare"><FONT SIZE="2" FACE="Courier New, Courier">The comparison used when sorting</FONT></A>
770 </TD>
771 </TR>
772 <TR>
773 <TD WIDTH="130">
774 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x[y]</FONT>
775 </TD>
776 <TD WIDTH="164">
777 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x[y]</FONT>
778 </TD>
779 <TD WIDTH="271">
780 <P>&nbsp;
781 </TD>
782 </TR>
783 <TR>
784 <TD WIDTH="130">
785 <P ALIGN="CENTER"><B><FONT SIZE="2" FACE="Courier New, Courier">variadic</FONT></B>
786 </TD>
787 <TD WIDTH="164">
788 <P ALIGN="CENTER"><B><FONT SIZE="2" FACE="Courier New, Courier">Icon Equivalent</FONT></B>
789 </TD>
790 <TD WIDTH="271">
791 <P>&nbsp;
792 </TD>
793 </TR>
794 <TR>
795 <TD WIDTH="130">
796 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x(...)</FONT>
797 </TD>
798 <TD WIDTH="164">
799 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x(...)</FONT>
800 </TD>
801 <TD WIDTH="271">
802 <P><A HREF="#Call"><FONT SIZE="2" FACE="Courier New, Courier">Icon procedure call</FONT></A>
803 </TD>
804 </TR>
805 <TR>
806 <TD WIDTH="130">
807 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">(a,b ...)</FONT>
808 </TD>
809 <TD WIDTH="164">
810 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">[a,b ...]</FONT>
811 </TD>
812 <TD WIDTH="271">
813 <P><A HREF="#Variadic"><FONT SIZE="2" FACE="Courier New, Courier">Variadic list construction</FONT></A>
814 </TD>
815 </TR>
816 <TR>
817 <TD WIDTH="130">
818 <P ALIGN="CENTER"><B><FONT SIZE="2" FACE="Courier New, Courier">member function</FONT></B>
819 </TD>
820 <TD WIDTH="164">
821 <P ALIGN="CENTER"><B><FONT SIZE="2" FACE="Courier New, Courier">Icon equivalent</FONT></B>
822 </TD>
823 <TD WIDTH="271">
824 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
825 </TD>
826 </TR>
827 <TR>
828 <TD WIDTH="130">
829 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x.slice(y,z)&nbsp;</FONT>
830 </TD>
831 <TD WIDTH="164">
832 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x[y:z]</FONT>
833 </TD>
834 <TD WIDTH="271">
835 <P><FONT SIZE="2" FACE="Courier New, Courier">&nbsp;</FONT>
836 </TD>
837 </TR>
838 <TR>
839 <TD WIDTH="130">
840 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x.apply(y)</FONT>
841 </TD>
842 <TD WIDTH="164">
843 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x ! y</FONT>
844 </TD>
845 <TD WIDTH="271">
846 <P><A HREF="#Call"><FONT SIZE="2" FACE="Courier New, Courier">Apply Icon procedure to arguments</FONT></A>
847 </TD>
848 </TR>
849 <TR>
850 <TD WIDTH="130">
851 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x.listcat(y)</FONT>
852 </TD>
853 <TD WIDTH="164">
854 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x ||| y</FONT>
855 </TD>
856 <TD WIDTH="271">
857 <P>&nbsp;
858 </TD>
859 </TR>
860 <TR>
861 <TD WIDTH="130">
862 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x.swap(y)</FONT>
863 </TD>
864 <TD WIDTH="164">
865 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x :=: y</FONT>
866 </TD>
867 <TD WIDTH="271">
868 <P>&nbsp;
869 </TD>
870 </TR>
871 <TR>
872 <TD WIDTH="130">
873 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x.create()</FONT>
874 </TD>
875 <TD WIDTH="164">
876 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">create !x</FONT>
877 </TD>
878 <TD WIDTH="271">
879 <P><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">&nbsp;</FONT>
880 </TD>
881 </TR>
882 <TR>
883 <TD WIDTH="130">
884 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x.create(y)</FONT>
885 </TD>
886 <TD WIDTH="164">
887 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">create x ! y</FONT>
888 </TD>
889 <TD WIDTH="271">
890 <P>&nbsp;
891 </TD>
892 </TR>
893 <TR>
894 <TD WIDTH="130">
895 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x.activate(y)</FONT>
896 </TD>
897 <TD WIDTH="164">
898 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">y@x</FONT>
899 </TD>
900 <TD WIDTH="271">
901 <P><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">y defaults to &amp;null</FONT>
902 </TD>
903 </TR>
904 <TR>
905 <TD WIDTH="130">
906 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x.refresh()</FONT>
907 </TD>
908 <TD WIDTH="164">
909 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">^x</FONT>
910 </TD>
911 <TD WIDTH="271">
912 <P>&nbsp;
913 </TD>
914 </TR>
915 <TR>
916 <TD WIDTH="130">
917 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x.random()</FONT>
918 </TD>
919 <TD WIDTH="164">
920 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">?x</FONT>
921 </TD>
922 <TD WIDTH="271">
923 <P>&nbsp;
924 </TD>
925 </TR>
926 <TR>
927 <TD WIDTH="130">
928 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x.dereference()</FONT>
929 </TD>
930 <TD WIDTH="164">
931 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">.x</FONT>
932 </TD>
933 <TD WIDTH="271">
934 <P>&nbsp;
935 </TD>
936 </TR>
937 </TABLE>
938 </P>
939 </BLOCKQUOTE>
940 <BLOCKQUOTE>
941 <H4><A NAME="Functions"></A>Icon Built-in Functions</H4>
942 <P>All of the functions built in to Icon are available in C++ in the namespace 'Icon'. The C++ counterpart of an
943 Icon built-in function returns &amp;null if the original function would have failed. Those functions that are generators
944 have been made to produce a single result. Those functions that are <A HREF="#Variadic">variadic</A> have been
945 made C++ compatible too; with a small number of arguments this can usually safely be ignored. The table below lists
946 each C++ variant of each Icon function that is a generator, along with a comment indicating how it has been modified
947 for C++ compatibility.</P>
948 </BLOCKQUOTE>
949 <BLOCKQUOTE ALIGN="CENTER">
950 <P>
951 <TABLE BORDER="0" WIDTH="551">
952 <TR>
953 <TH WIDTH="96">
954 <P><FONT SIZE="2" FACE="Courier New, Courier">Function</FONT>
955 </TH>
956 <TD WIDTH="441">
957 <P>&nbsp;
958 </TD>
959 </TR>
960 <TR>
961 <TD WIDTH="96">
962 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">bal</FONT>
963 </TD>
964 <TD WIDTH="441">
965 <P><FONT SIZE="2" FACE="Courier New, Courier">returns the first result generated only</FONT>
966 </TD>
967 </TR>
968 <TR>
969 <TD WIDTH="96">
970 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">find</FONT>
971 </TD>
972 <TD WIDTH="441">
973 <P><FONT SIZE="2" FACE="Courier New, Courier">returns the first result generated only</FONT>
974 </TD>
975 </TR>
976 <TR>
977 <TD WIDTH="96">
978 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">function</FONT>
979 </TD>
980 <TD WIDTH="441">
981 <P><FONT SIZE="2" FACE="Courier New, Courier">returns a list of the results originally generated</FONT>
982 </TD>
983 </TR>
984 <TR>
985 <TD WIDTH="96">
986 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">key</FONT>
987 </TD>
988 <TD WIDTH="441">
989 <P><FONT SIZE="2" FACE="Courier New, Courier">returns a list of the results originally generated</FONT>
990 </TD>
991 </TR>
992 <TR>
993 <TD WIDTH="96">
994 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">move</FONT>
995 </TD>
996 <TD WIDTH="441">
997 <P><FONT SIZE="2" FACE="Courier New, Courier">cannot be resumed</FONT>
998 </TD>
999 </TR>
1000 <TR>
1001 <TD WIDTH="96">
1002 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">tab</FONT>
1003 </TD>
1004 <TD WIDTH="441">
1005 <P><FONT SIZE="2" FACE="Courier New, Courier">cannot be resumed</FONT>
1006 </TD>
1007 </TR>
1008 <TR>
1009 <TD WIDTH="96">
1010 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">upto</FONT>
1011 </TD>
1012 <TD WIDTH="441">
1013 <P><FONT SIZE="2" FACE="Courier New, Courier">returns the first result generated only</FONT>
1014 </TD>
1015 </TR>
1016 </TABLE>
1017 </P>
1018 </BLOCKQUOTE>
1019 <BLOCKQUOTE>
1020 <P>Here is an example of the use of such Icon built-in functions in a new external function. The following function
1021 returns the set of its arguments.</P>
1022 <BLOCKQUOTE>
1023 <P>
1024 <TABLE BORDER="0" WIDTH="432">
1025 <TR>
1026 <TD WIDTH="432">
1027 <PRE><FONT COLOR="black" FACE="Courier New, Courier">extern &quot;C&quot; int makeset(int argc, value argv[]){
1028 safe arglist(argc, argv);
1029 argv[0] = Icon::set(arglist);
1030 return SUCCEEDED;
1031 }</FONT></PRE>
1032 </TD>
1033 </TR>
1034 </TABLE>
1035 </P>
1036 </BLOCKQUOTE>
1037 <H4><A NAME="Keywords"></A>Icon Keywords</H4>
1038 <P>All of the Icon keywords have been made available apart from &amp;cset (to avoid a possible name collision),
1039 and &amp;fail. The keywords are implemented through a keyword class with the unary '&amp;' operator overloaded
1040 and are used thus in C++, as in the following example.</P>
1041 <BLOCKQUOTE>
1042 <P>
1043 <TABLE BORDER="0" WIDTH="432">
1044 <TR>
1045 <TD WIDTH="432">
1046 <PRE><FONT COLOR="black" FACE="Courier New, Courier">extern &quot;C&quot; int assignprog(value argv[]){
1047 safe newname(argv[1]);
1048 &amp;progname = newname; //Icon assignment semantics
1049 return FAILED;
1050 }</FONT></PRE>
1051 </TD>
1052 </TR>
1053 </TABLE>
1054 </P>
1055 </BLOCKQUOTE>
1056 <P>The preceding function assigns a new value to the keyword &amp;progname, just as in Icon. In all cases a keyword
1057 is used with the unary '&amp;' operator, and therefore appears just as in an Icon program. The keywords that are
1058 generators in Icon produce a list of values in C++.</P>
1059 <H4><A NAME="Types"></A>Types, Conversions and Errors</H4>
1060 <P>A well designed external function will probably do some type checking and conversions of its arguments, and
1061 perhaps give a run-time error if they are problematic.</P>
1062 <P>The member function <FONT COLOR="black">type()</FONT> in the value class returns one of the following constants
1063 indicating its Icon type: <FONT COLOR="black">Null</FONT>, <FONT COLOR="black">Integer</FONT>, <A HREF="#BigInteger">BigInteger</A>,
1064 <FONT COLOR="black">Real</FONT>, <FONT COLOR="black">Cset</FONT>, <FONT COLOR="black">File</FONT>, <FONT COLOR="black">Procedure</FONT>,
1065 <FONT COLOR="black">Record</FONT>, <FONT COLOR="black">List</FONT>, <FONT COLOR="black">Set</FONT>, <FONT COLOR="black">Table</FONT>,
1066 <FONT COLOR="black">String</FONT>, <FONT COLOR="black">Constructor</FONT>, <FONT COLOR="black">Coexpression</FONT>,
1067 <FONT COLOR="black">External</FONT>, or <A HREF="#Variable">Variable</A>. Constructor means a record constructor,
1068 and <A HREF="#BigInteger">BigInteger</A> is an integer with a binary representation larger than a machine word.</P>
1069 <P>The member functions <FONT COLOR="black">isNull()</FONT> and <FONT COLOR="black">notNull()</FONT> in the value
1070 class each return a boolean indicating whether or not the Icon type is null. The member functions <FONT COLOR="black">toInteger()</FONT>,
1071 <FONT COLOR="black">toReal()</FONT>, <FONT COLOR="black">toNumeric()</FONT>, <FONT COLOR="black">toString()</FONT>
1072 and <FONT COLOR="black">toCset()</FONT> in the value class each endeavors to perform a conversion in place to the
1073 corresponding type following the same conventions as Icon. Each returns a boolean indicating whether the conversion
1074 succeeded. If the conversion failed, then the Icon value remains unchanged. These functions are intended for use
1075 with the arguments of an external function supplied to C++ before they are converted to the class safe and the
1076 real computation begins. (The use of these functions on the entries in argv[] is garbage-collection safe because
1077 Icon protects argv[].) For example to check that we have a string where we would need one as follows.
1078 <BLOCKQUOTE>
1079 <P>
1080 <TABLE BORDER="0" WIDTH="432">
1081 <TR>
1082 <TD WIDTH="432">
1083 <PRE><FONT COLOR="black" FACE="Courier New, Courier">extern &quot;C&quot; int assignprog(value argv[]){
1084 if( !argv[1].toString() ) {
1085 Icon::runerr(103, argv[1]);
1086 return FAILED; //in case &amp;error is set
1087 }
1088 safe newname(argv[1]);
1089 &amp;progname = newname; //Icon assignment semantics
1090 return FAILED;
1091 }</FONT></PRE>
1092 </TD>
1093 </TR>
1094 </TABLE>
1095 </P>
1096 </BLOCKQUOTE>
1097 <P>The function <FONT COLOR="black">syserror(const char*)</FONT> unconditionally and fatally terminates execution
1098 with an Icon style error message referring to the point of execution in Icon together with the error message supplied
1099 as a C string argument. This nicely complements <FONT COLOR="black">Icon::runerr</FONT>.<BR>
1100 <BR>
1101 To avoid problems with C++ conversion/overloading ambiguities, the class safe has been provided with a conversion
1102 to the class value only, and no conversions to the types char*, int, long or double. On the other hand, the value
1103 class has such conversions and so an explicit conversion to value can be used in many contexts to permit an implicit
1104 conversion to a built-in type. See below for details.<BR>
1105 <BR>
1106 The overloaded operators for the class safe defining much of Icon's repertoire in C++ have been defined outside
1107 the class safe, with the exception of those such as assignment, subscripting and call that C++ insists be non-static
1108 member functions, and almost all such as well as all other member functions have parameters of type safe only.
1109 This is so that the wide repertoire of conversions of other types to safe defined by loadfuncpp may be of maximum
1110 utility.<BR>
1111 <BR>
1112 Conversions of char*, double, int and long to safe as well as value are defined, those from the built-in types
1113 creating copies on the Icon heap. Specifically, the conversion from char* to safe or to value assumes a null terminated
1114 C string, and produces a correspondingly copied Icon string.<BR>
1115 <BR>
1116 Conversions of value to long and double have been defined. These behave as expected for Icon integers and reals
1117 respectively, but perform no conversions within Icon values (from integer to real or vice-versa). <BR>
1118 <BR>
1119 There is also a conversion from value to char* defined. This does <I>not</I> make a C string, but rather simply
1120 produces a pointer to the start of an Icon string, which is not null terminated, and can move in the event of a
1121 garbage collection. If null termination is desired, then concatenate the loadfuncpp constant value nullchar before
1122 converting to char*, and if a copy outside of Icon is needed, then you will have to explicitly make one. Here is
1123 an example.
1124 <BLOCKQUOTE>
1125 <P>
1126 <TABLE BORDER="0" WIDTH="432">
1127 <TR>
1128 <TD WIDTH="432">
1129 <PRE><FONT COLOR="black" FACE="Courier New, Courier">extern &quot;C&quot; int assignprog(value argv[]){
1130 if( !argv[1].toString() ) {
1131 Icon::runerr(103, argv[1]);
1132 return FAILED; //in case &amp;error is set
1133 }
1134 safe newname(argv[1]);
1135 char* s = value(newname || nullchar); //can move
1136 char sbuf[100];
1137 sprintf(sbuf, &quot;%s&quot;, s);
1138 //use the local copy sbuf
1139 //...
1140 }</FONT></PRE>
1141 </TD>
1142 </TR>
1143 </TABLE>
1144
1145 </BLOCKQUOTE>
1146 <P>The non-member functions <FONT COLOR="black">bytestointeger</FONT> and <FONT COLOR="black">integertobytes</FONT>
1147 are useful to overtly convert to and from Icon integers of any size (i.e. type <FONT COLOR="black">Integer</FONT>
1148 or <A HREF="#BigInteger">BigInteger</A> behind the scenes). Both functions take a value and return a value. In
1149 this context Icon strings are considered to be representations of natural numbers. Each character is considered
1150 a base 256 digit in the obvious way, and the digits are defined to be in order from most to least significant.
1151 The empty string represents zero. <FONT COLOR="black">bytestointeger</FONT> takes such a string and produces the
1152 corresponding Icon integer. <FONT COLOR="black">integertobytes</FONT> takes an Icon integer and produces an Icon
1153 string representing its absolute value in the preceding sense. Neither function attempts type conversions, so for
1154 meaningful results they must be passed respectively a string value and an integer value.<BR>
1155 <BR>
1156 The non-member functions <FONT COLOR="black">base64</FONT>, <FONT COLOR="black">base64tointeger</FONT> and <FONT
1157 COLOR="black">base64tostring</FONT> are useful to overtly convert strings and integers of any size to and from
1158 the commonly used <A HREF="http://www.faqs.org/rfcs/rfc3548.html">base64</A> encoding. Each function takes a value
1159 and returns a value, and none attempts any type conversion of its arguments. <FONT COLOR="black">base64</FONT>
1160 may be passed an Icon integer or string and produces a string containing the base64 encoding thereof. The sign
1161 of an integer is ignored, so the base64 encoding of its absolute value is produced. <FONT COLOR="black">base64tointeger</FONT>
1162 may be passed an Icon string that is a strict base64 encoding in which case it returns the corresponding Icon integer,
1163 and similarly <FONT COLOR="black">base64tostring</FONT> may be passed an Icon string that is a strict base64 encoding
1164 in which case it returns the corresponding Icon string. By strict base64 encoding is meant that the string's length
1165 is a multiple of four, that the end of the string is a sequence of between zero and two &quot;=&quot; characters
1166 (used to pad the file length to a multiple of four when encoding), and apart from that the remaining characters
1167 in the string are either lower or upper case letters, or digits, or the characters &quot;/&quot; and &quot;+&quot;.
1168 Failure to supply a string containing a strict base64 encoding to either function will cause null to be returned.</P>
1169 <H3><A NAME="Variadic"></A><A HREF="http://en.wikipedia.org/wiki/Variadic_function">Variadic Functions</A> and
1170 Dynamic List Construction</H3>
1171 <P>Some built-in Icon functions take an arbitrary number of arguments. Unfortunately, C++ as of the present standard
1172 has no convenient way to define a function with an arbitrary number of arguments of the same type. So variadic
1173 functions included in the namespace 'Icon' such as <FONT COLOR="black">writes</FONT> are defined in two versions.
1174 The first has at most eight arguments, with defaults and glue code to account for fewer being supplied. This takes
1175 care of most uses of such functions.</P>
1176 <P>The second uses a single argument of the class variadic, which is a wrapper for an Icon list of the arguments.
1177 The operator ',' (comma) has been overloaded so as to combine two locals into a variadic, and to combine a variadic
1178 and a safe so as to append the safe's value to the variadic's list. A variadic has a conversion to safe that in
1179 effect removes the wrapper, and there are other sundry conversions and overloads of comma. These enable lists to
1180 be constructed in place, providing a syntactic equivalent of things like <FONT COLOR="black">[x,y,z]</FONT> in
1181 Icon, namely <FONT COLOR="black">(x,y,z)</FONT> in C++. The second implementation of writes may then be called
1182 as <FONT COLOR="black">writes((x,y,z))</FONT>. The second pair of parentheses is necessary as comma is not regarded
1183 as an operator by C++ when it is in a parameter list. Here is an example of the use of dynamic list construction.</P>
1184 <BLOCKQUOTE>
1185 <P>
1186 <TABLE BORDER="0" WIDTH="432">
1187 <TR>
1188 <TD WIDTH="432">
1189 <PRE><FONT COLOR="black" FACE="Courier New, Courier">extern &quot;C&quot; int divide(value argv[]){
1190 safe x(argv[1]), y(argv[2]);
1191 argv[0] = (x / y, x % y);
1192 return SUCCEEDED;
1193 }</FONT></PRE>
1194 </TD>
1195 </TR>
1196 </TABLE>
1197 </P>
1198 </BLOCKQUOTE>
1199 <H3><A NAME="Calling"></A>Calling Icon from C++</H3>
1200 <P>The class safe has overloaded the function call operator '()' so that a safe may be called with function call
1201 syntax. If the value of the safe is an Icon procedure (or function or record constructor) the effect is to call
1202 Icon from C++. There are two kinds of restrictions on these calls.</P>
1203 <P>The first restriction is because C++ requires a specific <A HREF="http://en.wikipedia.org/wiki/Arity" target="_blank">arity</A>
1204 when overloading the function call operator, and has no convenient way to handle an arbitrary number of parameters
1205 of the same type. This restriction is the same one affecting the calling of <A HREF="#Variadic">variadic functions</A>,
1206 and is overcome in the same way with <A HREF="#Variadic">two implementations</A>. One with a single argument of
1207 class variadic necessitating <A HREF="#Variadic">two pairs of parentheses</A> when the call is made, and the other
1208 with up to eight arguments and useful for most procedure calls.</P>
1209 <P>The second restriction is because there are three ways Icon can pass control back to a caller: by returning
1210 a value, by failing and by suspending a value. However, there is only one way for C++ to receive control back from
1211 a call it has made: by a value (possibly void) being returned. For this reason a call of an Icon procedure from
1212 C++ will return &amp;null if the procedure fails, and will return rather than suspend if the procedure suspends
1213 a value. In either case, the call always returns cleanly with a single value. It is possible to <A HREF="#Iterate">iterate
1214 through the values suspended by an Icon procedure</A> in C++ through a different mechanism.</P>
1215 <H3><A NAME="Generators"></A>Working with Generators from C++</H3>
1216 <P>Generators and the flow of control in Icon have no counterpart in C++. Nevertheless, it is useful to be able
1217 to both implement generators for Icon in C++, and iterate through generator sequences produced by Icon in C++,
1218 as well as create coexpressions in C++. All these facilities are provided by loadfuncpp.</P>
1219 <H4><A NAME="Generate"></A>Writing External Functions that are Generators</H4>
1220 <P>Here is an example of a generator function written in C++. It is a C++ implementation of the built-in Icon function
1221 <FONT COLOR="black">seq</FONT>, without the restriction to machine size integers.</P>
1222 <BLOCKQUOTE>
1223 <P>
1224 <TABLE BORDER="0" WIDTH="456">
1225 <TR>
1226 <TD WIDTH="456">
1227 <PRE><FONT COLOR="black" FACE="Courier New, Courier">class sequence: public generator {
1228 safe current, inc;
1229 public:
1230 sequence(local start, local increment) {
1231 current = start - increment;
1232 inc = increment;
1233 }
1234 virtual bool hasNext() {
1235 return true;
1236 }
1237 virtual value giveNext() {
1238 return current += inc;
1239 }
1240 };
1241
1242 extern &quot;C&quot; int seq2(value argv[]){
1243 sequence seq(argv[1], argv[2]);
1244 return seq.generate(argv);
1245 }</FONT></PRE>
1246 </TD>
1247 </TR>
1248 </TABLE>
1249 </P>
1250 </BLOCKQUOTE>
1251 <P>This exemplifies all the features of loadfuncpp that enable generator functions to be written. First a C++ version
1252 of the generator is written as a class that inherits from the loadfuncpp class generator. Some data members are
1253 added to maintain state as generation occurs, and a constructor is written to initialize those data members. Finally
1254 the virtual functions <FONT COLOR="black">hasNext()</FONT> and <FONT COLOR="black">giveNext()</FONT> with exactly
1255 the above prototypes are overloaded. The sequence generated by an object of this class is defined to be that produced
1256 by repeatedly calling <FONT COLOR="black">hasNext()</FONT> to determine if there is a next member of the sequence,
1257 and if there is, calling <FONT COLOR="black">giveNext()</FONT> to get it.</P>
1258 <P>Now the external function itself simply creates a generator object of the above class, presumably using values
1259 passed to it from Icon to initialize that object's state. Then the inherited member function <FONT COLOR="black">generate</FONT>
1260 is called, passing the original argument array for technical reasons, and the signal it returns is passed back
1261 to Icon. The effect of this call is to iterate through the calls of <FONT COLOR="black">giveNext()</FONT> while
1262 <FONT COLOR="black">hasNext()</FONT> returns true, suspending the results produced by each call of <FONT COLOR="black">giveNext()</FONT>
1263 to Icon. In a nutshell the call to <FONT COLOR="black">generate</FONT> suspends the sequence of results produced
1264 by the object to Icon. The reason that <FONT COLOR="black">generate</FONT> needs to be passed argv is that it needs
1265 to send its results to Icon by assigning to argv[0], in just as a single result is passed back.</P>
1266 <H4><A NAME="Iterate"></A>Calling Icon Procedures that are Generators from C++</H4>
1267 <P>Here is an example of how to iterate over the results of a call of an Icon procedure. In the example the procedure
1268 to be called and its argument list are presumed to be the arguments passed to the external function, which then
1269 computes the sum of the first ten results suspended by the call, or the sum of all the results if less than ten
1270 results are computed.</P>
1271 <BLOCKQUOTE>
1272 <P>
1273 <TABLE BORDER="0" WIDTH="456">
1274 <TR>
1275 <TD WIDTH="456">
1276 <PRE><FONT COLOR="black" FACE="Courier New, Courier">class addup: public iterate {
1277 public:
1278 safe total;
1279 int count;
1280
1281 addup(): total(0), count(0) {}
1282
1283 virtual void takeNext(const value&amp; x) {
1284 total += x;
1285 }
1286 virtual bool wantNext(const value&amp; x) {
1287 return ++count &lt;= 10;
1288 }
1289 };
1290
1291 extern &quot;C&quot; int sum10(value argv[]){
1292 addup sum;
1293 sum.every(argv[1], argv[2]);
1294 argv[0] = sum.total;
1295 return SUCCEEDED;
1296 }</FONT></PRE>
1297 </TD>
1298 </TR>
1299 </TABLE>
1300 </P>
1301 </BLOCKQUOTE>
1302 <P>This exemplifies all the features of loadfuncpp that enable the results of a call to Icon to be iterated over
1303 in C++. First a class representing the loop that will iterate over the generator sequence is written, inheriting
1304 from the loadfuncpp class iterate. The data members of that class model the variables used in the loop, and the
1305 constructor models the initialization of those loop variables. It is convenient that these be public along with
1306 everything else; the class could be declared as a struct to achieve this. The two inherited virtual member functions
1307 <FONT COLOR="black">wantNext()</FONT> and <FONT COLOR="black">takeNext()</FONT> with exactly the above prototypes
1308 are then overridden. The function <FONT COLOR="black">wantNext()</FONT> models the loop condition: it returns true
1309 if the loop will process the next result produced by the generator, and false if the loop should be terminated.
1310 The function <FONT COLOR="black">takeNext()</FONT> models the loop body: it will be passed each result produced
1311 by the generator, and may modify the loop variables accordingly.</P>
1312 <P>Now the external function itself simply creates an object of this class, using the constructor to initialize
1313 the loop variables, or simply assigning to them directly. This models setup code before the loop proper starts.
1314 Then the inherited member function <FONT COLOR="black">every</FONT> is called with the generator function and its
1315 argument list as arguments to the call. The call of <FONT COLOR="black">every</FONT> models executing the loop
1316 body by calling the generator function applied to its argument list and repeatedly alternately calling <FONT COLOR="black">wantNext()</FONT>
1317 to see if the loop should continue and <FONT COLOR="black">takeNext()</FONT> to pass the loop body the next result
1318 produced by the call to Icon. The loop is terminated either by <FONT COLOR="black">wantNext()</FONT> returning
1319 false or by the sequence of results generated by the call to Icon coming to an end, whichever occurs first.</P>
1320 <H4><A NAME="Bang"></A>Iterating over Exploded Structures in C++</H4>
1321 <P>This feature of loadfuncpp enables iteration over the results that would be generated in Icon by an expression
1322 of the form <FONT COLOR="black">!x</FONT>, with one important difference: if <FONT COLOR="black">x</FONT> is a
1323 table, then the results iterated over are those that would be produced by the Icon expression <FONT COLOR="black">key(x)</FONT>.
1324 The technique use to perform such an iteration is almost identical to that used to <A HREF="#Iterate">iterate over
1325 the results of a call to an Icon procedure</A>. The only difference is that a different inherited member function
1326 (<FONT COLOR="black">bang</FONT>) is called to run the iteration. Here is an example that sums the first ten elements
1327 of a list by quite unnecessarily using this technique.</P>
1328 <BLOCKQUOTE>
1329 <P>
1330 <TABLE BORDER="0" WIDTH="456">
1331 <TR>
1332 <TD WIDTH="456">
1333 <PRE><FONT COLOR="black" FACE="Courier New, Courier">class addup: public iterate {
1334 public:
1335 safe total;
1336 int count;
1337
1338 addup(): total(0), count(0) {}
1339
1340 virtual void takeNext(const value&amp; x) {
1341 total += x;
1342 }
1343 virtual bool wantNext(const value&amp; x) {
1344 return ++count &lt;= 10;
1345 }
1346 };
1347
1348 extern &quot;C&quot; int sumlist(value argv[]) {
1349 addup sum;
1350 sum.bang(argv[1]);
1351 argv[0] = sum.total;
1352 return SUCCEEDED;
1353 }</FONT></PRE>
1354 </TD>
1355 </TR>
1356 </TABLE>
1357 </P>
1358 </BLOCKQUOTE>
1359 <H4><A NAME="Coexpressions"></A>Working with Coexpressions in C++</H4>
1360 <P>There are a handful of member functions in the class safe that provide an essentially complete set of operations
1361 on coexpressions. These are straightforward to use and are summarized here.</P>
1362 </BLOCKQUOTE>
1363 <BLOCKQUOTE ALIGN="CENTER">
1364 <P>
1365 <TABLE BORDER="0">
1366 <TR>
1367 <TD WIDTH="130">
1368 <P ALIGN="CENTER"><B><FONT SIZE="2" FACE="Courier New, Courier">safe function</FONT></B>
1369 </TD>
1370 <TD WIDTH="164">
1371 <P ALIGN="CENTER"><B><FONT SIZE="2" FACE="Courier New, Courier">Icon equivalent</FONT></B>
1372 </TD>
1373 <TD WIDTH="271">
1374 <P>&nbsp;
1375 </TD>
1376 </TR>
1377 <TR>
1378 <TD WIDTH="130">
1379 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x.create()</FONT>
1380 </TD>
1381 <TD WIDTH="164">
1382 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">create !x</FONT>
1383 </TD>
1384 <TD WIDTH="271">
1385 <P><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">&nbsp;</FONT>
1386 </TD>
1387 </TR>
1388 <TR>
1389 <TD WIDTH="130">
1390 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x.create(y)</FONT>
1391 </TD>
1392 <TD WIDTH="164">
1393 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">create x!y</FONT>
1394 </TD>
1395 <TD WIDTH="271">
1396 <P>&nbsp;
1397 </TD>
1398 </TR>
1399 <TR>
1400 <TD WIDTH="130">
1401 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x.activate(y)</FONT>
1402 </TD>
1403 <TD WIDTH="164">
1404 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">y@x</FONT>
1405 </TD>
1406 <TD WIDTH="271">
1407 <P><FONT SIZE="2" FACE="Courier New, Courier">y defaults to &amp;null</FONT>
1408 </TD>
1409 </TR>
1410 <TR>
1411 <TD WIDTH="130">
1412 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">x.refresh()</FONT>
1413 </TD>
1414 <TD WIDTH="164">
1415 <P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">^x</FONT>
1416 </TD>
1417 <TD WIDTH="271">
1418 <P>&nbsp;
1419 </TD>
1420 </TR>
1421 </TABLE>
1422 </P>
1423 </BLOCKQUOTE>
1424 <BLOCKQUOTE>
1425 <H3><A NAME="Externals"></A>Working with <A HREF="http://www.cs.arizona.edu/icon/uguide/extlvals.htm" target="_blank">External
1426 Values</A></H3>
1427 <P>A new kind of external value is easily defined and used via inheritance from the loadfuncpp class external,
1428 which permanently hides the low level machinery of the <A HREF="http://www.cs.arizona.edu/icon/uguide/extlvals.htm"
1429 target="_blank">C specification</A>. Here is an example of such that illustrates the use of the available features.</P>
1430 <BLOCKQUOTE>
1431 <P>
1432 <TABLE BORDER="0" WIDTH="456">
1433 <TR>
1434 <TD WIDTH="456">
1435 <PRE><FONT COLOR="black" FACE="Courier New, Courier">class Widget: public external {
1436 long state;
1437 public:
1438 Widget(long x): state(x) {}
1439
1440 virtual value name() {
1441 return &quot;Widget&quot;;
1442 }
1443 virtual external* copy() {
1444 return new Widget(state);
1445 }
1446 virtual value image() {
1447 char sbuf[100];
1448 sprintf(sbuf, &quot;Widget_%ld(%ld)&quot;, id, state);
1449 return value(NewString, sbuf);
1450 }
1451 virtual long compare(external* ep) {
1452 //negative:less, zero:equal, positive:greater
1453 Widget* wp = (Widget*)ep;
1454 return this-&gt;state - wp-&gt;state;
1455 }
1456 };
1457
1458 extern &quot;C&quot; int widget(value argv[]) {
1459 if( argv[1].type() != Integer ) {
1460 Icon::runerr(101, argv[1]);
1461 return FAILED;
1462 }
1463 argv[0] = new Widget(argv[1]);
1464 return SUCCEEDED;
1465 }
1466
1467 extern &quot;C&quot; int widgetint(value argv[]) {
1468 if( argv[1].type() != External ) {
1469 Icon::runerr(131, argv[1]);
1470 return FAILED;
1471 }
1472 if( !argv[1].isExternal(&quot;Widget&quot;) ) {
1473 Icon::runerr(132, argv[1]);
1474 return FAILED;
1475 }
1476 external* ep = argv[1]; //implied conversion
1477 Widget* wp = (Widget*)ep; //can move if GC occurs!
1478 argv[0] = ep-&gt;state;
1479 return SUCCEEDED;
1480 }</FONT></PRE>
1481 </TD>
1482 </TR>
1483 </TABLE>
1484 </P>
1485 </BLOCKQUOTE>
1486 <P>The example defines an external function <FONT COLOR="black">widget</FONT> that returns an external value to
1487 Icon, and an external function <FONT COLOR="black">widgetint</FONT> that returns an integer extracted from a Widget
1488 to Icon. Of course a real library would have in addition a number of external functions to work with Widgets; these
1489 could call additional member functions in the Widget class to do the necessary work.</P>
1490 <P>Overriding the inherited virtual functions <FONT COLOR="black">name()</FONT>, <FONT COLOR="black">copy()</FONT>,
1491 <FONT COLOR="black">image()</FONT> and <FONT COLOR="black">compare()</FONT> automatically redefines the behavior
1492 respectively of the built-in Icon functions type, copy and image and the Icon operators === and ~=== when applied
1493 to Widgets, as well as the order for sorting Widgets among themselves in Icon. Such overriding is optional, and
1494 the defaults defined in the <A HREF="http://www.cs.arizona.edu/icon/uguide/extlvals.htm" target="_blank">C specification</A>
1495 will apply otherwise. Specifically, the default copy is not to copy but to return the original.</P>
1496 <P>There are automatic conversions to and from <FONT COLOR="black">external*</FONT> so that new widgets may be
1497 assigned to values or safes, and vice versa when appropriate. The operator new has been overloaded so that an external
1498 is allocated by Icon as a part of an Icon external block on the Icon heap. The class external has a protected data
1499 member <FONT COLOR="black">id</FONT> that contains the serial number of the external value (assigned by Icon when
1500 it allocates the external block). Using <FONT COLOR="black">id</FONT> may be convenient when overriding the <FONT
1501 COLOR="black">image()</FONT> member function, as above.</P>
1502 <P>External blocks are assumed by Icon not to contain any Icon <A HREF="http://www.cs.arizona.edu/icon/uguide/cfuncs.htm"
1503 target="_blank">descriptors</A>, so do not declare any data members of the classes value or safe when inheriting
1504 from external, unless you wish to invite disaster when a garbage collection occurs. Take into account that external
1505 blocks may be relocated or garbage collected by Icon. It is not possible to arrange for a destructor or anything
1506 else to be called when that occurs. If calling a destructor is essential, then place a pointer to the real object
1507 in the external object, and allocate and manage the real object yourself.</P>
1508 <H3><A NAME="Records"></A>Using Icon Records as Objects</H3>
1509 <P>A new procedure that is a copy of another with an Icon record bound to it may be created by calling the procedure
1510 <FONT COLOR="black">bindself</FONT>. The new procedure behaves exactly as the old one, except that a call of the
1511 procedure <FONT COLOR="black">self</FONT> from within it returns the record attached to it by <FONT COLOR="black">bindself</FONT>.
1512 This enables a record to contain a procedure that behaves like a method by virtue of being bound to it, as illustrated
1513 by the following example.
1514 <BLOCKQUOTE>
1515 <P>
1516 <TABLE BORDER="0" WIDTH="496">
1517 <TR>
1518 <TD WIDTH="496">
1519 <PRE><FONT COLOR="black" FACE="Courier New, Courier">link loadfuncpp
1520
1521 record object(val, print)
1522
1523 procedure print()
1524 obj := self() | fail
1525 write( obj.val )
1526 end
1527
1528 procedure newObject(x)
1529 obj := object(x) #don't assign print method yet
1530 #print will be a copy bound to the record it's embedded in
1531 obj.print := bindself(print, obj)
1532 return obj
1533 end
1534
1535 procedure main()
1536 obj := newObject(&quot;Hello&quot;)
1537 obj.print()
1538 end</FONT></PRE>
1539 </TD>
1540 </TR>
1541 </TABLE>
1542
1543 </BLOCKQUOTE>
1544 <P>Note that <FONT COLOR="black">self</FONT> fails if called from a procedure that is not bound to a record i.e.
1545 one that has not been returned by <FONT COLOR="black">bindself</FONT>. It is possible to use bindself to bind a
1546 record to a procedure that already has a record bound to it. This simply replaces the bound record, which is useful
1547 for copying records that are to be treated as objects in this way, e.g. when copying a prototype object when simulating
1548 an object based inheritance scheme.
1549 </BLOCKQUOTE>
1550 </TD>
1551 </TR>
1552 </TABLE>
1553
1554 </CENTER>
1555
1556 </BODY>
1557
1558 </HTML>