Extension:Arrays/Pre 2.0 Documentation

This page contains the documentation for Extension:Arrays (former ArrayExtension) for versions prior to version 2.0 (1.4 alpha to be exact). It also applies in case you are using version 2.0+ with active compatibility mode.

Differences compared to Arrays 2.0

The following breaking behavior changes were introduced with Arrays 2.0 (some already within 1.4 alpha). They are only active in case the compatibilty mode is not active, so they don't apply to the documentation on this page. You should aware of these if you want to upgrade to 2.0 without using compatibility mode.

Introduced in 1.4 alpha:

• #arrayprint no longer returns an error text in case the array doesn't exist, just an empty string.
• #arrayreset now uses n parameters instead of , as separator for n arrays to reset (with compatibility mode, both is supported but not both mixed together in one function call)
• #arrayindex options removed, instead third parameter simply is the default value (without any default= in front).
• #arraysearch returns an empty string instead of '-1' in case nothing was found.
• #arraysearcharray and #arrayslice without all necessary parameters set will always create a new empty array.

Introduced in 2.0

• #arrayindex will return its default also in case of existing index but empty value. This makes the function consistent with Variables #var and HashTables #hashvalue.
• #arrayunion, #arraydiff and #arrayintersect with only one array for the operation will make a copy of that array instead of creating no array at all (just like #arraymerge behaved already).
• Default separator for #arrayprint now is the languages default separator instead of ', '.
• #arrayprint will no longer expand the given wiki markup twice. Instead, it will escape special characters of array values before they will be inserted into the markup. This way it won't be possible anymore that array values can break the functions output. $egArraysExpansionEscapeTemplates defines which special characters should be escaped by which template/parser function.

In addition to these breaking changes, there are several other improvements in Arrays 2.0, see the RELEASE-NOTES for a full list.

Functions

This extension defines the following parser functions:

Group	Functions
Construct an array, (with unique, sort, print options)	#arraydefine
Extract information from an array	#arrayprint, #arrayindex, #arraysize, #arraysearch, #arraysearcharray and #arrayslice
Alter an array	#arrayreset, #arrayunique and #arraysort
Interaction between several arrays	#arraymerge, #arrayunion, #arrayintersect and #arraydiff
In case Extension:HashTables is installed, for array/hash-table interaction	#hashtoarray, #arraytohash

Construction

arraydefine

This function constructs an array (identified by 'key') using a list of 'values' separated by the 'delimiter'. The variable can be accessed by other functions later.

Syntax:

