Functions managing item conversions, type detection, item structure management and generically manipulating Falcon items.
Returns the class item from which an object has been instantiated.
baseClass( item )
| item | |
| Return | A class item or nil. |
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.
The returned item can be used to create another instance of the same class, or for comparisons on select branches.
If the item on which this method is applied is not an object, it returns nil.
See also: BOM.
Returns a string containing a single character that corresponds to the given number.
chr( number )
| number | Numeric code of the desired character |
| Return | a single-char string. |
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.
Returns the name of the class an instance is instantiated from.
className( The )
| The | item to be checked. |
| Return | The class name of an object (a string) or nil. |
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.
See also: BOM.
Performs a deep copy of the item.
clone( item )
| item | The item to be copied. | ||
| Return | A copy of the item. | ||
| Raise |
|
Returns an item equal to the item, 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.
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.
Note: 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.
Performs a lexicographical comparison.
compare( operand1, operand2 )
| operand1 | The item to which this object must be compared. |
| operand2 | The item to which this object must be compared. |
| Return | -1, 0 or 1 depending on the comparation result. |
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.
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.
Item different by type are ordered by their type ID, as indicated in the documentation of the typeOf core function.
By default, string comparison is performed in UNICODE character order, and objects, classes, vectors, and dictionaries are ordered by their internal pointer address.
Checks if this item has a given parent.
derivedFrom( item, cls )
| item | The item to be checked. |
| cls | A symbolic class name or a class instance. |
| Return | true if the given class is one of the ancestors of this item. |
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.
If applied on class instances, it returns true if the parameter is its name or the name of one of its ancestors.
In all the other cases, it return false.
It is also possible to use directly the class instance as a parameter, instead of a class name. In example:
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 )
See also: BOM.
Returns the value of a property in an object.
getProperty( obj, propName )
| obj | the source object, array or (blessed) dictionary. | ||
| propName | A string representing the name of a property or a method inside the object. | ||
| Return | the property | ||
| Raise |
|
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.
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.
Converts the given parameter to integer.
int( item )
| item | The item to be converted | ||||
| Return | An integer value. | ||||
| Raise |
|
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.
Determines if an item is bound or not.
isBound( item )
| item | |
| Return | True if the item is bound. |
See also: BOM.
Determines if an item is callable.
isCallable( item )
| item | The item to be converted |
| Return | true if the item is callable, false otheriwse. |
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.
Retrieves the length of a collection
len( item )
| item | an item of any kind |
| Return | the count of items in the sequence, or 0. |
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.
Returns the metaclass associated with the given item.
metaclass( item )
| item | The item of which the metaclass must be found. |
| Return | The metaclass of this item. |
Converts the given parameter to numeric.
numeric( item )
| item | The item to be converted | ||||
| Return | A numeric value. | ||||
| Raise |
|
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.
Returns the numeric UNICODE ID of a given character.
ord( string )
| string | The character for which the ID is requested. |
| Return | the UNICODE value of the first element in the string. |
The first character in string is taken, and it's numeric ID is returned.
See also: chr.
Returns all the properties in the given item.
properties( item )
| item | An item that can be accessed via dot accessor. |
| Return | An array of strings representing property names. |
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.
The item susceptible of returning an array of properties are:
This function, applied to any other item type, returns nil.
Sets the value of a proprety in a given object
setProperty( obj, propName, value )
| obj | The source object. | ||
| propName | A string representing the name of a property or a method inside the object. | ||
| value | The property new value. | ||
| Raise |
|
Alters the value of the property in the given object. If the required property is not present, an AccessError is raised.
Returns a string representation of the item.
toString( item, [format] )
| item | The item to be converted to string. |
| format | Specific object format. |
| Return | the string representation of the item. |
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:
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.
If a format parameter is given, the format will be passed unparsed to toString() methods of underlying items.
See also: Format.
Returns an integer indicating the type of an item.
typeOf( item )
| item | An item of any kind. |
| Return | A constant indicating the type of the item. |
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.
The value returned may be one of the following: