Previous chapter To contents Next chapter

Chapter 11, Modules for specific data types

There are a few modules that provide extra functions that operate specifically on one data type. These modules have the same name as the data type, but are capitalized so you can tell the difference. At the time of writing, the only such modules are String and Array, but more are expected to show up in the future.

11.1 String

The module String contains some extra string functionality which is not always used. These functions are mostly implemented in Pike as a complement to those written in C.

FUNCTION
String.fuzzymatch - make a fuzzy compare of two strings

SYNTAX
int fuzzymatch(string word1, string word2);

DESCRIPTION
This function compares two strings using a fuzzy matching routine. The higher the resulting value, the better the strings match.

EXAMPLE
> fuzzymatch("cat", "hat");
Result: 66
> fuzzymatch("cat", "dog");
Result: 0
> fuzzymatch("United States", "United Nations");
Result: 70

SEE ALSO
Array.diff, Array.diff_compare_table and Array.diff_longest_sequence

FUNCTION
String.implode_nicely - make an English comma separated list

SYNTAX
string implode_nicely(array(string|float|int) words, string|void separator);

DESCRIPTION
This function implodes a list of words to a readable string. If the separator is omitted, the default is "and". If the words are numbers they are converet to strings first.

EXAMPLE
> implode_nicely(({"green"}));
Result: green
> implode_nicely(({"green","blue"}));
Result: green and blue
> implode_nicely(({"green","blue","white"}));
Result: green, blue and white
> implode_nicely(({"green","blue","white"}),"or");
Result: green, blue or white
> implode_nicely(({1,2,3}),"or even");
Result: 1, 2 or even 3

SEE ALSO
`*

FUNCTION
String.capitalize - capitalize a string

SYNTAX
string capitalize(string str);

DESCRIPTION
Convert the first character in str to upper case, and return the new string.

SEE ALSO
lower_case and upper_case

FUNCTION
String.common_prefix - find the longest common beginning

SYNTAX
string common_prefix(array(string) strs);

DESCRIPTION
Find the longest common beginning from an array of strings.

EXAMPLE
> String.common_prefix(({ "muzzle", "muzzy" }));
Result: "muzz"
> String.common_prefix(({ "labyrinth", "diatom" }));
Result: ""
> String.common_prefix(({}));
Result: ""

FUNCTION
String.sillycaps - Sillycaps A String

SYNTAX
string sillycaps(string str);

DESCRIPTION
Convert the first character in each word (separated by spaces) in str to upper case, and return the new string.

FUNCTION
String.strmult - multiply strings

SYNTAX
string strmult(string s, int num);

DESCRIPTION
This function multiplies 's' by 'num'. The return value is the same as appending 's' to an empty string 'num' times.

FUNCTION
String.count - count needles in a haystack string

SYNTAX
string count(string haystack, string needle);

DESCRIPTION
This function counts the number of times the needle can be found in haystack. Intersections between needles are not counted, ie count("....","..") is 2.

FUNCTION
String.width - return width of string

SYNTAX
int width(string s);

DESCRIPTION
Returns the width in bits (8, 16 or 32) of the widest character in s.

FUNCTION
String.trim_whites - trim spaces and tabs from a string

SYNTAX
string trim_whites(string s);

DESCRIPTION
Trim leading and trailing spaces and tabs from the string s.

FUNCTION
String.trim_all_whites - trim all white spaces from a string

SYNTAX
string trim_all_whites(string s);

DESCRIPTION
Trim leading and trailing white space characters (" \t\r\n") from the string s.

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 chapter To contents Next chapter