<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Function set "Type mangling" - Function set "Type mangling"</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./funset.html"><span>Function sets</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Function set "Type mangling"</h1>
<p class="faldoc_brief">Functions managing item conversions, type detection, item structure management and generically manipulating Falcon items. </p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#baseClass">baseClass()</a></td><td>Returns the class item from which an object has been instantiated. </td></tr>
<tr><td><a href="#chr">chr()</a></td><td>Returns a string containing a single character that corresponds to the given number. </td></tr>
<tr><td><a href="#className">className()</a></td><td>Returns the name of the class an instance is instantiated from. </td></tr>
<tr><td><a href="#clone">clone()</a></td><td>Performs a deep copy of the item. </td></tr>
<tr><td><a href="#compare">compare()</a></td><td>Performs a lexicographical comparison. </td></tr>
<tr><td><a href="#derivedFrom">derivedFrom()</a></td><td>Checks if this item has a given parent. </td></tr>
<tr><td><a href="#getProperty">getProperty()</a></td><td>Returns the value of a property in an object. </td></tr>
<tr><td><a href="#int">int()</a></td><td>Converts the given parameter to integer. </td></tr>
<tr><td><a href="#isBound">isBound()</a></td><td>Determines if an item is bound or not. </td></tr>
<tr><td><a href="#isCallable">isCallable()</a></td><td>Determines if an item is callable. </td></tr>
<tr><td><a href="#len">len()</a></td><td>Retrieves the length of a collection </td></tr>
<tr><td><a href="#metaclass">metaclass()</a></td><td>Returns the metaclass associated with the given item. </td></tr>
<tr><td><a href="#numeric">numeric()</a></td><td>Converts the given parameter to numeric. </td></tr>
<tr><td><a href="#ord">ord()</a></td><td>Returns the numeric UNICODE ID of a given character. </td></tr>
<tr><td><a href="#properties">properties()</a></td><td>Returns all the properties in the given item. </td></tr>
<tr><td><a href="#setProperty">setProperty()</a></td><td>Sets the value of a proprety in a given object </td></tr>
<tr><td><a href="#toString">toString()</a></td><td>Returns a string representation of the item. </td></tr>
<tr><td><a href="#typeOf">typeOf()</a></td><td>Returns an integer indicating the type of an item. </td></tr>
</table>
<h2 class="faldoc_title">Members</h2>
<h3 class="faldoc_funcname"><a name="baseClass">baseClass()</a></h3>
<p class="item_brief">Returns the class item from which an object has been instantiated. </p>
<p class="faldoc_funcdecl">baseClass( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc"></td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A class item or nil. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If applied on objects, returns the class item that has been used to instantiate an object. Calling the returned item is equivalent to call the class that instantiated this object. </p>
<p class="faldoc_text"> The returned item can be used to create another instance of the same class, or for comparisons on <b>select</b> branches. </p>
<p class="faldoc_text">If the item on which this method is applied is not an object, it returns nil. </p>
</p>
<h3 class="faldoc_funcname"><a name="chr">chr()</a></h3>
<p class="item_brief">Returns a string containing a single character that corresponds to the given number. </p>
<p class="faldoc_funcdecl">chr( number )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">number</td><td class="faldoc_paramdesc">Numeric code of the desired character </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">a single-char string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns a single character string whose only character is the UNICODE equivalent for the given number. The number must be a valid UNICODE character, so it must be in range 0-0xFFFFFFFF. </p>
</p>
<h3 class="faldoc_funcname"><a name="className">className()</a></h3>
<p class="item_brief">Returns the name of the class an instance is instantiated from. </p>
<p class="faldoc_funcdecl">className( The )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">The</td><td class="faldoc_paramdesc">item to be checked. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The class name of an object (a string) or nil. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If applied to objects, returns the name of the class of which the object is an instance. When applied to classes, it return the class symbolic name. In all other cases, return nil. </p>
</p>
<h3 class="faldoc_funcname"><a name="clone">clone()</a></h3>
<p class="item_brief">Performs a deep copy of the item. </p>
<p class="faldoc_funcdecl">clone( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be copied. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A copy of the item. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_CloneError.html">CloneError</a></td><td class="faldoc_raisedesc">if the item is not cloneable. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Returns an item equal to the <b>item</b>, but phisically separated. If the item is a sequence, only the first level of the item gets actually cloned: vectors and dictionaries gets cloned, but the items they store are just copied. This means that the new copy of the collection itself may change, and the older version will stay untouched, but if a deep item in the collection (as an object) is changed, its change will be reflected also in the original collection. </p>
<p class="faldoc_text">Cloning objects causes each of their properties to be cloned. If they store an internal user data which is provided by extension modules or embedding applications, that data is cloned too. Behavior of user data is beyond the control of the script, and the data may actually be just referenced or it may also refuse to be cloned. In that case, this method will raise a CloneError, which indicates that a deep user data provided by an external module or application doesn't provide a cloning feature. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> Cloning objects that stores other objects referencing themselves in their properties may cause an endless loop in this version. To provide a safe duplicate of objects that may be organized in circular hierarcies, overload the clone method so that it creates a new instance of the item and just performs a flat copy of the properties. </p>
</p>
<h3 class="faldoc_funcname"><a name="compare">compare()</a></h3>
<p class="item_brief">Performs a lexicographical comparison. </p>
<p class="faldoc_funcdecl">compare( operand1, operand2 )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">operand1</td><td class="faldoc_paramdesc">The item to which this object must be compared. </td></tr><tr><td class="faldoc_param">operand2</td><td class="faldoc_paramdesc">The item to which this object must be compared. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">-1, 0 or 1 depending on the comparation result. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Performs a lexicographical comparison between the self item and the item passed as a parameter. If the item is found smaller than the parameter, it returns -1; if the item is greater than the parameter, it returns 1. If the two items are equal, it returns 0. </p>
<p class="faldoc_text">The compare method, if overloaded, is used by the Virtual Machine to perform tests on unknown types (i.e. objects), and to sort dictionary keys. </p>
<p class="faldoc_text"> Item different by type are ordered by their type ID, as indicated in the documentation of the <a href="./functions.html#typeOf">typeOf</a> core function. </p>
<p class="faldoc_text">By default, string comparison is performed in UNICODE character order, and objects, classes, vectors, and dictionaries are ordered by their internal pointer address. </p>
</p>
<h3 class="faldoc_funcname"><a name="derivedFrom">derivedFrom()</a></h3>
<p class="item_brief">Checks if this item has a given parent. </p>
<p class="faldoc_funcdecl">derivedFrom( item, cls )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be checked. </td></tr><tr><td class="faldoc_param">cls</td><td class="faldoc_paramdesc">A symbolic class name or a class instance. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if the given class is one of the ancestors of this item. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If applied on objects, returns true if the given parameter is the name of the one of the classes that compose the class hierarchy of the object. </p>
<p class="faldoc_text">If applied on class instances, it returns true if the parameter is its name or the name of one of its ancestors. </p>
<p class="faldoc_text">In all the other cases, it return false. </p>
<p class="faldoc_text">It is also possible to use directly the class instance as a parameter, instead of a class name. In example: </p>
<pre class="faldoc_code">
object MyError from Error
//...
end
> "Is MyError derived from 'Error' (by name)?: ", \
derivedFrom( MyError, "Error" )
> "Is MyError derived from 'Error' (by class)?: ", \
derivedFrom( MyError, Error )
</pre>
</p>
<h3 class="faldoc_funcname"><a name="getProperty">getProperty()</a></h3>
<p class="item_brief">Returns the value of a property in an object. </p>
<p class="faldoc_funcdecl">getProperty( obj, propName )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">obj</td><td class="faldoc_paramdesc">the source object, array or (blessed) dictionary. </td></tr><tr><td class="faldoc_param">propName</td><td class="faldoc_paramdesc">A string representing the name of a property or a method inside the object. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">the property </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">if the property can't be found. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">An item representing the property is returned. The returned value is actually a copy of the property; assigning a new value to it won't have any effect on the original object. </p>
<p class="faldoc_text">If the property is a method, a callable method item is returned. If the property is not found, an error of class RangeError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="int">int()</a></h3>
<p class="item_brief">Converts the given parameter to integer. </p>
<p class="faldoc_funcdecl">int( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be converted </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An integer value. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_ParseError.html">ParseError</a></td><td class="faldoc_raisedesc">in case the given string cannot be converted to an integer. </td></tr><tr><td class="faldoc_raiseitem"><a href="./class_MathError.html">MathError</a></td><td class="faldoc_raisedesc">if a given floating point value is too large to be converted to an integer. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Integer values are just copied. Floating point values are converted to long integer; in case they are too big to be represented a RangeError is raised. Strings are converted from base 10. If the string cannot be converted, or if the value is anything else, a MathError instance is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="isBound">isBound()</a></h3>
<p class="item_brief">Determines if an item is bound or not. </p>
<p class="faldoc_funcdecl">isBound( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc"></td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the item is bound. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="isCallable">isCallable()</a></h3>
<p class="item_brief">Determines if an item is callable. </p>
<p class="faldoc_funcdecl">isCallable( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be converted </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">true if the item is callable, false otheriwse. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the function returns true, then the call operator can be applied. If it returns false, the item is not a callable one, and trying to call it would cause an error. </p>
</p>
<h3 class="faldoc_funcname"><a name="len">len()</a></h3>
<p class="item_brief">Retrieves the length of a collection </p>
<p class="faldoc_funcdecl">len( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">an item of any kind </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">the count of items in the sequence, or 0. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned value represent the "size" of the item passed as a parameter. The number is consistent with the object type: in case of a string, it represents the count of characters, in case of arrays or dictionaries it represents the number of elements, in all the other cases the returned value is 0. </p>
</p>
<h3 class="faldoc_funcname"><a name="metaclass">metaclass()</a></h3>
<p class="item_brief">Returns the metaclass associated with the given item. </p>
<p class="faldoc_funcdecl">metaclass( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item of which the metaclass must be found. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The metaclass of this item. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="numeric">numeric()</a></h3>
<p class="item_brief">Converts the given parameter to numeric. </p>
<p class="faldoc_funcdecl">numeric( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be converted </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A numeric value. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_ParseError.html">ParseError</a></td><td class="faldoc_raisedesc">in case the given string cannot be converted to an integer. </td></tr><tr><td class="faldoc_raiseitem"><a href="./class_MathError.html">MathError</a></td><td class="faldoc_raisedesc">if a given floating point value is too large to be converted to an integer. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Floating point values are just copied. Integer values are converted to floating point; in case of very large integers, precision may be lost. Strings are converted from base 10. If the string cannot be converted, or if the value is anything else, a MathError instance is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="ord">ord()</a></h3>
<p class="item_brief">Returns the numeric UNICODE ID of a given character. </p>
<p class="faldoc_funcdecl">ord( string )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">string</td><td class="faldoc_paramdesc">The character for which the ID is requested. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">the UNICODE value of the first element in the string. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The first character in string is taken, and it's numeric ID is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="properties">properties()</a></h3>
<p class="item_brief">Returns all the properties in the given item. </p>
<p class="faldoc_funcdecl">properties( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">An item that can be accessed via dot accessor. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array of strings representing property names. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns the properties offered by an item as a list of strings in an array. FBOM methods (item metaclass methods) are not returned; only explicitly declared properties are taken into account. </p>
<p class="faldoc_text">The item susceptible of returning an array of properties are: </p>
<ul>
<li> Objects (see <a href="./class_Object.html#properties">Object.properties</a>) </li><li> Dictionaries (if blessed, see <a href="./class_Dictionary.html#properties">Dictionary.properties</a>) </li><li> Arrays (see <a href="./class_Array.html#properties">Array.properties</a>) </li><li> Classes (see <a href="./class_Class.html#properties">Class.properties</a>) </li>
</ul>
<p class="faldoc_text"> This function, applied to any other item type, returns <b>nil</b>. </p>
</p>
<h3 class="faldoc_funcname"><a name="setProperty">setProperty()</a></h3>
<p class="item_brief">Sets the value of a proprety in a given object </p>
<p class="faldoc_funcdecl">setProperty( obj, propName, value )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">obj</td><td class="faldoc_paramdesc">The source object. </td></tr><tr><td class="faldoc_param">propName</td><td class="faldoc_paramdesc">A string representing the name of a property or a method inside the object. </td></tr><tr><td class="faldoc_param">value</td><td class="faldoc_paramdesc">The property new value. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">If the property can't be found. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Alters the value of the property in the given object. If the required property is not present, an AccessError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="toString">toString()</a></h3>
<p class="item_brief">Returns a string representation of the item. </p>
<p class="faldoc_funcdecl">toString( item, [format] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">The item to be converted to string. </td></tr>
<tr><td class="faldoc_optparam">format</td><td class="faldoc_optparamdesc">Specific object format. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">the string representation of the item. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function is useful to convert an unknown value in a string. The item may be any kind of Falcon item; the following rules apply: </p>
<ul>
<li>Nil items are represented as "<NIL>" </li><li>Integers are converted in base 10. </li><li>Floating point values are converted in base 10 with a default precision of 6; numprec may be specified to change the default precision. </li><li>Array and dictionaries are represented as "Array of 'n' elements" or "Dictionary of 'n' elements". </li><li>Strings are copied. </li><li>Objects are represented as "Object 'name of class'", but if a toString() method is provided by the object, that one is called instead. </li><li>Classes and other kind of opaque items are rendered with their names. </li>
</ul>
<p class="faldoc_text">This function is not meant to provide complex applications with pretty-print facilities, but just to provide simple scripts with a simple and consistent output facility. </p>
<p class="faldoc_text"> If a <b>format</b> parameter is given, the format will be passed unparsed to toString() methods of underlying items. </p>
</p>
<h3 class="faldoc_funcname"><a name="typeOf">typeOf()</a></h3>
<p class="item_brief">Returns an integer indicating the type of an item. </p>
<p class="faldoc_funcdecl">typeOf( item )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">item</td><td class="faldoc_paramdesc">An item of any kind. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A constant indicating the type of the item. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The typeId returned is an integer; the Falcon compiler is fed with a set of compile time constants that can be used to determine the type of an item. Those constants are always available at Falcon sources. </p>
<p class="faldoc_text">The value returned may be one of the following: </p>
<ul>
<li><b>NilType</b>- the item is NIL </li><li><b>BooleanType</b>- the item is true or false </li><li><b>NumericType</b>- the item is a number </li><li><b>RangeType</b>- the item is a range (a pair of two integers) </li><li><b>FunctionType</b>- the item is a function </li><li><b>StringType</b>- the item is a string </li><li><b>LBindType</b>- the item is a late binding symbol </li><li><b>MemBufType</b>- the item is a Memory Buffer Table </li><li><b>ArrayType</b>- the item is an array </li><li><b>DictionaryType</b>- the item is a dictionary </li><li><b>ObjectType</b>- the item is an object </li><li><b>ClassType</b>- the item is a class </li><li><b>MethodType</b>- the item is a method </li><li><b>ClassMethodType</b>- the item is a method inside a class </li>
</ul>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./funset.html">Function sets</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./globals.html">Globals</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
