Furthermore, after some thought, I’ve decided to split up Fep arrays. In PHP arrays aren’t really arrays in the traditional sense, but more like array/associate array hybrids (JavaScript uses a similar concept). This can be confusing, error-prone and I don’t think that the benefits of having an hybrid array system outweighs the complexity.

Thus, in Fep, there will be two main collection types: lists and dictionaries. Here’s how a Fep list will look like:

// Fep
fep = [ "foo", 1, 2, "bar" ];
fep.count(); // == 4
fep.add( "baz" );
fep.find( x => x > 1 ); // == 2
 
// Will compile into this PHP
$fep = new FepList("foo", 1, 2, "bar");
$fep->count();
$fep->add( "baz" );
$fep->find( function( $x ) { return x > 1 } );

And here’s how a Fep dictionary will look:

// Fep
fep = { blah: "blah", foo: "bar", 0: "zero" };
fep.keys(); // == [ "blah", "foo", 0 ]
fep.containsKey( "foo" ); // == true
fep.remove( "foo" ); // == true
 
// PHP
$fep = new FepDict(array("blah" => "blah", "foo" => "bar", 
         0 => "zero"));
$fep->keys();
$fep->containsKey( "foo" );
$fep->remove( "foo" );

In this article, I’ll write a bit about how I think Fep arrays will look. Keep in mind this a work in progress and is by no means comprehensive. Without further ado…

In PHP, you define an array using the array() construct. Fep will follow the lead of languages like JavaScript, Python, Ruby and Groovy and use the square bracket [] notation.

Initialization

For example, a simple array in PHP is creating like this:

$arr = array(1, 2, 3);

In Fep, this would be done like this:

arr = [1, 2, 3]

There are actually three things to notice here. First, Fep uses square brackets. Second, Fep has optional semicolons (similar to JavaScript and Scala). Third, Fep doesn't prefix all variables with $. This should give your pinky finger a bit of rest and de-noise-ify your Fep code.

How about associative arrays? In this case, I don't want to deviate too much from PHP, so I'm going to go with the same syntax:

// PHP
$fruits = array(
  "fruits"  => array("a" => "orange", "b" => "banana", 
                     "c" => "apple"),
  "numbers" => array(1, 2, 3, 4, 5, 6),
  "holes"   => array("first", 5 => "second", "third")
);
 
// Fep
fruits = 
[
  "fruits"  => ["a" => "orange", "b" => "banana", 
                "c" => "apple"],
  "numbers" => [1, 2, 3, 4, 5, 6],
  "holes"   => ["first", 5 => "second", "third")
]

Decomposition

What about that convenient list construct? In Fep, we'll try again to reduce the typing and improve readability by introducing this syntax:

// PHP
list($a, $b, $c) = array("a", "b", "c");
 
// Fep
a, b, c = ["a", "b", "c"]

Accessors

To fetch a value from a Fep array, the regular PHP-style accessors will be used, with the main difference being that Fep will support negative indexing. That is, $array[-1] == $array[$array.length - 1].

arr = [1, 2, 3]
println $arr[0]    // 1
println [4, 5, 6][1] // 5
println $arr[-1]   // 3
 
mixed = ["a" => "b", "foo"]
println arr["a"] // b
println arr[0]   // foo

API

All arrays in Fep will be Array objects. As such, they'll have access to all the PHP array functions in an object-oriented way. Here's a few examples:

// PHP
$arr = array(1, 2, "x");
$len = count($arr);
array_push($arr, "y", "z");
in_array(1, $arr);
$merged = array_merge($arr, array("a", "b", "c"));
 
// Fep
arr = [1, 2, "x"]
len = arr.length
arr.push("y", "z")
arr.contains(1)
merged = arr + ["a", "b", "c"]

In short, the merge() command allows you to merge your current zing with the previous zing in your stack. What’s the stack, you ask?

Recall that, by default, Arrayzing a functional API, meaning that (unless you’re using a mutator command) your zing is never modified. Instead a new one is returned. So, if we do this…

_(1, 4, 9, 144).gteq(4).map(Math.sqrt);

…we have in fact created 3 zings, not one. Although it seems wasteful to keep making new zings, it turns out to be pretty useful. For one, it allows us to step backwards using the undo() command:

_(1, 4, 9, 144)  // [1, 4, 9, 144]
  .gteq(4)        // [4, 9, 144]
  .map(Math.sqrt) // [2, 3, 12]
  .undo()         // [4, 9, 144]
  .undo()         // [1, 4, 9, 144]
  .undo();        // []

(Aside: For those familiar with jQuery, the undo() command is the same as the end() command from that library).

Keeping a history (or stack) also allows us to combine the past with the present using the andSelf() command:

var double = function (x) { return x * 2; };
_(1, 2, 3)    // [1, 2, 3]
  .map(double) // [2, 4, 6]
  .andSelf();  // [2, 4, 6, 1, 2, 3]

But what else? Well, consider this situation: What if we wanted to modify only a subset of a zing? For example, imagine we a list of monetary values and we wanted to make sure they all had the “$” character in front of them. Let’s try and do that without using merge():

var fn = function(e)
{
  if (!e.startsWith("$"))
    return "$" + e;
};
 
_("$1.00", "$1.99", "100.00", "$5").map(fn);

That solution is OK. It’s pretty simple but it still requires a lot of typing and it’s not really using Arrayzing for much (just the map() command). Let’s see if we can reduce the number of keystrokes and make better use of Arrayzing’s capabilities by using the new merge() command:

_("$1.00", "$1.99", "100.00", "$5")
  .not(/^\$/).prepend$("$").merge();

So what just happened there? What does it all mean? Let’s look at that again, and track the contents of the zing:

