<?xml version="1.0" encoding="utf-8" ?> <!-- for emacs: -*- coding: utf-8 -*- -->
<!-- Apache may like this line in the file .htaccess: AddCharset utf-8 .html -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN" "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg-flat.dtd" >
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head><title>lists and sequences</title>
<link rel="stylesheet" type="text/css" href="../../../../Macaulay2/Style/doc.css"/>
</head>
<body>
<table class="buttons">
<tr>
<td><div><a href="_ranges_spand_sprepetitions.html">next</a> | <a href="___Net.html">previous</a> | <a href="_hash_sptables.html">forward</a> | <a href="_strings_spand_spnets.html">backward</a> | <a href="___The_sp__Macaulay2_splanguage.html">up</a> | <a href="index.html">top</a> | <a href="master.html">index</a> | <a href="toc.html">toc</a> | <a href="http://www.math.uiuc.edu/Macaulay2/">Macaulay2 web site</a></div>
</td>
</tr>
</table>
<div><a href="index.html" title="">Macaulay2Doc</a> > <a href="___The_sp__Macaulay2_splanguage.html" title="">The Macaulay2 language</a> > <a href="_lists_spand_spsequences.html" title="">lists and sequences</a></div>
<hr/>
<div><h1>lists and sequences</h1>
<div>In this section we give an overview of the use of lists of all types, including:<ul><li><span>basic lists (of class <a href="___Basic__List.html" title="the class of all basic lists">BasicList</a>),</span></li>
<li><span>visible lists (of class <a href="___Visible__List.html" title="the class of all visible lists">VisibleList</a>),</span></li>
<li><span>lists (of class <a href="___List.html" title="the class of all lists -- {...}">List</a>),</span></li>
<li><span>sequences (of class <a href="___Sequence.html" title="the class of all sequences -- (...)">Sequence</a>), and</span></li>
<li><span>arrays (of class <a href="___Array.html" title="the class of all arrays -- [...]">Array</a>).</span></li>
<li><span>mutable lists (of class <a href="___Mutable__List.html" title="the class of all mutable lists">MutableList</a>).</span></li>
</ul>
<h2>lists</h2>
A list is a handy way to store a series of things. We create one by separating the elements of the series by commas and surrounding the series with braces.<table class="examples"><tr><td><pre>i1 : x = {a,b,c,d,e}
o1 = {a, b, c, d, e}
o1 : List</pre>
</td></tr>
</table>
We retrieve the length of a list with the operator <a href="__sh.html" title="length, or access to elements">#</a> or with the function <tt>length</tt>.<table class="examples"><tr><td><pre>i2 : #x
o2 = 5</pre>
</td></tr>
<tr><td><pre>i3 : length x
o3 = 5</pre>
</td></tr>
</table>
We use the expression <tt>x#n</tt> to obtain the n-th element of <tt>x</tt>. The elements are numbered consecutively starting with <tt>0</tt>. Alternatively, they are numbered consecutively ending with <tt>-1</tt>.<table class="examples"><tr><td><pre>i4 : x#2
o4 = c
o4 : Symbol</pre>
</td></tr>
<tr><td><pre>i5 : x#-2
o5 = d
o5 : Symbol</pre>
</td></tr>
</table>
The functions <a href="_first.html" title="first element of a list">first</a> and <a href="_last.html" title="last element of a list">last</a> retrieve the first and last elements of a list.<table class="examples"><tr><td><pre>i6 : first x
o6 = a
o6 : Symbol</pre>
</td></tr>
<tr><td><pre>i7 : last x
o7 = e
o7 : Symbol</pre>
</td></tr>
</table>
<p>Omitting an element of a list causes the symbol <a href="_null.html" title="the unique member of the empty class">null</a> to be inserted in its place.</p>
<table class="examples"><tr><td><pre>i8 : g = {3,4,,5}
o8 = {3, 4, , 5}
o8 : List</pre>
</td></tr>
<tr><td><pre>i9 : peek g
o9 = {3, 4, null, 5}</pre>
</td></tr>
</table>
<p>Lists can be used as vectors, provided their elements are the sorts of things that can be added and mutliplied.</p>
<table class="examples"><tr><td><pre>i10 : 10000*{3,4,5} + {1,2,3}
o10 = {30001, 40002, 50003}
o10 : List</pre>
</td></tr>
</table>
If the elements of a list are themselves lists, we say that we have a nested list.<table class="examples"><tr><td><pre>i11 : y = {{a,b,c},{d,{e,f}}}
o11 = {{a, b, c}, {d, {e, f}}}
o11 : List</pre>
</td></tr>
<tr><td><pre>i12 : #y
o12 = 2</pre>
</td></tr>
</table>
One level of nesting may be eliminated with <a href="_flatten.html" title="flatten a list by unnesting lists">flatten</a>.<table class="examples"><tr><td><pre>i13 : flatten y
o13 = {a, b, c, d, {e, f}}
o13 : List</pre>
</td></tr>
</table>
A table is a list whose elements are lists all of the same length. The inner lists are regarded as rows when the table is displayed as a two-dimensional array with <a href="___Matrix__Expression.html" title="the class of all matrix expressions">MatrixExpression</a>.<table class="examples"><tr><td><pre>i14 : z = {{a,1},{b,2},{c,3}}
o14 = {{a, 1}, {b, 2}, {c, 3}}
o14 : List</pre>
</td></tr>
<tr><td><pre>i15 : isTable z
o15 = true</pre>
</td></tr>
<tr><td><pre>i16 : MatrixExpression z
o16 = | a 1 |
| |
| b 2 |
| |
| c 3 |
o16 : Expression of class MatrixExpression</pre>
</td></tr>
</table>
<h2>sequences</h2>
Sequence are like lists, except that parentheses are used instead of braces to create them and to print them. Sequences are implemented in a more efficient way than lists, since a sequence is created every time a function is called with more than one argument. Another difference is that new types of list can be created by the user, but not new types of sequence.<table class="examples"><tr><td><pre>i17 : x = (a,b,c,d,e)
o17 = (a, b, c, d, e)
o17 : Sequence</pre>
</td></tr>
<tr><td><pre>i18 : #x
o18 = 5</pre>
</td></tr>
<tr><td><pre>i19 : x#2
o19 = c
o19 : Symbol</pre>
</td></tr>
</table>
It is a bit harder to create a sequence of length 1, since no comma would be involved, and parentheses are also used for simple grouping of algebraic expressions.<table class="examples"><tr><td><pre>i20 : ()
o20 = ()
o20 : Sequence</pre>
</td></tr>
<tr><td><pre>i21 : (a)
o21 = a
o21 : Symbol</pre>
</td></tr>
<tr><td><pre>i22 : (a,b)
o22 = (a, b)
o22 : Sequence</pre>
</td></tr>
</table>
Most of the functions that apply to lists also work with sequences. We give just one example.<table class="examples"><tr><td><pre>i23 : append(x,f)
o23 = (a, b, c, d, e, f)
o23 : Sequence</pre>
</td></tr>
</table>
The functions <a href="_to__List.html" title="list of elements">toList</a> and <a href="_to__Sequence.html" title="convert to sequence">toSequence</a> are provided for converting between lists to sequences.<table class="examples"><tr><td><pre>i24 : toList x
o24 = {a, b, c, d, e}
o24 : List</pre>
</td></tr>
<tr><td><pre>i25 : toSequence oo
o25 = (a, b, c, d, e)
o25 : Sequence</pre>
</td></tr>
</table>
Other functions for dealing especially with sequences include <a href="_sequence.html" title="make a sequence">sequence</a> and <a href="_deep__Splice.html" title="remove subsequences">deepSplice</a>.<h2>arrays</h2>
An array is like a list, except that brackets are used instead of braces when entering or displaying an array, and arrays can't be used as vectors. Their main use is notational: for example, they appear in the construction of polynomial rings.<table class="examples"><tr><td><pre>i26 : v = [a,b,c]
o26 = [a, b, c]
o26 : Array</pre>
</td></tr>
<tr><td><pre>i27 : v#2
o27 = c
o27 : Symbol</pre>
</td></tr>
<tr><td><pre>i28 : ZZ[a,b,c]
o28 = ZZ[a, b, c]
o28 : PolynomialRing</pre>
</td></tr>
</table>
<h2>visible lists</h2>
Lists, sequences, and arrays are the three examples of what we call visible lists, which constitute the class <a href="___Visible__List.html" title="the class of all visible lists">VisibleList</a>. Many functions are defined to act uniformly on visible lists.<table class="examples"><tr><td><pre>i29 : {a,b,c}
o29 = {a, b, c}
o29 : List</pre>
</td></tr>
<tr><td><pre>i30 : class oo
o30 = List
o30 : Type</pre>
</td></tr>
<tr><td><pre>i31 : parent oo
o31 = VisibleList
o31 : Type</pre>
</td></tr>
</table>
<h2>basic lists</h2>
There is a type of list more general than a visible list, which we call a basic list. Basic lists can be used for representing new datatypes in a more secure way, since the many functions that act on lists and sequences do not act on basic lists.<table class="examples"><tr><td><pre>i32 : {a,b,c}
o32 = {a, b, c}
o32 : List</pre>
</td></tr>
<tr><td><pre>i33 : class oo
o33 = List
o33 : Type</pre>
</td></tr>
<tr><td><pre>i34 : parent oo
o34 = VisibleList
o34 : Type</pre>
</td></tr>
<tr><td><pre>i35 : parent oo
o35 = BasicList
o35 : Type</pre>
</td></tr>
</table>
We can make a basic list with the <a href="_new.html" title="new objects and new types">new</a> operator.<table class="examples"><tr><td><pre>i36 : new BasicList from {a,b,c}
o36 = BasicList{a, b, c}
o36 : BasicList</pre>
</td></tr>
</table>
Similarly, we can make a new type of basic list, called <tt>Container</tt>, say.<table class="examples"><tr><td><pre>i37 : Container = new Type of BasicList
o37 = Container
o37 : Type</pre>
</td></tr>
</table>
We can make a new list of type Container.<table class="examples"><tr><td><pre>i38 : t = new Container from {a,b}
o38 = Container{a, b}
o38 : Container</pre>
</td></tr>
</table>
Some functions work on basic lists.<table class="examples"><tr><td><pre>i39 : join(t,t)
o39 = Container{a, b, a, b}
o39 : Container</pre>
</td></tr>
</table>
We can make a new method for the operator <tt>++</tt>, say, that will join two such lists.<table class="examples"><tr><td><pre>i40 : Container ++ Container := join;</pre>
</td></tr>
<tr><td><pre>i41 : t ++ t
o41 = Container{a, b, a, b}
o41 : Container</pre>
</td></tr>
</table>
<h2>mutable lists</h2>
The elements of a basic list cannot normally be replaced by others. However, there is a certain type of basic list, called a mutable list (of class <a href="___Mutable__List.html" title="the class of all mutable lists">MutableList</a>), whose elements can be changed. Because the elements of a mutable list can be changed, circular structures can be created that would cause a print routine to go into an infinite loop. We avoid such infinite loops by not printing out the contents of mutable lists. Instead, one uses <a href="_peek.html" title="examine contents of an object">peek</a> to display the elements in a controlled way.<table class="examples"><tr><td><pre>i42 : s = new MutableList from {a,b,c}
o42 = MutableList{...3...}
o42 : MutableList</pre>
</td></tr>
<tr><td><pre>i43 : peek s
o43 = MutableList{a, b, c}</pre>
</td></tr>
<tr><td><pre>i44 : s#2 = 1234;</pre>
</td></tr>
<tr><td><pre>i45 : s
o45 = MutableList{...3...}
o45 : MutableList</pre>
</td></tr>
<tr><td><pre>i46 : peek s
o46 = MutableList{a, b, 1234}</pre>
</td></tr>
</table>
Because the contents of mutable lists are not printed, they can be used as containers for big things that one normally doesn't want printed. For this purpose we have a special type of mutable list called a bag (of class <a href="___Bag.html" title="the class of all bags">Bag</a>), that displays, when printed, a little information about its contents.<table class="examples"><tr><td><pre>i47 : Bag {100!}
o47 = {*a bagged integer*}
o47 : Bag</pre>
</td></tr>
<tr><td><pre>i48 : peek oo
o48 = Bag{9332621544394415268169923885626670049071596826438162146859296389521
-----------------------------------------------------------------------
75999932299156089414639761565182862536979208272237582511852109168640000
-----------------------------------------------------------------------
00000000000000000000}</pre>
</td></tr>
</table>
<h2>summary</h2>
We can see the hierarchy of types mentioned above using <a href="_show__Structure.html" title="display parent structure">showStructure</a>.<table class="examples"><tr><td><pre>i49 : showStructure(List,Sequence,Array,Container,MutableList,Bag,BasicList)
o49 = Thing : BasicList : Container
MutableList : Bag
VisibleList : Array
List
Sequence
o49 : Descent</pre>
</td></tr>
</table>
</div>
<div><h3>Menu</h3>
<ul><li><span><a href="_ranges_spand_sprepetitions.html" title="">ranges and repetitions</a></span></li>
</ul>
<h4>basic access methods</h4>
<ul><li><span><a href="__sh_sp__Basic__List.html" title="length"># BasicList</a> -- length</span></li>
<li><span><a href="___Basic__List_sp_sh_sp__Z__Z.html" title="get element from list">BasicList # ZZ</a> -- get element from list</span></li>
<li><span><a href="___Basic__List_sp_sh_qu_sp__Z__Z.html" title="check for element in list">BasicList #? ZZ</a> -- check for element in list</span></li>
<li><span><a href="___Visible__List_sp_us_sp__Z__Z.html" title="get element from list">VisibleList _ ZZ</a> -- get element from list</span></li>
<li><span><a href="___Visible__List_sp_us_sp__List.html" title="get some entries of a list">VisibleList _ List</a> -- get some entries of a list</span></li>
<li><span><a href="_first.html" title="first element of a list">first</a> -- first element of a list</span></li>
<li><span><a href="_last.html" title="last element of a list">last</a> -- last element of a list</span></li>
</ul>
<h4>Conversions</h4>
<ul><li><span><a href="_to__List.html" title="list of elements">toList</a> -- list of elements</span></li>
<li><span><a href="_to__Sequence.html" title="convert to sequence">toSequence</a> -- convert to sequence</span></li>
<li><span><a href="_sequence.html" title="make a sequence">sequence</a> -- make a sequence</span></li>
<li><span><a href="_unsequence.html" title="extract the single element from a sequence of length 1">unsequence</a> -- extract the single element from a sequence of length 1</span></li>
</ul>
<h4>manipulating lists and sequences</h4>
<ul><li><span><a href="_append.html" title="append an element to a list">append</a> -- append an element to a list</span></li>
<li><span><a href="_between.html" title="insert something between elements of a list">between</a> -- insert something between elements of a list</span></li>
<li><span><a href="_delete.html" title="delete elements of a list">delete</a> -- delete elements of a list</span></li>
<li><span><a href="_drop.html" title="drop some elements from a list or sequence">drop</a> -- drop some elements from a list or sequence</span></li>
<li><span><a href="_flatten.html" title="flatten a list by unnesting lists">flatten</a> -- flatten a list by unnesting lists</span></li>
<li><span><a href="_fold.html" title="apply binary operator repeatedly">fold</a> -- apply binary operator repeatedly</span></li>
<li><span><a href="_join.html" title="join lists">join</a> -- join lists</span></li>
<li><span><a href="___List_sp_vb_sp__List.html" title="join lists, sequences or arrays">List | List</a> -- join lists, sequences or arrays</span></li>
<li><span><a href="_mingle.html" title="mingle elements of several lists">mingle</a> -- mingle elements of several lists</span></li>
<li><span><a href="_pack.html" title="pack elements of a list into shorter ones">pack</a> -- pack elements of a list into shorter ones</span></li>
<li><span><a href="_prepend.html" title="add an element to the beginning of a list">prepend</a> -- add an element to the beginning of a list</span></li>
<li><span>reverse, see <span><a href="_reverse_lp__Basic__List_rp.html" title="reverse a list">reverse(BasicList)</a> -- reverse a list</span></span></li>
<li><span><a href="_rsort.html" title="sort a list or matrix in reverse order">rsort</a> -- sort a list or matrix in reverse order</span></li>
<li><span><a href="_sort.html" title="sort a list or columns of a matrix">sort</a> -- sort a list or columns of a matrix</span></li>
<li><span><a href="_subtable.html" title="extract a subtable from a table">subtable</a> -- extract a subtable from a table</span></li>
<li><span><a href="_table.html" title="make a table (nested list)">table</a> -- make a table (nested list)</span></li>
<li><span><a href="_take.html" title="take some elements from a list">take</a> -- take some elements from a list</span></li>
<li><span><a href="_unique.html" title="eliminate duplicates from a list">unique</a> -- eliminate duplicates from a list</span></li>
</ul>
<h4>applying functions to elements of lists</h4>
<ul><li><span><a href="_apply_lp__Basic__List_cm__Function_rp.html" title="apply a function to each element of a list">apply(BasicList,Function)</a> -- apply a function to each element of a list</span></li>
<li><span><a href="_scan_lp__Basic__List_cm__Function_rp.html" title="apply a function to each element of a list">scan(BasicList,Function)</a> -- apply a function to each element of a list</span></li>
</ul>
<h4>testing elements of lists</h4>
<ul><li><span><a href="_all_lp__Basic__List_cm__Function_rp.html" title="whether all elements of a list satisfy a specified condition">all(BasicList,Function)</a> -- whether all elements of a list satisfy a specified condition</span></li>
<li><span><a href="_any_lp__Basic__List_cm__Function_rp.html" title="whether any elements of a list satisfy a specified condition">any(BasicList,Function)</a> -- whether any elements of a list satisfy a specified condition</span></li>
</ul>
<h4>finding things in lists</h4>
<ul><li><span>position(VisibleList,Function), see <span><a href="_position.html" title="find first element of a list satisfying a condition">position</a> -- find first element of a list satisfying a condition</span></span></li>
<li><span><a href="_positions_lp__Visible__List_cm__Function_rp.html" title="which elements of a list satisfy a condition">positions(VisibleList,Function)</a> -- which elements of a list satisfy a condition</span></li>
<li><span><a href="_select_lp__Basic__List_cm__Function_rp.html" title="select elements from a list">select(BasicList,Function)</a> -- select elements from a list</span></li>
<li><span><a href="_select_lp__Z__Z_cm__Basic__List_cm__Function_rp.html" title="select a limited number of elements from a list">select(ZZ,BasicList,Function)</a> -- select a limited number of elements from a list</span></li>
</ul>
<h4>more information</h4>
<ul><li><span><a href="___Visible__List.html" title="the class of all visible lists">VisibleList</a> -- the class of all visible lists</span></li>
<li><span><a href="___Basic__List.html" title="the class of all basic lists">BasicList</a> -- the class of all basic lists</span></li>
</ul>
</div>
</div>
</body>
</html>
