Slag Standard Reference v0.22

Class AltPatternMatcher

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. 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. create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. 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. equals( Object other ).Boolean Returns true if this object is equivalant to another. 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 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 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. 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 if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf init() 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().String 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

Class AnyMatcher

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. 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. create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. 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. equals( Object other ).Boolean Returns true if this object is equivalant to another. 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 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 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. 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 if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf init( [Int32 min_count], [Int32 max_count] ) match( PatternMatchInfo state ).Boolean match_next( PatternMatchInfo state ).Boolean matches_any().Boolean Overridden in CharRangePatternMatcher to_String().String 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

Class ArbitraryCountPatternMatcher

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. 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. create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. 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. equals( Object other ).Boolean Returns true if this object is equivalant to another. 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 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 returns true if the this object and the 'other' reference are the same object ('this is other'). find_matches( PatternMatchInfo state ).Boolean hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. 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 if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf init( PatternMatcher term, [Int32 min_count], [Int32 max_count] ) match( PatternMatchInfo state ).Boolean match_next( PatternMatchInfo state ).Boolean matches_any().Boolean Overridden in CharRangePatternMatcher to_String().String 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

Class Array<<DataType>>

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 promote( DataType value ).DataType[] When there is an operation of the form "DataType + ListAdaptable<<DataType>>" (where DataType is a primitive or compound), the compiler calls this method to promote the left-hand side operand to an object.

Object Methods

