====================================================================
FlexibleArray
====================================================================

The FlexibleArray domain constructor creates one-dimensional
arrays of elements of the same type.  Flexible arrays are an attempt
to provide a data type that has the best features of both
one-dimensional arrays (fast, random access to elements) and lists
(flexibility).  They are implemented by a fixed block of storage.
When necessary for expansion, a new, larger block of storage is
allocated and the elements from the old storage area are copied into
the new block.

Flexible arrays have available most of the operations provided by
OneDimensionalArray Vector.  Since flexible arrays are also of
category ExtensibleLinearAggregate they have operations concat!,
delete!, insert!, merge!, remove!, removeDuplicates!, and select!.  In
addition, the operations physicalLength and physicalLength! provide
user-control over expansion and contraction.

A convenient way to create a flexible array is to apply the operation
flexibleArray to a list of values.

  flexibleArray [i for i in 1..6]
    [1,2,3,4,5,6]
                     Type: FlexibleArray PositiveInteger

Create a flexible array of six zeroes.

  f : FARRAY INT := new(6,0)
    [0,0,0,0,0,0]
                     Type: FlexibleArray Integer

For i=1..6 set the i-th element to i.  Display f.

  for i in 1..6 repeat f.i := i; f
    [1,2,3,4,5,6]
                     Type: FlexibleArray Integer

Initially, the physical length is the same as the number of elements.

  physicalLength f
    6
                     Type: PositiveInteger

Add an element to the end of f.

  concat!(f,11)
    [1,2,3,4,5,6,11]
                     Type: FlexibleArray Integer

See that its physical length has grown.

  physicalLength f
    10
                     Type: PositiveInteger

Make f grow to have room for 15 elements.

  physicalLength!(f,15)
    [1,2,3,4,5,6,11]
                     Type: FlexibleArray Integer

Concatenate the elements of f to itself.  The physical length
allows room for three more values at the end.

  concat!(f,f)
    [1,2,3,4,5,6,11,1,2,3,4,5,6,11]
                     Type: FlexibleArray Integer

Use insert! to add an element to the front of a flexible array.

  insert!(22,f,1)
    [22,1,2,3,4,5,6,11,1,2,3,4,5,6,11]
                     Type: FlexibleArray Integer

Create a second flexible array from f consisting of the elements from
index 10 forward.

  g := f(10..)
    [2,3,4,5,6,11]
                     Type: FlexibleArray Integer

Insert this array at the front of f.

  insert!(g,f,1)
    [2,3,4,5,6,11,22,1,2,3,4,5,6,11,1,2,3,4,5,6,11]
                     Type: FlexibleArray Integer

Merge the flexible array f into g after sorting each in place.

  merge!(sort! f, sort! g)
    [1,1,2,2,2,2,3,3,3,3,4,4,4,4,5,5,5,5,6,6,6,6,11,11,11,11,22]
                     Type: FlexibleArray Integer

Remove duplicates in place.

  removeDuplicates! f
    [1,2,3,4,5,6,11,22]
                     Type: FlexibleArray Integer

Remove all odd integers.

  select!(i +-> even? i,f)
    [2,4,6,22]
                     Type: FlexibleArray Integer

All these operations have shrunk the physical length of f.

  physicalLength f
    8
                     Type: PositiveInteger

To force FriCAS not to shrink flexible arrays call the shrinkable
operation with the argument false.  You must package call this
operation.  The previous value is returned.

  shrinkable(false)$FlexibleArray(Integer)
    true
                     Type: Boolean

See Also:
o )help OneDimensionalArray
o )help Vector
o )help ExtensibleLinearAggregate
o )show FlexibleArray

