| 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 & 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 "loadfuncpp.h" |
| 253 |
|
| 254 |
extern "C" int hello(value argv[]) { |
| 255 |
argv[0] = "Hello World"; |
| 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("./hello.so", "hello", 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 "loadfuncpp.h" |
| 308 |
|
| 309 |
extern "C" int fixed_arity(value argv[]) { |
| 310 |
// ... has a fixed number of arguments |
| 311 |
return SUCCEEDED; //or FAILED |
| 312 |
} |
| 313 |
|
| 314 |
extern "C" 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 "loadfuncpp.h" |
| 335 |
|
| 336 |
extern "C" 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("./mylib.so", "fixed_arity", 2) |
| 362 |
variadic := loadfuncpp("./mylib.so", "variable_arity") |
| 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 "soon".)</P> |
| 383 |
<P>All of the C++ in this manual requires '#include "loadfuncpp.h"' 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 "C" 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("./dull.so", "dull", 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 "C" 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 "C" int f(value argv[]){ |
| 470 |
safe text = value(StringLiteral, "Hello"); |
| 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"> </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"> </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> |
| 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> |
| 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"> </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"> </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"> </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"> </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"> </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"> </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> |
| 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"> </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"> </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"> </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"> </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"> </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"> </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"> </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 & 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"> </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 && 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"> </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"> </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> |
| 726 |
</TD> |
| 727 |
</TR> |
| 728 |
<TR> |
| 729 |
<TD WIDTH="130"> |
| 730 |
<P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">&=</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> |
| 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"> </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"> </FONT> |
| 759 |
</TD> |
| 760 |
</TR> |
| 761 |
<TR> |
| 762 |
<TD WIDTH="130"> |
| 763 |
<P ALIGN="CENTER"><FONT SIZE="2" COLOR="black" FACE="Courier New, Courier">< > <= >=</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> |
| 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> |
| 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"> </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) </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"> </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> |
| 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> |
| 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"> </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> |
| 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 &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> |
| 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> |
| 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> |
| 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 &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> |
| 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 "C" 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 &cset (to avoid a possible name collision), |
| 1039 |
and &fail. The keywords are implemented through a keyword class with the unary '&' 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 "C" int assignprog(value argv[]){ |
| 1047 |
safe newname(argv[1]); |
| 1048 |
&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 &progname, just as in Icon. In all cases a keyword |
| 1057 |
is used with the unary '&' 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 "C" int assignprog(value argv[]){ |
| 1084 |
if( !argv[1].toString() ) { |
| 1085 |
Icon::runerr(103, argv[1]); |
| 1086 |
return FAILED; //in case &error is set |
| 1087 |
} |
| 1088 |
safe newname(argv[1]); |
| 1089 |
&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 "C" int assignprog(value argv[]){ |
| 1130 |
if( !argv[1].toString() ) { |
| 1131 |
Icon::runerr(103, argv[1]); |
| 1132 |
return FAILED; //in case &error is set |
| 1133 |
} |
| 1134 |
safe newname(argv[1]); |
| 1135 |
char* s = value(newname || nullchar); //can move |
| 1136 |
char sbuf[100]; |
| 1137 |
sprintf(sbuf, "%s", 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 "=" 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 "/" and "+". |
| 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 "C" 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 &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 "C" 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& x) { |
| 1284 |
total += x; |
| 1285 |
} |
| 1286 |
virtual bool wantNext(const value& x) { |
| 1287 |
return ++count <= 10; |
| 1288 |
} |
| 1289 |
}; |
| 1290 |
|
| 1291 |
extern "C" 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& x) { |
| 1341 |
total += x; |
| 1342 |
} |
| 1343 |
virtual bool wantNext(const value& x) { |
| 1344 |
return ++count <= 10; |
| 1345 |
} |
| 1346 |
}; |
| 1347 |
|
| 1348 |
extern "C" 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> |
| 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"> </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> |
| 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 &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> |
| 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 "Widget"; |
| 1442 |
} |
| 1443 |
virtual external* copy() { |
| 1444 |
return new Widget(state); |
| 1445 |
} |
| 1446 |
virtual value image() { |
| 1447 |
char sbuf[100]; |
| 1448 |
sprintf(sbuf, "Widget_%ld(%ld)", 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->state - wp->state; |
| 1455 |
} |
| 1456 |
}; |
| 1457 |
|
| 1458 |
extern "C" 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 "C" 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("Widget") ) { |
| 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->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("Hello") |
| 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> |