The one thing that annoys me most when producing the numerous open source libraries and tools I’m developing is the constant replication of code, in an attempt to keep each project separate from the others.

The number of times I’ve copied and pasted the same Classes and Methods surely by now constitutes tens of thousands (or more) of lines of unnecessary code, and a note-worthy (in the very least) amount of time.

Not anymore!

Introducing the LaKraven Studios Standard Library [LKSL] for Delphi

The LKSL is a behind-the-scenes library I have begun producing to bring all of the standard base Classes and Methods I use in my open source and client projects together into one place. Not only that, but it also introduces some very powerful new functionality we can all enjoy.

As a side note, the LKSL isn’t an additional project on my already long list of projects, but rather a common base to be used by them all. As such, it is being developed directly alongside all of the projects I have currently in development, as the need is encountered along the way. This means it’s not consuming more of my time, but will in fact save it.

There is one new feature introduced by the LKSL I consider so extraordinarily useful (nay, necessary) I’d like to focus on it now…

UPDATE: Due to performance issues, I will not be using Smart Types in my Public projects. At the same time, I will not be removing the code as the performance issue could potentially be solved in the future. Thank you all for your feedback (as overwhelmingly negative as it has been). I shall leave the rest of this article unaltered so people can see what the idea was, and continue to berate me for the Unicode > ANSI casting idea (which I now agree was a very silly idea)

Smart Types

“Smart Types” are Value Types just like String, Integer, Double, Single, Boolean and the like, but with a fundamental difference. The methods used to operate on normal types are encapsulated directly within Smart Types, as you can see in other languages like .NET, and in many scripting languages (such as Lua). This keeps related operations bound together under their corresponding Value Type, which not only reduces the amount of code you have to produce, but makes it easier to do so as well.

[SmartString] ANSI<>Unicode Casting

As of Delphi 2009, the standard String type in Delphi is Unicode, where in all prior versions of Delphi (2007 and earlier) it was ANSI. For many of us whom have already made the upgrade to Unicode versions of Delphi, this presented quite a lot of annoyance in larger projects, as much of the dependencies we required hadn’t been updated to support Unicode, meaning that we would get a spam of warnings about implicit casting between Unicode and ANSI strings, as well as issues at run-time with data corruption and the like.
What was previously needed to address these issues was to go through all of our code and cast between Unicode and ANSI such as:

function AnsiToUnicodeString(const AAnsiString: AnsiString): String;
begin
  Result := String(AAnsiString); // An explicit cast to supress compiler warnings
end;

function UnicodeToAnsiString(const AUnicodeString: String): AnsiString;
begin
  Result :=  AnsiString(AUnicodeString); // An explicit cast to supress compiler warnings, except unicode-specific chars will be omitted (truncation)
end;

function StringToPAnsiChar(const AValue: String): PAnsiChar;
begin
  Result := PAnsiChar(AnsiString(AValue)); // This enables us to pass a String value as a parameter of an ANSI-C DLL method!
end;

function PAnsiCharToString(const AValue: PAnsiChar): String;
begin
  Result := String(AnsiString(AValue)); // This enables us to work with values returned by ANSI-C DLL methods!
end;

Now, you could either place those functions inside a unit, and call them “in-line” for every string cast, or you’d have to call the casting they contained… either way, you have to do this every single time you’re casting between Unicode and ANSI.

The LKSL’s SmartString type, however, does this internally for you, meaning all you have to do is use SmartString in place of String or AnsiString in your code, and you need never bother with the explicit (manual) casting again!

function SomeAnsiCDLLMethod(AStringValue: PAnsiChar): PAnsiChar; cdecl; external MY_DLL; // Takes an Ansi String, returns an Ansi String!

var
  LSmartString: SmartString;
  LUniString: String;
  LAnsiString: AnsiString;
begin
  // SmartString accepts assignments just like traditional String types!
  LSmartString := 'Hello World!';
  // No compiler warnings, no truncation! A clean implicit cast!
  LUniString := LSmartString;
  // No compiler warnings, but Unicode-specific chars will be omitted (truncation)
  LAnsiString := LSmartString;

  // We can even call our ANSI-C DLL method too!
  LSmartString := SomeAnsiCDLLMethod(LSmartString);
end;

As you can see above, SmartString handles all the casting for you, so there is no need to explicitly define the required String Type each time you pass the value around! This means that when you use SmartString instead of String and its kin, you don’t need to think too much about how it’s being cast.
Of course, you do need to consider that Unicode chars will be lost when the value is passed to an ANSI container, but this is always the case whether you’re casting manually or not.

