Keyword Index

Object: SPArray

This is used to return arrays of objects.

  • append - Append a single item, or the contents of another SPArray.
  • apply - Call a given method for each element in the array
  • keep - Keeps only the given elements, either in a specified range, or matching a given regular expression. All other items are removed.
  • length - Returns the number of elements in the array
  • remove - Removes elements from the array, either in a specified range, or matching a given regular expression, and moves all subsequent items forward.
  • removeDuplicates - Check each element of the array and removes it if it matches a previous one. Valid only for arrays of strings.
  • slice - Return a new SPArray into which the selected elements have been copied.
  • sort - Place the items in a string array in ascending order
  • splitIntegerParams - Appends integers extracted from a comma-separated list string
  • splitParams - Appends strings extracted from comma-separated parameters.
    •

    Method: append

    Version added: 1.1

    Append a single item, or the contents of another SPArray.

    void append(array);

    void append(object);

    void append(binaryData);

    void append(string);

    Parameters
    Name Expected Type Description
    string string A string item to append to this string array.
    object object A complex object to append to this array.
    binaryData data Any non-string data to append to this binary array.
    array SPArray Another array whose elements will be appended to this array. The source array is not affected.

    Remarks:

    Remember that an SPArray is restricted to having all elements of the same type, either string, object or binary.

    Example:

    // Accumulate two sets of file objects into a single array

files = getFileList("c:/temp");
files.append(getFileList("c:/documents");

    Method: apply

    Call a given method for each element in the array

    void apply(object, methodName);

    Parameters
    Name Expected Type Description
    object object The object whose method we want to call
    methodName String The name of the method to call

    Returns:

    nothing

    Remarks:

    The called method must accept one string argument, which is the value of the array element converted to a string. The method is called repeatedly, once for each element in the array, starting with the lowest-numbered element

    Method: keep

    Version added: 1.1

    Keeps only the given elements, either in a specified range, or matching a given regular expression. All other items are removed.

    void keep(index);

    void keep(start, num);

    void keep(regExp);

    Parameters
    Name Expected Type Description
    regExp regExp A regular expression to match. All elements not matching this expression are removed.
    start int The first index to keep,
    index int The index of the item to keep. This will leave the array with only one element.
    num int The number of elements to keep.

    Remarks:

    This function modifies the array by removing all elements not matching the given criteria.

    The regular expression form is supported only for array elements that have a string value, i.e. not binary arrays.

    See also "remove", which is the opposite function.

    Example:

    // Keep only files in "temp" that have a ".html" extension.

files = getFileList("c:/temp");
file.keep(/.+\.html/);

    See Also:

  • remove
    •

    Method: length

    Returns the number of elements in the array

    int length();

    Remarks:

    This can be used either as a method or a property

    Example:

    files = getFileList("c:/temp");
for (i = 0; i < files.length; i++)
{
    writeln("Found file " + files[i];
}

    Method: remove

    Version added: 1.1

    Removes elements from the array, either in a specified range, or matching a given regular expression, and moves all subsequent items forward.

    void remove(index);

    void remove(start, num);

    void remove(regExp);

    Parameters
    Name Expected Type Description
    regExp regExp A regular expression to match. All elements matching this expression are removed.
    start int The first index to remove,
    index int The index of the item to remove.
    num int The number of elements to remove.

    Remarks:

    Note that removing an element of course causes the length of the array to be reduced by one and all subsequent elements to be renumbered. Be careful when doing this in a loop. See the example.

    The regular expression form is supported only for array elements that have a string value, i.e. not binary arrays.

    See also "keep", which is the opposite function.

    Example:

    // Delete all file objects in the list where the file is less than 1K.
// Note we have to work backwards through the array because
// it keeps getting shorter!

files = getFileList("c:/temp");
for (i = files.length-1; i >= 0; i--)
{   // Note: We're removing the element from the array here,
    // NOT removing the file from the disk!
    // Using the statement "files[i].remove()" would remove
    // the file from the disk but leave the element in the array!!!

    if (files[i].length < 1024) files.remove(i);
}

    See Also:

  • keep
    •

    Method: removeDuplicates

    Version added: 1.2

    Check each element of the array and removes it if it matches a previous one. Valid only for arrays of strings.

    void removeDuplicates();

    Errors:

    Generates an exception if the array is not an array of strings.

    Method: slice

    Version added: 1.1

    Return a new SPArray into which the selected elements have been copied.

    void slice(start);

    void slice(start, end);

    Parameters
    Name Expected Type Description
    end int If specified and > 0, the last item to copy + 1. If negative, the number of items to leave (i.e. not copy) at the end of the array.
    start int The first element to include in the destination array.

    Remarks:

    The source array is not affected.

    Method: sort

    Place the items in a string array in ascending order

    void sort();

    Remarks:

    Only applies to an array of string values, a type error will be reported otherwise.

    Method: splitIntegerParams

    Version added: 1.3

    Appends integers extracted from a comma-separated list string

    void splitIntegerParams(source);

    Parameters
    Name Expected Type Description
    source string The string from which parameters will be extracted.

    Errors:

    Generates an exception if the array is not either empty or an array of variants

    Remarks:

    Parses the source string and extracts comma-separated integers, each parameter becoming an additional element.

    Method: splitParams

    Version added: 1.3

    Appends strings extracted from comma-separated parameters.

    void splitParams(source);

    Parameters
    Name Expected Type Description
    source string The string from which parameters will be extracted.

    Errors:

    Generates an exception if the array is not either empty or an array of strings.

    Remarks:

    Parses the source string and extracts comma-separated parameters, each parameter becoming an additional element.