First of all, there is no need to be in a rush! API 1.0 will continue to stay for a long, as Xojo has officially communicated: “ Moving to API 2.0 “.

This turns to the fact that many might conclude to just ignore API 2.0 for a very long time, but I don’t believe that it’s wise not to move. I’ll start all new projects with API2. Why?

The Basics

• There are a lot(!) of benefits in API2 (more on this later).

• Many libraries and modules will be converted to API2. So we will see a transition time where some code examples will be written in API1 and other routines are already published in API2. This might confuse not only beginners. The sooner we all will move the better.

• New users, who will become the future “gurus” will most likely start to work solely with API2 (at least I encourage them doing so) and they might have difficulties understanding questions from users still living isolated in their API 1.0 world.

• Change is a constant in our modern world. Better get used to it.

Before I will upset the savvy and experienced developer: of course there are pitfalls and caveats and the paradigm to never change a running system remains to be true.

I will never transition a huge project only to make it compliant with the new API. Again there is no need to be in a rush! But for new projects, it’s crystal clear to me that I will embrace the new changes (though it will be tough sometimes, as with every change) and ensure API2 compliancy. Let me start by showing you a few benefits:

What Is In For Me?

I converted 2 larger libraries: StringUtils and ArrayUtils for Xojo originally developed by Joe Strout. I did this mainly for reason that both libraries included so-called “Test Units”.

Using “Test Units” basically means that you are calling each routine with different parameters and you are checking if the returned results fit to what you expected as the developer. They are a fantastic approach whenever you need to change code in future.

The fact that Joe had included test units made it easier for me to see if my changes worked and to learn the pitfalls of API2 the hard way, but with the “parachute” that his unit tests, will tell me if I’m right or wrong.

For those of you interested in learning API2 I encourage you to do the conversion of both libraries on your own. You will learn a lot! Much more than I could tell you by writing more articles. You have to go through the learning curve by yourself.

Your code is much cleaner in API2!

Let’s have a look at the following code snippets:

API1:

The string operation is 1-based and not zero-based as for instance Xojo arrays, plus it looks compact but you need a second to understand what is happening here.

return mid(repeated, 1, ceil((width-length)/2)) + s + mid(repeated,1,(width-length)\2)

API2:

It’s first a good thing that all string operations are now 0-based, as everything else in Xojo. But the code is as well easier to understand.

return repeated.middle(0, ceiling((width-length)/2)) + s + repeated.middle(0,(width-length)\2)

API1:

This code is “shorter” than in API2 but it is harder to read and less clear, what is happening here?

Dim cutLenB As Integer = stringToCut.LenB if StrComp( RightB(s, cutLenB), stringToCut, 0 ) = 0 then return s.LeftB( s.LenB - cutLenB ) else return s end if

API2:

Yes, the code below is longer! But so much easier to read. Of course, the enumeration ComparisonOptions.CaseSensitive is “longer” than just typing in a 0. But who will remember the different options behind such numbers? I never (or very rarely) did.
Will a beginner understand the API1 code w/o consulting the documentation? Nope! In API2 the code is easy to read.

Var cutLeftBytes As Integer = stringToCut.Bytes if s.rightBytes(cutLeftBytes).Compare(stringToCut, ComparisonOptions.CaseSensitive ) = 0 then return s.LeftBytes( s.Bytes - cutLeftBytes ) else return s end if

How Complex Is The Transition?

Now, this depends on the nature of your original code and what command you used.

Converting a simple:

Var strLength as Integer = len( myString )

into:

Var strLength as Integer = myString.Length

is a simple change, which can’t break anything. You could probably even automate it with some RegEx etc. A change from “UBound” to “LastIndex” is similarly simple.

The tricky changes are whenever the base changes for 1-based to 0-based. First, this means that you have to subtract the number 1 from your parameters, which is easy to do if you have something like the following:

Var myMiddleString as String = Mid(myMainString, 5, 10)

which will have to be altered to:

Var myMiddleString as String = myMainString.Middle( 4, 10 ) or Var myMiddleString as String = myMainString.Middle( 5 - 1, 10 )

That’s easy as well, isn’t it?

But what if you are working with parameters? Then it will become a bit nasty and more complex. Let’s take the following example: you have somewhere a method returnMiddleString which you are calling with a parameter x.

[...] return myResult.Middle( x, 10 )

Now if you are coming from API1 the variable x will need to be subtracted by 1 before calling this API2 method because the old mid-command was 1-based, but the new “middle”-command is 0-based. This can easily become complex and hard to debug and adapt. Imagine a program where you are dynamically calculating the value of x in several places before calling this particular method.

The same applies for InStr in comparison to the new IndexOf:

API1:

return InStr( "AEIOUY", Mid(source, atPos, 1) ) > 0

will change to the following in API2:

return str("AEIOUY").IndexOf( source.Middle(atPos-1, 1) ) > -1

Please note that “ InStr” is 1-based and “ IndexOf” is now 0-based, so the atPos value has to change!

Not a big deal in this case, as we are returning a boolean value but what if we would return the current position? Then the calling part of your code needs to reflect this change as well. It would be a bad idea to change your method in a way that it will still return a 1-based value, as you will run sooner or later into issues while converting more parts of your code!

Do I Like The New API?

The short version: Yes. Working on a real project to transition from API1 to API2 is an experience. I was impressed by how better the new API2 code is readable.

The more complex answer: Yes, I will continue on new projects to only work with API2. The benefits are clear to me. But transitioning old projects will depend on the nature of those. If I had developed unit tests for them and/or my documentation is good, then the transition will be easy (or at least more secure, as I can easily test my changes). If my old code is cumbersome, if I haven’t touched it for years, if I can’t remember exactly what I did, if I “forgot” to add meaning full comments … well, then I will probably feel ashamed but not touch it at all.

The fact that now everything is finally 0-based is great, but you really have to spend a lot of attention to test any conversion from 1-based commands of Xojo API 1.0 to Xojo API 2.0 and this might easily lead to a lot(!) of work. But again, remember that Xojo API 1.0 will stay for a very long (if not forever). So I don’t see the urge to be in a rush for old projects.

The tricky and crucial parts will most likely be shared methods and modules, classes, etc. I will copy those before altering them to ensure that the old code will still work. I hate to have 2 code repositories, but as it is very rare that I have to maintain very old code, I don’t think this will be a very big deal overall.

Do I Have Wishes?

Well, we can discuss for ages if all re-namings are appropriate or not. I compare it to the evolution of languages. We don’t speak these days like Shakespeare or Goethe did. And similar to the evolution of languages, API2 will as well be extended or even change in the next years.

But I hope (and I’m confident) that we are now finally well on track, and we won’t again see such a big change any time soon.

But don’t forget “deprecated” doesn’t mean “sunset”! As the whole Xojo IDE is written in Xojo I don’t think anyone should get too nervous about any warning in your old code that a certain statement is outdated. The fact that many Xojo staff members are still sharing non-API2 compliant code on the Xojo Forum is yet another indicator that we are not in a rush or all in the same boat. But it is a good and beautiful boat.

Kudos to the Xojo team, I imagine that the change to API2 must have been an awful lot of work (with little fun). Overall I think it is the right move, even though it means that we all have to learn something new and I’m sure I will bump into situations where I will hate the conversion work, but I am still convinced that the benefits of API2.0 will predominate!