mingw/html/ext/List/Util/lib/List/Util.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>List::Util - A selection of general-utility list subroutines</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;List::Util - A selection of general-utility list subroutines</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#known_bugs">KNOWN BUGS</a></li>
  26         <li><a href="#suggested_additions">SUGGESTED ADDITIONS</a></li>
  27         <li><a href="#copyright">COPYRIGHT</a></li>
  28 </ul>
  29 <!-- INDEX END -->
  30
  31 <hr />
  32 <p>
  33 </p>
  34 <h1><a name="name">NAME</a></h1>
  35 <p>List::Util - A selection of general-utility list subroutines</p>
  36 <p>
  37 </p>
  38 <hr />
  39 <h1><a name="synopsis">SYNOPSIS</a></h1>
  40 <pre>
  41     use List::Util qw(first max maxstr min minstr reduce shuffle sum);</pre>
  42 <p>
  43 </p>
  44 <hr />
  45 <h1><a name="description">DESCRIPTION</a></h1>
  46 <p><code>List::Util</code> contains a selection of subroutines that people have
  47 expressed would be nice to have in the perl core, but the usage would
  48 not really be high enough to warrant the use of a keyword, and the size
  49 so small such that being individual extensions would be wasteful.</p>
  50 <p>By default <code>List::Util</code> does not export any subroutines. The
  51 subroutines defined are</p>
  52 <dl>
  53 <dt><strong><a name="item_first">first BLOCK LIST</a></strong>
  54
  55 <dd>
  56 <p>Similar to <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_grep"><code>grep</code></a> in that it evaluates BLOCK setting <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item___"><code>$_</code></a> to each element
  57 of LIST in turn. <a href="#item_first"><code>first</code></a> returns the first element where the result from
  58 BLOCK is a true value. If BLOCK never returns true or LIST was empty then
  59 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> is returned.</p>
  60 </dd>
  61 <dd>
  62 <pre>
  63     $foo = first { defined($_) } @list    # first defined value in @list
  64     $foo = first { $_ &gt; $value } @list    # first value in @list which
  65                                           # is greater than $value</pre>
  66 </dd>
  67 <dd>
  68 <p>This function could be implemented using <a href="#item_reduce"><code>reduce</code></a> like this</p>
  69 </dd>
  70 <dd>
  71 <pre>
  72     $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list</pre>
  73 </dd>
  74 <dd>
  75 <p>for example <code>wanted()</code> could be <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_defined"><code>defined()</code></a> which would return the first
  76 defined value in @list</p>
  77 </dd>
  78 </li>
  79 <dt><strong><a name="item_max">max LIST</a></strong>
  80
  81 <dd>
  82 <p>Returns the entry in the list with the highest numerical value. If the
  83 list is empty then <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> is returned.</p>
  84 </dd>
  85 <dd>
  86 <pre>
  87     $foo = max 1..10                # 10
  88     $foo = max 3,9,12               # 12
  89     $foo = max @bar, @baz           # whatever</pre>
  90 </dd>
  91 <dd>
  92 <p>This function could be implemented using <a href="#item_reduce"><code>reduce</code></a> like this</p>
  93 </dd>
  94 <dd>
  95 <pre>
  96     $foo = reduce { $a &gt; $b ? $a : $b } 1..10</pre>
  97 </dd>
  98 </li>
  99 <dt><strong><a name="item_maxstr">maxstr LIST</a></strong>
 100
 101 <dd>
 102 <p>Similar to <a href="#item_max"><code>max</code></a>, but treats all the entries in the list as strings
 103 and returns the highest string as defined by the <code>gt</code> operator.
 104 If the list is empty then <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> is returned.</p>
 105 </dd>
 106 <dd>
 107 <pre>
 108     $foo = maxstr 'A'..'Z'          # 'Z'
 109     $foo = maxstr &quot;hello&quot;,&quot;world&quot;   # &quot;world&quot;
 110     $foo = maxstr @bar, @baz        # whatever</pre>
 111 </dd>
 112 <dd>
 113 <p>This function could be implemented using <a href="#item_reduce"><code>reduce</code></a> like this</p>
 114 </dd>
 115 <dd>
 116 <pre>
 117     $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z'</pre>
 118 </dd>
 119 </li>
 120 <dt><strong><a name="item_min">min LIST</a></strong>
 121
 122 <dd>
 123 <p>Similar to <a href="#item_max"><code>max</code></a> but returns the entry in the list with the lowest
 124 numerical value. If the list is empty then <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> is returned.</p>
 125 </dd>
 126 <dd>
 127 <pre>
 128     $foo = min 1..10                # 1
 129     $foo = min 3,9,12               # 3
 130     $foo = min @bar, @baz           # whatever</pre>
 131 </dd>
 132 <dd>
 133 <p>This function could be implemented using <a href="#item_reduce"><code>reduce</code></a> like this</p>
 134 </dd>
 135 <dd>
 136 <pre>
 137     $foo = reduce { $a &lt; $b ? $a : $b } 1..10</pre>
 138 </dd>
 139 </li>
 140 <dt><strong><a name="item_minstr">minstr LIST</a></strong>
 141
 142 <dd>
 143 <p>Similar to <a href="#item_min"><code>min</code></a>, but treats all the entries in the list as strings
 144 and returns the lowest string as defined by the <code>lt</code> operator.
 145 If the list is empty then <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> is returned.</p>
 146 </dd>
 147 <dd>
 148 <pre>
 149     $foo = minstr 'A'..'Z'          # 'A'
 150     $foo = minstr &quot;hello&quot;,&quot;world&quot;   # &quot;hello&quot;
 151     $foo = minstr @bar, @baz        # whatever</pre>
 152 </dd>
 153 <dd>
 154 <p>This function could be implemented using <a href="#item_reduce"><code>reduce</code></a> like this</p>
 155 </dd>
 156 <dd>
 157 <pre>
 158     $foo = reduce { $a lt $b ? $a : $b } 'A'..'Z'</pre>
 159 </dd>
 160 </li>
 161 <dt><strong><a name="item_reduce">reduce BLOCK LIST</a></strong>
 162
 163 <dd>
 164 <p>Reduces LIST by calling BLOCK multiple times, setting <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__a"><code>$a</code></a> and <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__b"><code>$b</code></a>
 165 each time. The first call will be with <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__a"><code>$a</code></a> and <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__b"><code>$b</code></a> set to the first
 166 two elements of the list, subsequent calls will be done by
 167 setting <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__a"><code>$a</code></a> to the result of the previous call and <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__b"><code>$b</code></a> to the next
 168 element in the list.</p>
 169 </dd>
 170 <dd>
 171 <p>Returns the result of the last call to BLOCK. If LIST is empty then
 172 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> is returned. If LIST only contains one element then that
 173 element is returned and BLOCK is not executed.</p>
 174 </dd>
 175 <dd>
 176 <pre>
 177     $foo = reduce { $a &lt; $b ? $a : $b } 1..10       # min
 178     $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
 179     $foo = reduce { $a + $b } 1 .. 10               # sum
 180     $foo = reduce { $a . $b } @bar                  # concat</pre>
 181 </dd>
 182 </li>
 183 <dt><strong><a name="item_shuffle">shuffle LIST</a></strong>
 184
 185 <dd>
 186 <p>Returns the elements of LIST in a random order</p>
 187 </dd>
 188 <dd>
 189 <pre>
 190     @cards = shuffle 0..51      # 0..51 in a random order</pre>
 191 </dd>
 192 </li>
 193 <dt><strong><a name="item_sum">sum LIST</a></strong>
 194
 195 <dd>
 196 <p>Returns the sum of all the elements in LIST. If LIST is empty then
 197 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> is returned.</p>
 198 </dd>
 199 <dd>
 200 <pre>
 201     $foo = sum 1..10                # 55
 202     $foo = sum 3,9,12               # 24
 203     $foo = sum @bar, @baz           # whatever</pre>
 204 </dd>
 205 <dd>
 206 <p>This function could be implemented using <a href="#item_reduce"><code>reduce</code></a> like this</p>
 207 </dd>
 208 <dd>
 209 <pre>
 210     $foo = reduce { $a + $b } 1..10</pre>
 211 </dd>
 212 </li>
 213 </dl>
 214 <p>
 215 </p>
 216 <hr />
 217 <h1><a name="known_bugs">KNOWN BUGS</a></h1>
 218 <p>With perl versions prior to 5.005 there are some cases where reduce
 219 will return an incorrect result. This will show up as test 7 of
 220 reduce.t failing.</p>
 221 <p>
 222 </p>
 223 <hr />
 224 <h1><a name="suggested_additions">SUGGESTED ADDITIONS</a></h1>
 225 <p>The following are additions that have been requested, but I have been reluctant
 226 to add due to them being very simple to implement in perl</p>
 227 <pre>
 228   # One argument is true</pre>
 229 <pre>
 230   sub any { $_ &amp;&amp; return 1 for @_; 0 }</pre>
 231 <pre>
 232   # All arguments are true</pre>
 233 <pre>
 234   sub all { $_ || return 0 for @_; 1 }</pre>
 235 <pre>
 236   # All arguments are false</pre>
 237 <pre>
 238   sub none { $_ &amp;&amp; return 0 for @_; 1 }</pre>
 239 <pre>
 240   # One argument is false</pre>
 241 <pre>
 242   sub notall { $_ || return 1 for @_; 0 }</pre>
 243 <pre>
 244   # How many elements are true</pre>
 245 <pre>
 246   sub true { scalar grep { $_ } @_ }</pre>
 247 <pre>
 248   # How many elements are false</pre>
 249 <pre>
 250   sub false { scalar grep { !$_ } @_ }</pre>
 251 <p>
 252 </p>
 253 <hr />
 254 <h1><a name="copyright">COPYRIGHT</a></h1>
 255 <p>Copyright (c) 1997-2005 Graham Barr &lt;<a href="mailto:gbarr@pobox.com">gbarr@pobox.com</a>&gt;. All rights reserved.
 256 This program is free software; you can redistribute it and/or
 257 modify it under the same terms as Perl itself.</p>
 258 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 259 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 260 <big><strong><span class="block">&nbsp;List::Util - A selection of general-utility list subroutines</span></strong></big>
 261 </td></tr>
 262 </table>
 263
 264 </body>
 265
 266 </html>