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:

<eucode>
? 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
</eucode>

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

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

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

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

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:

<eucode>

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

What a //nested// sequence must be output, be careful:

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

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:

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

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**.

|= first sequence |= second sequence |= same shape? |
| "one" | "two" | yes , same length and dimension |
| { 1,2,3 } | "one" | yes, same length and dimension |
| { 'a', 'b' , "cdef" } | { 'a', 'b', 'c', 'd', 'e', 'f' } |no, shapes differ|

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:

<eucode>
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 */
</eucode>