1
2
3
4
5

_("$1.00", "$1.99", "100.00", "$5")
  .not(/^\$/)    // [ "100.00" ]
  .prepend$("$") // [ "$100.00" ]
  .merge(); 
  // [ "$1.00", "$1.99", "$100.00", "$5" ]

In line 1, we create the Arrayzing (nothing special here). In the following line, we filter out all strings that don’t begin with “$” using a regular expression. Things get a little more interesting on line 3, where we use the mutator version of prepend() to modify the filtered array in-place. Finally, on line 4, we use the merge() command which, basically puts the originally filtered monetary value back into the preceding zing.

So why did we use the prepend$() instead of prepend()? The reason for that is because using prepend() would have created another level of history. For example, here is what would happen if we had used prepend() instead of prepend$():

1
2
3
4

_("$1.00", "$1.99", "100.00", "$5")
  .not(/^\$/)   // [ "100.00" ]
  .prepend("$") // [ "$100.00" ]
  .merge();     // [ "$100.00" ]

Why did that happen? The answer to that question lies in how merge() merges. Let’s start by looking at line 2 of the last code snippet. In that line, we filtered out all strings that did not start with a “$” character. When Arrayzing returns a new zing that contains only the elements that start with a “$”, it also remembers where the new elements came from. So in the case of the not() function on line 2, Arrayzing remembers that “100.00″ came from index 2 of the zing in line 1 (that is, the zing _(“$1.00″, “$1.99″, “100.00″, “$5″)). The merge() command only operates on the current zing and the one immediately previous to it on the stack.

With that in mind, let’s look at line 3. On line 3, we run the prepend() command, which creates and returns a new zing that contains the value “$100.00″. What’s more, it also remembers that the value “$100.00″ was derived from “100.00″ (index 0) in the zing immediately previous to it in the stack (that is, the zing _(“100.00″)). Thus, when merged, it simply overwrites the value it derived from, which is the 0th index of the zing [ "100.00" ]… which results in the zing [ "$100.00" ]. You follow all that?

This concept is easier to understand by annotating the previous code snippet:

var zing1 = _("$1.00", "$1.99", "100.00", "$5");
// [ "$1.00", "$1.99", "100.00", "$5" ] index 0-3 come from nothing
 
var zing2 = zing1.not(/^\$/);
// [ "100.00" ] index 0 comes from index 2 in zing1
 
var zing3 = zing2.prepend("$");
// [ "$100.00" ] index 0 comes from index 0 in zing2
 
var zing4 = zing3.merge();
// [ "$100.00" ] copy index 0 from zing3 over index 0 in zing2

Now, with that more or less explained, let’s go on to one final item: What happens when we try to merge a zing that we’ve added to or removed from. For example, if we added elements like this:

_("str", 2, 3, 4, "a", "b").numbers().add$(7).merge();

What would be in the zing returned by this sequence of functions? In this case, when merge() is called, Arrayzing would not know where to merge the 7 element (since it only remembers the original indices of elements that directly derived from the previous zing). Arrayzing deals with this scenario by simply adding all elements that it does not have an index for to the end of the previous zing in the stack. Here’s what that same snippet would look like if we documented each step:

_("str", 2, 3, 4, "a", "b")
  .numbers() // [ 2, 3, 4 ]
  .add$(7)   // [ 2, 3, 4, 7 ]
  .merge();  // [ "str", 2, 3, 4, "a", "b", 7 ]

How about if we removed elements? If we were to remove elements, they would simply not be merged back into the previous zing on the stack. For example:

_("str", 2, 3, 4, "a", "b")
  .numbers()    // [ 2, 3, 4 ]
  .set$(0, 4)   // [ 4, 3, 4 ]
  .set$(2, 7)   // [ 4, 3, 7 ]
  .removeAt$(0) // [ 3, 7 ]
  .merge();     // [ "str", 2, 3, 7, "a", "b" ]

As you can see, the merge() command is a powerful addition to Arrayzing. It allows us to select a subset of the elements, transform them, and then re-add them to our original zing.

When using plain old JavaScript Array objects, a common operation is to access or modify elements. For example:

var a = [1, 2, 3];
var sum = a[0] + a[1] + a[2]; // = 6
a[0] = 6;
a.join(); // "6,2,3"

Arrayzing also supports the built-in [] accessor. However, it should be noted there are limitations to accessing an Array in this manner, most notable amongst them being that we must always index from the left. For example, imagine we wanted to access the last element. Using a normal Array, we would have to do this:

var a = [1, 2, 3];
a[a.length - 1] = 4; // a = [1, 2, 4];
alert(a[a.length - 1]); // shows 4

Although this works, it’s not the most convenient or elegant way to do it. To address this problem, Arrayzing provides two new functions get() and set(). These functions act essentially the same as the built-in [] accessors with an added benefit: we can index from the left and the right. For example, to implement the above example using Arrayzing, we could instead do this:

var a = _(1, 2, 3);
a.set$(-1, 4); // a = [1, 2, 4];
alert(a.get(-1)); // shows 4

(Aside: If you’re not familiar with the $ after set$(), check out this article. It means that the function is a mutator).

What’s more, all Arrayzing commands that take an index as an argument allow right-indexing. What convenience!

There is one further advantage of using set(): we can change an element in your zing (a zing is an Arrayzing array) without modifying the original array. For example, if we wanted to replace an element in our zing but didn’t want to modify the original array, we would do this:

var a = _(1, 2, 3);
var b = a.set(0, 10); // not set$()
a.str(); // returns "1,2,3"
b.str(); // returns "10,2,3"

As you can see, Arrayzing provides a strict superset of the capabilities of a normal Array’s accessors, allowing you to write cleaner, easier code.