clear( Int32 first_index, Int32 last_index ) Clears all the elements in this array between the two indices. Using 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(). compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. 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. compare_to( Readable<<DataType>> values ).Ternary[] Compares each of this object's values to each corresponding given value and returns a list of Ternary 'gt', 'lt', and 'eq' values. compare_to( DataType value ).Ternary[] Compares each of this object's values to the given value and returns a list of Ternary 'gt', 'lt', and 'eq' values. contains( DataType value ).Boolean 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 ). For example, end(0) is equivalent to last() and end(-1) is equivalent to get(count-2). 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. 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 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 returns true if the this object and the 'other' reference are the same object ('this is other'). equals( Readable<<DataType>> other ).Boolean Returns true if each element of this data equals() each corresponding element from in 'other'. first().DataType 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. Example: local Int32[] nums = {1..10} println( nums[nums % 2 == 0] ) #prints: {2,4,6,8,10} get( Readable<<Int32>> indices ).DataType[] Gets the element at each of the given zero-based 'indices'. Example: local Int32[] nums = {1..5} nums[{0,4}] = nums[{4,0}] println( nums ) #prints: {5,2,3,4,1} get( Int32 index ).DataType Retieves the element at the zero-based 'index'. Requires: 0 <= index < count hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. 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 if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf index_of( DataType value, [Int32 starting_index] ).Int32 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. op!().DataType[] Returns a list containing the logical complement of each value in this object. Only implemented for integer and Boolean ListAdaptable types. op%( DataType value ).DataType[] Returns a list of the remainders of each of this object's values divided by the given value. op%( Readable<<DataType>> values ).DataType[] Returns a list of the remainders of each of this object's values divided by each of the corresponding given values. op&( Readable<<DataType>> values ).DataType[] Performs a bitwise 'and' operation between each of this object's values and each corresponding given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. op&( DataType value ).DataType[] Performs a bitwise 'and' operation between each of this object's values and the given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. op*( Readable<<DataType>> values ).DataType[] Multiplies each of the given values by each of this object's corresponding values and returns a list of the results. op*( DataType value ).DataType[] Multiplies the given value by each of this object's values and returns a list of the results. op+( Readable<<DataType>> values ).DataType[] Adds each of the given values to each of this object's corresponding values and returns a list of the results. op+( DataType value ).DataType[] Adds the given value to each of this object's values and returns a list of the results. op-().DataType[] Returns a list containing the negative of each value in this object. op-( DataType value ).DataType[] Subtracts the given value from each of this object's values and returns a list of the results. op-( Readable<<DataType>> values ).DataType[] Subtracts each of the given values from each of this object's corresponding values and returns a list of the results. op/( DataType value ).DataType[] Divides each of this object's values by the given value and returns a list of the results. op/( Readable<<DataType>> values ).DataType[] Divides each of this object's values by each of the corresponding given values and returns a list of the results. op^( DataType value ).DataType[] Raises each of this object's values by the given value and returns a list of the results. op^( Readable<<DataType>> values ).DataType[] Raises each of this object's values by each of the corresponding given values and returns a list of the results. op|( DataType value ).DataType[] Performs a bitwise 'or' operation between each of this object's values and the given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. op|( Readable<<DataType>> values ).DataType[] Performs a bitwise 'or' operation between each of this object's values and each corresponding given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. op~( Readable<<DataType>> values ).DataType[] Performs a bitwise 'xor' operation between each of this object's values and each corresponding given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. op~( DataType value ).DataType[] Performs a bitwise 'xor' operation between each of this object's values and the given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. product().DataType Returns the product of all the values contained in this list-adaptable object. 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). Example: local Int32[] nums = {5..7} forEach (i in nums.reverse_indices) println( i ) #prints: 2 | 1 | 0 set( Readable<<Int32>> indices, DataType value ) Sets the element at each of the given 'indices' to the given 'value'. Example: local Int32[] nums = {1..5} nums[{0,4}] = nums[{4,0}] println( nums ) #prints: {5,2,3,4,1} set( Readable<<Int32>> indices, Readable<<DataType>> values ) Sets the element at each of the given 'indices' to each of the corresponding 'values'. 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} set( Readable<<Boolean>> flags, DataType value ) Starting at index 0, sets each element to the given 'value' if the corresponding 'element_flags' are true. Example: local Int32[] nums = {1..5} nums[nums%2==1] = 0 println( nums ) #prints: {0,2,0,4,0} set( Readable<<Boolean>> element_flags, Readable<<DataType>> values ) Starting at index 0, sets each element to the next of the given 'values' if the corresponding 'element_flags' are true. Example: local Int32[] nums = {1..5} nums[nums%2==1] = -nums println( nums ) #prints: {-1,2,-3,4,-5} set( Int32 index, DataType value ) Sets the element at the zero-based 'index' to the new 'value'. Requires: 0 <= index < count shuffle() 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. sum().DataType Returns the sum of all the values contained in this list-adaptable object. swap( Int32 index_a, Int32 index_b ) Swaps the value at 'index_a' with the one at 'index_b'. Requires: 0 <= index_a < count 0 <= index_b < count Invariant: this[index_a] = old[index_b] this[index_b] = old[index_a] to_List().DataType[] 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

