insert

Gamma: Version 4.0
Prev |  | Next

# `insert`

`insert` -- inserts an array value at a given position.

## Syntax

    insert (array, position|compare_function, value)

## Arguments

`array`

  An array.

`position`

  A number giving the zero-based position of the new element within the array, or a function.

`compare_function`

  A function on two arguments used to compare elements in the list or array.

`value`

  Any Gamma or Lisp expression.

## Returns

The `value` inserted.

## Description

The `insert` function widens an array at the given `position` and inserts the `value`. If a `compare_function` is used, it must return a negative number if the value is ordinally less than the array element, 0 if the two are equal and a positive number if the value is ordinally greater than the array element. The `value` will be inserted using a binary insertion sort, based on the return value of the function.

## Example

        Gamma> x = array("a", "b", "c");
        ["a" "b" "c"]
        Gamma> insert(x,3,"d");
        "d"
        Gamma> x;
        ["a" "b" "c" "d"]
        Gamma> insert(x,strcmp,"acme");
        "acme"
        Gamma> x;
        ["a" "acme" "b" "c" "d"]
        Gamma>

See the Photon: Setting Up Plots section of the History Functions chapter in the Cogent Tools Demo book for an example of this function used in context.

## See Also

`aref`, `array`, `aset`

Prev | Home | Next
`find`, `find_equal` | Up | `intersection`

Copyright 1995-2002 by Cogent Real-Time Systems, Inc.