NB5 Docs► Reference Section► Binding Functions▼ collection functions 🖺

Collection functions allow you to construct Java Lists, Maps or Sets. These functions often take the form of a higher-order function, where the inner function definitions are called to determine the size of the collection, the individual values to be added, etc.

For each type of collection, there exists multiple forms which allow you to control how the provided function arguments are used to set the values into the collection.

Sized or Pair-wise functions

Any function in this category with Sized occuring in its name must be initialized with a sizing function as an argument. For example, ListSized(Mod(5),NumberNameToString()) will create a list which is sized by the first function -- a list between 0 and 4 elements in this case. With an input value of 3L, the resulting List will contain 3 elements. With an input of 7L, it will contain 2 elements.

Alternately, when a function does not contain Sized in its name, the arguments provided are used as pair-wise mapping functions to the elements in the resulting collection.

Simply put, a Sized function will always require a sizing function as the first argument.

Stepped or Hashed or Same

Any function in this category which contains Stepped in its name will automatically increment the input value used for each element in the collection. For example ListStepped(NumberNameToString(),NumberNameToString()) will always creat a two-element List, but the inputs to the provided functions will be i+0, i+1, where i is the input value to the ListStepped function.

Alternately, any function in this category which contains Hashed in its name will automatically hash the input value used for each element. This is useful when you want to create values within a collection that vary significantly with respect of their common seed value. For example, ListHashed(NumberNameToString(),NumberNameToString(),NumberNameToString()) will always provide a three element List with values that are not obviously related to each other. For each additional element added to the collection, the previous input is hashed, so there is a relationship, but it will not be obvious nor discernable for most testing purposes.

If neither Stepped nor Hashed occurs in the function name, then every element function gets the exact value given to the main function.

Overview of functions

All of the useful collection binding functions follow the same basic patterns above.

List Functions**

Same InputStepped InputHashed Input
Pair-wiseListFunctions(...)ListStepped(...)ListHashed(...)
SizedListSized(...)ListSizedStepped(...)ListSizedHashed(...)

The name ListFunctions(...) was chosen to avoid clashing with the existing List(...) function.

Set Functions

The values produced by the provided element functions for Sets do not check for duplicate values. This means that you must ensure that your element functions yield distinct values to insert into the collection as it is being built if you want to have a particular cardinality of values in your collection. Overwrites are allowed, although they may not be intended in most cases.

Same InputStepped InputHashed Input
Pair-wiseSetFunctions(...)SetStepped(...)SetHashed(...)
SizedSetSized(...)SetSizedStepped(...)SetSizedHashed(...)

The name SetFunctions(...) was chosen to avoid clashing with the existing Set(...) function.

Map Functions

The values produced by the provided element functions for Maps do not check for duplicate values. This means that you must ensure that your element functions yield distinct keys to insert into the collection as it is being built if you want to have a particular cardinality of values in your collection. Overwrites are allowed, although they may not be intended in most cases.

Same InputStepped InputHashed Input
Pair-wiseMapFunctions(...)MapStepped(...)MapHashed(...)
SizedMapSized(...)MapSizedStepped(...)MapSizedHashed(...)

The name MapFunctions(...) was chosen to avoid clashing with the existing Map(...) function.

For the key and value functions provided to a Map function, they are taken as even-odd pairs (starting at zero). For sized functions, the last defined key function will be used for elements past the size of the key functions provided. The same is true for the value functions. For example, a call to MapSized(3,f(...),g(...),h(...)) will use f(...) and g(...) for the first key and value, but from that point forward will use h(...) for all keys and g(...) for all values.

HashedLineToStringList

Creates a List<String> from a list of words in a file.

HashedLineToStringSet

Return a pseudo-randomly created Set from the values in the specified file.

HashedLineToStringStringMap

Create a String-String map from the specified file, ranging in size from 0 to the specified maximum.

HashedRangeToLongList

Create a list of longs.

Join

This takes any collection and concatenates the String representation with a specified delimiter.

List

Create a {@code List} from a long input based on two functions, the first to determine the list size, and the second to populate the list with object values. The input fed to the second function is incremented between elements.

To directly create Lists of Strings from the String version of the same mapping functions, simply use {@link StringList} instead.

This function is not recommended, given that the other List functions are more clear about how they construct values. This function may be removed in the next major release, but it will be retained as deprecated for now.