Class ArrayList<<DataType>>

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)

  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 promote( DataType value ).DataType[] When there is an operation of the form "DataType + ListAdaptable<<DataType>>" (where DataType is a primitive or compound), the compiler calls this method to promote the left-hand side operand to an object.

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, Int32 after_index ).List<<DataType>> Inserts 'value' after the given index. Returns: A reference to this list for call-chaining. Requires: after_index >= -1 and after_index < count Invariant: new.count == old.count + 1 new[after_index+1] == value add( DataType value ).ArrayList<<DataType>> Adds the given 'value' to the end of this list. Returns a reference to this list for call chaining. Invariant: count = old.count + 1 get[count-1] == value add( Readable<<DataType>> source ).List<<DataType>> Adds each item from the Readable source to this list. Returns a reference to this list for call-chaining. capacity().Int32 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. Invariant: new.count == 0 new.capacity == old.capacity compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. 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. compare_to( Readable<<DataType>> values ).Ternary[] Compares each of this object's values to each corresponding given value and returns a list of Ternary 'gt', 'lt', and 'eq' values. compare_to( DataType value ).Ternary[] Compares each of this object's values to the given value and returns a list of Ternary 'gt', 'lt', and 'eq' values. contains( DataType value ).Boolean 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. Results: A duplicate list such that "all(this is result)" equals true. create_reader().Reader<<DataType>> Returns a reader that can be used to read() this data one element at a time. discard( Range<<Int32>> range ) Removes elements in the specified range. Requires: range.is_contiguous_ascending 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. 'first' and 'last' are clipped to be a valid range. end( Int32 from_end ).DataType Equivalent to get( (count-1) + from_end ). For example, end(0) is equivalent to last() and end(-1) is equivalent to get(count-2). ensure_capacity( Int32 min_capacity ) 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. 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 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 returns true if the this object and the 'other' reference are the same object ('this is other'). expand_to_capacity().ArrayList<<DataType>> 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. Returns: A reference to this list for call chaining. Invariant: count == capacity first().DataType Returns the first element of this data. This convenience method is equivalent to get(0). get( Int32 index ).DataType Returns the element at the given zero-based index. Requires: 0 <= index and index < count get( Readable<<Boolean>> flags ).DataType[] Returns a new list containing the subset of elements of which each of the corresponding 'flags' is true. Example: local Int32[] nums = {1..10} println( nums[nums % 2 == 0] ) #prints: {2,4,6,8,10} get( Readable<<Int32>> indices ).DataType[] Gets the element at each of the given zero-based 'indices'. Example: local Int32[] nums = {1..5} nums[{0,4}] = nums[{4,0}] println( nums ) #prints: {5,2,3,4,1} hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. 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 if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf index_of( DataType value, [Int32 starting_index] ).Int32 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( Readable<<DataType>> readable ) Initializes this list to contain all the items from the 'readable' data source. init( Int32 initial_capacity, DataType content ) Creates an array list full of 'initial_capacity' duplicates of the given 'content'. init() Creates an empty arraylist of capacity 10. init( Int32 initial_capacity ) Creates an empty arraylist with a specified initial capacity. 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. Returns: A reference to this list for call chaining. Requires: 0 <= before_index and before_index <= count Invariant: this[before_index] = value this[before_index+seq.count] = old[before_index] count = old.count + seq.count insert( DataType value, [Int32 before_index] ).ArrayList<<DataType>> Inserts the 'value' in front of 'before_index'. Elements at 'begin_index' and higher are shifted over by one. Returns: A reference to this list for call chaining. Requires: 0 <= before_index and before_index <= count Invariant: this[before_index] = value this[before_index+1] = old[before_index] count = old.count + 1 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. op!().DataType[] Returns a list containing the logical complement of each value in this object. Only implemented for integer and Boolean ListAdaptable types. op%( Readable<<DataType>> values ).DataType[] Returns a list of the remainders of each of this object's values divided by each of the corresponding given values. op%( DataType value ).DataType[] Returns a list of the remainders of each of this object's values divided by the given value. op&( Readable<<DataType>> values ).DataType[] Performs a bitwise 'and' operation between each of this object's values and each corresponding given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. op&( DataType value ).DataType[] Performs a bitwise 'and' operation between each of this object's values and the given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. op*( Readable<<DataType>> values ).DataType[] Multiplies each of the given values by each of this object's corresponding values and returns a list of the results. op*( DataType value ).DataType[] Multiplies the given value by each of this object's values and returns a list of the results. op+( Readable<<DataType>> values ).DataType[] Adds each of the given values to each of this object's corresponding values and returns a list of the results. op+( DataType value ).DataType[] Adds the given value to each of this object's values and returns a list of the results. op-().DataType[] Returns a list containing the negative of each value in this object. op-( Readable<<DataType>> values ).DataType[] Subtracts each of the given values from each of this object's corresponding values and returns a list of the results. op-( DataType value ).DataType[] Subtracts the given value from each of this object's values and returns a list of the results. op/( Readable<<DataType>> values ).DataType[] Divides each of this object's values by each of the corresponding given values and returns a list of the results. op/( DataType value ).DataType[] Divides each of this object's values by the given value and returns a list of the results. op^( Readable<<DataType>> values ).DataType[] Raises each of this object's values by each of the corresponding given values and returns a list of the results. op^( DataType value ).DataType[] Raises each of this object's values by the given value and returns a list of the results. op|( DataType value ).DataType[] Performs a bitwise 'or' operation between each of this object's values and the given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. op|( Readable<<DataType>> values ).DataType[] Performs a bitwise 'or' operation between each of this object's values and each corresponding given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. op~( DataType value ).DataType[] Performs a bitwise 'xor' operation between each of this object's values and the given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. op~( Readable<<DataType>> values ).DataType[] Performs a bitwise 'xor' operation between each of this object's values and each corresponding given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. product().DataType Returns the product of all the values contained in this list-adaptable object. random().DataType Returns an element of this data at random. remove( Int32 index ).DataType 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. Returns: old[index] Requires: 0 <= index and index < count Invariant: new[index] = old[index+1] remove( Range<<Int32>> range ).DataType[] 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. Requires: range.is_contiguous_ascending 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. 'first' and 'last' are clipped to be a valid range. Returns: The list of elements from old[first] through old[last]. remove_first().DataType Equivalent to: list.remove(0) remove_last().DataType Equivalent to: list.remove(list.count-1) remove_value( DataType value ).Boolean Removes the first occurrence of 'value' from the list. 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. 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). Example: local Int32[] nums = {5..7} forEach (i in nums.reverse_indices) println( i ) #prints: 2 | 1 | 0 set( Readable<<Boolean>> element_flags, Readable<<DataType>> values ) Starting at index 0, sets each element to the next of the given 'values' if the corresponding 'element_flags' are true. Example: local Int32[] nums = {1..5} nums[nums%2==1] = -nums println( nums ) #prints: {-1,2,-3,4,-5} set( Readable<<Boolean>> flags, DataType value ) Starting at index 0, sets each element to the given 'value' if the corresponding 'element_flags' are true. Example: local Int32[] nums = {1..5} nums[nums%2==1] = 0 println( nums ) #prints: {0,2,0,4,0} set( Readable<<Int32>> indices, DataType value ) Sets the element at each of the given 'indices' to the given 'value'. Example: local Int32[] nums = {1..5} nums[{0,4}] = nums[{4,0}] println( nums ) #prints: {5,2,3,4,1} set( Readable<<Int32>> indices, Readable<<DataType>> values ) Sets the element at each of the given 'indices' to each of the corresponding 'values'. 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} set( Int32 index, DataType value ) Sets the element at the given zero-based index. Requires: 0 <= index and index < count shuffle() 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. 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 subset( Int32 first_index, Int32 last_index ).ArrayList<<DataType>> Returns the subset of this data between indices [first_index,last_index] inclusive. sum().DataType Returns the sum of all the values contained in this list-adaptable object. swap( Int32 index_a, Int32 index_b ) Swaps the value at 'index_a' with the one at 'index_b'. Requires: 0 <= index_a < count 0 <= index_b < count Invariant: this[index_a] = old[index_b] this[index_b] = old[index_a] to_List().DataType[] 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. Returns: A reference to this list for call chaining. Invariant: capacity == count 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

