Re: Discuss changing the behaviour of append()

• Posted by _tom (admin) Jun 12, 2014
• 3969 views

Here is a another draft of possible documentation. After the change to the definition of "length" from Euphoria 3 to 4, these results follow. Everything seems to fit a consistent pattern once you allow for atomatic promotion of an atom to a sequence.

_tom

(Edit, I made an interesting typo: atomatic vs automatic...)

Object Length

The length of an object "is a count of the top-level items it contains."

The length of a sequence is the number of items it contains; if an item is a nested sequence it still counts as one item. The length of an empty sequence is zero; it contains no items.

The length of an atom is one. This is a convenient viewpoint because when an atom is added to a sequence (by inserting or concatenating) the result is an increase in length by one.

It is easy to argue that a number or a character has no defined length. In Euphoria versions before O[ 4 atoms did not have a defined length.

An atom a is not the same as a sequence {a} containing one atom. This distinction is important and is used in many algorithms.

Increasing Length

You can increase the length of an object by adding one or more items. There are two ways to do this: insertion and concatenation.

• An insertion (prepend, insert, append) increases length by exactly one.
• A concatenation ( & ) increases length by the length of the added object.

It is really convenient to promote an atom into a one item sequence automatically when performing an object lengthening.

Concatenation &

The concatenation operator "joins two objects together to make a sequence whose length is equal to the sum of their individual lengths."

? 3 & 4
--> {4,5} 

? 'O' & 'E'
--> "OE" 

? {1,2} & {3,4}
--> {1,2,3,4} 

? "Open" & "Euphoria"
--> "OpenEuphoria" 

Visualizing Concatenation

A way to visualize the process of concatenation is to imagine some intermediate steps:

Concatenating sequences:

? {1,2} & {3,4} 
--> {1,2  }&{  3,4} 
--> {1,2   ,   3,4} 

When concatenation involves an atom:

? {1,2} & 3 
--> {1,2  }&   3 
--> {1,2  }&{  3}   -- promotion of atom to sequence required 
--> {1,2   ,   3} 

Prepend, Insert, Append

An insertion function (prepend, insert, append) "places an object as an item within a sequence."

The index argument of the insert function places the new item at the index value of the new sequence.

Think of prepend as insertion of an object before the first item of a sequence. Think of append as insertion of an object after the last item in a sequence.

An insertion of a string into a string never produces another string. Use a concatenation if you need the result to be a string.

? prepend(3,4)
--> {4,3} 

? prepend('a','z')
--> "za" 

? append({1,2},3)
--> {1,2,3} 

? insert("horse", 'a', 3)
--> {104,111,97,114,115,101}
-- "hoarse" 

? prepend({1,2},{3,4})
--> { {3,4}, 1,2} 

? prepend("jay","blue")
--> { {98,108,117,101},
--    106,
--    97,
--    121 } 

Visualizing Insertion

A way to visualize an insertion function is to imagine some intermediate steps:

An append of an atom to a sequence:

? append({1,2},3) 
--> {1,2,   } 
           ^  
           3 
--? {1,2,3} 

An insertion of a character in a string:

? insert("44",'X',2) 
--> {52,    52} 
         ^ 
         120 
--> {52,120,52} 
--  "4X4" 

Inserting an object into an atom makes no sense unless you allow for an automatic promotion of an atom into a sequence:

? prepend(1, 5) 
--> prepend( {1}, 5)  -- promotion of atom to sequence required 
--> {  1} 
      ^ 
      5 
--> { 5, 1 } 

For version O[ 4 and earlier Euphoria this automatic promotion of an atom to a sequence was not allowed.