OpenEuphoria

Sequences

Sequences enable simple and powerful programming in Euphoria.

Learn the basic operations that apply to a sequences, and you gain the ability to manipulate any data structure in a simple and flexible way.

Length and Shape

The length() function returns a value that is descriptive of the "size" of a Euphoria object. The value is based on the 'top level' number of elements:

? length( { } ) 
? length( ""  )  
    -- 0 
    -- an empty sequence as no length 
 
? length( 5 ) 
   -- 1 
   -- since an atom can contribute one element to a sequence 
   -- { } & 5 ==> {5} --length becomes one 
 
? length( { 'a', 2, 3, 'four' } ) 
    -- 4 
    -- there are four elements in this sequence 
 
? length( {  'a', { 2, 20, 200 },  3,  { 'four', {-1, -3} } } 
    -- 4 
    -- there are still 4 elements at the top level of the sequence 
    -- nested elements do not increase the length of a sequence 

It is useful to distinguish between a flat and a nested sequence.

-- flat sequences 
"this is a string of text" 
{ 1, 3, 9, 12 } 

A flat sequence is easy to display or print. The puts() function works on flat string sequences:

-- flat, one dimensional strings are easy to output 
puts(1, "the weather is fine today" ) 
    --> the weather is fine today 

A nested sequence could be described has having "dimensions". In the next example there are multiple dimensions to the sequence. Every time a sequence is nested, the dimensions increase by one:

 
      ""          -- empty: no dimension 
    "fine"        -- flat : one dimension 
  { "fine" }      -- nested :  two dimensions 
{ { "fine" } }    -- nested again:  three dimensions 

What a nested sequence must be output, be careful:

-- nested, multi-dimensional strings do not output using puts() 
puts(1,  { "the weather", {"is", "fine", "today" } } ) 
   -- error 
   -- sequence found inside character string  

The puts() function will not output a nested sequence because there is is no way to know what the intended layout should be--lots of possibilities exist. Use petty_print() to output a complicated sequence:

include std/pretty.e 
pretty_print(1, {"the weather", {"is", "fine", "today"}, {2} } 
    -- { 
    --   "the weather", 
    --     { 
    --      "is", 
    --      "fine", 
    --      "today" 
    --     } 
    -- } 

Do not expect pretty_print() to put strings into a sentence for you. That you have to program yourself.

If two sequences have the same length and dimensions (for every corresponding element, and every nested element), then the two sequences have the same shape.

Sometimes it is important that sequences have the same shape.

Some operations on two objects will work if they have compatible shapes. Shapes do not always have to be identical for operations on sequences.

The binop_ok() function will return a value of 1 (true) when two objects are compatible. An example of its use would be to test if two sequences could be added together:

sequence a = { 1, 2, {3, {4,5} } } 
sequence b = { 1, 2, 3, {4, 5} } 
sequence c = { 0, 3, {2, {1,1} } } 
 
? binop_ok( a, b ) --> 0  /* not same shape */ 
? binop_ok( a, c ) --> 1 /* compatible shape */ 
? binop_ok( a, 4 ) --> 1 /* compatible sequence and atom */