
viewable_expand(++ViewableName, ++DimensionNumber, +ExtraElements)

   Expand a dimension of a viewable by adding new elements.

Arguments
   ViewableName        A string or atom; the name of an existent viewable
   DimensionNumber     An integer: the number of the dimension to be enlarged.
   ExtraElements       A nested list or an array of the right size/dimensions, containing the new viewable elements.

Type
   library(viewable)

Description


        NOTE:When there are no registered visualisation clients,
        this predicate succeeds with any arguments, and has no effect.



      A viewable which has a flexible dimension (see
      viewable_create/3) may be expanded along that dimension
      by adding new elements. The dimension must have been declared
      flexible when the viewable was first created. The
      ExtraElements argument is of the same format as the
      Elements argument of viewable_create/3.

      The number and size of the dimensions of ExtraElements
      depends on the number and size of dimensions of the viewable being
      expanded. ExtraElements should have one less dimension than
      the viewable -- dimension DimensionNumber should be
      missing. The remaining dimensions should have the same sizes as the
      corresponding dimensions in the viewable.

      For example, a viewable of size 3 x 0 x 0 with all dimensions
      flexible, can be expanded along dimenson 3 using an
      ExtraElements argument of []([], [], []) which has size 3 x
      0. The viewable would then have size 3 x 0 x 1. It could then be
      expanded along dimension 1 using [] as
      ExtraElements since [] can implicitly have the
      size 0 x 1. The viewable would then have the size 4 x 0 x 1. Then
      dimension 2 could be expanded using [[W],[X],[Y],[Z]]
      for ExtraElements as this has size 4 x 1. The final size of
      the viewable would then be 4 x 1 x 1.

      The extra viewable elements must each also conform to the element
      type specified when the viewable was created.

       Note that when the viewable has one dimension, the
      ExtraElements argument will simply become the new element
      itself.

      viewable_expand/3 sets the name of the new location 
      (e.g. the column or row name) to its number as a string. For example, 
      adding a third row using viewable_expand/3 will result
      in the row being named "3". For more control over the name of the new
      location use viewable_expand/4.



Fail Conditions
   Fails if ViewableName is not the name of an existent viewable, or if the requested dimension of the viewable is not flexible.

Resatisfiable
   no

Exceptions
     4 --- ViewableName is not a string or atom
     5 --- DimensionNumber is not a ground integer
     6 --- DimensionNumber is not positive, or exceeds the viewable's number of dimensions
     1 --- ExtraElements is not a regular nested list or array of the correct size/dimensions
     5 --- ExtraElements contains elements which do not conform to the element type of the viewable

Examples
   

[Assuming that at least one visualisation client is registered]

       Success:

       viewable_create(v1, [[X, Y, Z], [A, B, C]], 
       	               array([flexible, fixed], any)), 
       viewable_expand(v1, 1, [R, S, T]).

       lib(fd), fd:([X, Y, Z, R] :: 1..10), 
       viewable_create(v1, [X, Y, Z], array([flexible], numeric_bounds)),
       viewable_expand(v1, 1, R).
       
       viewable_create(v1, []([](X, Y, Z), [](A, B, C)), 
       	               array([fixed, flexible], any)), 
       viewable_expand(v1, 2, [R, S]).


       viewable_create(v1, [[], [], []], 
		       array([flexible, flexible, flexible], any)),
       viewable_expand(v1, 3, []([], [], [])), 
       viewable_expand(v1, 1, []), 
       viewable_expand(v1, 2, [[W], [X], [Y], [Z]]),  
       viewable_size(v1, Size).
       [gives Size = [4,1,1]]

       viewable_create(v1, [], array([flexible], any)), 
       viewable_expand(v1, 1, F), 
       viewable_expand(v1, 1, G),
       viewable_size(v1, Size).
       [gives Size = [2]]
       
       


       Failure:

       viewable_expand(no, 2, [R, S]).


       viewable_create(v1, [[X, Y, Z], [A, B, C]], 
	               array([fixed, flexible], any)), 
       viewable_expand(v1, 1, [R, S, T]).


       viewable_create(v1, [[X, Y, Z], [A, B, C]], 
	               array([flexible, fixed], any)), 
       viewable_expand(v1, 2, [R, S]).



       Exceptions raised:

       viewable_create(v1, [[X, Y, Z], [A, B, C]], 
	               array([flexible, fixed], any)), 
       viewable_expand(_, 1, [R, S, T]).
       [gives error 4]

       viewable_create(v1, [[X, Y, Z], [A, B, C]], 
	               array([flexible, fixed], any)), 
       viewable_expand(v1, _, [R, S, T]).
       [gives error 5]

       viewable_create(v1, [[X, Y, Z], [A, B, C]], 
                       array([flexible, fixed], any)), 
       viewable_expand(v1, 3, [R, S, T]).
       [gives error 6]

       viewable_create(v1, []([](X, Y, Z), [](A, B, C)), 
	               array([fixed, flexible], any)), 
       viewable_expand(v1, 2, _).
       [gives error 1]

       viewable_create(v1, [[X, Y, Z], [A, B, C]], 
	               array([flexible, fixed], any)), 
       viewable_expand(v1, 1, [R, S, T, Q]).
       [gives error 1]

       lib(fd), fd:([X, Y, Z] :: 1..10), 
       viewable_create(v1, [X, Y, Z], array([flexible], numeric_bounds)),
       viewable_expand(v1, 1, an_atom)
       [gives error 5]





See Also
   viewable_expand / 4, viewable_create / 3, viewable_size / 2, viewable_type / 2
