5.1 Class Object
5.1.1 Object properties
5.1.2 Object methods
+ (integer$)length(void)
Returns the size (e.g., length) of the receiving object. This is equivalent to the length() (or size()) function; in other words, for any object x, the return value of the function call length(x) equals the return value of the class method call x.length(). This method is provided solely for syntactic convenience. Note that +length() is a synonym for +size().
+ (void)methodSignature([Ns$ methodName = NULL])
Prints the method signature for the method specified by methodName, or for all methods supported by the receiving object if methodName is NULL (the default).
+ (void)propertySignature([Ns$ propertyName = NULL])
Prints the property signature for the property specified by propertyName, or for all properties supported by the receiving object if propertyName is NULL (the default).
+ (integer$)size(void)
Returns the size of the receiving object. This is equivalent to the size() (or length()) function; in other words, for any object x, the return value of the function call size(x) equals the return value of the class method call x.size(). This method is provided solely for syntactic convenience. Note that +length() is a synonym for +size().
– (void)str(void)
Prints the internal property structure of the receiving object; in particular, the element type of the object is printed, followed, on successive lines, by all of the properties supported by the object, their types, and a sample of their values.
5.2 Class Dictionary
(object<Dictionary>$)Dictionary(...)
Creates a new Dictionary object. Called without arguments, as Dictionary(), this creates a new empty Dictionary.
Alternatively, key-value pairs can be passed to set up the initial state of the new Dictionary. These are set, sequentially, on the new Dictionary, just as setValue() would do. For example, calling Dictionary("a", 0:3, "b", c("foo", "bar")) is equivalent to calling Dictionary() and then calling setValue("a", 0:3) and then setValue("b", c("foo", "bar")) on it; it is just a shorthand for convenience.
Another alternative is to call Dictionary() with a singleton Dictionary as its only argument; this creates a new Dictionary that is a copy of the Dictionary passed, containing the same keys and values. This is equivalent to creating a new empty Dictionary and then calling addKeysAndValuesFrom() to copy key-value pairs over; it is just a shorthand for convenience.
A final alternative is to call Dictionary() with a singleton string as its only argument; this creates a new Dictionary from the string, assuming that it is a data archive in JSON format. Note that a JSON string can be generated from the serialize() method of Dictionary; together with this way of creating a Dictionary, this provides the ability to persist arbitrary information to a string (perhaps a file on disk) and back again. The recreated Dictionary should be identical to the original, except that zero length vectors such as integer(0), float(0), logical(0), and string(0) will all be serialized as "[]" and recreated as integer(0) since JSON does not provide a way to specify the type of a zero-length array.
5.2.1 Dictionary properties
allKeys => (string)
A vector containing all of the string keys that have been assigned values using setValue(), in sorted (alphabetical) order.
5.2.2 Dictionary methods
– (void)addKeysAndValuesFrom(object$ source)
Adds all of the key-value pairs contained by source (which must be a Dictionary or a subclass of Dictionary) to the receiver. If the target already contains a key that is defined in source, the target’s value for that key will be replaced by the value in source (contrast this with appendKeysAndValuesFrom()).
– (void)appendKeysAndValuesFrom(object source)
Appends all of the key-value pairs contained by source (which must be a Dictionary or a subclass of Dictionary) to the receiver. If the target already contains a key that is defined in source, the value from source will be appended to the target’s existing value, which must be of the same type (contrast this with addKeysAndValuesFrom()); if the target does not already contain a key that is defined in source, that key-value pair will simply be added to the target.
In the current implementation, it is an error for either of the values involved in an append to be a matrix or array; values in these Dictionary objects should be simple vectors. This limitation preserves the future option to expand this method’s functionality to do smart things with matrices and arrays.
– (void)clearKeysAndValues(void)
Removes all key-value pairs from the receiver.
– (object<Dictionary>$)getRowValues(li index)
Returns a new Dictionary containing values for selected “rows” of the target Dictionary, allowing Dictionary to act similarly to a dataframe (see the Dictionary class documentation for discussion). From this perspective, the selection logic described below works exactly as the subset operator [] does in Eidos, selecting the “rows” of the target Dictionary.
The index parameter may be either integer or logical; we will discuss the integer case first. If index is a singleton integer, the returned Dictionary will contain the index’th element of the value of each key of the target, under the same keys; this is a single “row” of the target Dictionary. If index is a non-singleton integer vector, the returned Dictionary will contain the values for all of the selected rows, in the order that they are selected by index. If any index value in index is out of range for any key of the target Dictionary (such that that key does not have an index’th value), an error will result.
If index is logical, the target Dictionary must not be “ragged” (the length of the values for all of its keys must be equal), and the length of index must be equal to the number of “rows” in the target. In this case, the T values in index select the “rows” which will be included in the returned Dictionary. The values of each column in the returned Dictionary will be in the same order as in the target.
In the current implementation, it is an error for any value in the target Dictionary to be a matrix or array; values in the target should be simple vectors. This limitation preserves the future option to expand this method’s functionality to do smart things with matrices and arrays.
– (*)getValue(string$ key)
Returns the value previously set for the dictionary entry identifier key using setValue(), or NULL if no value has been set.
– (logical$)identicalContents(object$ x)
Returns T if the target Dictionary is equal to x in all respects – containing the same keys, with values that are identical in the sense defined by the identical() function in Eidos – or returns F otherwise.
Note that if Dictionary objects are contained, as values, by the dictionaries being tested for equality, they will be compared according to the standards of identical(), and must therefore actually be the same Dictionary object, shared by both dictionaries, for isEqual() to return T.
– (string$)serialize([string$ format = "slim"])
Returns a serialized form of the dictionary’s contents as a singleton string. Two formats are supported at present, as chosen with the format parameter: "slim" and "json".
The default "slim" format is intended for simple, informal use where a very easily parseable string is desired. For a simple dictionary containing only keys with singleton non-object values, this will be a semicolon-delimited string like "key1=value1;key2=value2;". Values of type string will be quoted, and will be escaped with backslash escape sequences, including \\, \", \', \t, \r, and \n. Values that are not singleton will be separated by spaces, such as "key1=1 2 3;", while values that are themselves dictionaries will be delimited by braces, such as "key1={key1=value1;key2=value2;};". Keys, since they are also of type string, will be quoted and backslash-escaped if necessary, but simple keys that do not require that treatment will be serialized without quotes for simplicity.
The "json" format, introduced in Eidos 2.7 (SLiM 3.7), provides serialization of the Dictionary into the standard JSON format, which may not be quite as brief or human-readable, but which can be used as a standard interchange format and read by many other programs. For example, a Dictionary with a key "key1" with integer value 1:3 and key "key2" with string value "value2" would produce the JSON serialization '{"key1":[1,2,3],"key2":["value2"]}', where the outer single quotes are not part of the serialization itself, but are indicating that the serialization is a string value. Note that since all Eidos values are vectors, even singleton values are serialized into JSON as arrays by Eidos; the hope is that this will make automated parsing of these JSON strings easier, since the singleton case will not have to be special-cased. Documentation on the JSON format can be found online.
– (void)setValue(string$ key, * value)
Sets a value for the dictionary entry identifier key. The value, which may be of any type, can be fetched later using getValue(). If value is of type object, the object class must internally be under retain-release memory management; among SLiM’s Eidos classes, only Chromosome, Mutation, and Substitution presently are (see the Eidos manual’s documentation for defineConstant() for further discussion). Setting a key to a value of NULL removes that key from the dictionary.
5.3 Class Image
(object<Image>$)Image(string$ filePath)
Creates a new Image object from the PNG file at filePath. If the file represents a grayscale image, an 8-bit grayscale (K) Image will be created; all other PNG files will yield a 24-bit color (RGB) Image.
5.3.1 Image properties
width => (integer$)
The width of the image, in pixels.
height => (integer$)
The height of the image, in pixels.
isGrayscale => (logical$)
This flag is T if the image is grayscale, with only a K channel; it is F if the image is color, with R/G/B channels.
bitsPerChannel => (integer$)
The number of bits used to represent a single pixel, in one channel of the image. At present this is always 8; grayscale (K) images are 8-bit, color (RGB) images are 24-bit. It could be extended to support 16-bit channels in future.
integerR => (integer)
The red (R) channel of the image, represented as a 2D integer matrix. Values will be in [0,255]. See the floatR property for an alternative representation. If the image is grayscale, this property is unavailable.
integerG => (integer)
The green (G) channel of the image, represented as a 2D integer matrix. Values will be in [0,255]. See the floatG property for an alternative representation. If the image is grayscale, this property is unavailable.
integerB => (integer)
The blue (R) channel of the image, represented as a 2D integer matrix. Values will be in [0,255]. See the floatB property for an alternative representation. If the image is grayscale, this property is unavailable.
integerK => (integer)
The gray (K) channel of the image, represented as a 2D integer matrix. Values will be in [0,255]. See the floatK property for an alternative representation. If the image is color, this property is unavailable.
floatR => (float)
The red (R) channel of the image, represented as a 2D float matrix. Values will be in [0,1], obtained by dividing the integerR layer by 255. See the integerR property for an alternative representation. If the image is grayscale, this property is unavailable.
floatG => (float)
The green (G) channel of the image, represented as a 2D float matrix. Values will be in [0,1], obtained by dividing the integerG layer by 255. See the integerG property for an alternative representation. If the image is grayscale, this property is unavailable.
floatB => (float)
The blue (B) channel of the image, represented as a 2D float matrix. Values will be in [0,1], obtained by dividing the integerB layer by 255. See the integerB property for an alternative representation. If the image is grayscale, this property is unavailable.
floatK => (float)
The gray (K) channel of the image, represented as a 2D float matrix. Values will be in [0,1], obtained by dividing the integerK layer by 255. See the integerK property for an alternative representation. If the image is color, this property is unavailable.
5.3.2 Image methods
– (void)write(string$ filePath)
Writes the image to the given filesystem path filePath as PNG data. It is suggested, but not required, that filePath should end in a .png or .PNG filename extension. If the file cannot be written, an error will result. At present, since bitsPerChannel is always 8, grayscale data will be written as an 8-bit grayscale PNG while color (RGB) data will be written as a 24-bit color PNG without alpha.