<doc>
	<legacy_id>1364</legacy_id>
	<name>function</name>
	<type>control structure</type>

	<syntax>
		<example>function <i>functionName </i>[<i>parametersList</i>] <i>statementList</i> end <i>functionName</i></example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Defines a custom function <glossary tag="handler">handler</glossary>.</summary>

	<examples>
<example><p>function myFunctioneturn "test"</p><p>end myFunction</p></example>
	</examples>

	<history>
		<introduced version="1.0">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		
		<experimental version=""></experimental>
		<nonexperimental version=""></nonexperimental>
	</history>

	<objects>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
		<ios/>
		<android/>
	</platforms>

	<classes>
		<desktop/>
		<server/>
		<web/>
		<mobile/>
	</classes>

	<security>
	</security>


	<classification>
		<category>Writing LiveCode</category>
	</classification>

	<references>
		<function tag="param">param Function</function>
		<function tag="paramCount">paramCount Function</function>
		<function tag="functionNames">functionNames Function</function>
		<keyword tag="private">private Keyword</keyword>
		<keyword tag="$">$ Keyword</keyword>
		<keyword tag="end">end Keyword</keyword>
		<control_st tag="exit">exit Control Structure</control_st>
	</references>

	<description>Use the <b>function</b> <glossary tag="control structure">control structure</glossary> to implement a custom function.<p></p><p><b>Form:</b></p><p>The first line of a <b>function</b> <glossary tag="handler">handler</glossary> consists of the word "function" followed by the function's name. If the function has any <glossary tag="parameter">parameters</glossary>, their names come after the function name, separated by commas.</p><p></p><p>The last line of a <b>function</b> <glossary tag="handler">handler</glossary> consists of the word "end" followed by the function's name.</p><p></p><p><b>Parameters:</b></p><p>The <i>functionName</i> is a <keyword tag="string">string</keyword> up to 65,535 <keyword tag="characters">characters</keyword> in length.</p><p></p><p>The <i>parametersList</i> consists of one or more <glossary tag="parameter">parameter</glossary> names, separated by commas.</p><p></p><p>The <i>statementList</i> consists of one or more <glossary tag="LiveCode">LiveCode</glossary> <glossary tag="statement">statements</glossary>.</p><p></p><p><b>Comments:</b></p><p>The purpose of a function is to compute a value and return it to the handler that called the function. The function's value is returned by a <b>return</b> <glossary tag="control structure">control structure</glossary> within the <b>function</b> <glossary tag="handler">handler</glossary>.</p><p></p><p>A function handler can contain any set of LiveCode statements. Most functions contain a <b>return</b> <glossary tag="statement">statement</glossary>, which <glossary tag="return">returns</glossary> the value to the <glossary tag="caller">calling handler</glossary>. This example of a custom function uses two <glossary tag="parameter">parameters</glossary> and <glossary tag="return">returns</glossary> a <keyword tag="string">string</keyword>:</p><p></p><p>function reversedName firstName,lastName</p><p><i>-- firstName and lastName are parameters</i></p><p>put lastName,firstName into constructedName</p><p>return constructedName</p><p>end reversedName</p><p></p><p>You create a custom function by writing a function handler for it. When you use the function in a script,  the function call is passed through the message path. When it reaches the object whose script contains the <b>function</b> <glossary tag="handler">handler</glossary>, the <glossary tag="statement">statements</glossary> in the <glossary tag="handler">handler</glossary> are <glossary tag="execute">executed</glossary>.</p><p></p><p>A custom function is called by name, just like a built-in function, as part of an expression. For example, this handler calls the custom function above:</p><p></p><p>on mouseUp</p><p>ask "What is your first name?"</p><p>put it into firstParam</p><p>ask "What is your last name?"</p><p>put it into secondParam</p><p>put reversedName(firstParam,secondParam) into field "Name"</p><p>end mouseUp</p><p></p><p>A function can call itself. The following example calls itself to compute the factorial of an integer:</p><p></p><p>function factorial theNumber</p><p>if theNumber = 1 then return 1</p><p>else return theNumber * factorial(theNumber -1)</p><p>end factorial</p><p></p><p></p><p></p><p></p><note>To declare a function that is local to the script it is contained in, prefix the declaration with <keyword tag="private">private</keyword>. For more information about this see the dictionary entry for the <keyword tag="private">private keyword</keyword>.</note><p></p><p></p><p></p><p></p><note>As the <function tag="result">result</function> is a global property, if you do not explicitly <control_st tag="return">return</control_st> a value, then <function tag="result">the result</function> will no change, but reflect the last engine command, engine function or command or function handler that did return a value.</note><p></p><p></p><p></p><p></p><change></change>The ability to declare private functions using the private keyword was added in LiveCode 2.8.1</description>
</doc>