Class ArrayType

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. Using 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(). compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. 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. 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().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. 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. equals( Object other ).Boolean Returns true if this object is equivalant to another. 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 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 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. 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 if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf to_String().String Returns: A String representation of this object. Most classes should override this method to summarize an object's state for convenience in testing and debugging. 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

Class BeginTagGroupPatternMatcher

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. 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. create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. 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. equals( Object other ).Boolean Returns true if this object is equivalant to another. 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 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 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. 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 if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf init( Int32 tag_group_index ) match( PatternMatchInfo state ).Boolean match_next( PatternMatchInfo state ).Boolean matches_any().Boolean Overridden in CharRangePatternMatcher to_String().String 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

Aspect BitFlags<<EnumType>>

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. 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. create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. 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. equals( EnumType other ).Boolean 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. 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 if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf includes( Int32 other_flags ).Boolean 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

Class BitReader

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 promote( DataType value ).DataType[] When there is an operation of the form "DataType + ListAdaptable<<DataType>>" (where DataType is a primitive or compound), the compiler calls this method to promote the left-hand side operand to an object.

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. 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. close() Closes this reader as a source of input. Useful for file readers, but for most others this command does nothing. compare_to( DataType value ).Ternary[] Compares each of this object's values to the given value and returns a list of Ternary 'gt', 'lt', and 'eq' values. compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. 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. compare_to( Readable<<DataType>> values ).Ternary[] Compares each of this object's values to each corresponding given value and returns a list of Ternary 'gt', 'lt', and 'eq' values. consume( DataType look_for ).Boolean Attempts to match and discard the next value from this reader, returning true, or else leaves the next value still pending and returns false. Returns: "true" if old.peek == look_for "false" if old.peek != look_for Invariant: if (old.peek == look_for) old.skip create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. 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. equals( Object other ).Boolean Returns true if this object is equivalant to another. 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 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 returns true if the this object and the 'other' reference are the same object ('this is other'). fill_buffer( Int32 to_n_bits ) Internal use. has_another().Boolean Returns true if there are at least 8 bits left to read. See also: has_another(Int32) has_another( Int32 n_bits ).Boolean 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. 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 if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf init( Reader<<Char>> src ) Initializes this BitReader to read from the given character reader. init( Readable<<Char>> readable ) Initializes this BitReader to read from the given readable character data. is_exhausted().Boolean Returns "true" if this reader does not have another value or "false" if it does. op!().DataType[] Returns a list containing the logical complement of each value in this object. Only implemented for integer and Boolean ListAdaptable types. op%( Readable<<DataType>> values ).DataType[] Returns a list of the remainders of each of this object's values divided by each of the corresponding given values. op%( DataType value ).DataType[] Returns a list of the remainders of each of this object's values divided by the given value. op&( Readable<<DataType>> values ).DataType[] Performs a bitwise 'and' operation between each of this object's values and each corresponding given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. op&( DataType value ).DataType[] Performs a bitwise 'and' operation between each of this object's values and the given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. op*( Readable<<DataType>> values ).DataType[] Multiplies each of the given values by each of this object's corresponding values and returns a list of the results. op*( DataType value ).DataType[] Multiplies the given value by each of this object's values and returns a list of the results. op+( DataType value ).DataType[] Adds the given value to each of this object's values and returns a list of the results. op+( Readable<<DataType>> values ).DataType[] Adds each of the given values to each of this object's corresponding values and returns a list of the results. op-( Readable<<DataType>> values ).DataType[] Subtracts each of the given values from each of this object's corresponding values and returns a list of the results. op-( DataType value ).DataType[] Subtracts the given value from each of this object's values and returns a list of the results. op-().DataType[] Returns a list containing the negative of each value in this object. op/( Readable<<DataType>> values ).DataType[] Divides each of this object's values by each of the corresponding given values and returns a list of the results. op/( DataType value ).DataType[] Divides each of this object's values by the given value and returns a list of the results. op^( Readable<<DataType>> values ).DataType[] Raises each of this object's values by each of the corresponding given values and returns a list of the results. op^( DataType value ).DataType[] Raises each of this object's values by the given value and returns a list of the results. op|( Readable<<DataType>> values ).DataType[] Performs a bitwise 'or' operation between each of this object's values and each corresponding given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. op|( DataType value ).DataType[] Performs a bitwise 'or' operation between each of this object's values and the given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. op~( DataType value ).DataType[] Performs a bitwise 'xor' operation between each of this object's values and the given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. op~( Readable<<DataType>> values ).DataType[] Performs a bitwise 'xor' operation between each of this object's values and each corresponding given value and returns a list of results. Only implemented for integer and Boolean ListAdaptable types. 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. Readers that don't implement this property will throw an UnsupportedMethodError when it's accessed. position( Int32 new_position ) 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. product().DataType Returns the product of all the values contained in this list-adaptable object. read().Char Returns the next 8 bits as a Char. read( Int32 n_bits ).Int32 Returns the next value of size 'n_bits', giving a value between 0 and n_bits-1. Example: ... 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 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. Only defined for Reader<<Char>>. read_list( Int32 size ).DataType[] 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). Requires: n_bits == 16 or n_bits == 32 remaining().Int32 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(). This program fragment: local var a = reader.read reader.read reader.read local var b = reader.read is equivalent to this: local var a = reader.read reader.skip(2) local var b = reader.read sum().DataType Returns the sum of all the values contained in this list-adaptable object. to_List().DataType[] 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

