# $EPIC: 6_Functions,v 1.7 2001/11/28 09:13:09 anders Exp $
Section 6: Built-In Functions                                               

This section is one of the most important sections because it discusses the
built in functions which are the staple of any EPIC script.  Every built in
function is supposed to be described here, and each help file shows exactly
how each function works.

Inline expandos (ie, $A, $B, $C, et al) are not explained here.  Please see
Special_Vars(7)

The format of each function help file:

	Synopsis:
	   $name(<argument1> [<argument2>])

The name of the function is underlined.  Each argument is enclosed in
angle brackets, <like> <this>.  Optional arguments are further enclosed in
square brackets, [<like> <this>].  Each square bracket set is independently
optional.  $name([<arg1>] [<arg2> <arg3>]) means that you can provide
<arg1> if you like, and <arg2> <arg3> if you like, but if you provide either
<arg2> or <arg3> you must provide them both.

	Technical:
	   This function returns its arguments.  One argument is required.

The technical section precisely specifies the behavior of the function in
as technical of terms as is necessary to be exact.  This section is for
advanced users who want to know exactly what "surprises" to expect.

	Practical:
	  This function is used to make a copy of its arguments.

Some functions may have immediate practical use and if so, it will be
described here.  Not every function has an immediately obvious practical
use and this section may be omitted in such cases.

	Returns:
	  This function returns its arguments.

This section describes in non-technical terms what the function is expected
to return.  You will need to refer to the technical section if you want to 
get a precise, exact explanation.

	History:
	   This function first appeared in ircII.

This section tells you the first version that this function appeared in.
Functions that are available in historical ircII versions look like this.

	Cost:
	   This function has a relative cost of 1 delta

Each function require a certain amount of time to do its work.  Many times
the quantity of work is obscured because of the simplicity of the function.
This section gives you a relative cost of the function so that you may compare
the relative efficiency of several different solutions.  When calculating 
strings of function calls, remember that every function call has an overhead
of three deltas (strictly for overhead) above and beyond what is included here.

This is a non-exhaustive list of things that cost one "delta"
	Separating one argument from the argument list
	Returning a string or integer value from a function
	Five or more division or floating point operations.
	Looking up a /set value
	One or two system time retrievals
	Anything that requires a malloc() to be done.
	Five or more size-controlled string copies
	One any-character-in-string lookup (forward or backward)
	One nickname/userhost lookup from the userhost cache.

This is a non-exhaustive list of things that cost more than one "delta"
	One time-to-string conversion (two deltas)
	One strftime conversion (one delta, plus...)
		1 delta for each conversion in the format string
	One printf operation (one delta, plus...)
		1 delta for each floating point conversion
		1 delta for each two integer conversions
		1 delta for each four string conversions
		1 delta for each padding operation
	One pattern match (one delta, plus...)
		1 delta for every wildcard in the pattern
	Establishing a network connection (five deltas plus any overhead)
	A "relative character search" (two deltas)
	A "word extraction" (two or three deltas)



	Examples:
	   $name(booya)				returns "booya"

If examples help demonstrate the use of the function, actual examples of
the use will be given and their return value shown.

	See Also:
	   mid(6)

Some functions may work in tandem with other functions, and the See Also
section will show which other functions you should look at for further
information.