Good example for Pairs

We've had several users request that we deprecate the Collection class since it's ancient, and trivial to implement yourself. It's not exactly high on my list of things to deprecate because it works, and doesn't have a very high maintenance burden. But, it would be a very interesting test case for a deprecation strategy I've had. My idea has been to take some of the simpler functionality that we deprecate and replace it with example projects. When it comes time to remove the deprecated feature, we could have a process automatically add the example project to your existing project. Voila! Instant migration strategy that involves very little pain on the user's part. You can continue to use the Foobar class, since it's part of your project. And we can officially stop supporting it since you would then have the source code to it.

Now, the process whereby we determine a user is making use of the Collection class is an interesting one, and best left for another time. The thing that I found very cute about this little idea came about when I rewrote the Collection class.

In our C++ code, the collection class is about 270 lines of C++ code when you include all of the declarations, comments, etc. Not huge, by any means. When I rewrote it in REALbasic, it was a whopping 47 lines, 35 of which are comments and declarations! The collection class is an excellent example of when to use Pairs. It essentially wraps an array of pairs, where Pair.Left is the key, and Pair.Right is the value. As you can imagine, writing the class is pretty easy. The add method just Appends a new pair into an array. The remove and lookup methods that use an index just index into the array. The remove and add methods which use a key loop over the array and look at the element's .Left value to match against the key. That's it. Nothing more!

Kind of neat, and so I'm attaching the entire source code for the Collection class here so you can see why Pairs are a handy construct to have built into the framework.

Class Collection

  Function Item(index as Integer) As Variant

    // Indexes are one-based for historical reasons, so we need to

    // subtract one since our arrays are zero-based.

    //

    // We don't have to do any error checking -- the out of bounds

    // exception is on the user to deal with.

    return mItems( index - 1 ).Right

  End Function

  Function Item(key as String) As Variant

    // See if we can locate the value by key.  If we

    // can, then return the value.  If we can't, then

    // we just return nil.

    for i as Integer = 0 to UBound( mItems )

      if mItems( i ).Left = key then return mItems( i ).Right

    next i


    return nil

  End Function

  Sub Add(value as Variant, key as String = "")

    mItems.Append( key : value )

  End Sub

  Sub Remove(index as Integer)

    // Indexes are one-based for historical reasons, so we need to

    // subtract one since our arrays are zero-based.

    //

    // We don't have to do any error checking -- the out of bounds

    // exception is on the user to deal with.

    mItems.Remove( index - 1 )

  End Sub

  Sub Remove(key as String)

    // See if we can find the item to remove by key.  Note that

    // for historical reasons, we only delete the first element that

    // we find with a matching key.

    for i as Integer = 0 to UBound( mItems )

      if mItems( i ).Left = key then

        mItems.Remove( i )

        return

      end if

    next i

  End Sub

  Property Count As Integer

    Get

      return UBound( mItems ) + 1

    End Get

  End Property

  Private mItems() As Pair

End Class

As for whether Collection will be deprecated or not: I really don't know. There's not been enough research done to determine whether it would justify doing it. For instance, if there were plugins using Collection, then those might break depending on how they were written. My gut tells me that it won't be deprecated because there's no cost to maintaining it, but some risk in deprecating it, to be entirely honest.

What's interesting here was the fact that Collection was so trivial to rewrite -- back when Collection was added to the framework, it would have been very inefficient to implement in pure RB code (if not impossible -- I don't think you could implement optional parameters in v2 when Collection was first exposed). Now it's blindingly simple to do!