=head1 Title [DRAFT] Synopsis 29 - Builtin Functions [DRAFT] =head1 Version Maintainer: Rod Adams Date: 12 Mar 2005 Last Modified: 03 Apr 2005 This document attempts to document the list of builtin functions in Perl 6. It assumes familiarity with Perl 5 and prior synopses. =head1 Notes In Perl 6, all builtin functions belong to a named package. Not all functions are guaranteed to be imported into the global package C<::*>. In addition, the list of functions imported into C<::*> will be subject to change with each release of Perl. Authors wishing to "Future Proof" their code should either specifically import the functions they will be using, or always refer to the functions by their full name. After 6.0.0 comes out, global aliases will not be removed lightly, and will never be removed at all without having gone through a deprecation cycle of at least a year. In any event, you can specify that you want the interface for a particular version of Perl, and that can be emulated by later versions of Perl to the extent that security updates allow. Where code is given here, it is intended to define semantics, not to dictate implementation. =head1 Type Declarations The following type declarations are assumed: =over =item Char The root class of all "character" types, regardless of level. This is a subtype of C, limited to a length of 1 at it's highest supported Unicode level. Subclasses (things that are C): =over =item LanguageChar aka LChar =item Grapheme aka Grf =item CodePoint aka CdPt =item Byte Yes, Byte is both a string and a number. =back =item MatchTest type MatchTest ::= Scalar | Junction; Used to supply a test to match against. Assume C<~~> will be used against it. =back =head1 Function Packages =head2 Math::Basic =over =item abs multi sub Perl6::Num::abs ( Num $x ) returns Num multi sub Math::Basic::abs (: Num ?$x = $CALLER::_ ) returns Num Absolute Value. =item exp multi sub Perl6::Num::exp ( Num $exponent : Num +$base) returns Num multi sub Math::Basic::exp (: Num ?$exponent = $CALLER::_, Num +$base) returns Num Performs similar to C<$base ** $exponent>. C<$base> defaults to the constant I. =item log multi sub Perl6::Num::log ( Num $x : Num +$base) returns Num multi sub Math::Basic::log (: Num ?$x = $CALLER::_, Num +$base) returns Num Logarithm of base C<$base>, default Natural. Calling with C<$x == 0> is an error. =item log10 &log10<> := &log<>.assuming:base(10); =item rand multi sub Math::Basic::rand (: Num ?$x = 1) returns Num Psuedo random number between C<0> and C<$x>. =item sign multi sub Perl6::Num::sign ( Num $x ) returns Int multi sub Math::Basic::sign (: Num ?$x = $CALLER::_) returns Int { if !defined($x) { return undef }; if $x < 0 { return -1 }; if $x > 0 { return 1 }; if $x == 0 { return 0 }; undef; } =item srand multi sub Math::Basic::srand (: Num ?$seed) Seed the generator C uses. C<$seed> defaults to some combination of various platform dependent characteristics to yield a non- deterministic seed. =item sqrt multi sub Perl6::Num::sqrt ( Num $x ) returns Num multi sub Math::Basic::sqrt (: Num ?$x = $CALLER::_) returns Num C<$x ** 0.5> =back =head2 Math::Trig =over 4 =item I multi sub Perl6::Num::func ( Num $x : +$base) returns Num multi sub Math::Trig::func (: Num ?$x = $CALLER::_, +$base) returns Num where I is one of: sin, cos, tan, asin, acos, atan, sec, cosec, cotan, asec, acosec, acotan, sinh, cosh, tanh, asinh, acosh, atanh, sech, cosech, cotanh, asech, acosech, acotanh. Performs the various trigonmetric functions. Option C<$base> is used to declare your how you measure your angles. Given the value of an arc representing a single full revolution. $base Result ---- ------- /:i ^r/ Radians (2*pi) /:i ^d/ Degrees (360) /:i ^g/ Gradians (400) Num Units of 1 revolution. =item atan multi sub Math::Trig::atan (Num $y, Num $x : Num +$base) returns Num This second form of C computes the arctangent of $y/$x, and takes the quadrant into account. Otherwise behaves as other trigonometric functions. Replaces Perl 5 C. =item pi multi sub Math::Trig::pi () returns Num =back =head2 Perl6::Array =over =item delete multi method Perl6::Array::delete (@array : *@indices) returns List Sets elements specified by C<@indices> in the invocant to a non-existent state, as if they never had a value. Deleted elements at the end of an Array shorten the length of the Array, unless doing so would violate an C definition. C<@indices> is interpreted the same way as subscripting is in terms of slices and multidimensionality. See Synopsis 9 for details. Returns the value(s) previously held in deleted locations. An unary form is expected. See C. =item exists multi method Perl6::Array::exists (@array : Int *@indices) returns Bool True if the specified Array element has been assigned to. This is not the same as being defined. Supplying a different number of indices than invocant has dimensions is an error. An unary form is expected. See C. =item pop &Perl6::Array::pop := &Perl6::Array::splice.assuming(:offset(-1) :length(1)); multi sub Perl6::Array::pop () returns Scalar { pop @CALLER::_; } =item push multi sub Perl6::Array::push (@array is rw : *@values) returns Int { Perl6::Array::splice(@array, @array.elems, 0, @values); @array.elems; } =item shift &Perl6::Array::shift := &Perl6::Array::splice.assuming(:offset(0) :length(1)); multi sub Perl6::Array::shift () returns Scalar { Perl6::Array::shift @CALLER::_; } =item splice multi sub Perl6::Array::splice ( @array is rw : Int ?$offset = 0, Int ?$length, *@values ) returns List is rw Behaves similar as Perl 5 C. If C<@array> is multidimensional, C operates only on the first dimension, and works with Array References. =item unshift multi sub Perl6::Array::unshift (@array is rw : *@values) returns Int { Perl6::Array::splice(@array, 0, 0, @values); @array.elems; } =item keys =item kv =item pairs =item values multi sub Perl6::Array::keys (@array : MatchTest *@indextests) returns Int|List multi sub Perl6::Array::kv (@array : MatchTest *@indextests) returns Int|List multi sub Perl6::Array::pairs (@array : MatchTest *@indextests) returns Int|(List of Pair) multi sub Perl6::Array::values (@array : MatchTest *@indextests) returns Int|List Iterates the elements of C<@array>, in order. If C<@indextests> are provided, only elements whose indices match C<$index ~~ any(@indextests)> are iterated. What is returned at each element of the iteration varies with function. C returns the value of the associated element; C returns a 2 element list in (index, value) order, C a C. C<@array> is considered single dimensional. If it is in fact multi- dimensional, the values returned will be array references to the sub array. In Scalar context, they all return the count of elements that would have been iterated. =back =head2 Perl6::List =over =item grep multi sub Perl6::Array::grep (@values : Code *&test ) returns Lazy multi sub Perl6::Array::grep (@values, MatchTest $test ) returns Lazy multi sub Perl6::List::grep (MatchTest $test : *@values) returns Lazy { gather { for @values -> $x { take $x if $x ~~ $test; } } } =item join multi sub Perl6::Array::join (@values, Str $delimiter) returns Str multi sub Perl6::List::join (Str $delimiter : *@values) returns Str { my $str = ~@values[0]; for 1..@values.end { $str ~= $delimiter ~ @values[$_]; } $str; } &join<> := &join.assuming:delimiter(' '); =item map multi sub Perl6::Array::map (@values, Code $expression) returns Lazy multi sub Perl6::List::map (Code $expression : *@values) returns Lazy { gather { while @values { take $expression .( splice(@values, 0, $expression.arity) ); } } } =item reduce multi sub Perl6::Array::reduce (@values : Code *&expression) returns Scalar multi sub Perl6::List::reduce (Code $expression : *@values) returns Scalar { my $res; for @values -> $cur { FIRST {$res = $cur; next;} $res = &$expression($res, $cur); } $res; } =item reverse multi sub Perl6::Hash::reverse (%hash) returns Hash is default { my %result; for %hash.kv -> $k, $v { %result{$v} = $k; } %result; } multi sub Perl6::Array::reverse ( @values) returns Lazy|Str { multi sub Perl6::List::reverse (: *@values) returns Lazy|Str { given want { when List { gather { 1 while take pop @values; } } when Scalar { reverse @values ==> join; } } } =item sort type KeyExtractor ::= Code(Any) returns Any; type Comparator ::= Code(Any, Any) returns Int; type SortCriterion ::= KeyExtractor | Comparator | Pair(KeyExtractor, Comparator); multi sub Perl6::Array::sort( @values is rw, *&by : Bit +$inplace ) returns Array multi sub Perl6::Array::sort( @values is rw, SortCriterion @by : Bit +$inplace ) returns Array multi sub Perl6::Array::sort( @values is rw : SortCriterion +$by = &infix:, Bit +$inplace ) returns Array multi sub Perl6::List::sort( SortCriterion @by : *@values ) returns List multi sub Perl6::List::sort(: SortCriterion $by = &infix:, *@values ) returns List Returns C<@values> sorted, using criteria C<$by> or C<@by> for comparisions. C<@by> differs from C<$by> in that each criteria is applied, in order, until a non-zero (tie) result is achieved. Criterion can take a few different forms: =over 8 =item Comparator A closure with arity of 2, which returns negative/zero/positive, signaling the first arguement should be before/tied with/after the second in the final ordering of the List. aka "The Perl 5 way" =item KeyExtractor A closure with arity of 1, which returns the "key" by which to sort. If the closure returns a Num, C=E> is used for comparison, otherwise C. =item Pair(KeyExtractor, Comparator) A combination of the two methods above, for when one wishs to take advantage of the internal caching of keys that is expected to happen, but wishes to compare them with something other than C=E> or C. =back Any Criterion may recieve either or both of the traits C and C to reverse the order of sort, or the adjust the case sensitivity of C as a Comparator. If all criteria are exhausted when comparing two elements, sort should return them in the same relative order they had in C<@values>. If C<$inplace> is specified, the array is sorted in place. See L for more details and examples. =item zip multi sub Perl6::Lists::zip (: Array *@lists, Bit +$shortest) returns Lazy { gather { while $shortest ?? all (@lists) :: any(@lists) { for @lists -> @list { take shift @list; } } } } =back =head2 Perl6::Hash =over 4 =item delete multi method Perl6::Hash::delete (: *@keys) returns List multi method Perl6::Hash::delete ( $key ) returns Scalar is default Deletes the elements specified by C<$key> or C<$keys> from the invocant. returns the value(s) that were associated to those keys. =over =item Unary Form Implementations should create a suitable macro, or otherwise support the unary form C in all it's forms. Below are some example translations. This list is I exhaustive. delete %hash{$key} %hash.delete{$key} delete %hash %hash.delete{'key'} delete %hash{@keys} %hash.delete{@keys} =back =item exists multi method Perl6::Hash::exists ($key) returns Bool True if invocant has an element whose key matches C<$key>, false otherwise. An unary form is expected. See Perl6::Hash::delete =item keys =item kv =item pairs =item values multi sub Perl6::Hash::keys (%hash : MatchTest *@keytests) returns Int|List multi sub Perl6::Hash::kv (%hash : MatchTest *@keytests) returns Int|List multi sub Perl6::Hash::pairs (%hash : MatchTest *@keytests) returns Int|(List of Pair) multi sub Perl6::Hash::values (%hash : MatchTest *@keytests) returns Int|List Iterates the elements of C<%hash> in no apparent order, but the order will be the same between successive calls to these functions, as long as C<%hash> doesn't change. If C<@keytests> are provided, only elements whose keys evaluate C<$key ~~ any(@keytests)> as true are iterated. What is returned at each element of the iteration varies with function. C only returns the key; C the value; C returns both as a 2 element list in (key, value) order, C a C. Note that C returns the same as C In Scalar context, they all return the count of elements that would have been iterated. The lvalue form of C is not longer supported. Use the C<.buckets> property instead. =back =head2 Perl6::Str General notes about strings: A Str can exist at several Unicode levels at once. Which level you interact with typically depends on what your current lexical context has declared the "working unicode level to be". Default is LChars. Attempting to use a string at a level higher it can support is handled without warning. The highest supported level is simply mapped char for char to the desired level. However, attempting to stuff something into the string at a higher level that doesn't map to the lower level is an error (for example, attempting to store Kanji in a Byte uplifted to an LChar). Attempting to use a string at a level lower than what it supports is not allowed. If a function takes a C and returns a C, the returned C will support the same levels as the input, unless specified otherwise. =over =item chop multi sub Perl6::Str::chop ( Str $string is rw ) returns Char multi sub Perl6::Str::chop (: Str *@strings = ($CALLER::_) is rw ) returns Char Trims the last character from C<$string>, and returns it. Called with a list, it chops each item in turn, and returns the last character chopped. =item chomp multi sub Perl6::Str::chomp ( Str $string is rw ) returns Int multi sub Perl6::Str::chomp (: Str *@strings = ($CALLER::_) is rw ) returns Int Related to C, only removes trailing chars that match C. In either case, it returns the number of chars removed. Note: Most users should consider setting their I/O handles to autochomp instead of this step. =item lc multi sub Perl6::Str::lc ( Str $string ) returns Str multi sub Perl6::Str::lc (: Str ?$string = $CALLER::_ ) returns Str Returns the input string after converting each character to it's lowercase form, if uppercase. =item lcfirst multi sub Perl6::Str::lcfirst ( Str $string ) returns Str multi sub Perl6::Str::lcfirst (: Str ?$string = $CALLER::_ ) returns Str Like C, but only affects the first character. =item uc multi sub Perl6::Str::uc ( Str $string ) returns Str multi sub Perl6::Str::uc (: Str ?$string = $CALLER::_ ) returns Str Returns the input string after converting each character to it's uppercase form, if lowercase. This is not a Unicode "titlecase" operation, but a full "uppercase". =item ucfirst multi sub Perl6::Str::ucfirst ( Str $string ) returns Str multi sub Perl6::Str::ucfirst (: Str ?$string = $CALLER::_ ) returns Str Performs a Unicode "titlecase" operation on the first character of the string. =item capitalize multi sub Perl6::Str::capitalize ( Str $string ) returns Str multi sub Perl6::Str::capitalize (: Str ?$string = $CALLER::_ ) returns Str Has the effect of first doing an C on the entire string, then performing a C on it. =item length =item index =item pack =item pos =item quotemeta =item rindex =item split multi sub Perl6::Str::split ( Str $delimiter , Str ?$input = $CALLER::_ ) returns List multi sub Perl6::Str::split ( Rule $delimiter , Str ?$input = $CALLER::_ ) returns List multi sub Perl6::Str::split ( Str $input : Str $delimiter ) returns List multi sub Perl6::Str::split ( Str $input : Rule $delimiter ) returns List &split<> := &split.assuming:delimiter(' '); =item sprintf =item substr multi sub substr(Str $s, StrPos $start : StrPos ?$end, ?$replace) multi sub substr(Str $s, StrPos $start, StrLen $length : ?$replace) multi sub substr(Str $s, StrLen $offset : StrLen ?$length, ?$replace) =item unpack =item vec =back =head2 Control::Basic =over =item eval multi sub Control::Basic::eval (: Str $code = $CALLER::_, Str +$lang = 'Perl6') Execute C<$code> as if it were code written in C<$lang>. C is the only required language, but supporting C is I recommended. Returns whatever C<$code> returns, or undef on error. =item evalfile multi sub Control::Basic::evalfile (Str $filename : Str +$lang = 'Perl6') Behaves like, and replaces Perl 5 C, with optional C<$lang> support. =item exit multi sub Control::Basic::exit (: Int ?$status = 0) Stops all program execution, and returns C<$status> to the calling environment. =item nothing multi sub Control::Basic::nothing () No operation. Literally does nothing. =item sleep multi sub Control::Basic::sleep (: Num ?$for = Inf ) returns Num Attempt to sleep for up to C<$for> seconds. Implementations are only obligated to support integral seconds, but higher resolutions are preferred. =item die =item fail B: Research the exception handling system. =back =head2 Conversions =over =item bless sub =item chr =item ord B: I think these should be strictly Code Point level activitities, but I'm not sure. They likely need to be renamed, as well. =item list multi sub Conversions::List:list (: *@list) returns List Forces List Context on it's arguements, and returns them. =item scalar multi sub Conversions::Scalar:scalar ($scalar) returns Scalar Forces generic Scalar context on it's arguement, and returns it. =item 0x, 0o, 0b, 0d multi sub prefix::<0x> (: Str ?$hexstr = $CALLER::_) returns Num multi sub prefix::<0o> (: Str ?$octstr = $CALLER::_) returns Num multi sub prefix::<0b> (: Str ?$binstr = $CALLER::_) returns Num multi sub prefix::<0d> (: Str ?$binstr = $CALLER::_) returns Num Interprets string as a number, with a default hexadecimal/octal/binary/decimal radix. Any radix mentioned inside the string will be override this operator. Returns C on failure. Replaces Perl 5 C and C. =back =head2 Time::Local =over =item gmtime =item localtime =item time =back =head2 I =over 4 =item study =item defined =item undef =item scalar =item want =item caller =back =head2 Obsolete =over 4 =item dbmopen, dbmclose use DB_File; =item dump With Parrot? =item each See C or C instead. =item format, formline, write See Exgesis 7. =item /[msg|sem|shm].*/ use IPC::SysV; =item ref Can be done with C<$var.meta.name>, but you're likely better off performing an C, or just C<$var ~~ TYPE>. =item reset Was there a I use for this? =item prototype &func.meta.signature; =back =head2 Pending Apocalypse The following functions are pending a future Apocalypse/Synopsis/p6l Discussion before progress can be made: =over 4 =item A/S14: Tied Variables tie tied untie =item A/S16: IPC / IO / Signals -X accept alarm bind binmode chown close closedir connect eof fcntl fileno flock getc getpeername /[get|set][host|net|proto|serv|sock].*/ glob ioctl link listen lstat mkdir open opendir pipe print printf read readdir readline readlink readpipe recv rename rewinddir rmdir seek seekdir select(both) send setsockopt shutdown slurp socket socketpair stat symlink syscall sysopen sysread sysseek syswrite tell telldir truncate umask unlink utime warn =item A/S??: OS Interaction chroot crypt exec getlogin /[get|set][pw|gr].*/ kill setpgrp setpriority system times =item A/S17: Threads and Multiprocessing fork lock wait waitpid =back =head1 Additions Is your favorite function, which you spent weeks B arguing on perl6-language to get accepted, nowhere on this document? Have no fear. Email rod@rodadams.net with a brief description and a link to the thread on L, and it'll get listed. Post errors to perl6-language.