Class BitWriter

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. 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. create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. 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. equals( Object other ).Boolean Returns true if this object is equivalant to another. 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 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 returns true if the this object and the 'other' reference are the same object ('this is other'). flush() 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. 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 if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf holds_has_another().Boolean 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. Not all writers implement this property; those that don't will throw an UnsupportedMethodError when it's accessed. position( Int32 new_pos ) 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. Not all writers implement this property; those that don't will throw an UnsupportedMethodError when it's accessed. skip( Int32 skip_count ) This optional method repositions the writer to be 'skip_count' values further along. If a writer does not implement the 'position' property then an UnsupportedMethodError will be generated when skip() is called. to_String().String Returns: A String representation of this object. Most classes should override this method to summarize an object's state for convenience in testing and debugging. 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 write( Int32 value, Int32 n_bits ) Writes 'value' in 'n_bits' using high-low byte order. write( DataType value ) Outputs 'value' in an implementation-specific way. Requires: holds_has_another == true write( Char value ) 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

Class CastReader<<FromType,ToType>>

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

  # 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 duplication. The compiler transforms the duplicate(obj) command into Object.create_duplicate(obj). Returns: 'null' if 'existing' is null. existing.create_duplicate otherwise promote( DataType value ).DataType[] When there is an operation of the form "DataType + ListAdaptable<<DataType>>" (where DataType is a primitive or compound), the compiler calls this method to promote the left-hand side operand to an object.

