Previous section To contents

11.2 Array

As with String these functions are mostly Pike functions written to supplement those written in C.

FUNCTION
Array.diff - gives the difference of two arrays

SYNTAX
array(array(array)) diff(array a, array b);

DESCRIPTION
Calculates which parts of the arrays that are common to both, and which parts that are not. Returns an array with two elements, the first is an array of parts in array a, and the second is an array of parts in array b.

EXAMPLE 
> Array.diff("Hello world!"/"","Help!"/"");
Result: ({ /* 2 elements */
    ({ /* 3 elements */
        ({ /* 3 elements */
            "H",
            "e",
            "l"
        }),
        ({ /* 8 elements */
            "l",
            "o",
            " ",
            "w",
            "o",
            "r",
            "l",
            "d"
        }),
        ({ /* 1 elements */
            "!"
        })
    }),
    ({ /* 3 elements */
        ({ /* 3 elements */
            "H",
            "e",
            "l"
        }),
        ({ /* 1 elements */
            "p"
        }),
        ({ /* 1 elements */
            "!"
        })
    })
})

SEE ALSO
Array.diff_compare_table, Array.diff_longest_sequence and String.fuzzymatch

FUNCTION
Array.diff_compare_table - gives the comparison-table used by Array.diff()

SYNTAX
array(array(int)) diff_compare_table(array a, array b);

DESCRIPTION
Returns an array which maps from index in a to corresponding indices in b.

EXAMPLE 
> Array.diff_compare_table("Hello world!"/"","Help!"/"");
Result: ({ /* 12 elements */
    ({ /* 1 elements */
        0
    }),
    ({ /* 1 elements */
        1
    }),
    ({ /* 1 elements */
        2
    }),
    ({ /* 1 elements */
        2
    }),
    ({ }),
    ({ }),
    ({ }),
    ({ }),
    ({ }),
    ({ /* 1 elements */
        2
    }),
    ({ }),
    ({ /* 1 elements */
        4
    })
})

SEE ALSO
Array.diff, Array.diff_longest_sequence and String.fuzzymatch

FUNCTION
Array.diff_longest_sequence - gives the longest common sequence of two arrays

SYNTAX
array(int) diff_longest_sequence(array a, array b);

DESCRIPTION
Gives the longest sequence of indices in b that have corresponding values in the same order in a.

EXAMPLE 
> Array.diff_longest_sequence("Hello world!"/"","Help!"/"");
Result: ({ /* 4 elements */
    0,
    1,
    2,
    4
})

SEE ALSO
Array.diff, Array.diff_compare_table and String.fuzzymatch

FUNCTION
Array.everynth - return every n:th element of an array

SYNTAX
array(mixed) Array.everynth(array(mixed) arr1, void|int nth, void|int start);

DESCRIPTION
This function returns an array with every n:th element of an other array. If nth is zero, every second element is returned.

EXAMPLE
> Array.everynth(({"1","2","3","4","5","6"}),2,1);
Result: ({ /* 3 elements */
    "2",
    "4",
    "6"
})

SEE ALSO
Array.splice and `/

FUNCTION
Array.filter - filter an array or mapping through a function

SYNTAX
array filter(array arr,function fun,mixed ... args);
array filter(array(object) arr,string fun,mixed ... args);
array filter(array(function) arr,-1,mixed ... args);

DESCRIPTION
First syntax:
Filter array returns an array holding the items of arr for which fun returns true.

Second syntax:
Filter array calls fun in all the objects in the array arr, and return all objects that returned true.

Third syntax:
Filter array calls all function pointers in the array arr, and return all that returned true.

SEE ALSO
Array.sum_arrays and Array.map

FUNCTION
Array.longest_ordered_sequence - find the longest ordered sequence of elements

SYNTAX
array(int) longest_ordered_sequence(array a);

DESCRIPTION
This function returns an array of the indices in the longest ordered sequence of elements in the array.

EXAMPLE 
> array a = ({ 1,2,3,4,2,3,5,6 });
Result: ({ /* 8 elements */
    1,
    2,
    3,
    4,
    2,
    3,
    5,
    6
})
> array seq = Array.longest_ordered_sequence(a);
Result: ({ /* 6 elements */
    0,
    1,
    4,
    5,
    6,
    7
})
> rows(a,seq);
Result: ({ /* 6 elements */
    1,
    2,
    2,
    3,
    5,
    6
})

SEE ALSO
Array.diff

FUNCTION
Array.map - map an array or mapping over a function

SYNTAX
array map(array arr,function fun,mixed ... args);
array map(array(object) arr,string fun,mixed ... args);
array map(array(function) arr,-1,mixed ... arg);

DESCRIPTION
First syntax:
Map array returns an array holding the items of arr mapped through the function fun. i.e. arr[x]=fun(arr[x], @args) for all x.

Second syntax:
Map array calls function fun in all objects in the array arr. i.e. arr[x]=arr[x]->fun(@ args);

Third syntax:
Map array calls the functions in the array arr: arr[x]=arr[x]->fun(@ args);

SEE ALSO
Array.sum_arrays and Array.filter

FUNCTION
Array.permute - Give a specified permutation of an array

SYNTAX
array permute(array in,int number);

DESCRIPTION
permute gives you a selected permutation of an array. The numbers of permutations equal sizeof(in)! (the factorial of the size of the given array).

EXAMPLE
Array.permute( ({ 1,2,3 }), 0) -> ({1,2,3})
Array.permute( ({ 1,2,3 }), 3) -> ({1,3,2})

SEE ALSO
Array.shuffle

FUNCTION
Array.reduce - Iterativily apply a function on an array

SYNTAX
mixed reduce(function f, array arr, void|mixed zero);

DESCRIPTION
reduce sends the first two elements in arr to f, then the result and the next element in arr to f and so on. Then it returns the result. The function will return zero if arr is the empty array. If arr has size 1 it will return the element in arr.

EXAMPLE 
Array.reduce(aggregate, indices(allocate(4)))  ->
   ({ ({ ({ 0, 1 }), 2 }), 3 })
Array.reduce(`+, ({}), "FOO?")  ->  
   "FOO?"
