Collections Management
The first category of functions relate to managing resource collections and arrays of values.
| • | size |
| • | first and last |
| • | sort |
| • | contains |
| • | empty |
| • | any |
| • | all |
| • | select |
| • | unique |
Syntax
size($array, $hash, $string or @collection)
Description
This function simply returns the size of the resource collection or array of values given as argument.
Arguments
|
Position |
Possible Values |
Required |
Default Value |
||||||||||||
|
1 |
One of the following:
|
Yes |
None |
Result
The result is an integer representing the size of the given array, hash, string, or collection.
Syntax
first($array or @collection) and last($array or @collection)
Description
These functions simply retrieve the first or last element of a resource collection or array of values.
Note:For resource collections, the result is a resource collection itself, consisting of a single resource. However, for an array of values, the result is a single value.
Arguments
The only argument is the collection from which the first or last element should be extracted.
|
Position |
Possible Values |
Required |
Default Value |
||||||
|
1 |
-OR-
|
Yes |
None |
Result
A resource collection if the argument is a resource collection or a value if the argument is an array of values.
Examples
$one = first([1, 2, 3]) # $one == 1
@servers = rs_cm.deployments.get(filter: ["name==default"]).servers()
@first = first(@servers) # size(@first) == 1
Syntax
sort($array or @collection[, $field][, $order])
Description
The sort() function allows sorting resource collections and arrays of values. If sorting an array of values, then all values must be of the same type and the array must not contain null. The ordering follows the same logic as the comparison operators:
| • | Numbers and datetime use the natural order (think of datetime in terms of seconds since the epoch for comparison) |
| • | Strings and arrays follow the lexicographical order |
| • | true > false |
Hashes cannot be compared directly. Instead the sort() function accepts an argument to specify recursively which key should be used for sorting. That same argument can be used on resource collections to specify which field should be used for sorting. If the field ends up being a hash, then recursively what key of the hash should be used. By default, sorting resource collections is done using the name field.
Arguments
|
Position |
Possible Values |
Required |
Default Value |
Comment |
||||||
|
1 |
-OR-
|
Yes |
None |
Collection to be sorted |
||||||
|
2 |
String |
Only if collection is an array of hashes |
name for resource collections |
-OR-
|
||||||
|
3 |
asc or desc |
No |
asc |
Sorting order (ascendant or descendant) |
Result
The result type is the same as the first argument: a resource collection or an array of values.
Examples
Sorting a resource collection by name:
@servers = rs_cm.deployments.get(filter: ["name==default"]).servers()
@sorted_servers = sort(@servers)
Sorting a collection of instances by their user data descending:
@instances = rs_cm.deployments.get(filter: ["name==default"]).server().current_instance()
@sorted_instances = sort(@instances, "settings/user_data", "desc")
Sorting an array of hashes (using a key called timestamp in this example):
$data = [{ "value": 42, "timestamp": d"1/1/2012 12:32" },
{ "value": 43, "timestamp": d"1/1/2012 16:31" }]
$sorted_data = sort($data, "timestamp")
Syntax
contains?($array or @collection, elements)
Description
This function checks whether all the elements of a given collection or a specific value are contained in another given collection. The elements may be in different order and they may appear a different number of times, but as long as all elements appear at least once, then the function returns true, otherwise it returns false.
Arguments
|
Position |
Possible Values |
Required |
Default Value |
Comment |
||||||
|
1 |
-OR-
|
Yes |
None |
Container being tested |
||||||
|
2 |
-OR-
|
Yes |
None |
Elements that must be in container for function to return true |
Result
true if all elements are contained in given collection, false otherwise.
Examples
$array = [1, 2, 3, 4]
contains?($array, [1]) == true
contains?($array, [5]) == false
contains?($array, [2, 1, 3, 3]) == true
contains?($array, [1, 2, 3, 5]) == false
@servers = rs_cm.deployments.get(filter: ["name==default"]).servers()
@server = rs_cm.get(href: "servers/123") # Assume this server belongs to a deployment named 'default'
contains?(@servers, @server) == true
Syntax
empty?($array or @collection)
Description
Returns true if the given collection (resource collection or array of values) is empty, false otherwise.
Arguments
|
Position |
Possible Values |
Required |
Default Value |
||||||
|
1 |
-OR-
|
Yes |
None |
Result
true if given collection is empty, false otherwise.
Syntax
any?($array[, $value_or_regexp])
Description
This function checks for the existence of an element in an array of JSON values. When only an array is given then returns true if the array contains a value that is neither null nor false. When both an array and a value are provided then returns true if the array contains at least once the given value. If the value is a regular expression, it will return true if there is a least one value that is a string and that matches the regexp. The syntax used to write a regular expressions is /regexp/.
Arguments
|
Position |
Possible Values |
Required |
Default Value |
||||||
|
1 |
Array of values |
Yes |
None |
||||||
|
2 |
-OR-
|
No |
None |
Result
true or false.
Examples
$array_of_false = [false, false, null]
any?($array_of_false) == false # All elements are null or false, result is false
$array = [1, 2, 3, "a", "b", "cde"]
any?($array) == true # Array contains values that are not either false or null, result is true
any?($array, 1) == true # Array contains the value 1
any?($array, "cd") == false # Array does not contain value "cd"
any?($array, "/cd/") == true # Value "cde" matches regular expression "cd"
Syntax
all?($array[, $value_or_regexp])
Description
This function checks whether all elements of an array have a given value. When only an array is provided, then it returns true if the array does not contain a value that is either null or false. When both an array and a value is provided, then it returns true if the array values all match the given value. If the value is a regular expression, it will return true if all the values in the array are all strings that match the regular expression. It returns true if the array is empty.
Arguments
|
Position |
Possible Values |
Required |
Default Value |
||||||
|
1 |
Array of values |
Yes |
None |
||||||
|
2 |
-OR-
|
No |
None |
Result
true or false.
Examples
$array_with_one_false = [1, 2, false]
all?($array_with_one_false) == false # One element is null or false, result is false
$array = [1, 2, 3, "a", "b", "cde"]
all?($array) == true # Array contains no null or false, result is true
all?($array, 1) == false # Not all values are one
all?($array, "/cd/") == false # Not all values are strings that match regular expression "cd"
Syntax
select($array or @collection, $hash)
Description
This function extracts the elements of a resource collection or of an array of hashes that have fields or values with a given value. The name of the field or hash key that should be selected for comparison correspond to the keys of the hash given as second argument. The values of that hash are the values that the resource fields or hash entries must be selected. If the resource field or hash values are strings, then the selector hash value can represent regular expressions.
Arguments
|
Position |
Possible Values |
Required |
Default Value |
Comment |
||||||
|
1 |
-OR-
|
Yes |
None |
Container being tested |
||||||
|
2 |
Hash |
Yes |
None |
-OR-
|
Result
A resource collection composed of resources that have fields with the given values or an array of hashes that have the given values for given keys.
Examples
@servers = rs_cm.deployments.get(filter: ["name==default"]).servers()
@app_servers = select(@servers, { "name": "/app/" }) # @app_servers contains servers whose name match
# the regular expression "app" (i.e. contain the string "app")
$hashes = [{ "key": "value1" }, { "key": "value2" }]
$hashes_with_value1 = select($hashes, { "key": "value1" }) # $hashes_with_value1 contains hashes whose values
# stored in key "key" is "value1"
Syntax
unique($array or @collection)
Description
This function traverses the given collection and returns a new collection made of all the unique elements. Two resources are considered identical if they have the same href.
Arguments
|
Position |
Possible Values |
Required |
Default Value |
Comment |
||||||
|
1 |
-OR-
|
Yes |
None |
Container to be traversed and whose unique elements should be extracted |
Result
A collection composed of the distinct elements in the initial collection. The types of the elements is preserved (so the result is a resource collection or an array of values depending on the argument).
Examples
@servers = rs_cm.deployments.get(filter: ["name==default"]).servers()
@duplicated_servers = @servers + @servers
@unique_servers = unique(@duplicated_servers)
assert @servers == @unique_servers