Object Variables
has_next : Boolean If "true" then 'next' is a valid value. next : OutputDataType The next data that will be returned by peek() or read(). src : Reader<<InputDataType>> The backing source of values for this reader.

Object Methods

available().Int32 Returns the minimum number of additional values that can be immediately read from this reader. 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. close() Closes this reader as a source of input. Useful for file readers, but for most others this command does nothing. compare_to( DataType value ).Ternary[] Compares each of this object's values to the given value and returns a list of Ternary 'gt', 'lt', and 'eq' values. compare_to( Readable<<DataType>> values ).Ternary[] Compares each of this object's values to each corresponding given value and returns a list of Ternary 'gt', 'lt', and 'eq' values. compare_to( Object other ).Ternary This method is used for ordering (quantitative) comparisons between this object and another. 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. consume( DataType look_for ).Boolean Attempts to match and discard the next value from this reader, returning true, or else leaves the next value still pending and returns false. Returns: "true" if old.peek == look_for "false" if old.peek != look_for Invariant: if (old.peek == look_for) old.skip create_duplicate().Object Should create a duplicate of this object such that obj1.equals(obj1.create_duplicate) return true. 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. equals( Object other ).Boolean Returns true if this object is equivalant to another. 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 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 returns true if the this object and the 'other' reference are the same object ('this is other'). has_another().Boolean Returns "true" if this reader has another value that can be previewed with peek() or read with read(). hash_code().Int32 Returns the hash code of this object, which some classes (like HashTable) rely on. This default implementation throws an UnsupportedMethodError. 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 if (obj1.equals(obj2)) obj1.hash_code == obj2.hash_code endIf init( Reader<<InputDataType>> src ) Initializes this BitReader to read from the given readable data. init( Readable<<InputDataType>> readable ) Initializes this BitReader to read from the given reader. is_exhausted().Boolean Returns "true" if this reader does not have another value or "false" if it does.