Array.reduce(lambda(int a, int b) {
             while(b) { int t=b; b=a%b; a=t; }
             return a;
             }, ({7191,21573,64719,33694}))
  -> 17

SEE ALSO
Array.rreduce

FUNCTION
Array.rreduce - Iterativily apply a function on an array backwards

SYNTAX
mixed rreduce(function f, array arr, void|mixed zero);

DESCRIPTION
reduce sends the last two elements in arr to f, then the third last element in arr and the result to f and so on. Then it returns the result. The function will return zero if arr is the empty array. If arr has size 1 it will return the element in arr.

EXAMPLE 
Array.rreduce(aggregate, indices(allocate(4)))  ->
   ({ 0, ({ 1, ({ 2, 3 }) }) })

SEE ALSO
Array.reduce

FUNCTION
Array.search_array - search for something in an array

SYNTAX
int search_array(array arr,function fun,mixed arg, ...);
int search_array(array(object) arr,string fun,mixed arg, ...);
int search_array(array(function) arr,-1,mixed arg, ...);

DESCRIPTION
search_array works like map_array, only it returns the index of the first call that returned true instead or returning an array of the returned values. If no call returns true, -1 is returned.

SEE ALSO
Array.sum_arrays and Array.filter

FUNCTION
Array.shuffle - Random-shuffle an array

SYNTAX
array shuffle(array in);

DESCRIPTION
shuffle gives back the same elements, but by random order.

EXAMPLE
Array.shuffle( ({"this","is","an","ordered","array"}) ) -> ({"is","ordered","array","this","an"})

SEE ALSO
Array.permute

FUNCTION
Array.sort_array - sort an array

SYNTAX
array sort_array(array arr,function fun,mixed ... args);

DESCRIPTION
This function sorts an array after a compare-function fun which takes two arguments and should return 1 if the first argument is larger then the second. The rest of the arguments args will be sent as 3rd, 4th etc. argument to fun. If fun is omitted, `> is used instead.

SEE ALSO
Array.map and sort

FUNCTION
Array.splice - splice two or more arrays

SYNTAX
array(mixed) Array.splice(array(mixed) arr1, array(mixed) arr2, array(mixed) ...);

DESCRIPTION
This function splice two or more arrays together. This means that the the array becomes an array of the first element in the first given array, the first argument in next array and so on for all arrays. Then the second elements are added.

EXAMPLE
> Array.splice(({1,2,3}),({"1","2","3"}),({"a","b","c"}));
Result: ({ /* 9 elements */
    1,
    "1",
    "a",
    2,
    "2",
    "b",
    3,
    "3",
    "c"
})
> Array.splice(({1,2,3}),({"1","2","3"}),({"a","b"}));
Result: ({ /* 9 elements */
    1,
    "1",
    "a",
    2,
    "2",
    "b",
})

SEE ALSO
`/, `*, `+, `- and Array.everynth

FUNCTION
Array.sum_arrays - map any number of arrays over a function

SYNTAX
array sum_arrays(function fun,array arr1,...);

DESCRIPTION
Works like this: 
array sum_arrays(function fun,array arr1,...)
{
    int e;
    array res=allocate(sizeof(arr1));
    for(e=0;e<sizeof(arr1);e++)
    {
        res[e]=fun(arr1[e],arr2[e],...);
    }
    return res;
}

Simple ehh?

SEE ALSO
Array.map, Array.filter and Array.search_array

FUNCTION
Array.uniq - remove elements that are duplicates

SYNTAX
array uniq(array a);

DESCRIPTION
This function returns an copy of the array a with all duplicate values removed. The order of the values in the result is undefined.
Previous section To contents