Index | | | Related pages | | | Classes | | | Functions | | | Entities | | | Function Sets | | | Groups |
class BOM
Methods common to all Falcon items. more...
Methods | |
allTrim | Trims whitespaces from both ends of a string. |
attribs | Returns an array of attributes being given to a certain object. |
back | Returns the last element of a collection. |
backTrim | Trims trailing whitespaces in a string. |
baseClass | Returns the class item from which an object has been instantiated. |
className | Returns the name of the class an object is derived from. |
clone | Performs a deep copy of the item. |
compare | Performs a lexicographical comparison. |
derivedFrom | Checks if this item has a given parent. |
equal | Checks for item equality. |
first | Returns an iterator to the first element of a collection |
front | Returns the first element of a collection. |
frontTrim | Trims front whitespaces in a string. |
last | Returns an iterator to the last element of a collection |
len | Gets the length of a sequence. |
serialize | Serialize the item on a stream for persistent storage. |
tabField | Returns one of the items in the array, given the field name. |
tabRow | Returns the row ID of this element. |
table | Returns the table related with this array. |
toString | Coverts the object to string. |
type | Returns an integer representing the type of the item. |
Basic object model
Falcon provides a basic object model, (short BOM), which is namely a collection of predefined methods that can be applied on any Falcon item, be it an object, or any other basic type.
BOM methods may be overloaded by classes and objects; the only difference between BOM and ordinary methods is that, while every item provides them, an explicit test with provides or in operators will fail. In example, an object must explicitly provide toString() overloading for the operator provides to report success; testing “item provides toString” on an object (or any other item) will fail unless the method is explicitly defined by the tested object.
BOM is sparingly used also by the Virtual Machine. In example, key sorting in dictionaries and relational operators uses the “compare()” BOM method. A class may define a personalized ordering by redefining the compare method. Also, toString() is often used by the VM to provide consistent output.
Currently, BOM is undifferentiated. Future extension may provide type specific methods.
Trims whitespaces from both ends of a string.
BOM.allTrim( ) | |||
Returns: | The trimmed version of the string. | ||
Raises: |
|
This method removes whitespaces from the beginning and the end of a string and returns the trimmed version.
Returns an array of attributes being given to a certain object.
BOM.attribs( ) | |||
Returns: | An array of attributes or nil. | ||
Raises: |
|
This method can be used to inspect which attributes are given to a certain object. If the method is called on a non-object item, nil is returned. If the object hasn't any attribute, an empty array is returned.
Returns the last element of a collection.
BOM.back( [bRemove], [bNumOrKey] ) | |||
bRemove | If true, remove also the element. | ||
bNumOrKey | If true, returns a character value instead of a string, or a key instead of a value. | ||
Returns: | The first element. | ||
Raises: |
|
This BOM method retreives the first element of a collection. It translates into an array accessor with [0] in case of arrays. This method is particularly useful to deal with collections that cannot be directly accessed by item number, as i.e. dictionaries.
If the sequence is a string, then a second parameter may be provided; if it's true, the UNICODE value of the string character will be returned, otherwise the caller will receive a string containing the desired character.
If the sequence is a dictionary, normally, only the value will be returned. If bNumOrKey is true, then the coresponding key will be returned instead.
Also, this method is relatively efficient with respect to both direct access and iterator instantation.
Trims trailing whitespaces in a string.
BOM.backTrim( ) | |||
Returns: | The trimmed version of the string. | ||
Raises: |
|
This method removes whitespaces from the end of a string and returns the trimmed version.
Returns the class item from which an object has been instantiated.
BOM.baseClass( ) | |
Returns: | 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.
Returns the name of the class an object is derived from.
BOM.className( ) | |
Returns: | The class name of an object 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.
Performs a deep copy of the item.
BOM.clone( ) | |||
Returns: | A copy of the item. | ||
Raises: |
|
Returns an item equal to the current one, 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.
BOM.compare( item ) | |
item | The item to which this object must be compared. |
Returns: | -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.
BOM.derivedFrom( class ) | |
class | A symbolic class name or a class instance. |
Returns: | 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 items, 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)?: ", MyError.derivedFrom( "Error" ) > "Is MyError derived from 'Error' (by class)?: ", MyError.derivedFrom( Error )
Checks for item equality.
BOM.equal( item ) | |
item | The item to which this object must be compared. |
Returns: | true if the two items are considered equal, false otherwise. |
Returns true when two items are found identical. It is internally implemented using the BOM.compare method, so it is sufficient to overload the compare method so that it returns 0 when two items are found identical.
Returns an iterator to the first element of a collection
BOM.first( ) | |||
Returns: | An iterator. | ||
Raises: |
|
If the item is an array, a dictionary or a string, it returns an iterator pointing to the first element of the collection. If it's a range, it returns the begin of the range. In every other case, it raises an AccessError.
Returns the first element of a collection.
BOM.front( [bRemove], [bNumeric] ) | |||
bRemove | If true, remove also the element. | ||
bNumeric | If true, returns a character value instead of a string. | ||
Returns: | The first element. | ||
Raises: |
|
This BOM method retreives the first element of a collection. It translates into an array accessor with [0] in case of arrays. This method is particularly useful to deal with collections that cannot be directly accessed by item number, as i.e. dictionaries.
If the sequence is a string, then a second parameter may be provided; if it's true, the UNICODE value of the string character will be returned, otherwise the caller will receive a string containing the desired character.
If the sequence is a dictionary, normally, only the value will be returned. If bNumOrKey is true, then the coresponding key will be returned instead.
Also, this method is relatively efficient with respect to both direct access and iterator instantation.
Trims front whitespaces in a string.
BOM.frontTrim( ) | |||
Returns: | The trimmed version of the string. | ||
Raises: |
|
This method removes whitespaces from the beginning of a string and returns the trimmed version.
Returns an iterator to the last element of a collection
BOM.last( ) | |||
Returns: | An iterator. | ||
Raises: |
|
If the item is an array, a dictionary or a string, it returns an iterator pointing to the last element of the collection. If it's a range, it returns the end of the range, or nil if the range is open. In every other case, it raises an AccessError.
Gets the length of a sequence.
BOM.len( ) | |
Returns: | sequence lenght or 0 if the item is not a sequence. |
Equivalent to the Core len function. Applied on collections and strings, it returns the count of items in the collection, or the number of characters in the string.
Applied to other values, it returns 0.
Serialize the item on a stream for persistent storage.
BOM.serialize( stream ) | |||
stream | The stream on which to perform serialization. | ||
Raises: |
|
The item is stored on the stream so that a deserialize() call on the same position in the stream where serialization took place will create an exact copy of the serialized item.
The application must ensure that the item does not contains circular references, or the serialization will enter an endless loop.
In case the underlying stream write causes an i/o failure, an error is raised.
Returns one of the items in the array, given the field name.
BOM.tabField( field ) | |||
field | The field name or position to be retreived. | ||
Returns: | An item in the array or the default column value. | ||
Raises: |
|
If this item is an array and is part of a table, the field with the given name or ID (number) is searched in the table definition, and if found, it is returned. If the coresponding item in the array is nil, then the table column data (default data) is returned instead, unless the item is also an OOB item. In that case, nil is returned and the default column value is ignored.
Returns the row ID of this element.
BOM.tabRow( ) | |||
Returns: | A number indicating the position of this row in the table, or nil if this item is an array, but it's not stored in a table. | ||
Raises: |
|
This method returns the position of this element in a table.
This number gets valorized only after a Table.get or Table.find method call, so that it is possible to know what index had this element in the owning table. If the table is changed by inserting or removing a row, the number returned by this function becomes meaningless.
Returns the table related with this array.
BOM.table( ) | |||
Returns: | The table of which this item is a row. | ||
Raises: |
|
This BOM method retreives the table that is related with the item, provided the item is an array being part of a table.
In case the item is an array, but it doesn't belong to any table, nil is returned.
Coverts the object to string.
BOM.toString( [format] ) | |
format | Optional object-specific format string. |
Calling this BOM method is equivalent to call toString() core function passing the item as the first parameter.
Returns a string representation of the given item. If applied on strings, it returns the string as is, while it converts numbers with default internal conversion. Ranges are represented as “[N:M:S]” where N and M are respectively lower and higher limits of the range, and S is the step. Nil values are represented as “Nil”.
The format parameter is not a Falcon format specification, but a specific optional object-specific format that may be passed to objects willing to use them. In example, the TimeStamp class uses this parameter to format its string representation.
Returns an integer representing the type of the item.
BOM.type( ) | |
Returns: | The type of the item. |
Returns the typeID of this object; it is equivalent to call the core typeOf function.
Index | | | Related pages | | | Classes | | | Functions | | | Entities | | | Function Sets | | | Groups |