Changeset 13527 for docs/Perl6/Spec
- Timestamp:
- 09/21/06 05:43:41 (2 years ago)
- Files:
-
- 1 modified
-
docs/Perl6/Spec/Functions.pod (modified) (41 diffs)
Legend:
- Unmodified
- Added
- Removed
-
docs/Perl6/Spec/Functions.pod
r13519 r13527 14 14 Date: 12 Mar 2005 15 15 Last Modified: 20 Sep 2006 16 Version: 716 Version: 8 17 17 18 18 This document attempts to document the list of builtin functions in Perl 6. … … 27 27 =head1 Notes 28 28 29 In Perl 6, all builtin functions belong to a named package. Not all 29 In Perl 6, all builtin functions belong to a named package (generally a 30 class or role). Not all 30 31 functions are guaranteed to be imported into the global package 31 32 C<::*>. In addition, the list of functions imported into C<::*> will be … … 54 55 of this document. 55 56 57 =head2 Multis vs. Functions 58 59 In actual fact, most of the "functions" defined here are multi subs, 60 or are multi methods that are also exported as multi subs. Multi subs 61 are all visible in the global namespace (unless declared with a "my 62 multi"). The assumption is that with sufficiently specific typing on 63 the multis, the user is free to extend a particular name to new types. 64 56 65 =head1 Type Declarations 57 66 … … 100 109 (Plus the corresponding C<StrLingua> types, presumably.) 101 110 102 =item Match Test103 104 subset Match Testof Item | Junction;111 =item Matcher 112 113 subset Matcher of Item | Junction; 105 114 106 115 Used to supply a test to match against. Assume C<~~> will be used against it. … … 114 123 =head1 Function Packages 115 124 116 =head2 Math::Basic 117 118 B<API document>: L<Math::Basic> 119 120 C<Math::Basic> provides a number of constants in addition to the basic 125 =head2 Num 126 127 The following are all defined in the C<Num> role: 128 129 B<API document>: L<Num> 130 131 C<Num> provides a number of constants in addition to the basic 121 132 mathematical functions. To get these constants, you must request 122 133 them: 123 134 124 use Math::Basic:constants;125 126 or use the full name, e.g. C< Math::Basic::pi>.135 use Num :constants; 136 137 or use the full name, e.g. C<Num::pi>. 127 138 128 139 =over … … 130 141 =item abs 131 142 132 our Num multi Math::Basic::abs ( Num $x )143 our Num multi method abs ( Num $x: ) is export 133 144 134 145 Absolute Value. … … 136 147 =item floor 137 148 138 our Int multi Math::Basic::floor ( Num $x )149 our Int multi method floor ( Num $x: ) is export 139 150 140 151 Returns the highest integer not greater than $x. … … 142 153 =item ceiling 143 154 144 our Int multi Math::Basic::ceiling ( Num $x ) 145 our Int multi Math::Basic::ceil ( Num $x ) 155 our Int multi method ceil ( Num $x: ) is export 146 156 147 157 Returns the lowest integer not less than $x. … … 149 159 =item round 150 160 151 our Int multi Math::Basic::round ( Num $x )161 our Int multi method round ( Num $x: ) is export 152 162 153 163 Returns the nearest integer to $x. The algorithm is floor($x + 0.5). … … 156 166 =item truncate 157 167 158 our Int multi Math::Basic::truncate ( Num $x )159 our Int multi Math::Basic::int ( Num $x )168 our Int multi method truncate ( Num $x: ) is export 169 our Int multi method int ( Num $x: ) is export 160 170 161 171 Returns the closest integer to $x whose absolute value is not greater … … 167 177 =item exp 168 178 169 our Num multi Math::Basic::exp ( Num $exponent, Num :$base = Num::e )179 our Num multi method exp ( Num $exponent: Num :$base = Num::e ) is export 170 180 171 181 Performs similar to C<$base ** $exponent>. C<$base> defaults to the … … 174 184 =item log 175 185 176 our Num multi Math::Basic::log ( Num $x, Num :$base )186 our Num multi method log ( Num $x: Num :$base = Num::e ) is export 177 187 178 188 Logarithm of base C<$base>, default Natural. Calling with C<$x == 0> is an … … 182 192 =item log10 183 193 184 our Num multi Math::Basic::log10 (Num $x);194 our Num multi method log10 (Num $x:); is export 185 195 186 196 A base C<10> logarithm, othewise identical to C<log>. … … 188 198 =item rand 189 199 190 our Num multi Math::Basic::rand ( Num $x = 1 ) 200 our Num multi method rand ( Num $x: ) 201 our Num multi rand ( Num $x = 1 ) 191 202 192 203 Pseudo random number in range C<< 0 ..^ $x >>. That is, C<0> is theoretically possible, … … 196 207 =item sign 197 208 198 our Int multi Math::Basic::sign ( Num $x )209 our Int multi method sign ( Num $x: ) is export 199 210 200 211 Returns 1 when C<$x> is greater than 0, -1 when it is less than 0, 0 when it … … 203 214 =item srand 204 215 205 multi Math::Basic::srand ( Num $seed = default_seed_algorithm()) 216 multi method srand ( Num $seed: ) 217 multi srand ( Num $seed = default_seed_algorithm()) 206 218 207 219 Seed the generator C<rand> uses. C<$seed> defaults to some combination … … 213 225 =item sqrt 214 226 215 our Num multi Math::Basic::sqrt ( Num $x )227 our Num multi method sqrt ( Num $x: ) is export 216 228 217 229 Returns the square root of the parameter. … … 230 242 231 243 232 =head2 Math::Trig 244 =head2 The :Trig tag 245 246 The following are also defined in C<Num> but not exported without a C<:Trig> 247 tag. (Which installs their names into C<Num::Trig>, as it happens.) 233 248 234 249 =over 4 … … 236 251 =item I<Standard Trig Functions> 237 252 238 our Num multi Num::func ( Num $x, $base = 'radians' ) 239 our Num multi Math::Trig::func ( Num $x, $base = 'radians' ) 253 Num multi method func ( Num $x: $base = 'radians' ) is export(:Trig) 240 254 241 255 where I<func> is one of: … … 259 273 a consistent base so you don't have to supply it with every call: 260 274 261 my module Trig ::= Math::Trig.assuming(:base<degrees>);275 my module Trig ::= Num::Trig.assuming(:base<degrees>); 262 276 263 277 This overrides the default of "radians". … … 265 279 =item atan2 266 280 267 our Num multi Math::Trig::atan2 ( Num $y, Num $x = 1, Num $base ) 281 our Num multi method atan2 ( Num $y: Num $y = 1 ) 282 our Num multi atan2 ( Num $y, Num $x = 1 ) 268 283 269 284 This second form of C<atan> computes the arctangent of $y/$x, and takes 270 285 the quadrant into account. Otherwise behaves as other trigonometric functions. 271 272 [Note: changed atan back to atan2, or the default $x = 1 will confuse MMD.273 The other alternative would be to remove the default. --law]274 286 275 287 =back … … 436 448 =head2 Array 437 449 450 All these methods are defined in the C<Array> role/class. 451 438 452 =over 439 453 440 454 =item delete 441 455 442 our List multi method Array::delete (@array : *@indices )456 our List multi method delete (@array : *@indices ) is export 443 457 444 458 Sets elements specified by C<@indices> in the invocant to a … … 457 471 =item exists 458 472 459 our Bool multi method Array::exists (@array : Int *@indices )473 our Bool multi method exists (@array : Int *@indices ) is export 460 474 461 475 True if the specified Array element has been assigned to. This … … 470 484 =item pop 471 485 472 473 our Scalar multi Array::pop ( @array is rw ) 474 our Scalar multi method Array::pop ( @array: ) 486 our Scalar multi method pop ( @array: ) is export 475 487 476 488 Remove the last element of C<@array> and return it. … … 478 490 =item push 479 491 480 our Int multi Array::push ( @array is rw, *@values ) 481 our Int multi method Array::push ( @array: *@values ) 492 our Int multi method push ( @array: *@values ) is export 482 493 483 494 Add to the end of C<@array>, all of the subsequent arguments. … … 485 496 =item shift 486 497 487 our Scalar multi Array::shift ( @array is rw ) 488 our Scalar multi method Array::shift ( @array: ) 498 our Scalar multi method shift ( @array: ) is export 489 499 490 500 Remove the first element from C<@array> and return it. … … 492 502 =item splice 493 503 494 our List multi Array::splice( @array is rw, Int $offset = 0, Int $size?, *@values )504 our List multi method splice( @array is rw, Int $offset = 0, Int $size?, *@values ) is export 495 505 496 506 C<splice> fills many niches in array-management, but its fundamental behavior … … 524 534 =item unshift 525 535 526 our Int multi Array::unshift ( @array is rw, *@values ) 527 our Int multi method Array::unshift ( @array: *@values ) 536 our Int multi method unshift ( @array: *@values ) is export 528 537 529 538 C<unshift> adds the values onto the start of the C<@array>. … … 537 546 =item values 538 547 539 multi Int|List Array::keys ( @array ; MatchTest *@indextests ) 540 multi Int|List Array::kv ( @array ; MatchTest *@indextests ) 541 multi Int|(List of Pair) Array::pairs (@array ; MatchTest *@indextests ) 542 multi Int|List Array::values ( @array ; MatchTest *@indextests ) 543 544 (XXX these signatures are wrong. -luqui) 548 our List multi method keys ( @array: Matcher *@indextests ) is export 549 our List multi method kv ( @array: Matcher *@indextests ) is export 550 our List multi method pairs (@array: Matcher *@indextests ) is export 551 our List multi method values ( @array: Matcher *@indextests ) is export 545 552 546 553 Iterates the elements of C<@array>, in order. … … 565 572 =head2 List 566 573 574 The following are defined in the C<List> role/class: 575 567 576 =over 568 577 569 578 =item classify 570 579 571 our Lazy of Pair multi Array::classify ( @values, Code *&test ) 572 our Lazy of Pair multi Array::classify ( @values, MatchTest $test ) 573 our Lazy of Pair multi List::classify ( MatchTest $test, *@values ) 580 our Lazy of Pair multi method classify ( @values: Matcher $test ) 581 our Lazy of Pair multi classify ( Matcher $test, *@values ) 574 582 575 583 C<classify> takes a list or array of values and returns a lazily evaluated … … 593 601 =item grep 594 602 595 our Lazy multi Array::grep ( @values, Code *&test ) 596 our Lazy multi Array::grep ( @values, MatchTest $test ) 597 our Lazy multi List::grep ( MatchTest $test, *@values ) 603 our Lazy multi method grep ( @values: Matcher $test ) 604 our Lazy multi grep ( Matcher $test, *@values ) 598 605 599 606 C<grep> takes a list or array of values and returns a lazily evaluated … … 603 610 Here is an example of its use: 604 611 605 @friends = grep { .is_friend } @coworkers;612 @friends = grep { .is_friend }, @coworkers; 606 613 607 614 This takes the array C<@coworkers>, checks every element to see … … 609 616 the resulting list to store into C<@friends>. 610 617 618 Note that, unlike in Perl 5, a comma is required after the C<Matcher> 619 in the multi form. 620 621 =item pick 622 623 our Lazy multi method pick ( @values: Int $num = 1 ) 624 our Lazy multi method pick ( @values: Whatever ) 625 our Lazy multi pick ( Int $num, *@values ) 626 our Lazy multi pick ( Whatever, *@values ) 627 628 C<pick> takes a list or array of values and returns a random selection 629 of elements from the list (without replacement). If C<*> is specified 630 as the number (or if the number of elements in the list is less than 631 the specified number), all the available elements are returned in 632 random order: 633 634 @team = @volunteers.pick(5); 635 @shuffled = @deck.pick(*); 636 611 637 =item join 612 638 613 our Str multi Array::join ( @values, Str $separator?)614 our Str multi List::join ( Str $separator?, *@values )639 our Str multi method join ( @values: Str $separator = ' ' ) 640 our Str multi join ( Str $separator = ' ', *@values ) 615 641 616 642 C<join> returns a single string comprised of all of the elements … … 620 646 Given an empty list, C<join> returns the empty string. 621 647 648 To join with no separator you can use the C<[~]> reduce operator. 649 622 650 =item map 623 651 624 our Lazy multi Array::map ( @values,Code *&expression )625 our Lazy multi List::map ( Code $expression?, *@values )652 our Lazy multi method map ( @values: Code *&expression ) 653 our Lazy multi map ( Code $expression, *@values ) 626 654 627 655 C<map> returns a lazily evaluated list which is comprised of … … 631 659 Here is an example of its use: 632 660 633 @addresses = map { %addresses_by_name<$_> } @names;661 @addresses = map { %addresses_by_name<$_> }, @names; 634 662 635 663 Here we take an array of names, and look each name up in … … 641 669 that were passed. For example: 642 670 643 @factors = map { prime_factors($_) } @composites;671 @factors = map { prime_factors($_) }, @composites; 644 672 645 673 =item reduce 646 674 647 our Scalar multi Array::reduce ( @values ;Code *&expression )648 our Scalar multi List::reduce ( Code $expression ; *@values )675 our Item multi method reduce ( @values: Code *&expression ) 676 our Item multi reduce ( Code $expression ; *@values ) 649 677 my $res; 650 678 for @values -> $cur { … … 658 686 =item reverse 659 687 660 our Hash multi Hash::reverse ( %hash ) { 661 (my %result){%hash.values} = %hash.keys; 662 %result; 688 role Hash { 689 our Hash multi method reverse ( %hash: ) is export { 690 (my %result){%hash.values} = %hash.keys; 691 %result; 692 } 663 693 } 664 694 665 multi Lazy Array::reverse ( @values )666 multi Lazy List::reverse ( *@values ) {695 our Lazy multi method reverse ( @values: ) is export 696 our Lazy multi reverse ( *@values ) { 667 697 gather { 668 698 1 while take pop @values; … … 670 700 } 671 701 672 multi Str Str::reverse ( $str ) { 673 split('', $str).reverse.join 674 ) 702 role Str { 703 our Str multi method reverse ( $str: ) is export { 704 split('', $str).reverse.join 705 ) 706 } 675 707 676 708 677 709 =item sort 678 710 679 subset KeyExtractor of Code (Any --> Any);680 subset Comparator of Code (Any, Any --> Int );681 subset SortCriterion of KeyExtractor | Comparator | Pair(KeyExtractor, Comparator);682 683 our Array multi Array::sort( @values is rw, *&by, Bit $inplace?)684 our Array multi Array::sort( @values is rw, SortCriterion @by, Bit $inplace?)685 our Array multi Array::sort( @values is rw, SortCriterion $by = &infix:<cmp>, Bit $inplace?)686 687 our List multi List::sort( SortCriterion @by, *@values )688 our List multi List::sort( SortCriterion $by = &infix:<cmp>, *@values )711 subset KeyExtractor of Code where { .sig === :(Any --> Any) }; 712 subset Comparator of Code where { .sig === :(Any, Any --> Int ) }; 713 subset SortCriterion of Signature | KeyExtractor | Comparator | Pair(KeyExtractor, Comparator); 714 715 our Array multi method sort( @values: *&by ) 716 our Array multi method sort( @values: SortCriterion @by ) 717 our Array multi method sort( @values: SortCriterion $by = &infix:<cmp> ) 718 719 our List multi sort( SortCriterion @by, *@values ) 720 our List multi sort( SortCriterion $by = &infix:<cmp>, *@values ) 689 721 690 722 Returns C<@values> sorted, using criteria C<$by> or C<@by> for 691 comparisons. C<@by> differs from C<$by> in that each criteri ais723 comparisons. C<@by> differs from C<$by> in that each criterion is 692 724 applied, in order, until a non-zero (tie) result is achieved. 693 725 694 Criteri oncan take a few different forms:726 Criteria can take a few different forms: 695 727 696 728 =over 8 … … 704 736 =item KeyExtractor 705 737 706 A closure with arity of 1, which returns the "key" by which to sort. If 707 the closure returns a Num, C<E<lt>=E<gt>> is used for comparison, 708 otherwise C<cmp>. 738 A closure with arity of 1, which returns the "key" by which to sort. 739 Values are compared using C<cmp>, which in Perl 6 does different 740 comparisons depending on the types. (To get a Perl 5 string comparison 741 you must use C<leg> instead.) 709 742 710 743 =item Pair(KeyExtractor, Comparator) … … 712 745 A combination of the two methods above, for when one wishes to take 713 746 advantage of the internal caching of keys that is expected to happen, 714 but wishes to compare them with something other than C<E<lt>=E<gt>> or 715 C<cmp>. 716 717 =back 718 719 Any Criterion may receive either or both of the traits C<is descending> 720 and C<is insensitive> to reverse the order of sort, or the adjust the 721 case sensitivity of C<cmp> as a Comparator. 747 but wishes to compare them with something other than C<cmp>, such 748 as C<E<lt>=E<gt>> or C<leg>. 749 750 =item Signature 751 752 If a signature is specified as a criterion, the signature is bound 753 to each value and then each parameter does comparisons in positional order 754 according to its type, as modified by its traits. Sort-specific traits 755 are allowed in such a signature such as C<is descending> or C<is insensitive>. 756 Basically, the system will write the body of the key extraction subroutine 757 for you based on the signature. 758 759 =back 760 761 Any Criterion may receive either or both of the mixins C<descending> 762 and C<insensitive> to reverse the order of sort, or the adjust the 763 case sensitivity of C<cmp> as a Comparator. (Mixins are applied to 764 values using C<but>.) 722 765 723 766 If all criteria are exhausted when comparing two elements, sort should 724 767 return them in the same relative order they had in C<@values>. 725 768 726 If C<$inplace> is specified, the array is sorted in place.769 To sort an array in place use the C<.=sort> mutator form. 727 770 728 771 See L<http://www.nntp.perl.org/group/perl.perl6.language/16578> for more … … 782 825 =item values 783 826 784 multi Int|List Hash::keys ( %hash ; Match Test*@keytests )785 multi Int|List Hash::kv ( %hash ; Match Test*@keytests )786 multi Int|(List of Pair) Hash::pairs (%hash ; Match Test*@keytests )787 multi Int|List Hash::values ( %hash ; Match Test*@keytests )827 multi Int|List Hash::keys ( %hash ; Matcher *@keytests ) 828 multi Int|List Hash::kv ( %hash ; Matcher *@keytests ) 829 multi Int|(List of Pair) Hash::pairs (%hash ; Matcher *@keytests ) 830 multi Int|List Hash::values ( %hash ; Matcher *@keytests ) 788 831 789 832 Iterates the elements of C<%hash> in no apparent order, but the order