NOTE: SmartString types are not an excuse to forget about the differences between Unicode and ANSI… but it provides a useful shortcut to those with large existing projects working entirely with ANSI data already.

If you wish to force your strings to be ANSI-only (disregarding all Unicode chars as a design), you can simply use SmartAnsiString instead! It works the same way as SmartString only it stores its values in ANSI. It’ll automatically cast its value to String (Unicode) containers, but it’ll only ever hold ANSI chars! This is particularly useful if you are working with third-party DLLs only available in ANSI!

[SmartString] IntToStr, FloatToStr etc… bye bye!

When you want to directly cast an Integer (or any other ordinal-type) value to a string type, currently you have to so manually (explicitly)…

var
  LInteger: Integer;
  LString: String;
begin
  LInteger := 1337;
  // Explicitly cast the Integer to a String
  LString := IntToStr(LInteger);

  // Explicitly cast a String to an Integer
  LInteger := StrToInt(LString);
end;

This is fine, and has served us all well for many years… but really it’s just more code than is necessary!

Here’s how the LKSL’s SmartString types do it:

var
  LInteger: Integer;
  LString: SmartString;
begin
  LInteger := 1337;
  // Passing an Integer value directly to a String
  LString := LInteger;
  // Also works with all Floating Point types:
  LString := 3.14159;
  // You can even do it with Booleans!
  LString := True;

  // And now from SmartString to Integer...
  LString := 9001;
  LInteger := LString;
end;

As you can see, it is no longer essential to explicitly declare casts when assigning compatible types to a SmartString (and vice versa), as SmartString takes care of that for us! A full list of compatible types will be provided in the upcoming LKSL documentation, or you can very easily look at the source code found in LKSL.SmartTypes.pas to see what works and how!

Should you wish to format an ordinal value for presentation purposes, this is of course still possible… only now, it’s more intuitive thanks to SmartString…

[SmartString] Composing and manipulating Values

As mentioned previously, Smart Types encapsulate common methods used to compose or manipulate their value. In fact, the Smart Types provided by the LKSL enable you to do this in two ways:

1. Perform an operation to compose or manipulate a value, and return that manipulated value as a fresh “instance” of the Smart Type, leaving the original value in-tact
2. Perform an operation to compose or manipulate a value, returning the manipulated value as a fresh “instance” of the Smart Type, and/or modifying the original.

This provides the greatest degree of flexibility, enabling you to produce code both to a style more suitable to yourself, and in the most logical (therefore easiest to follow) manner.

Leaving the original value in-tact…

var
  LFoo, LBar: SmartString;
begin
  LFoo := '   Hello   ';
  // Remove the preceding and proceeding whitespace
  LBar := LFoo.Trim;
end;

The above code snip demonstrates two things. First of all, Smart Types contain methods we can execute (such as Trim) secondly, that this method returns a fresh (modified) SmartString based on the contents of the original, while leaving the original in-tact. This means that the value of LFoo will remain ‘   Hello   ‘, while the value of LBar will be ‘Hello’.

Modify the original value…

var
  LFoo: SmartString;
begin
  LFoo := '   Hello   ';
  LFoo.TrimSelf;
end;

The above code snip shows an example of Trim used to modify the original value, as opposed to just returning a new SmartString (though note that methods which modify the original value do also return the new value as well, for in-line usage [keep reading for more info]). All methods in the LKSL’s Smart Types which modify the original value have the Self suffix so are defined as [Method]Self.

The reason for the Self suffix is that Delphi does not allow the overloading of functions with procedures (or vice-versa), and so the method name must be different. We settled on Self because it is a universally-understood precept of Object-Oriented Programming. We have elected to make it a suffix rather than a prefix for the sake of Delphi’s Code Completion display order (which is alphanumeric).

Since Self-suffixed methods also return a copy of the value as a new Smart Type “instance”, we can use them “in-line”…

var
  LFoo, LBar: SmartString;
begin
  LFoo := '   Hello   ';
  // "in-line" value composition
  LBar := LFoo.TrimSelf.UpperCase;
end;

The above code snip above results in LFoo‘s value being changed to ‘Hello’, and LBar‘s value being set to ‘HELLO’ (the UpperCase value of LFoo)… all with a single line of code!

It’s worth noting that while the concept of “in-line” operation such as demonstrated here is great for code production, if used irresponsibly it can make the code more difficult to read, since one line of code will be performing multiple operations.  With that said, it is up to you – as a developer – to determine when it’s appropriate to make use of this feature.

