Internal use.
| Class Methods |
|---|
|
create_duplicate( Object existing ).Object
This factory method initiates object duplication. The
compiler transforms the duplicate(obj) command into
Object.create_duplicate(obj).
Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise |
| Object Variables |
|---|
|
next : PatternMatcher terms : PatternMatcher[] |
| Object Methods |
|---|
|
chain_next( PatternMatcher _next ) compare_to( Object other ).Ternary
This method is used for ordering (quantitative) comparisons
between this object and another.
create_duplicate().ObjectReturns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt'Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract:
if (obj1.compare_to(obj2) == eq)
obj1.equals(obj2) == true
obj1.hash_code == obj2.hash_code
else
obj1.equals(obj2) == false
endIf
Note that two "equal" objects *must* have the same hash code,
but "unequal" objects may or may not have the same hash code.
This default implementation throws an UnsupportedMethodError.
Should create a duplicate of this object such that
obj1.equals(obj1.create_duplicate) return true.
equals( Object other ).BooleanThe command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError.
Returns true if this object is equivalant to another.
hash_code().Int32The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIfNote that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other').
Returns the hash code of this object, which some classes
(like HashTable) rely on. This default implementation
throws an UnsupportedMethodError.
init()Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant:
if (obj1.hash_code != obj2.hash_code)
obj1.equals(obj2) == false
obj1.compare_to(obj2) != eq
endIf
init( PatternMatcher p1, PatternMatcher p2 ) init( PatternMatcher p1, PatternMatcher p2, PatternMatcher p3 ) match( PatternMatchInfo state ).Boolean match_next( PatternMatchInfo state ).Boolean matches_any().Boolean
Overridden in CharRangePatternMatcher
to_String().Stringtype_name().String
Returns the true class name of this object. Implemented by
the runtime; you should not override this method.
Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String |
Internal use.
| Class Methods |
|---|
|
create_duplicate( Object existing ).Object
This factory method initiates object duplication. The
compiler transforms the duplicate(obj) command into
Object.create_duplicate(obj).
Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise |
| Object Variables |
|---|
|
max_count : Int32 min_count : Int32 next : PatternMatcher |
| Object Methods |
|---|
|
chain_next( PatternMatcher _next ) compare_to( Object other ).Ternary
This method is used for ordering (quantitative) comparisons
between this object and another.
create_duplicate().ObjectReturns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt'Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract:
if (obj1.compare_to(obj2) == eq)
obj1.equals(obj2) == true
obj1.hash_code == obj2.hash_code
else
obj1.equals(obj2) == false
endIf
Note that two "equal" objects *must* have the same hash code,
but "unequal" objects may or may not have the same hash code.
This default implementation throws an UnsupportedMethodError.
Should create a duplicate of this object such that
obj1.equals(obj1.create_duplicate) return true.
equals( Object other ).BooleanThe command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError.
Returns true if this object is equivalant to another.
hash_code().Int32The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIfNote that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other').
Returns the hash code of this object, which some classes
(like HashTable) rely on. This default implementation
throws an UnsupportedMethodError.
init( [Int32 min_count], [Int32 max_count] )Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant:
if (obj1.hash_code != obj2.hash_code)
obj1.equals(obj2) == false
obj1.compare_to(obj2) != eq
endIf
match( PatternMatchInfo state ).Boolean match_next( PatternMatchInfo state ).Boolean matches_any().Boolean
Overridden in CharRangePatternMatcher
to_String().Stringtype_name().String
Returns the true class name of this object. Implemented by
the runtime; you should not override this method.
Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String |
The base class for every Plasmacore game or application. Extend your game class from this class and override methods as warranted. Start with init(), update(), and draw().
| Class Methods |
|---|
|
close_all_archives()
Closes all archives cached by open_archive() and frees the memory
used by them.
create_duplicate( Object existing ).Object
This factory method initiates object duplication. The
compiler transforms the duplicate(obj) command into
Object.create_duplicate(obj).
exit_program()Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise
Causes the native framework to immediately exit the
application. Typically called from on_exit_request(), but
may be called independently.
mouse_capture( Boolean setting )Example: Application.exit_program
Property-set that specifies whether the mouse is captured by
(and restricted to) this application in windowed mode. This
is "false" by default.
mouse_visible( Boolean setting )Example: Application.mouse_capture = true
Property-set that specifies the visibility of the system
mouse. This is "true" by default.
open_archive( String filename )Example: Application.mouse_visible = false
Attempts to locate and load the named ZIP file
into memory. The archive is not uncompressed when loaded.
Subsequent attempts to open any file for reading (including
loading images and sounds) will first check and see if the file
is in any of the archives that have been opened with
open_archive(). If found, the file is uncompressed and read
from the archive. If not found, Plasmacore searches for the file
in the regular filesystem.
window_title( String title )If 'filename' is, for example, "images", Plasmacore will attempt to open the archive using the following paths: images images.zip data/images data/images.zipAny number of archives may be opened concurrently - all of them are searched when a file is requested. Call close_all_archives() to close the archives and free up the memory used by them. Using archives in this fashion allows for a clean and compact distribution with no significant difference in loading speed on the Windows Plasmacore platform. However, writing games to utilize the archive system should yield speed benefits on platforms (e.g. Wii) where I/O seek time and data transfer rates are an issue (such as reading data off optical drive or over the network). Note when opening input files (including loading images and sounds), the following variations of the filename are automatically checked: filename filename.ext (ext = png, jpg, etc. as appropriate) data/filename data/filename.extThis means that when creating this new image object: Image("images/sprites"), the file "sprites.png" could either be located under "data/images/sprites.png" or under "images/sprites.png" in the archive "data/images.zip". WARNING: once again, open_archive does not simply add a search path to the zip file on disc - it actually loads the entire file into memory!
Window title property-set for this application.
Example: Application.window_title = "MadStone" |
| Object Methods |
|---|
|
call_draw( Int32 window_width, Int32 window_height )
Internal use. Wraps a call to draw() in a try/catch block.
call_init( Int32 display_width, Int32 display_height )
Internal use. Wraps a call to init() in a try/catch block.
call_update()
Internal use. Wraps a call to update() in a try/catch block.
compare_to( Object other ).Ternary
This method is used for ordering (quantitative) comparisons
between this object and another.
create_duplicate().ObjectReturns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt'Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract:
if (obj1.compare_to(obj2) == eq)
obj1.equals(obj2) == true
obj1.hash_code == obj2.hash_code
else
obj1.equals(obj2) == false
endIf
Note that two "equal" objects *must* have the same hash code,
but "unequal" objects may or may not have the same hash code.
This default implementation throws an UnsupportedMethodError.
Should create a duplicate of this object such that
obj1.equals(obj1.create_duplicate) return true.
draw()The command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError.
Redraws the game. Called up to 60 times per second. You
should not change the game's data model at this point.
equals( Object other ).Boolean
Returns true if this object is equivalant to another.
hash_code().Int32The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIfNote that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other').
Returns the hash code of this object, which some classes
(like HashTable) rely on. This default implementation
throws an UnsupportedMethodError.
init()Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant:
if (obj1.hash_code != obj2.hash_code)
obj1.equals(obj2) == false
obj1.compare_to(obj2) != eq
endIf
Called to set up the game. Do not call any drawing operations
at this point.
listen_to( DispatcherType dispatcher )
Instructs this JoystickListener to listen to the given
dispatcher.
on_exit_request()
Called when the user presses the close window button. Calls
exit_program() by default. You can override this method to
perform cleanup and/or postpone the call to exit_program at
some later point.
on_joystick_button_press( JoystickEvent event )
See JoystickEvent for more information.
on_joystick_button_release( JoystickEvent event )
See JoystickEvent for more information.
on_joystick_hat_movement( JoystickEvent event )
See JoystickEvent for more information.
on_joystick_movement( JoystickEvent event )
See JoystickEvent for more information.
on_key_press( KeyEvent event )
Called when a key is pressed. An on_keystroke() event is
generated at the same time. If the key is held down for
a while, key repeat events are sent as additional
on_keystroke() events. 'event' contains information about
the key.
on_key_release( KeyEvent event )
Called when a key is released. 'event' contains information
about the key.
on_keystroke( KeyEvent event )
Called when a key has either been pressed and released or is
pressed and is repeating. 'event' contains information about
the key.
on_mouse_absent()
Called when the the game window loses mouse focus.
on_mouse_button_press( MouseEvent event )
Called when a mouse button has been pressed.
on_mouse_button_release( MouseEvent event )'event.button' contains the index of the mouse button being pressed (1=left, 2=right). 'event.position' contains the absolute mouse position at the time of the press.
Called when a mouse button has been pressed.
on_mouse_movement( MouseEvent event )'event.button' contains the index of the mouse button being pressed (1=left, 2=right). 'event.position' contains the absolute mouse position at the time of the press.
Called when the mouse position changes. 'event' contains the
new mouse position in relative (delta) coordinates.
on_mouse_position( MouseEvent event )on_mouse_position() is also called with the new absolute position.
Called when the mouse position changes. 'event' contains the
new mouse position in absolute coordinates.
on_mouse_present()on_mouse_movement() is also called with the relative position change.
Called when the mouse focus returns to the game window after
being elsewhere.
on_mouse_wheel_down( MouseEvent event )
Called when the mouse wheel has been rotated one click down.
on_mouse_wheel_up( MouseEvent event )'event.position' contains the absolute mouse position at the time of the wheel movement.
Called when the mouse wheel has been rotated one click up.
on_toggle_fullscreen()'event.position' contains the absolute mouse position at the time of the wheel movement.
Called by the input object when an ALT+ENTER key combination
is detected. The default behavior is to toggle the fullscreen
property setting.
on_trackball_movement( JoystickEvent event )
See JoystickEvent for more information.
stop_listening_to( DispatcherType dispatcher )
Stops this JoystickListener from listening to the given
dispatcher.
to_String().String
Returns:
type_name().StringA String representation of this object. Most classes should override this method to summarize an object's state for convenience in testing and debugging.
Returns the true class name of this object. Implemented by
the runtime; you should not override this method.
update()Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String
Called 60 times per second guaranteed. Do not perform any
drawing actions; just update the world's data model.
|
Internal use.
| Class Methods |
|---|
|
create_duplicate( Object existing ).Object
This factory method initiates object duplication. The
compiler transforms the duplicate(obj) command into
Object.create_duplicate(obj).
Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise |
| Object Variables |
|---|
|
max_count : Int32 min_count : Int32 next : PatternMatcher term : PatternMatcher |
| Object Methods |
|---|
|
chain_next( PatternMatcher _next ) compare_to( Object other ).Ternary
This method is used for ordering (quantitative) comparisons
between this object and another.
create_duplicate().ObjectReturns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt'Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract:
if (obj1.compare_to(obj2) == eq)
obj1.equals(obj2) == true
obj1.hash_code == obj2.hash_code
else
obj1.equals(obj2) == false
endIf
Note that two "equal" objects *must* have the same hash code,
but "unequal" objects may or may not have the same hash code.
This default implementation throws an UnsupportedMethodError.
Should create a duplicate of this object such that
obj1.equals(obj1.create_duplicate) return true.
equals( Object other ).BooleanThe command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError.
Returns true if this object is equivalant to another.
find_matches( PatternMatchInfo state ).BooleanThe compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIfNote that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other'). hash_code().Int32
Returns the hash code of this object, which some classes
(like HashTable) rely on. This default implementation
throws an UnsupportedMethodError.
init( PatternMatcher term, [Int32 min_count], [Int32 max_count] )Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant:
if (obj1.hash_code != obj2.hash_code)
obj1.equals(obj2) == false
obj1.compare_to(obj2) != eq
endIf
match( PatternMatchInfo state ).Boolean match_next( PatternMatchInfo state ).Boolean matches_any().Boolean
Overridden in CharRangePatternMatcher
to_String().Stringtype_name().String
Returns the true class name of this object. Implemented by
the runtime; you should not override this method.
Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String |
Primarily for internal use - in most cases use ArrayList instead.
Array is a placeholder type. Arrays are actually implemented in the runtime implementation; calls to array methods are intercepted by the program loader and translated into array-related opcodes.
The exception to this is when a call is made to an array using a reference of aspect types Readable or IndexedData - the loader is unable to intercept. However, the Slag-side implementation of each array simply calls itself, and *that* call *is* intercepted by the compiler.
To get an array in Slag you must be explicit, e.g. "Array<<Int32>>(20)". Convenience notation (such as Array[20]) generates ArrayLists instead.
Arrays are not covariant as they are in Java. An Array<<String>> counts as an Object but not as an Array<<Object>>.
Arrays may be extended or augmented but no new object variables may be added.
| Class Methods |
|---|
|
create_duplicate( Object existing ).Object
This factory method initiates object duplication. The
compiler transforms the duplicate(obj) command into
Object.create_duplicate(obj).
Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise |
| Object Methods |
|---|
|
clear( Int32 first_index, Int32 last_index )
Clears all the elements in this array between the two indices.
compare_to( Object other ).TernaryUsing this method to clear elements at the end of an arraylist allows the runtime to limit the number of reference array elements it searches through during a data collection. Technical note: the runtime tracks the furthest position that a non-null reference array element could possibly be at after various calls to clear() and set().
This method is used for ordering (quantitative) comparisons
between this object and another.
contains( DataType value ).BooleanReturns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt'Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract:
if (obj1.compare_to(obj2) == eq)
obj1.equals(obj2) == true
obj1.hash_code == obj2.hash_code
else
obj1.equals(obj2) == false
endIf
Note that two "equal" objects *must* have the same hash code,
but "unequal" objects may or may not have the same hash code.
This default implementation throws an UnsupportedMethodError.
Returns "true" if this data contains the given value.
copy_elements( ArrayType src_array, Int32 src_index, Int32 dest_index, Int32 number )
Copies 'number' elements from another array (starting at
element 'src_index') into this one (starting at element
'dest_index').
count().Int32
Returns the count of how many elements are in this array.
create_duplicate().Array<<DataType>>
Creates a duplicate of this array when the "duplicate(array)"
command is given. If the array element type is a reference
type, the new array contains a copy of the same references
to the same objects - the objects themeselves are not
duplicated.
create_reader().Reader<<DataType>>
Returns a reader that can be used to read() this data one
element at a time.
end( Int32 from_end ).DataType
Equivalent to get( (count-1) + from_end ).
equals( Readable<<DataType>> other ).BooleanFor example, end(0) is equivalent to last() and end(-1) is equivalent to get(count-2).
Returns true if each element of this data equals() each
corresponding element from in 'other'.
equals( DataType value ).Boolean[]
Returns a list of Boolean values where each value true if
the corresponding element of this indexed data equals()
the given value.
equals( Object other ).Boolean
Returns true if this object is equivalant to another.
first().DataTypeThe compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIfNote that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other').
Returns the first element of this data. This convenience
method is equivalent to get(0).
get( Readable<<Boolean>> flags ).DataType[]
Returns a new list containing the subset of elements
of which each of the corresponding 'flags' is true.
get( Readable<<Int32>> indices ).DataType[]Example:
local Int32[] nums = {1..10}
println( nums[nums % 2 == 0] )
#prints: {2,4,6,8,10}
Gets the element at each of the given zero-based 'indices'.
get( Int32 index ).DataTypeExample:
local Int32[] nums = {1..5}
nums[{0,4}] = nums[{4,0}]
println( nums )
#prints: {5,2,3,4,1}
Retieves the element at the zero-based 'index'.
hash_code().Int32Requires: 0 <= index < count
Returns the hash code of this object, which some classes
(like HashTable) rely on. This default implementation
throws an UnsupportedMethodError.
index_of( DataType value, [Int32 starting_index] ).Int32Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant:
if (obj1.hash_code != obj2.hash_code)
obj1.equals(obj2) == false
obj1.compare_to(obj2) != eq
endIf
Returns the first index that the given value occurs at
starting at index 0 by default. (-1) is returned if
'value' is not found.
indices().Range<<Int32>>
Returns this data's range of indices (0..count-1).
init( Int32 size )
Sets up this array to contain the given number of elements.
is_empty().Boolean
Returns true if count == 0.
is_not_empty().Boolean
Returns true if count > 0.
last().DataType
Returns the last element of this data. This convenience
method is equivalent to get(count-1).
last_index_of( DataType value, [Int32 starting_index] ).Int32
Returns the last index that the given value occurs at
starting at index (count-1) by default. (-1) is
returned if 'value' is not found.
modification_count().Int32
Returns a counter representing the number of times items
has been added to or removed. Used by readers to detect
concurrent list modification errors. For example, when an inner
method removes an item from a list the modification counter
is incremented. An outer "forEach" loop will detect that the
count is different from its original value and throw a
ConcurrentListModification error.
random().DataType
Returns an element of this data at random.
reverse()
Reverses the order of the elements in this data.
reverse_indices().Range<<Int32>>
Returns this data's range of indices reversed (count-1 downTo 0).
set( Readable<<Boolean>> element_flags, Readable<<DataType>> values )Example:
local Int32[] nums = {5..7}
forEach (i in nums.reverse_indices) println( i )
#prints: 2 | 1 | 0
Starting at index 0, sets each element to the next of the
given 'values' if the corresponding 'element_flags' are true.
set( Int32 index, DataType value )Example:
local Int32[] nums = {1..5}
nums[nums%2==1] = -nums
println( nums ) #prints: {-1,2,-3,4,-5}
Sets the element at the zero-based 'index' to the new 'value'.
set( Readable<<Int32>> indices, DataType value )Requires: 0 <= index < count
Sets the element at each of the given 'indices' to the given
'value'.
set( Readable<<Boolean>> flags, DataType value )Example:
local Int32[] nums = {1..5}
nums[{0,4}] = nums[{4,0}]
println( nums )
#prints: {5,2,3,4,1}
Starting at index 0, sets each element to the given 'value'
if the corresponding 'element_flags' are true.
set( Readable<<Int32>> indices, Readable<<DataType>> values )Example:
local Int32[] nums = {1..5}
nums[nums%2==1] = 0
println( nums ) #prints: {0,2,0,4,0}
Sets the element at each of the given 'indices' to each of
the corresponding 'values'.
shuffle()Requires: The number of indices == the number of values.Example:
local Int32[] nums = {1..5}
nums[0..4 step 2] = {7,8,9}
println( nums )
#prints: {7,2,8,4,9}
Swaps every element of this data with another element at a
randomly-chosen position.
subset( Int32 first_index, Int32 last_index ).ArrayList<<DataType>>
Returns the subset of this data between indices
[first_index,last_index] inclusive.
swap( Int32 index_a, Int32 index_b )
Swaps the value at 'index_a' with the one at 'index_b'.
to_List().DataType[]Requires: 0 <= index_a < count 0 <= index_b < countInvariant: this[index_a] = old[index_b] this[index_b] = old[index_a]
Converts this data into a list.
to_String().String
Returns a string representation of this data.
type_name().String
Returns the true class name of this object. Implemented by
the runtime; you should not override this method.
Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String |
The most common "collection" type in Slag, an ArrayList is an indexable list of items implemented using arrays.
An array list has 'count' and 'capacity'. Capacity is how many elements an arraylist can store before it has to create a larger backing array. Count is how many elements of the current array are currently in use. When 'count' reaches 'capacity', the next add() operation causes the backing array to be doubled in size.
An arraylist starts out at capacity 10, count 0 by default.
When you use "array notation" in Slag it creates arraylists. The following convenience conversions are performed:
# Create an empty list with 10 capacity
Int32[] nums(10) # 10 capacity
-> List<<Int32>> nums = ArrayList<<Int32>>(10)
# Create a list of 10 zero/null values
Int32[] nums = Int32[10]
-> List<<Int32>> nums = ArrayList<<Int32>>( 10, 0 )
# Create a list with the numbers 1 to 3
Int32[] nums = { 1, 2, 3 }
-> List<<Int32>> nums = ...
ArrayList<<Int32>>().add(1).add(2).add(3)
Invariant:
count >= 0 capacity >= count data.count == capacity
| Class Methods |
|---|
|
create_duplicate( Object existing ).Object
This factory method initiates object duplication. The
compiler transforms the duplicate(obj) command into
Object.create_duplicate(obj).
Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise |
| Object Variables |
|---|
|
counter : Int32
The position to add the next item - also equivalent to the
used item count.
data : Array<<DataType>>
The backing array for this arraylist.
modification_count : Int32 |
| Object Methods |
|---|
|
add( DataType value ).ArrayList<<DataType>>
Adds the given 'value' to the end of this list.
add( Readable<<DataType>> source ).List<<DataType>>Returns a reference to this list for call chaining. Invariant: count = old.count + 1 get[count-1] == value
Adds each item from the Readable source to this list.
add( DataType value, Int32 after_index ).List<<DataType>>Returns a reference to this list for call-chaining.
Inserts 'value' after the given index.
capacity().Int32Returns: A reference to this list for call-chaining.Requires: after_index >= -1 and after_index < countInvariant: new.count == old.count + 1 new[after_index+1] == value
Returns how many values this list can store before its backing
array must be doubled in size.
clear()
Removes all elements from this list. The capacity
is unchanged.
compare_to( Object other ).TernaryInvariant: new.count == 0 new.capacity == old.capacity
This method is used for ordering (quantitative) comparisons
between this object and another.
contains( DataType value ).BooleanReturns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt'Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract:
if (obj1.compare_to(obj2) == eq)
obj1.equals(obj2) == true
obj1.hash_code == obj2.hash_code
else
obj1.equals(obj2) == false
endIf
Note that two "equal" objects *must* have the same hash code,
but "unequal" objects may or may not have the same hash code.
This default implementation throws an UnsupportedMethodError.
Returns "true" if this data contains the given value.
count().Int32
Returns how many values there are in this list.
create_duplicate().ArrayList<<DataType>>
Creates a duplicate of this list when the "duplicate(list)"
command is given. If the list element type is a reference
type, the new list contains a copy of the same references
to the same objects - the objects themeselves are not
duplicated.
create_reader().Reader<<DataType>>Results: A duplicate list such that "all(this is result)" equals true.
Returns a reader that can be used to read() this data one
element at a time.
discard( Int32 first_index, [Int32 last_index] )
Removes the elements in the specified range. Does not return
the list of removed elements like remove() does. If only
the 'first' parameter is given, elements from 'first' to the
end of the list are discarded.
discard( Range<<Int32>> range )'first' and 'last' are clipped to be a valid range.
Removes elements in the specified range.
end( Int32 from_end ).DataTypeRequires: range.is_contiguous_ascending
Equivalent to get( (count-1) + from_end ).
ensure_capacity( Int32 min_capacity )For example, end(0) is equivalent to last() and end(-1) is equivalent to get(count-2).
Effects that this list has a capacity of at least
'min_capacity'. If it has a lower capacity, the backing
array is reallocated to have the necessary capacity.
equals( DataType value ).Boolean[]
Returns a list of Boolean values where each value true if
the corresponding element of this indexed data equals()
the given value.
equals( Readable<<DataType>> other ).Boolean
Returns true if each element of this data equals() each
corresponding element from in 'other'.
equals( Object other ).Boolean
Returns true if this object is equivalant to another.
expand_to_capacity().ArrayList<<DataType>>The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIfNote that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other').
Effectively adds enough null/zero values to this arraylist so
that the count matches the capacity. Technically the backing
array is maintained with null/zero values and so a counter
is adjusted.
first().DataTypeReturns: A reference to this list for call chaining.Invariant: count == capacity
Returns the first element of this data. This convenience
method is equivalent to get(0).
get( Readable<<Int32>> indices ).DataType[]
Gets the element at each of the given zero-based 'indices'.
get( Int32 index ).DataTypeExample:
local Int32[] nums = {1..5}
nums[{0,4}] = nums[{4,0}]
println( nums )
#prints: {5,2,3,4,1}
Returns the element at the given zero-based index.
get( Readable<<Boolean>> flags ).DataType[]Requires: 0 <= index and index < count
Returns a new list containing the subset of elements
of which each of the corresponding 'flags' is true.
hash_code().Int32Example:
local Int32[] nums = {1..10}
println( nums[nums % 2 == 0] )
#prints: {2,4,6,8,10}
Returns the hash code of this object, which some classes
(like HashTable) rely on. This default implementation
throws an UnsupportedMethodError.
index_of( DataType value, [Int32 starting_index] ).Int32Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant:
if (obj1.hash_code != obj2.hash_code)
obj1.equals(obj2) == false
obj1.compare_to(obj2) != eq
endIf
Returns the first index that the given value occurs at
starting at index 0 by default. (-1) is returned if
'value' is not found.
indices().Range<<Int32>>
Returns this data's range of indices (0..count-1).
init( Int32 initial_capacity )
Creates an empty arraylist with a specified initial capacity.
init( Readable<<DataType>> readable )
Initializes this list to contain all the items from the
'readable' data source.
init()
Creates an empty arraylist of capacity 10.
init( Int32 initial_capacity, DataType content )
Creates an array list full of 'initial_capacity' duplicates of
the given 'content'.
insert( IndexedData<<DataType>> seq, [Int32 before_index] ).ArrayList<<DataType>>
Inserts all the given values in front of 'before_index'. Elements
at 'begin_index' and higher are shifted over by one.
insert( DataType value, [Int32 before_index] ).ArrayList<<DataType>>Returns: A reference to this list for call chaining.Requires: 0 <= before_index and before_index <= countInvariant: this[before_index] = value this[before_index+seq.count] = old[before_index] count = old.count + seq.count
Inserts the 'value' in front of 'before_index'. Elements
at 'begin_index' and higher are shifted over by one.
is_empty().BooleanReturns: A reference to this list for call chaining.Requires: 0 <= before_index and before_index <= countInvariant: this[before_index] = value this[before_index+1] = old[before_index] count = old.count + 1
Returns true if count == 0.
is_not_empty().Boolean
Returns true if count > 0.
last().DataType
Returns the last element of this data. This convenience
method is equivalent to get(count-1).
last_index_of( DataType value, [Int32 starting_index] ).Int32
Returns the last index that the given value occurs at
starting at index (count-1) by default. (-1) is
returned if 'value' is not found.
modification_count().Int32
Returns a counter representing the number of times items
has been added to or removed. Used by readers to detect
concurrent list modification errors. For example, when an inner
method removes an item from a list the modification counter
is incremented. An outer "forEach" loop will detect that the
count is different from its original value and throw a
ConcurrentListModification error.
random().DataType
Returns an element of this data at random.
remove( DataType value ).Boolean
Calls remove_value(value). Only available for non-numerical
lists - see note in remove_value().
remove( Int32 first_index, Int32 last_index ).DataType[]
Removes and returns the elements in the specified range.
remove( Range<<Int32>> range ).DataType[]'first' and 'last' are clipped to be a valid range. Returns: The list of elements from old[first] through old[last].
Removes and returns the elements in the specified range.
See discard() for a variant that's optimal when you don't
need the return value.
remove( Int32 index ).DataTypeRequires: range.is_contiguous_ascending
Removes and returns the element at position 'index'. All
elements higher than 'index' are shifted down by one spot
and the list count is decremented.
remove_first().DataTypeReturns: old[index]Requires: 0 <= index and index < countInvariant: new[index] = old[index+1]
Equivalent to:
remove_last().DataTypelist.remove(0)
Equivalent to:
remove_value( DataType value ).Booleanlist.remove(list.count-1)
Removes the first occurrence of 'value' from the list.
reverse()Returns: "true" if an occurrence of 'value' was found and removed, or "false" if it was not found.Technical note: this method can't be named remove() because in an Int32[] list, remove(index) and remove(value) would have the same signature.
Reverses the order of the elements in this data.
reverse_indices().Range<<Int32>>
Returns this data's range of indices reversed (count-1 downTo 0).
set( Readable<<Int32>> indices, Readable<<DataType>> values )Example:
local Int32[] nums = {5..7}
forEach (i in nums.reverse_indices) println( i )
#prints: 2 | 1 | 0
Sets the element at each of the given 'indices' to each of
the corresponding 'values'.
set( Int32 index, DataType value )Requires: The number of indices == the number of values.Example:
local Int32[] nums = {1..5}
nums[0..4 step 2] = {7,8,9}
println( nums )
#prints: {7,2,8,4,9}
Sets the element at the given zero-based index.
set( Readable<<Boolean>> flags, DataType value )Requires: 0 <= index and index < count
Starting at index 0, sets each element to the given 'value'
if the corresponding 'element_flags' are true.
set( Readable<<Boolean>> element_flags, Readable<<DataType>> values )Example:
local Int32[] nums = {1..5}
nums[nums%2==1] = 0
println( nums ) #prints: {0,2,0,4,0}
Starting at index 0, sets each element to the next of the
given 'values' if the corresponding 'element_flags' are true.
set( Readable<<Int32>> indices, DataType value )Example:
local Int32[] nums = {1..5}
nums[nums%2==1] = -nums
println( nums ) #prints: {-1,2,-3,4,-5}
Sets the element at each of the given 'indices' to the given
'value'.
shuffle()Example:
local Int32[] nums = {1..5}
nums[{0,4}] = nums[{4,0}]
println( nums )
#prints: {5,2,3,4,1}
Swaps every element of this data with another element at a
randomly-chosen position.
sort( [SORT_ORDER order] )
Sorts this list in place using a HeapSort.
'order' is SORT_ORDER.ascending by default.
subset( Int32 first_index, Int32 last_index ).ArrayList<<DataType>>Only implemented for numerical and String lists. To enable it for lists of other types (say, Event), add this augment:
augment List<<Event>>
METHODS
method sort( SORT_ORDER order=SORT_ORDER.ascending ):
HeapSort<<DataType>>.sort( this, order )
endAugment
Returns the subset of this data between indices
[first_index,last_index] inclusive.
swap( Int32 index_a, Int32 index_b )
Swaps the value at 'index_a' with the one at 'index_b'.
to_List().DataType[]Requires: 0 <= index_a < count 0 <= index_b < countInvariant: this[index_a] = old[index_b] this[index_b] = old[index_a]
Satisifies the ListAdaptable aspect of the IndexedData aspect
by returning this list with no modifications.
to_String().String
Returns a string representation of this data.
trim_to_count().ArrayList<<DataType>>
Resizes the backing array to exactly fit the values currently
stored in this list. Only recommended when memory usage is
a concern and you won't be adding additional elements in the
near future.
type_name().StringReturns: A reference to this list for call chaining.Invariant: capacity == count
Returns the true class name of this object. Implemented by
the runtime; you should not override this method.
Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String |
Placeholder class that provides a common base type for all Array<<DataType>> classes.
| Class Methods |
|---|
|
create_duplicate( Object existing ).Object
This factory method initiates object duplication. The
compiler transforms the duplicate(obj) command into
Object.create_duplicate(obj).
Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise |
| Object Methods |
|---|
|
clear( Int32 first_index, Int32 last_index )
Clears all the elements in this array between the two indices.
compare_to( Object other ).TernaryUsing this method to clear elements at the end of an arraylist allows the runtime to limit the number of reference array elements it searches through during a data collection. Technical note: the runtime tracks the furthest position that a non-null reference array element could possibly be at after various calls to clear() and set().
This method is used for ordering (quantitative) comparisons
between this object and another.
copy_elements( ArrayType src_array, Int32 src_index, Int32 dest_index, Int32 number )Returns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt'Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract:
if (obj1.compare_to(obj2) == eq)
obj1.equals(obj2) == true
obj1.hash_code == obj2.hash_code
else
obj1.equals(obj2) == false
endIf
Note that two "equal" objects *must* have the same hash code,
but "unequal" objects may or may not have the same hash code.
This default implementation throws an UnsupportedMethodError.
Copies 'number' elements from another array (starting at
element 'src_index') into this one (starting at element
'dest_index').
count().Int32
Returns the count of how many elements are in this array.
create_duplicate().Object
Should create a duplicate of this object such that
obj1.equals(obj1.create_duplicate) return true.
equals( Object other ).BooleanThe command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError.
Returns true if this object is equivalant to another.
hash_code().Int32The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIfNote that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other').
Returns the hash code of this object, which some classes
(like HashTable) rely on. This default implementation
throws an UnsupportedMethodError.
to_String().StringHash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant:
if (obj1.hash_code != obj2.hash_code)
obj1.equals(obj2) == false
obj1.compare_to(obj2) != eq
endIf
Returns:
type_name().StringA String representation of this object. Most classes should override this method to summarize an object's state for convenience in testing and debugging.
Returns the true class name of this object. Implemented by
the runtime; you should not override this method.
Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String |
Internal use.
| Class Methods |
|---|
|
create_duplicate( Object existing ).Object
This factory method initiates object duplication. The
compiler transforms the duplicate(obj) command into
Object.create_duplicate(obj).
Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise |
| Object Variables |
|---|
|
next : PatternMatcher tag_group_index : Int32 |
| Object Methods |
|---|
|
chain_next( PatternMatcher _next ) compare_to( Object other ).Ternary
This method is used for ordering (quantitative) comparisons
between this object and another.
create_duplicate().ObjectReturns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt'Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract:
if (obj1.compare_to(obj2) == eq)
obj1.equals(obj2) == true
obj1.hash_code == obj2.hash_code
else
obj1.equals(obj2) == false
endIf
Note that two "equal" objects *must* have the same hash code,
but "unequal" objects may or may not have the same hash code.
This default implementation throws an UnsupportedMethodError.
Should create a duplicate of this object such that
obj1.equals(obj1.create_duplicate) return true.
equals( Object other ).BooleanThe command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError.
Returns true if this object is equivalant to another.
hash_code().Int32The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIfNote that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other').
Returns the hash code of this object, which some classes
(like HashTable) rely on. This default implementation
throws an UnsupportedMethodError.
init( Int32 tag_group_index )Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant:
if (obj1.hash_code != obj2.hash_code)
obj1.equals(obj2) == false
obj1.compare_to(obj2) != eq
endIf
match( PatternMatchInfo state ).Boolean match_next( PatternMatchInfo state ).Boolean matches_any().Boolean
Overridden in CharRangePatternMatcher
to_String().Stringtype_name().String
Returns the true class name of this object. Implemented by
the runtime; you should not override this method.
Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String |
Incorporate this aspect into enumerated types associated with Int32 values that define bit flags.
For example:
enum DIRECTION : BitFlags<<DIRECTION>>
CATEGORIES
north(1), east(2), south(4), west(8)
endEnum
...
local DIRECTION d = DIRECTION.north | DIRECTION.east
println( d == DIRECTION.north ) #prints: false
println( d.includes(DIRECTION.north) ) #prints: true
println( d ) #prints: north,east
println( d.flags ) #prints: 3
d &= !DIRECTION.north
println( d ) #prints: east
println( d == DIRECTION.east ) #prints: true
println( d.flags ) #prints: 2
| Class Variables |
|---|
|
default_next_flag : Int32 |
| Class Methods |
|---|
|
create_duplicate( Object existing ).Object
This factory method initiates object duplication. The
compiler transforms the duplicate(obj) command into
Object.create_duplicate(obj).
Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise |
| Object Variables |
|---|
|
flags : Int32 |
| Object Methods |
|---|
|
compare_to( Object other ).Ternary
This method is used for ordering (quantitative) comparisons
between this object and another.
create_duplicate().ObjectReturns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt'Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract:
if (obj1.compare_to(obj2) == eq)
obj1.equals(obj2) == true
obj1.hash_code == obj2.hash_code
else
obj1.equals(obj2) == false
endIf
Note that two "equal" objects *must* have the same hash code,
but "unequal" objects may or may not have the same hash code.
This default implementation throws an UnsupportedMethodError.
Should create a duplicate of this object such that
obj1.equals(obj1.create_duplicate) return true.
equals( EnumType other ).BooleanThe command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError. equals( Object other ).Boolean equals( Int32 other_flags ).Boolean hash_code().Int32
Returns the hash code of this object, which some classes
(like HashTable) rely on. This default implementation
throws an UnsupportedMethodError.
includes( Int32 other_flags ).BooleanHash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant:
if (obj1.hash_code != obj2.hash_code)
obj1.equals(obj2) == false
obj1.compare_to(obj2) != eq
endIf
Returns "true" if this category contains any of the
bitflags from 'other_flags'.
includes( EnumType other ).Boolean
Returns "true" if this category contains any of the
bitflags from the 'other' category.
init( Int32 flags )init() op!().EnumType
Returns a new category that contains the inverse
of this category's bitflags.
op&( EnumType other ).EnumType
Returns a new category that contains the intersection
of bitflags from this category and the 'other' category.
op&( Int32 other_flags ).EnumType
Returns a new category that contains the intersection
of bitflags from this category and 'other_flags'.
op|( Int32 other_flags ).EnumType
Returns a new category that includes all the bitflags
from this category and 'other_flags'.
op|( EnumType other ).EnumType
Returns a new category that includes all the bitflags
from this category and the 'other' category.
to_String().String
Returns a string containing the names of all comma-separated
categories included in this category's bitflags.
type_name().String
Returns the true class name of this object. Implemented by
the runtime; you should not override this method.
Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String |
A BitReader wraps an existing Reader<<Char>> and is able to read in 1-bit to 32-bit values at a time under normal operations. There are special method variants capable of reading in 64-bit values.
| Class Methods |
|---|
|
create_duplicate( Object existing ).Object
This factory method initiates object duplication. The
compiler transforms the duplicate(obj) command into
Object.create_duplicate(obj).
Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise |
| Object Variables |
|---|
|
bit_buffer : Int64
Internal use.
bit_count : Int32
Internal use.
src : Reader<<Char>>
The backing source of characters.
|
| Object Methods |
|---|
|
available().Int32
Returns the minimum number of additional values that can be
immediately read from this reader.
close()If the reader is exhausted or if it must block to peek or read next then the result will be 0. It is important to note that '0' does not necessarily mean the reader is exhausted. Many readers will report that they have 1 available even if there are thousands of values waiting to be read. The 'available' property should be used as an aide for buffer sizes and the like but should not be taken as an absolute size.
Closes this reader as a source of input. Useful for file
readers, but for most others this command does nothing.
compare_to( Object other ).Ternary
This method is used for ordering (quantitative) comparisons
between this object and another.
consume( DataType look_for ).BooleanReturns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt'Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract:
if (obj1.compare_to(obj2) == eq)
obj1.equals(obj2) == true
obj1.hash_code == obj2.hash_code
else
obj1.equals(obj2) == false
endIf
Note that two "equal" objects *must* have the same hash code,
but "unequal" objects may or may not have the same hash code.
This default implementation throws an UnsupportedMethodError.
Attempts to match and discard the next value from this
reader, returning true, or else leaves the next value still
pending and returns false.
create_duplicate().ObjectReturns: "true" if old.peek == look_for "false" if old.peek != look_forInvariant: if (old.peek == look_for) old.skip
Should create a duplicate of this object such that
obj1.equals(obj1.create_duplicate) return true.
equals( Object other ).BooleanThe command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError.
Returns true if this object is equivalant to another.
fill_buffer( Int32 to_n_bits )The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIfNote that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other').
Internal use.
has_another().Boolean
Returns true if there are at least 8 bits left to read.
has_another( Int32 n_bits ).BooleanSee also: has_another(Int32)
Returns true if there are at least 'n_bits' left to read. 'n_bits'
must be 1..32.
hash_code().Int32
Returns the hash code of this object, which some classes
(like HashTable) rely on. This default implementation
throws an UnsupportedMethodError.
init( Readable<<Char>> readable )Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant:
if (obj1.hash_code != obj2.hash_code)
obj1.equals(obj2) == false
obj1.compare_to(obj2) != eq
endIf
Initializes this BitReader to read from the given readable
character data.
init( Reader<<Char>> src )
Initializes this BitReader to read from the given character
reader.
is_exhausted().Boolean
Returns "true" if this reader does not have another value
or "false" if it does.
peek( Int32 n_bits ).Int32
Returns the next 'n_bits' value that will be returned by
read(n_bits).
peek().Char
Returns the next 8-bit value that will be returned by read().
peek_bit().Int32
Returns the bit of input that will be returned by read_bit.
position().Int32
This optional property-read returns the zero-based read
position of this reader. When a reader is first created
position() returns 0. After a single read() it returns 1,
and so on.
position( Int32 new_position )Readers that don't implement this property will throw an UnsupportedMethodError when it's accessed.
This optional property-write sets the zero-based read position
of this reader. When a reader is first created position()
returns 0. After a single read() it returns 1, and so on.
Readers that don't implement this property will throw an
UnsupportedMethodError when it's accessed.
read( Int32 n_bits ).Int32
Returns the next value of size 'n_bits', giving a value
between 0 and n_bits-1.
read().CharExample:
...
if (bits.peek == 0b01011000)
println( bits.read(3) ) # prints "2" (010)
println( bits.read(2) ) # prints "3" (11)
println( bits.read(3) ) # prints "0" (000)
endIf
Returns the next 8 bits as a Char.
read_Int64().Int64
Returns the next 64 bits as an Int64 assumed to be in
high-low byte order.
read_Int64_low_high().Int64
Returns the next 64 bits as an Int64 assumed to be in
low-high byte order.
read_bit().Int32
Returns the next bit of input.
read_line().String
Reads and returns the next line of characters up to the next
LF or CRLF. The CRLF characters are not part of
the return value and are discarded.
read_list( Int32 size ).DataType[]Only defined for Reader<<Char>>.
Reads the next 'size' number of values and returns them in a
list. Requires that there are at least 'size' number of
values remaining to be read.
read_low_high( Int32 n_bits ).Int32
Returns the next n_bits as a value. n_bits must be 16 or 32
bits. This method assumes that the first 8 bits to be read
are the least significant byte of the answer (bits 7:1) and
the last 8 bits are the most significant byte of the number
(e.g. bits 31:24).
remaining().Int32Requires: n_bits == 16 or n_bits == 32
This optional property returns how many values remain to be
read before the reader is exhausted. Not all readers
can implement this property; those that don't will throw
an UnsupportedMethodError when it's accessed.
rewind()
This optional method resets this reader so that the next
read() will return the first value of the series.
Readers that don't implement this property will throw an
UnsupportedMethodError when it's accessed.
skip( [Int32 skip_count] )
Discards exactly the next 'skip_count' number of values
rather than reading them. If there are not enough values
remaining then a NoNextValueError will be thrown from read().
to_List().DataType[]This program fragment: local var a = reader.read reader.read reader.read local var b = reader.readis equivalent to this: local var a = reader.read reader.skip(2) local var b = reader.read
Creates and returns a list of all the remaining values of
this reader.
to_String().String
Returns a string representation of this reader's values.
type_name().String
Returns the true class name of this object. Implemented by
the runtime; you should not override this method.
Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String |
A BitWriter wraps an existing Writer<<Char>> and allows arbitrarily-sized values of 1-32 bits to be written. 64-bit values may also be written using a separate call.
The bits are buffered and groups of 8 at a time (single bytes) are written to the backing Char writer.
| Class Methods |
|---|
|
create_duplicate( Object existing ).Object
This factory method initiates object duplication. The
compiler transforms the duplicate(obj) command into
Object.create_duplicate(obj).
Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise |
| Object Variables |
|---|
|
bit_buffer : Int64
Internal use.
bit_count : Int32
Internal use.
dest : Writer<<Char>>
The backing character writer that a BitWriter outputs to.
|
| Object Methods |
|---|
|
capacity().Int32
Returns the minimum number of additional values that can
written with this writer, or (-1) for "unlimited".
clean_up()
Closes the writer. Base aspect Writer does not incorporate
the RequiresCleanup interface, but types for writers that do
this method will be called when there are no more references
to the object.
close()
Flushes and closes this BitWriter.
compare_to( Object other ).Ternary
This method is used for ordering (quantitative) comparisons
between this object and another.
create_duplicate().ObjectReturns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt'Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract:
if (obj1.compare_to(obj2) == eq)
obj1.equals(obj2) == true
obj1.hash_code == obj2.hash_code
else
obj1.equals(obj2) == false
endIf
Note that two "equal" objects *must* have the same hash code,
but "unequal" objects may or may not have the same hash code.
This default implementation throws an UnsupportedMethodError.
Should create a duplicate of this object such that
obj1.equals(obj1.create_duplicate) return true.
equals( Object other ).BooleanThe command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError.
Returns true if this object is equivalant to another.
flush()The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIfNote that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other').
If there are any buffered bits that haven't been written
to the backing writer yet, flush() writes out enough zero
bits to make eight total and writes the resulting byte
of information.
hash_code().Int32
Returns the hash code of this object, which some classes
(like HashTable) rely on. This default implementation
throws an UnsupportedMethodError.
holds_has_another().BooleanHash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant:
if (obj1.hash_code != obj2.hash_code)
obj1.equals(obj2) == false
obj1.compare_to(obj2) != eq
endIf
Returns true if at least one more value can be written with
write().
init( Writable<<Char>> writable )
Initializes this BitWriter to output to the given writable
object.
init( Writer<<Char>> dest )
Initializes this BitWriter to output to the given writer.
position().Int32
This optional property-read returns the zero-based write
position. This will be "0" before anything is written, "1"
after a single write(), and so on.
position( Int32 new_pos )Not all writers implement this property; those that don't will throw an UnsupportedMethodError when it's accessed.
This optional property-write sets the zero-based write
position. It is up to the implementation to define how
repositioning works with gaps and what happens to data at a
later spot after a reposition to an earlier spot.
skip( Int32 skip_count )Not all writers implement this property; those that don't will throw an UnsupportedMethodError when it's accessed.
This optional method repositions the writer to be
'skip_count' values further along.
to_String().StringIf a writer does not implement the 'position' property then an UnsupportedMethodError will be generated when skip() is called.
Returns:
type_name().StringA String representation of this object. Most classes should override this method to summarize an object's state for convenience in testing and debugging.
Returns the true class name of this object. Implemented by
the runtime; you should not override this method.
write( Int32 value, Int32 n_bits )Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String
Writes 'value' in 'n_bits' using high-low byte order.
write( DataType value )
Outputs 'value' in an implementation-specific way.
write( Char value )Requires: holds_has_another == true
Writes 'value' in 8 bits.
write_Int64( Int64 value )
Writes 'value' in 64 bits using high-low byte order.
write_Int64_low_high( Int64 value )
Writes 'value' in 64 bits using low-high byte order.
write_bit( Int32 b )
Writes 'b' (0 or 1) as a single bit.
write_low_high( Int32 value, Int32 n_bits )
Writes 'value' in 'n_bits' using low-high byte order.
'n_bits' must be 16 or 32. The least-significant byte
is written first and the most significant byte is written
last.
Requires: n_bits == 16 or n_bits == 32 |
Pixel data wrapper for examining and manipulating image data. Many native layer implementations load textures as Bitmap objects first and then convert them into hardware-accelerated Images.
| Class Methods |
|---|
|
create( String filename ).Bitmap
Creates a Bitmap containing the pixel data from the specified
file. Currently only png and jpg files are supported.
create_duplicate( Object existing ).Object
This factory method initiates object duplication. The
compiler transforms the duplicate(obj) command into
Object.create_duplicate(obj).
Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise |
| Object Variables |
|---|
|
data : Array<<Color>>
Single-dimensional array of Color values. Values
data[0 ..< width] are the first row, data[width ..< width*2]
are the second row, and so on.
height : Int32
The height of this bitmap, in pixels.
width : Int32
The width of this bitmap, in pixels.
|
| Object Methods |
|---|
|
add_transparent_outline()
Adjusts this bitmap's data to include a 1-pixel transparent
black border on each edge.
clear( [Color color] )
Clears all the pixels of this bitmap to be the given color
or opaque black by default.
clear_channel( Color color, Int32 channel_mask )
Clears a certain channel of this bitmap to the given color.
column_transparent( Int32 x ).BooleanParameters:
color
The color to clear to. Only the bits of the AARRGGBB
'color' that correspond to the set bits in 'channel_mask'
are copied.
Returns "true" if column 'x' (where x is 0 ..< width)
contains completely transparent pixel values.
compare_to( Object other ).Ternary
This method is used for ordering (quantitative) comparisons
between this object and another.
create_duplicate().ObjectReturns 'eq' if they're equivalent, 'lt' if this object is "less than" the other, or 'gt' if this object is "greater than" another. The compiler converts: 'obj1 < obj2' -> 'obj1.compare_to(obj2) == lt' 'obj1 > obj2' -> 'obj1.compare_to(obj2) == gt' 'obj1 <= obj2' -> 'obj1.compare_to(obj2) != gt' 'obj1 >= obj2' -> 'obj1.compare_to(obj2) != lt'Implementations of compare_to() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract:
if (obj1.compare_to(obj2) == eq)
obj1.equals(obj2) == true
obj1.hash_code == obj2.hash_code
else
obj1.equals(obj2) == false
endIf
Note that two "equal" objects *must* have the same hash code,
but "unequal" objects may or may not have the same hash code.
This default implementation throws an UnsupportedMethodError.
Should create a duplicate of this object such that
obj1.equals(obj1.create_duplicate) return true.
draw( Int32 x, Int32 y )The command duplicate(obj) is transformed by the compiler into Object.create_duplicate(obj), which then calls this method. For optimal performance (by removing an internal typecast in most situations), have your overridden create_duplicate have the same return type as the class it's defined in. For instance, Strings implementation is 'create_duplicate.String'. This default implementation throws an UnsupportedMethodError.
For native layer debugging purposes. Performs a slow image
draw using a draw_point() call per pixel.
draw( Rect r, Color color, Boolean blend_alpha )
Draws the outline of the given rectangle in the given color,
optionally performing alpha-blending (default: true).
draw( Vector2 pos )
For native layer debugging purposes. See draw(Int32,Int32).
draw_channel_to( Bitmap dest, Int32 x, Int32 y, Int32 channel_mask )
Draws selected bits of this bitmap to the destination. No
alpha blending is performed.
draw_to( Bitmap dest, Vector2 pos, [Boolean blend_alpha] )Parameters:
dest
A bitmap to draw to. Edge clipping is performed.
Draws this bitmap to the given destination bitmap. This is
operation is performed in software and is not intended for
heavy per-frame use.
draw_to( Bitmap dest, Int32 x, Int32 y, [Boolean blend_alpha] )Parameters:
dest
A bitmap to draw to. Edge clipping is performed.
Draws this bitmap to the given destination bitmap. This is
operation is performed in software and is not intended for
heavy per-frame use.
equals( Object other ).BooleanParameters:
dest
A bitmap to draw to. Edge clipping is performed.
Returns true if this object is equivalant to another.
fill( Rect r, Color color, [Boolean blend_alpha] )The compiler converts 'obj1 == obj2' into 'obj1.equals(obj2)' and 'obj1 != obj2' into 'not obj1.equals(obj2)'. Implementations of equals() must maintain the following general contract between equals(), compare_to(), and hash_code(). Contract: if (obj1.equals(obj2)) obj1.compare_to(obj2) == eq obj1.hash_code == obj2.hash_code else obj1.compare_to(obj2) != eq endIfNote that two "equal" objects *must* have the same hash code, but "unequal" objects may or may not have the same hash code. This default implementation returns true if the this object and the 'other' reference are the same object ('this is other').
Fills the given rectangle with the given color, optionally
performing alpha-blending [default: false].
hash_code().Int32
Returns the hash code of this object, which some classes
(like HashTable) rely on. This default implementation
throws an UnsupportedMethodError.
init( String filename )Hash codes are used to quickly test and see if two complex objects are NOT equal. The value returned has no intrinsic meaning, but should conform to the following rules: 1. Two objects that are equivalent should produce the same hash code. 2. If an object's state doesn't change, its hash code shouldn't change either. Internally, this precludes the hash code being based on an object's memory address since Slag doesn't guarantee that an object's address won't change over time. This has the following implications: If you override hash_code you should also override equals() and possibly compare_to() and ensure the following contract. Invariant:
if (obj1.hash_code != obj2.hash_code)
obj1.equals(obj2) == false
obj1.compare_to(obj2) != eq
endIf
Creates a Bitmap containing image data from the given
png or jpeg file.
init( Bitmap existing, Rect rect )
Creates a bitmap that's a given subset of an existing bitmap.
init( Int32 width, Int32 height )
Creates a transparent black bitmap of the given width and
height.
init( Bitmap existing )
Creates a bitmap that's an exact duplicate of an existing bitmap.
init( Bitmap existing, Vector2 top_left, Vector2 new_size )
Creates a bitmap that's a given subset of an existing bitmap.
init( Vector2 pixel_size )
Creates a transparent black bitmap of the given size.
non_transparent_region().Rect
Returns a rectangle just large enough to enclose all pixels
that aren't completely transparent. If the area of the
resulting rectangle is zero then this bitmap is completely
transparent.
region().RectInvariant: result == intersection_of(old,result)
Returns the rectangular region occupied by this bitmap.
The 'position' of the resulting rectangle is (0,0).
row_transparent( Int32 y ).Boolean
Returns "true" if row 'y' (where y is 0 ..< height)
contains completely transparent pixel values.
set( Bitmap existing )
Sets this bitmap to reference the same data as another
existing bitmap. Note that the array of Color data is shared
rather than duplicated.
size().Vector2
Returns the two-dimensional size of this bitmap, in pixels.
split_into_tiles( Int32 tiles_wide, Int32 tiles_high ).Bitmap[]
Splits this Bitmap into an array of separate Bitmap tiles.
to_String().StringReturns a list of Bitmap objects where index 0 is the top-left tile, index[tiles_wide-1] is the top-right tile, and so on.
Returns:
type_name().StringA String representation of this object. Most classes should override this method to summarize an object's state for convenience in testing and debugging.
Returns the true class name of this object. Implemented by
the runtime; you should not override this method.
Example: local Object obj = "Hello World" println( obj.type_name ) #prints: String |
Wraps an existing Reader<<FromType>> and casts each value to ToType.
Example:
local Real64[] nums = { 3.0, 3.5, 3.9, 4.0 }
forEach (n in CastReader<<Real64,Int32>>(nums)) println(n)
# prints: 3 3 3 4
Example:
# Read "data.txt" into a byte buffer.
local Byte[] buffer = CastReader<<Char,Byte>>(File("data.txt").create_reader).to_List
| Class Methods |
|---|
|
create_duplicate( Object existing ).Object
This factory method initiates object duplicat |