MBMLCollectionFunctions Class Reference
| Inherits from | NSObject |
|---|---|
| Declared in | MBMLCollectionFunctions.h |
Overview
This class provides a set of MBML functions that perform common
operations on collections such as NSArray, NSSet and NSDictionary
objects.
These functions are exposed to the Mockingbird environment via
<Function ... /> declarations in the MBDataEnvironmentModule.xml
file.
For more information on MBML functions, see the MBMLFunction class.
Testing for collection types
+ isCollection:
Determines whether a given object is considered a collection; that is, an
instance of NSSet, NSArray or NSDictionary.
+ (NSNumber *)isCollection:(id)paramParameters
param |
The function’s input parameter. |
|---|
Return Value
@YES if param represents a collection object, @NO otherwise.
Discussion
This Mockingbird function accepts a single parameter: an object expression yielding the instance to be tested.
Expression usage
Assume the MBML variable $cities contains an array value. The expression:
^isCollection($cities)
would return the value @YES.
See Also
Declared In
MBMLCollectionFunctions.h
+ isSet:
Determines whether a given object is an instance of NSSet.
+ (NSNumber *)isSet:(id)paramParameters
param |
The function’s input parameter. |
|---|
Return Value
@YES if param represents an NSSet, @NO otherwise.
Discussion
This Mockingbird function accepts a single parameter: an object expression yielding the instance to be tested.
Expression usage
Assume the MBML variable $cities contains an array value. The expression:
^isSet($cities)
would return the value @NO.
See Also
Declared In
MBMLCollectionFunctions.h
+ isDictionary:
Determines whether a given object is an instance of NSDictionary.
+ (NSNumber *)isDictionary:(id)paramParameters
param |
The function’s input parameter. |
|---|
Return Value
@YES if param represents an NSDictionary, @NO otherwise.
Discussion
This Mockingbird function accepts a single parameter: an object expression yielding the instance to be tested.
Expression usage
Assume $accountIdsToNames is a dictionary. The expression:
^isDictionary($accountIdsToNames)
would return the value @YES.
See Also
Declared In
MBMLCollectionFunctions.h
+ isArray:
Determines whether a given object is an instance of NSArray.
+ (NSNumber *)isArray:(id)paramParameters
param |
The function’s input parameter. |
|---|
Return Value
@YES if param represents an NSArray, @NO otherwise.
Discussion
This Mockingbird function accepts a single parameter: an object expression yielding the instance to be tested.
Expression usage
Assume $cities is an array. The expression:
^isArray($cities)
would return the value @YES.
See Also
Declared In
MBMLCollectionFunctions.h
Counting the items in a collection
+ count:
Returns the count of items in a collection object.
+ (id)count:(id)paramParameters
param |
The function’s input parameter. |
|---|
Return Value
A number containing the count of items in the input parameter.
Discussion
This Mockingbird function accepts a single parameter, an object expression
that’s expected to yield an NSSet, NSArray or NSDictionary instance.
Expression usage
Assume $cities is an array containing the values “New York”, “London”,
and “Boston”. The expression:
^count($cities)
would return the value 3.
Declared In
MBMLCollectionFunctions.h
Modifying collections
+ removeObject:
Creates and returns a new NSArray instance by removing all instances of
one or more objects from an input array.
+ (id)removeObject:(NSArray *)paramsParameters
params |
The function’s input parameters. |
|---|
Return Value
An array containing the items in the input array, with the specified items removed.
Discussion
This Mockingbird function accepts two or more pipe-separated expressions as parameters:
The array expression, which should evaluate to an
NSArrayinstanceOne or more items to be removed, object expressions yielding the item(s) to be removed from the array
Expression usage
Assume $babies is an array containing the values “Juno”, “Theo”,
“Cooper” and “Shiloh”. The expression:
^removeObject($babies|Juno|Shiloh)
would return an array containing the values “Cooper” and “Theo”.
See Also
Declared In
MBMLCollectionFunctions.h
+ removeObjectAtIndex:
Creates and returns a new NSArray instance by removing an object at a
given index from the input array.
+ (id)removeObjectAtIndex:(NSArray *)paramsParameters
params |
The function’s input parameters. |
|---|
Return Value
An array containing the items in the input array, with the specified item removed.
Discussion
This Mockingbird function accepts two pipe-separated expressions as parameters:
The array expression, which should evaluate to an
NSArrayinstanceThe index, a numeric expression that specifies the array index of the object to remove
Expression usage
Assume $cities is an array containing the values “New York”, “London”,
and “Boston”. The expression:
^removeObjectAtIndex($cities|2)
would return an array containing the values “New York” and “London”.
See Also
Declared In
MBMLCollectionFunctions.h
+ appendObject:
Creates and returns a new NSArray by adding one or more items to the end of
an input array.
+ (id)appendObject:(NSArray *)paramsParameters
params |
The function’s input parameters. |
|---|
Return Value
An array containing the items in the input array, with the specified item(s) appended.
Discussion
This Mockingbird function accepts two or more pipe-separated expressions as parameters:
The array expression, which should evaluate to an
NSArrayinstanceOne or more items to be added, object expressions yielding the item(s) to be appended to the array
Expression usage
Assume $cities is an array containing the values “New York”, “London”,
and “Boston”. The expression:
^appendObject($cities|Chicago|Las Vegas)
would return an array containing the values “New York”, “London”,
“Boston”, “Chicago” and “Las Vegas”.
See Also
Declared In
MBMLCollectionFunctions.h
+ insertObjectAtIndex:
Creates and returns a new NSArray instance by inserting an item into an
input array.
+ (id)insertObjectAtIndex:(NSArray *)paramsParameters
params |
The function’s input parameters. |
|---|
Return Value
An array containing the items in the input array, with the specified item inserted at the given index.
Discussion
This Mockingbird function accepts three pipe-separated expressions as parameters:
The array, an object expression expected to yield an
NSArrayinstanceThe insert item, an expression that yields the object to be inserted into the array
The index expression, which should evaluate to a numeric value specifying the array index into which the object should be inserted
Expression usage
Assume $cities is an array containing the values “New York”, “London”,
and “Boston”. The expression:
^insertObjectAtIndex($cities|Chicago|1)
would return an array containing the values “New York”, “Chicago”,
“London”, and “Boston”.
Warning: An error will be logged to the console if the index is out-of-range for the given array.
See Also
Declared In
MBMLCollectionFunctions.h
Creating collections
+ array:
Returns an NSArray containing the result of evaluating each input parameter
as an object expression.
+ (id)array:(NSArray *)paramsParameters
params |
The function’s input parameters. |
|---|
Return Value
An array containing the value of each input parameter expression.
Discussion
This Mockingbird function accepts zero or more pipe-separated expressions as parameters. If zero parameters are provided, an empty array is returned.
Expression usage
The expression:
^array(One|2|III)
would return an NSArray containing the strings “One”, “2”, and “III”.
See Also
Declared In
MBMLCollectionFunctions.h
+ subarray:
Returns an NSArray containing the receiving array’s elements that fall
within the limits specified by a given range.
+ (id)subarray:(NSArray *)paramsParameters
params |
The function’s input parameters. |
|---|
Return Value
An array containing the receiving array’s elements that fall within the limits specified by range.
Discussion
This Mockingbird function accepts three pipe-separated expressions as parameters:
The array expression, which should evaluate to an
NSArrayinstanceThe start location in the provided array, which used for range location within the receiving array’s range of elements.
The length for subarray, which used for range length within the receiving array’s range of elements.
Expression usage
Assume $cities is an array containing the values “New York”, “London”,
and “Boston”. The expression:
^subarray($cities|1|2)
would return an array containing the values “London” and “Boston”.
Declared In
MBMLCollectionFunctions.h
+ set:
Returns an NSSet containing the result of evaluating each input parameter
as an object expression.
+ (id)set:(NSArray *)paramsParameters
params |
The function’s input parameters. |
|---|
Return Value
A set containing the value of each input parameter expression.
Discussion
This Mockingbird function accepts zero or more pipe-separated expressions as parameters. If zero parameters are provided, an empty set is returned.
Expression usage
The expression:
^set(One|2|III)
would return an NSSet containing the strings “One”, “2”, and “III”.
See Also
Declared In
MBMLCollectionFunctions.h
+ setWithArray:
Returns an NSSet containing the same elements as the passed-in array.
+ (id)setWithArray:(id)arrayParameters
array |
The function’s input parameter. |
|---|
Return Value
A set containing the values of the passed-in array.
Discussion
This Mockingbird function accepts as input an object expression that yields
an NSArray instance.
Expression usage
The expression:
^setWithArray(^array(One|2|III))
would return an NSSet containing the strings “One”, “2”, and “III”.
See Also
Declared In
MBMLCollectionFunctions.h
+ dictionary:
Creates a new NSDictionary instance containing the items provided as
keys and values.
+ (id)dictionary:(NSArray *)paramsParameters
params |
The function’s input parameters. |
|---|
Return Value
A dictionary containing the specified key/value pairs.
Discussion
This Mockingbird function accepts zero or more pipe-separated object expressions as parameters:
If zero parameters are provided, an empty dictionary is returned.
If more than zero parameters are provided, the function will expect an even number of parameters representing key/value pairs. The first item in each pair is an expression yielding the dictionary key, and the second item is an expression yielding the corresponding value for that key.
Expression usage
The expression:
^dictionary(firstKey|The first item|secondKey|item 2)
would return an NSDictionary containing two key/value pairs:
- The key “
firstKey” has the value “The first item” - The key “
secondKey” has the value “item 2”
Declared In
MBMLCollectionFunctions.h
+ keys:
Returns an array containing the keys of an NSDictionary.
+ (id)keys:(NSDictionary *)dictParameters
dict |
The function’s input parameter, which is expected to be a dictionary. |
|---|
Return Value
An array containing the passed-in dictionary’s keys.
Discussion
This Mockingbird function accepts a single parameter: an object expression
yielding an NSDictinary instance.
Expression usage
Assume that the expression $namesToAges yields a dictionary containing a
mapping of people’s names (keys) to their ages (values). The expression:
^keys($namesToAges)
would return an array containing the names of each person in $namesToAges.
See Also
Declared In
MBMLCollectionFunctions.h
+ values:
Returns an array containing the values of an NSDictionary.
+ (id)values:(NSDictionary *)dictParameters
dict |
The function’s input parameter, which is expected to be a dictionary. |
|---|
Return Value
An array containing the passed-in dictionary’s values.
Discussion
This Mockingbird function accepts a single parameter: an object expression
yielding an NSDictinary instance.
Expression usage
Assume that the expression $namesToAges yields a dictionary containing a
mapping of people’s names (keys) to their ages (values). The expression:
^values($namesToAges)
would return an array containing the age of each person in $namesToAges.
See Also
Declared In
MBMLCollectionFunctions.h
+ removeLastObject:
Creates and returns a new NSArray instance by removing the last object
from the input array.
+ (id)removeLastObject:(id)arrayParameters
array |
The function’s input parameter, which is expected to be an array. |
|---|
Return Value
A copy of the input array, with the last item removed.
Discussion
This Mockingbird function accepts a single parameter: an object expression
yielding an NSArray instance.
Expression usage
Assume that the object expression $colors yields an array containing the
values “red”, “yellow”, “green”, and “blue” in that order.
The expression:
^removeLastObject($colors)
would return an array containing the values “red”, “yellow” and “green”.
See Also
Declared In
MBMLCollectionFunctions.h
+ lastObject:
Returns the last object in an array.
+ (id)lastObject:(id)arrayParameters
array |
The function’s input parameter, which is expected to be an array. |
|---|
Return Value
The last item in the input array.
Discussion
This Mockingbird function accepts a single parameter: an object expression
yielding an NSArray instance.
Expression usage
Assume that the object expression $colors yields an array containing the
values “red”, “yellow”, “green”, and “blue” in that order.
The expression:
^lastObject($colors)
would return the string “blue”.
Declared In
MBMLCollectionFunctions.h
+ indexOf:
Returns the index of a specified value within an array, or -1 if the
value is not found.
+ (id)indexOf:(NSArray *)paramsParameters
params |
an array containing the input parameters for the function |
|---|
Return Value
A number indicating the zero-based index of the value in the array.
If the value does not exist in the array, -1 is returned.
Discussion
This Mockingbird function accepts two pipe-separated object expressions as parameters:
The array, expected to yield an
NSArrayinstanceThe value, the object whose array index is sought
Expression usage
Assume that the expression $colors yields an array containing the
values “red”, “yellow”, “green”, and “blue” in that order.
The expression:
^indexOf($colors|yellow)
would return the number 1 indicating that the value “yellow” exists
in $colors at array index 1.
Declared In
MBMLCollectionFunctions.h
+ copyOf:
Returns a copy of an object adopting the NSCopying protocol.
+ (id)copyOf:(id)paramParameters
param |
The function’s input parameter. |
|---|
Return Value
A copy of the object yielded by the input expression.
Discussion
If the input object is mutable and is subsequently modified, the copy would be unaffected.
This Mockingbird function accepts a single parameter: an expression yielding the object instance to be copied.
Expression usage
Note: This function is exposed to the Mockingbird environment with a name that differs from that of its implementing method:
^copy($array)
Assuming $array yields an NSArray, the expression above would return a
new NSArray containing the same items as $array.
See Also
Declared In
MBMLCollectionFunctions.h
+ mutableCopyOf:
Returns a mutable copy of an object adopting the NSMutableCopying protocol.
+ (id)mutableCopyOf:(id)paramParameters
param |
The function’s input parameter. |
|---|
Return Value
A mutable copy of the object yielded by the input expression.
Discussion
If the input object is mutable and is subsequently modified, the copy would be unaffected. Similarly, if the copy is modified, the input object would be unaffected.
This Mockingbird function accepts a single parameter: an expression yielding the object instance to be copied.
Expression usage
Note: This function is exposed to the Mockingbird environment with a name that differs from that of its implementing method:
^mutableCopy($array)
Assuming $array yields an NSArray, the expression above would return a
new NSMutableArray containing the same items as $array.
See Also
Declared In
MBMLCollectionFunctions.h
+ getValueForKey:
Uses key-value coding (KVC) to retrieve the value for a given key from a target object.
+ (id)getValueForKey:(NSArray *)paramsParameters
params |
The function’s input parameters. |
|---|
Return Value
The value for the given key. If the key does not have an associated
value, the default value (if it was provided) or nil (if no
default was provided) is returned.
Discussion
This Mockingbird function accepts two or three pipe-separated expressions as parameters:
The target, an object expression yielding the object whose key will be queried
The key, a string expression
An optional default value, an object expression whose result will be returned if target does not possess a value for key
Expression usage
Note: This function is exposed to the Mockingbird environment with a name that differs from that of its implementing method:
^valueForKey($dictionaryOfImages|$myImageKey|default.png)
Assuming that the expression $dictionaryOfImages yields a dictionary, the
expression above would return the value for the key identified by the string
expression $myImageKey in the dictionary $dictionaryOfImages.
If $dictionaryOfImages contains no value for the key identified by
$myImageKey, the value of “default.png” will be returned.
Declared In
MBMLCollectionFunctions.h