{{#arraydefine:key|values|delimiter|options}}

Notes:

• values is a list of strings separated by delimiter
• The resulting array is an array of strings.
• The default delimiter is ',' if not specified, a delimiter can be (i) a string (the white-spaces surrounding delimiter will be trimmed) or (ii) a perl regular expression (for advanced user only), e.g. '/\s*,\s*/' (see preg_split)
• Users can define an empty array (see example)
• Users can specify options including unique, sort, and print (see example).

Examples:

Define a one-element array named 'a'	{{#arraydefine:a|red}}
Define a four-element array named 'b', use default delimiter (',')	{{#arraydefine:b|orange,red ,yellow, yellow}}
Define/set an empty array named 'c'	{{#arraydefine:c}}
Define a one-element array named 'd', use no delimiter	{{#arraydefine:d|apple, pear}}
Define a one-element array named 'e', using ';' as delimiter	{{#arraydefine:e|apple, pear|;}}
(Advanced user only) define a three-element array named 'f', using '/\s*[;,]\s*/' as delimiter	{{#arraydefine:f|apple, pear; orange|/\s*[;,]\s*/}}
Define a three-element array named 'b1', use delimiter (','), "unique ,sort=desc, print=list" options (the array elements are unique, sorted in descending order and being printed). for more option-values of "sort" see #arraysort	{{#arraydefine:b|orange,red ,yellow, yellow|,|unique,sort=desc, print=list}}

Extracting Information

arrayprint

This function prints the values of an array in customizable format.

Syntax:

{{#arrayprint:key|delimiter|pattern|subject}}

Notes:

• 'subject' accepts wiki links, templates and parser functions.
• Within the 'subject, you don't have to escape pipe characters '|', but you can since the whole will be parsed two times. Within the whole construct, the pattern will be searched an replaced with the current (un-escaped!) array value of each loop. Then the whole string will be parsed and put into an array of results which will be imploded with delimiter as separator. Finally, the whole result will be parsed a second time.
• The second time parsing is due to historical reasons and is removed in Arrays 2.0 (without active compatibility mode)

Examples:

Print - using default delimiter ', '	{{#arrayprint:b}}
Print - without delimiter	{{#arrayprint:b | }}
Print - using '<br/>' (line-break) as delimiter	{{#arrayprint:b |<br/> }}
Embed wiki link	{{#arrayprint:b |<br/> |@@@@ |[[@@@@ |Text]] }}
Define a Semantic MediaWiki property value	{{#arrayprint:b |<br/> |@@@@ |[[prop1::@@@@]] }}
Embed parser function	{{#arrayprint:b |<br/> |@@@@ |length of @@@@:{{#len:@@@@}} }}
Embed template (with parameters)	{{#arrayprint:b|<br/>|@@@@|{{template|prop2|@@@@}} }}

arrayindex

This function print the value of an array (identified by 'key') at position 'index'.

Syntax:

{{#arrayindex:key|index|options}}

Notes:

• Invalid index (non-number, out of bound) will result in printing an empty string.
• The index is 0-based, i.e. the first element's index is 0.
• Users can specify options on default value.

Examples:

Array index test	{{#arrayindex:b|2}}
Print default value for invalid index	{{#arrayindex:b|-2|default=bad value}}

arraysize

This function returns the size (number of elements) of an array. See: http://www.php.net/manual/en/function.count.php

In case the given array doesn't exist the output of the function will be a void string instead of a number. This allows to check whether the array exists.

Syntax:

{{#arraysize:key}}

Examples:

Size of array a:	{{#arraysize:a}}
Check whether array a exists or not:	{{#if: {{#arraysize:b}} | ''array exists'' | ''array not defined'' }}

arraysearch

This function returns the index of the first occurrence of the 'value' in the array (identified by 'key') starting from the position identified by 'index' parameter, and returns '-1' when failed. when 'yes' and 'no' specified, print value of yes if found, and value of no otherwise. See: http://www.php.net/manual/en/function.array-search.php

Syntax:

{{#arraysearch:key|value|index|yes|no}}

Examples:

Return index of first occurrence of a value	{{#arraysearch:b|white}} {{#arraysearch:b|red}}
Return index of first occurrence of a value	{{#arraysearch:b|white}} {{#arraysearch:b|red}} use offset {{#arraysearch:b|red|0}} {{#arraysearch:b|red|2}} use preg regular expression match {{#arraysearch:b|/low/}} {{#arraysearch:b|/LOW/i}} - case insensitive {{#arraysearch:b|low}} use yes no print option {{#arraysearch:b|white|0|yes|no}} {{#arraysearch:b|yellow|0|yes|no}}

arraysearcharray

This function searches an array (identified by key) and creates a new array (identified by new_key) from the search with all the results. The search criteria value can be a string or a regular expression. If index is given the search will start there, limit can define the maximum search results. The parameter identified by transform can be used if value is a regular expression. It can transform the result of the matched entries into the new_key array like PHP preg_replace would do it.

Syntax:

{{#arraysearcharray:new_key|key|value|index|limit|transform}}

Notes:

• If value is a string the new_key array will only contain entries of exact this string.
• Negative index values like -n can be used to search the last n entries only.

Examples:

Find all entries in array 'a' that start with A followed by a space and put them into a new array 'x'	{{#arraysearcharray:a |x |/^A\s.+/ }}
searching all entries of array 'a' which end with numbers and put the numbers only into a new array 'y'	{{#arraysearcharray:a |y |/^.*?(\d+)$/ |0 |-1 | $1 }}

arrayslice

This function extracts a sub-array from an array (identified by 'key') into a new array (identified by 'new_key'). See: http://www.php.net/manual/en/function.array-slice.php

Syntax:

{{#arrayslice:new_key|key|offset|length}}

Notes:

• Offset indicates starting point of slice, it can be (i) non-negative number (ii) negative number for backwards index (e.g. the last element of the array's offset is -1). offset is different from index (which must be non-negative number)
• Length indicates how many element to extract. If it is omitted, then the sequence will have everything from offset up until the end of the array.
• If offset is no less than array size, empty array will be returned, if offset if no greater than negative array size, a new array with all elements will be returned

Examples:

Extract a two-element slice starting from the element at offset 1	{{#arrayslice:x|b|1|2}}
Extract a two-element slice starting from the element at offset -2	{{#arraymerge:x|b|-2|2}}

Alteration

Functions which alter an array directly instead of creating a new array.

arrayunique

This function converts an array (identified by 'key') into a set (no duplicated members, no empty element). see: http://www.php.net/manual/en/function.array-unique.php

Syntax:

{{#arrayunique:key}}

Example:

convert array to set

{{#arrayunique:b}}

arrayreset

This function free-up some or all defined arrays.

Syntax:

{{#arrayreset:}}
{{#arrayreset:key1,key2,...keyn}}

arraysort

This function sorts an array in the following order.

• none (default) - no sort
• desc - in descending order (see: http://www.php.net/manual/en/function.sort.php)
• asce/asc - in ascending order (see: http://www.php.net/manual/en/function.rsort.php)
• random - in random order (see: http://www.php.net/manual/en/function.array-rand.php)
• reverse - in reverse order (see: http://www.php.net/manual/en/function.array-reverse.php)

Syntax:

{{#arraysort:key|order}}

Note:

• Each array element is being treated as a string, this means numbers might not be ordered as expected.

Examples:

Sort an array	{{#arraysort:x|desc}}
Randomize an array	{{#arraysort:x|random}}
Reverse an array	{{#arraysort:x|reverse}}

Interaction Between Arrays

Functions which work with more than one array, creating one new array or overwriting an existing one as result.

arraymerge

This function merges values of two arrayes (identified by 'key1' and 'key2') into a new array (identified by 'new_key'). See: http://www.php.net/manual/en/function.array-merge.php Note: a wrong parameter will terminate this operation, and the array identified by 'new_key' will not be affected.

Syntax:

{{#arraymerge:new_key|key1|key2}}

Note:

• This merge is different from array_merge offered by PHP because it merges values instead of keys

Examples:

Merge two arrays	{{#arraymerge:x|a|b}}
Duplicate an array (keep the third argument of arraymerge empty	{{#arraymerge:x|b}}

arrayunion

This function merges values of two arrayes (identified by 'key1' and 'key2') into a new array (identified by 'new_key') without duplicated values.

Syntax:

{{#arrayunion:new_key|key1|key2}}

Notes:

• This is a set operator, i.e., the returned array is a set without duplicated values.
• Similar to arraymerge, this union operation works on values.

Example:

Union of two arrays

{{#arrayunion:x|a|b}}

arraydiff

This function computes the (set theoretic) difference of two given arrays (identified by 'key1' and 'key2'), and the result array is identified by 'new_key'. The returned array (identified by 'key') is a set that contains elements in an array (identified by 'key1') but not in the other array (identified by 'key2'). See: http://www.php.net/manual/en/function.array-diff.php

Syntax:

{{#arraydiff:new_key|key1|key2}}

Note:

• This is a set operator, i.e. the returned array is a set without duplicated values.
• This function can be used to test sub-class relation

Examples:

Diff (b-a)	{{#arraydiff:x|b|a}}
Diff (a-b)	{{#arraydiff:x|a|b}}

arrayintersect

This function computes the set theoretic intersection of two given arrays (identified by 'key1' and 'key2'), and the result array is identified by 'new_key'. See: http://www.php.net/manual/en/function.array-intersect.php

Syntax:

{{#arrayintersect:new_key|key1|key2}}

Note:

• This is a set operator, i.e., the returned array is a set without duplicated values.

Example:

Intersect

{{#arrayintersect:x|a|b}}

FAQ

Iteratively accessing array elements

It is possible to iteratively access elements of an array using #arrayprint or Extension:Loops.

Using arrayprint

<!--define an array-->
{{#arraydefine:colors|Red,Blue,Yellow}}

{{#arrayprint:colors||@@@@|<nowiki/>
* length of @@@@: {{#len:@@@@}}
}}

below is the expected output:

length of Red: 3 length of Blue: 4 length of Yellow: 6

for live examples, follow this URL.

Using Loops extension

For more complex tasks it is possible to loop through an array using the Loops extension.

{{#arraydefine: colors | red;#FF0000, green;#00FF00, blue;#0000FF }}
{{
  #loop: i
  | 0
  | {{#expr:{{#arraysize:colors}} }}
  | <nowiki/>
* {{
    #arraydefine: val | {{#arrayindex:colors | {{#var:i}} }} | ;

    }}<span style="color:{{#arrayindex: val | 1}}">{{
    #arrayindex: val | 0
    }}</span>
}}

This would output something like:

• red
• green
• blue

Working with Extension:SemanticMediaWiki

There are two ways populating an array with semantic data. The first solution, using Semantic Result Formats is faster and more reliable, also works with complex data sets including record data and multiple values for one property.

Using Extension:Semantic Result Formats

Semantic Result Formats (SRF) introduces the Array format in version 1.6.1. It can be used to query data which will automatically be stored within an ArryExtension array. This is the preferred solution dealing with semantic data in arrays. Details can be found on the semantic-mediawiki.org.

Example:

{{#ask: [[Category:Color]][[:+]] |format=array |name=colors}}
{{#arrayprint: colors}}

Using a standard query

If you can't use the SRF solution above, Arrays also allows to populate an array using a SMW query result of the list format:

Example A: to create a list of instances of the class 'Color'

{{#arraydefine:colors|{{#ask:[[Category:Color]][[:+]] |sep =, |limit=1000}} }}

Example B: To create a unique list of values of property 'has color'

{{#arraydefine:colors|{{#ask:[[has color::+]][[:+]] |?color= |mainlabel=- |sep =, |limit=1000}} |,|unique}}

Example C: to deal with 2D array generated by SWM query (e.g. record-type property)

given a 2D array "red;#da2021, yellow;#fcff00, green;#00ff00"

1. create an array 'colors'
{{#arraydefine:colors|red;#da2021, yellow;#fcff00, green;#00ff00}}

2. split the first element of 'colors' into another array 'colors0'
{{#arraydefine:color0|{{#arrayindex:colors|0}}|;}}

Note(s)

• semantic query parameters
  • limit=1000 option is used to exhaust all returned results of the semantic query
  • sep=, option is used to set the separator for entries of the results
  • mainlabel=- option cut of the page column

Working with Extension:DynamicPageList

In a similar way as described above for SMW the Arrays extension can be used to store results of a DPL query.

In the Example we show how a result list can be "inverted". We collect all parameter values which are used by certain pages when they include a given template. We store pairs of template parameter value and pagename. Then we sort the array and print the pairs. If consecutive array elements have the same first part (i.e. the parameter values are identical), the first part is only printed once. Thus we can construct a simple "inverted index". The same mechanism could be applied to other problems as well.

Working with Extension:SemanticQueryFormTool

Arrays allows users to populate an array using a SemanticQueryFormTool query result.

to create a list of instances of the class 'Color'

{{#arraydefine: colors|{{#sask: ?Color | format=list | lastsep=}} }}

to deal with 2D array generated by SWM query (e.g. n-ary property)

given a 2D array "red;#da2021, yellow;#fcff00, green;#00ff00"

1. create an array 'colornames'
{{#arraydefine: colornames|{{#sask: ?Color | nary=1 | format=list | lastsep=}} }}

2. create an array 'colorcodes'
{{#arraydefine: colorcodes|{{#sask: ?Color | nary=2 | format=list | lastsep=}} }}

this can be combined with filtering

3. create an array 'none_red_colornames' but leave out any color containing 'red'
{{#arraydefine: none_red_colornames|{{#sask: ?Color | nary=1 | format=list | lastsep= | filter=!strpos:::red}} }}

source: thanks for [email protected]