[SmartString] Sub-String Subtraction (the Subtract operator)

The LKSL’s SmartString types include what I consider to be a very useful feature, enabling you to subtract a Sub-String from a value. It’s easier to understand with an example:

var
  LFoo, LBar: SmartString;
begin
  LFoo := 'Hello';
  // Subtract "l" from LFoo using the "subtract" operator
  LBar := LFoo - 'l';
end;

The above code would make the value of LBar equal to the value of LFoo, but without any instances of the Sub-String “l” (case-sensitive), which evaluates as “Heo”. This is fundamentally the same as:

var
  LFoo, LBar: SmartString;
begin
  LFoo := 'Hello';
  // Subtract "l" from LFoo using the "subtract" method
  LBar := LFoo.Subtract('l');
end;

It is also worth noting that you can perform subtraction in a case-insensitive manner:

var
  LFoo, LBar: SmartString;
begin
  LFoo := 'Hello';
  // Subtract "l" from LFoo using the "subtract" method (case-insensitive)
  LBar := LFoo.AnsiSubtract('l');
  // The above is the same as...
  LBar := LFoo.Subtract('l', False);
end;

The last line of the above code snip demonstrates that the Subtract method has an optional Boolean parameter ACaseSensitive (defaults to True), where AnsiSubtract just places that call internally, and exists to adhere to the convention set by Delphi in its own String methods such as AnsiCompare and AnsiPos (both of which are encapsulated by SmartString, by the way).

Compatibility

Smart Types (along with, at present, all of the LKSL) are compatible with Win32, Win64 and MacOSX. Due to the language features used in the LKSL, it’ll only work with Delphi 2007 and above.

iOS is not supported for XE2, as we have yet to even test it on this platform and we do not develop for iOS anyway. If you’re desperate to use the LKSL (any part of it, not just Smart Types) you’ll either have to submit changes for approval and integration, or you can contract me to add iOS support (since I have no personal interest in the iOS platform, I refuse to pursue this for free).

Where’s the “T”?

You’ve no doubt noticed that the LKSL’s Smart Types are not prefixed with the letter “T” (as is the custom when defining your own Types). This is because the Smart Types behave exactly like basic Value Types (none of which are prefixed with “T”). It is not only more intuitive to prefix the name of types you already know and use with “Smart” to take advantage of these new enhancements, it is easier to read.

I’ve heard all the arguments for and against, but ultimately my mind is made up and they will not be changed.

Got any ideas/requests/recommendations for Smart Type operations?

If you have an idea, request or recommendation for any sort of common operation you’d like to see included in a Smart Type (not just SmartString, but any of the Smart Types), you’re invited to leave a comment with comprehensive details about the idea, how it’s done (where appropriate/possible), and (most importantly) why it should be added.

Please do not post requests etc for any case-specific operations! An example of an inappropriate suggestion would be to include encryption/decryption operations directly into SmartString. This is not a common String operation, and therefore will not be added to the type itself!

There’s no need to suggest anything contained within .NET as we’re already introducing all of the suitable operations found in .NET 4′s Value Types already.

When can I get my hands on the LKSL?

The first roll-out of the LKSL will coincide with the release of Lua4Delphi, as it is the first of my public projects to make extensive use of the LKSL. Of course, the LKSL will continue to grow both along-side other public/private projects, as well as on its own.

Is the LKSL FREE (Open Source) or Commercial?

It’s FREE and Open Source, subject to a fairly liberal license. The only restrictions are that you may not sell the LKSL (its source or the compiled DCUs) for a fee (and that includes a fee for distribution), and you may not make changes to the LKSL’s units yourself. You can, of course, derive from them in your own units, but you must not under any circumstances modify the original sources themselves.

You are (as always) welcome to submit requests and suggested changes to myself (and LaKraven Studios Ltd) for approval and integration, but it is absolutely crucial that you do not modify the sources yourself. This is because any changes you make could very easily break compatibility with other projects which make use of the LKSL. I have stipulated this restriction as a legal requirement of the license primarily for liability purposes, but also because I do not want to be receiving bug reports when said bug is caused by your own modifications to my code.

The final restriction is that derived sources must contain a provided copyright block at the very top of each derived unit, for the sake of attribution.

Those are the only restrictions… beyond that, you may enjoy it as you wish!

Is this the start of a commercial “LaKraven Studios SDK”?

Yes, it is! More info on that when the time is right, but to say that the LKSL itself will continue to be free and Open Source under the aforementioned license.