File: x1229.html

package info (click to toggle)
gambit-doc 0.97.0-1
links: PTS
area: main
in suites: etch, etch-m68k, lenny, sarge, squeeze
size: 1,344 kB
sloc: makefile: 19; sh: 10
file content (298 lines) | stat: -rw-r--r-- 5,748 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML
><HEAD
><TITLE
>Listability of functions</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.59"><LINK
REL="HOME"
TITLE="Gambit"
HREF="gambit.html"><LINK
REL="UP"
TITLE="The Gambit Command Language"
HREF="c524.html"><LINK
REL="PREVIOUS"
TITLE="Lists"
HREF="x1214.html"><LINK
REL="NEXT"
TITLE="Online documentation"
HREF="x1259.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Gambit: Software Tools for Game Theory</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="x1214.html"
>&#60;&#60;&#60; Previous</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>The Gambit Command Language</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="x1259.html"
>Next &#62;&#62;&#62;</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN1229"
>Listability of functions</A
></H1
><P
>Almost all of the functions in the GCL are ``listable''.  This means
that if there is a version of the function which takes a type <SPAN
CLASS="TYPE"
>T</SPAN
>
as the data type for a parameter, then it can be called with
<SPAN
CLASS="TYPE"
>LIST(T)</SPAN
> as well.  This results in the function generating a
list of the corresponding length and data type as its output.  For
example, consider a function
<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>Foo[x-&#62;T,y-&#62;S] =: R</PRE
></TD
></TR
></TABLE
>
where <SPAN
CLASS="TYPE"
>T</SPAN
>, <SPAN
CLASS="TYPE"
>S</SPAN
>, and <SPAN
CLASS="TYPE"
>R</SPAN
>
represent arbitrary data types.
Then if \verb+a+ is a <SPAN
CLASS="TYPE"
>LIST(T)</SPAN
>, and \verb+b+ is of type
<SPAN
CLASS="TYPE"
>S</SPAN
>, then \verb+c := Foo[a,b]+ generates \verb+c+ of type
<SPAN
CLASS="TYPE"
>LIST(R)</SPAN
>, where the length of \verb+c+ is equal to the length of
\verb+a+, and where \verb+c[[i]] = Foo[a[[i]],b]+.</P
><P
>If <TT
CLASS="FUNCTION"
>Foo[]</TT
> is called with both \verb+a+ and \verb+b+ being lists
of the correct data type, then the GCL checks whether the length of
\verb+a+ and \verb+b+ is the same.  If not, it generates a
dimensionality error. If they are of the same dimension, then 
\verb+c := Foo[a,b]+ generates \verb+c+ of type <SPAN
CLASS="TYPE"
>LIST(R)</SPAN
>, where the
length of \verb+c+ is equal to the length of \verb+a+, and where
\verb+c[[i]] = Foo[a[[i]],b[[i]]]+.</P
><P
>Note that the above rules implicitly define versions of <TT
CLASS="FUNCTION"
>Foo</TT
>
of the following forms:
<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>Foo[x-&#62;LIST(T),y-&#62;S] =: LIST(R)
Foo[x-&#62;T,y-&#62;LIST(S)] =: LIST(R)
Foo[x-&#62;LIST(T),y-&#62;LIST(S)] =: LIST(R)</PRE
></TD
></TR
></TABLE
></P
><P
>The same rules apply recursively using these function prototypes as
well.  So if \verb+a+ is of type <SPAN
CLASS="TYPE"
>LIST(LIST(T))</SPAN
>, and \verb+b+ is
of type \verb+S+, the command \verb+c := Foo[a, b]+ results in a
listable call to \verb+Foo[x-&#62;LIST(T),y-&#62;S]+.  Thus, \verb+c+ is of
type <SPAN
CLASS="TYPE"
>LIST(LIST(R))</SPAN
>, where \verb+c[[i]] = +
\verb+Foo[a[[i]],b]+.  Hence, \verb+c[[i]][[j]] = +
\verb+Foo[a[[i]][[j]],b]+.</P
><P
>Note that many vector and matrix math operations follow directly as
listable calls to the basic arithmetic functions.  In this example,
listability of <TT
CLASS="FUNCTION"
>Times</TT
> is used to provide scalar multiplication
of a scalar and a matrix, and listability of <TT
CLASS="FUNCTION"
>Plus</TT
>
is used to
add two conformable matrices:  
<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>GCL1:= a:={{1,2},{3,4}};
GCL2:= &#60;&#60; 2*a
{{2,4},{6,8}}
GCL3:= &#60;&#60; a+Transpose[a]
{{2,5},{5,8}}</PRE
></TD
></TR
></TABLE
></P
><P
>Here listability of <TT
CLASS="FUNCTION"
>Power</TT
> is used to create a list of the first
ten perfect squares:
<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>GCL4:= &#60;&#60; List[1,10,1]^2
{ 1, 4, 9, 16, 25, 36, 49, 64, 81, 100 }</PRE
></TD
></TR
></TABLE
></P
><P
>While most functions in the GCL are listable, there are some
exceptions.  Built-in functions that are not listable are noted as
such in the Function Reference section of this document.</P
><P
>Listability of functions is a powerful tool of the GCL. Many GCL
programs using flow control statements can be written using listable
function calls instead.  It is encouraged to use listable functions as
much as possible because it typically leads to more concise, easier to
read GCL programs, and in addition the programs typically run
faster than they would if flow control satements were used instead.
This is because listable calls to functions are executed in compiled
code, while flow control statements are executed in interpreted code.</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="x1214.html"
>&#60;&#60;&#60; Previous</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="gambit.html"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="x1259.html"
>Next &#62;&#62;&#62;</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Lists</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="c524.html"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Online documentation</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>