.. _list-functions: List Functions -------------- .. _19.2.1|EKB-2752: .. _19.3.4|EKB-6920: .. index:: Macro function;fn.group_by_larger_than_count * *fn.group_by_larger_than_count*: Returns either a list of instance names or dictionary instance names with count values, given parameters: * model type * model attribute * *greater* than an input numeric value of the attribute * specified search direction in hierarchy: *up* or *down* .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | | | | Context hierarchy: ``sys``, list of more than 1 of | :: | | ``iso_country_code`` in ``data/Countries``, search ``down`` | | | | | | * display as dictionary: | [ | | | { | | :: | "iso_country_code": "AUS", | | | "count": 2 | | {{ fn.group_by_larger_than_count data/Countries, | }, | | iso_country_code, | { | | down,1,dict }} | "iso_country_code": "CHN", | | | "count": 2 | | | } | | | ] | | | | | | | | | | | * display as list: | [ | | | "AUS", | | :: | "CHN" | | | ] | | {{ fn.group_by_larger_than_count data/Countries, | | | iso_country_code, | | | down,1,list }} | | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.is_list * *fn.is_list*: Return true or false if the parameter is a list or not. .. index:: Macro function;fn.list_index * *fn.list_index*: Return a specified item from a list. Zero is the first item. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | | | | | | {{fn.list_index 2,data.Countries.country_name}} | | | | "Canada" if this is the | | | third item. | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_index_item * *fn.list_index_item*: Return the position of item in list. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MACRO1={# fn.sequence 40,43 #} | | | | | | {{ fn.list_index_item 42,macro.MACRO1 }} | 2 | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_count * *fn.list_count*: Return the number of items in a list. Note that if the list is *known* and empty, the count is 0, but if the list is *not known*, then the count is 1, because the returned message string count is 1. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | {{fn.list_count data.Countries}} | 25 if the | | | list has | | | 25 items. | | | | | {{fn.list_count input.does_not_exist}} | 0 | | | | | {{fn.list_count non_existant_namespace.does_not_exist}} | 1 | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_count_item * *fn.list_count_item*: Return the number of times item is in a list. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MACRO1={# data.Countries.international_access _prefix #} | | | | | | | | | {{ fn.list_index_item 00,macro.MACRO1 }} | 19 | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_in * *fn.list_in*: Return true or false if item is in a list or not. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | {{fn.list_in 'AUS',data.Countries.iso_country_code}} | true | | | | | | | | {{fn.list_in 'AUZ',data.Countries.iso_country_code}} | false | | | | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_contain * *fn.list_contain*: Return true or false if item is a substring of an input context *or* is in a list or not. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | | | | | | | | | { | | | "input": { | | | "list": [ | | | "AUS", | | | "BHR" | | | ], | | | "key": "aaAUZa" | | | | | | } | | | } | | | | | | | | | :: | :: | | | | | {{fn.list_contain 'AUS',input.list }} | true | | | | | | | | {{fn.list_contain 'AUZ',input.key }} | true | | | | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_append * *fn.list_append*: Returns a list with item appended. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MACRO1={# fn.sequence 40,43 #} | | | | | | {{fn.list_append 999,macro.MACRO1 }} | ['40', '41', | | | '42', '43', | | | '999'] | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_pop * *fn.list_pop*: Return the last item of the list. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MACRO1={# fn.sequence 40,43 #} | | | | | | {{fn.list_pop macro.MACRO1}} | "43" | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_insert * *fn.list_insert*: Return a list with item inserted at position. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MACRO1={# fn.sequence 40,43 #} | | | | | | {{fn.list_insert 1,999,macro.MACRO1 }} | ['40', '999', | | | '41', '42', | | | '43'] | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_insert_no_dup * *fn.list_insert_no_dup*: Return a list with item inserted at position and all duplicates ignored. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MACRO1={# fn.sequence 40,43 #} | | | | | | MACRO7={# fn.sequence 39,41 #} | | | | | | {{fn.list_insert_no_dup macro.MACRO1,macro.MACRO7}} | ['40','41', | | | '42','43', | | | '39'] | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_remove * *fn.list_remove*: Return a list with all instances of item or list of items removed. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MAC1={# fn.sequence 40,43 #} | | | MAC7={# fn.sequence 40,41 #} | | | MAC3={{fn.list_insert 1,43,macro.MAC1 }} | | | | | | | | | {{fn.list_remove 43,macro.MAC3 }} | ['40','41', | | | '42'] | | | | | {{fn.list_remove macro.MAC7,macro.MAC1 }} | ['42','43'] | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_remove_dup_dict * *fn.list_remove_dup_dict*: Given a list of dictionaries, a sort key and an optional sort direction, return a list with the duplicate entries removed, sorted by the specified sort direction or if not specified, sorted in ascending order. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | { | | | "input": { | | | "dupl": | {"dupl": | | [ | [ | | { | { | | "country_name": "Canada", | "country_name": "Canada", | | "iso_country_code": "CAN" | "iso_country_code": "CAN" | | }, | }, | | { | { | | "country_name": "China", | "country_name": "China", | | "iso_country_code": "CHN" | "iso_country_code": "CHN" | | }, | }, | | { | { | | "country_name": "China", | "country_name": "Switzerland", | | "iso_country_code": "CHN" | "iso_country_code": "CHE" | | }, | } | | { | ] | | "country_name": "Switzerland", | } | | "iso_country_code": "CHE" | | | } | | | ] | | | } | | | } | | | | | | | | | {{ fn.list_remove_dup_dict input.dupl, | | | country_name }} | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_remove_dup * *fn.list_remove_dup*: Return a list with all instances of item or list of items removed, including duplicates. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | Given the following list is the result of | :: | | the regex for iso_country_code: | | | :: | | | | | | {# data.Countries.iso_country_code | | ['AUS','SAU', | | iso_country_code:/AU/ #} | 'AUS','AUS'] | | | | | | :: | | | | | {# fn.list_remove_dup data.Countries.iso_country_code | | ['AUS','SAU'] | | iso_country_code:/AU/ #} | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_remove_nulls * *fn.list_remove_nulls*: Return a list with all ``null`` instances in a list of items removed. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | {"pwf": { | | | "my_list": [1, null, 2,"test", 3, null] | | | } | | | } | | | | | | | | | {{ fn.list_remove_nulls pwf.my_list }} | [1,2,"test",3] | | | | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_reverse * *fn.list_reverse*: Return a list that is the reverse of a given list. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MACRO1={# fn.sequence 40,43 #} | | | | | | {{fn.list_reverse macro.MACRO1}} | ['43','42', | | | '41','40'] | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_extend * *fn.list_extend*: Return a list that is an extension of list 1 with list 2. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MACRO1={# fn.sequence 40,43 #} | | | | | | MACRO9={# fn.sequence 50,52 #} | | | | | | {{fn.list_extend macro.MACRO1,macro.MACRO9 }} | ['40', '41', | | | '42', '43', | | | '50', '51', | | | '52'] | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_extend_no_dup * *fn.list_extend_no_dup*: Return the concatenation of list1 and list2, ignoring duplicates. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MACRO1={# fn.sequence 40,43 #} | | | | | | MACRO8={# fn.sequence 42,45 #} | | | | | | {{fn.list_extend_no_dup macro.MACRO1,macro.MACRO8 }} | ['40','41', | | | '42','43', | | | '44','45'] | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.sequence * *fn.sequence*: Return a sequence of numbers running from the first value to the second value, optionally padded with zeroes to be the length of a third value. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | {# fn.sequence 40,43 #} | ['40','41', | | | '42','43'] | | | | | {# fn.sequence 110,100,4 #} | ['0110','0109', | | | '0108', | | | '0107','0106', | | | '0105','0104', | | | '0103','0102', | | | '0101','0100'] | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_set_symdiff * *fn.list_set_symdiff*: Given two lists as input, return the list of items that are *not* common to both lists. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MACRO1={# fn.sequence 40,43 #} | ['40','44','45'] | | MACRO2={# fn.sequence 41,45 #} | | | | | | {{ fn.list_set_symdiff macro.MACRO1,macro.MACRO2 }} | | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_sort * *fn.list_sort*: Return a sorted list; by ascending (A) or descending (D) order. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MACRO1={# fn.sequence 40,43 #} | | | | | | {{fn.list_sort macro.MACRO1,D}} | ['43','42', | | | '41','40'] | | | | | {{fn.list_sort macro.MACRO1,Descending}} | ['43','42', | | | '41','40'] | | | | | MACRO5={# fn.sequence 110,108,4 #} | ['0110','0109', | | | '0108'] | | | | | {{fn.list_sort macro.MACRO5,A}} | ['0108','0109', | | | '0110'] | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.one * *fn.one*: Return a single result from a list. This is used to convert a single element list to a string. If fn.one is called with a string, it returns the string unchanged. The string can be a macro that might get the value of another attribute from a context, such as ``input.some_variable``. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | A single result, e.g. 'DEU' | | | :: | | {{fn.one data.Countries.iso_country_code | | | | emergency_access_prefix:'112'}} | | | | | | | | | {{fn.one abc}} | 'abc' | | | | | | | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.as_list * *fn.as_list*: Return a string result as a list. If fn.as_list is called with a string, it returns a list. Again, abc could be a macro that resolves to the value of an attribute in its context. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | {{fn.as_list data.Countries.country_name | country_name:'China'}} | ['China'] | | | | | {{fn.as_list abc}} | ['abc'] | | | | | | | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_empty * *fn.list_empty*: Returns an empty list .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | {{fn.list_empty}} | [] | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_set_intersect * *fn.list_set_intersect*: Given two lists, return the intersection as a list. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MACRO1={# fn.sequence 40,43 #} | | | MACRO2={# fn.sequence 41,42 #} | | | | | | {# fn.list_set_intersect macro.MACRO1,macro.MACRO2 #} | ['41','42'] | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_set_union * *fn.list_set_union*: Given two lists, return the union as a list. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MACRO1={# fn.sequence 40,43 #} | | | MACRO2={# fn.sequence 41,45 #} | | | | | | {# fn.list_set_union macro.MACRO1,macro.MACRO2 #} | ['40','41', | | | '42','43', | | | '44','45'] | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_set_left * *fn.list_set_left*: Given two lists, return a list of items in the left list only. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MACRO1={# fn.sequence 40,43 #} | | | MACRO2={# fn.sequence 41,45 #} | | | | | | {# fn.list_set_left macro.MACRO1,macro.MACRO2 #} | ['40'] | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_set_right * *fn.list_set_right*: Given two lists, return a list of items in the right list only. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | MACRO1={# fn.sequence 40,43 #} | ['44','45'] | | MACRO2={# fn.sequence 41,45 #} | | | | | | {# fn.list_set_right macro.MACRO1,macro.MACRO2 #} | | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_filter_fields * *fn.list_filter_fields*: Given a model name, two field names, hierarchy PKID and a list of field values from one of the fields, return the list of values from the other field. The hierarchy PKID parameter must be passed in as a PKID of the hierarchy node. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | | [ | | { | "Australia", | | "input": { | "Bharain" | | "list": [ | ] | | "AUS", | | | "BHR" | | | ] | | | } | | | } | | | | | | | | | {# fn.list_filter_fields data/Countries, | | | 8c0hfle2c0deab00da595101,iso_country_code, | | | country_name,input.list #} | | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.flatten_list_of_lists * *fn.flatten_list_of_lists*: Given a list of lists, return a single, flattened list. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | | [ | | | "AAA", | | { | "BBBB", | | "input": { | "CCCC", | | "args": [ | "DD" | | [ | ] | | "AAA" | | | ], | | | [ | | | "BBBB", | | | "CCCC" | | | ], | | | [ | | | "DD" | | | ] | | | ] | | | } | | | } | | | | | | {# fn.flatten_list_of_lists input.args #} | | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.flatten_nested_lists * *fn.flatten_nested_lists*: Given a list of scalars and lists (which could have different levels of nesting), return a single, flattened list. .. tabularcolumns:: |p{13cm}|p{3cm}| +---------------------------------------------+------------------+ | Example | Output | +=============================================+==================+ | :: | :: | | | | | | [ | | | "77174011", | | { | "77174021", | | "input": { | "77174080", | | "args": [ | "55555", | | "77174011", | "1", | | [ | "12345" | | "77174021", | ] | | "77174080", | | | [ | | | "55555", | | | "1", | | | ] | | | ], | | | "12345" | | | ] | | | } | | | } | | | | | | {{ fn.flatten_nested_lists input.args }} | | | | | +---------------------------------------------+------------------+ .. index:: Macro function;fn.modulo_list * *fn.modulo_list*: Given a list and divisor, return a modulo list: list items that leave no remainder after divided. The input list is typically a directory number list and the divisor is an E164 range. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | | [ | | | "12000", | | { | "13000" | | "input": { | ] | | "args": [ | | | [ | | | "100", | | | "12000", | | | "13000", | | | ] | | | } | | | } | | | | | | {{ fn.modulo_list input.args,1000 }} | | | | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.get_tvpair_list * *fn.get_tvpair_list*: Given an input list of dictionaries containing repeated pairs of equal type and a title-value mapping of these pairs, return a list of objects of these pairs where the pairs are mapped to ``title`` and ``value`` pairs that can for example be shown in a GUI rule in a choices drop-down list on a GUI form. .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------------------------------------+------------------------------------------------------------------------+ | Example | Output | +======================================================================+========================================================================+ | :: | :: | | | | | { | [ | | "input": { | { | | "dataList" = [ | "value": "10", | | { | "title": "Africa | | "timeZoneCode": "10", | /Bissau" | | "timeZoneName": "Africa/Bissau" | }, | | }, | { | | { | "value": "100", | | "timeZoneCode": "100", | "title": "America | | "timeZoneName": "America/Noronha" | /Noronha" | | }, | }, | | ... | ... | | ... | ... | | ] | ] | | } | | | } | | | | | | {{ fn.get_tvpair_list input.dataList, | | | title:timeZoneName,value:timeZoneCode }} | | +----------------------------------------------------------------------+------------------------------------------------------------------------+ .. index:: Macro function;fn.list_batch * *fn.list_batch*: Given a batch size and list as parameters, return the list as a batch of lists - each with size `batchsize`. If list cannot divide into ``batchsize``, then the last list item is the remainder. The function is useful when processing large lists, which can then first be split into smaller batches. Example input: :: { "input": { "list": [ "foo", "bar", "baz", "qux", "quux" ] } } .. tabularcolumns:: |p{13cm}|p{3cm}| +----------------------------------------+------------------------+ | Example | Output | +========================================+========================+ | ``input.list`` as above (5-item list): | batch of 2-item lists: | | | | | :: | :: | | | | | {{ fn.list_batch 2,input.list }} | | | | [ | | | [ | | | "foo", | | | "bar" | | | ], | | | [ | | | "baz", | | | "qux" | | | ], | | | [ | | | "quux" | | | ] | | | ] | | | | +----------------------------------------+------------------------+ .. |VOSS Automate| replace:: VOSS Automate .. |Unified CM| replace:: Unified CM