<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>