There are many books and resources about Pascal out there, but too many of them talk about the old Pascal, without classes, units or generics.
So I wrote this quick introduction to what I call modern Object Pascal. Most of the programmers using it don’t really call it "modern Object Pascal", we just call it "our Pascal". But when introducing the language, I feel it’s important to emphasize that it’s a modern, object-oriented language. It evolved a lot since the old (Turbo) Pascal that many people learned in schools long time ago. Feature-wise, it’s quite similar to C++ or Java or C#.
-
It has all the modern features you expect — classes, units, interfaces, generics…
-
It’s compiled to a fast, native code,
-
It’s very type safe,
-
High-level but can also be low-level if you need it to be.
It also has excellent, portable and open-source compiler called the Free Pascal Compiler, http://freepascal.org/ . And an accompanying IDE (editor, debugger, a library of visual components, form designer) called Lazarus http://lazarus.freepascal.org/ . There’s also a proprietary and commercial compiler and IDE Delphi https://www.embarcadero.com/products/Delphi . There’s a lot of libraries (for both FPC and Delphi) available, see https://github.com/Fr0sT-Brutal/awesome-pascal . We also support existing editors like VS Code, see https://castle-engine.io/vscode . Myself, I’m the creator of Castle Game Engine, https://castle-engine.io/ , which is an open-source 3D and 2D game engine using modern Pascal to create games on many platforms (Windows, Linux, macOS, Android, iOS, Nintendo Switch; also WebGL is coming).
This introduction is mostly directed at programmers who already have experience in other languages. We will not cover here the meanings of some universal concepts, like "what is a class", we’ll only show how to do them in Pascal.
link:modern_pascal_code_samples/hello_world.lpr[role=include]
This is a complete program that you can compile and run.
-
If you use the command-line FPC, just create a new file
myprogram.lpr
and executefpc myprogram.lpr
. -
If you use Lazarus, create a new project (menu Project → New Project → Simple Program). Save it as
myprogram
and paste this source code as the main file. Compile using the menu item Run → Compile. -
This is a command-line program, so in either case — just run the compiled executable from the command-line.
The rest of this article talks about the Object Pascal language, so don’t expect to see anything more fancy than the command-line stuff. If you want to see something cool, just create a new GUI project in Lazarus (Project → New Project → Application). Voila — a working GUI application, cross-platform, with native look everywhere, using a comfortable visual component library. The Lazarus and Free Pascal Compiler come with lots of ready units for networking, GUI, database, file formats (XML, json, images…), threading and everything else you may need. I already mentioned my cool Castle Game Engine earlier:)
link:modern_pascal_code_samples/functions_primitives.lpr[role=include]
To return a value from a function, assign something to the magic Result
variable. You can read and set the Result
freely, just like a local variable.
function MyFunction(const S: string): string;
begin
Result := S + 'something';
Result := Result + ' something more!';
Result := Result + ' and more!';
end;
You can also treat the function name (like MyFunction
in example above) as the variable, to which you can assign. But I would discourage it in new code, as it looks "fishy" when used on the right side of the assignment expression. Just use Result
always when you want to read or set the function result.
If you want to call the function itself recursively, you can of course do it. If you’re calling a parameter-less function recursively, be sure to specify the parenthesis ()
(even though in Pascal you can usually omit the parentheses for a parameter-less function), this makes a recursive call to a parameter-less function different from accessing this function’s current result. Like this:
function SumIntegersUntilZero: Integer;
var
I: Integer;
begin
ReadLn(I);
Result := I;
if I <> 0 then
Result := Result + SumIntegersUntilZero();
end;
You can call Exit
to end the execution of the procedure or function before it reaches the final end;
. If you call parameter-less Exit
in a function, it will return the last thing you set as Result
. You can also use Exit(X)
construct, to set the function result and exit now — this is just like return X
construct in C-like languages.
function AddName(const ExistingNames, NewName: string): string;
begin
if ExistingNames = '' then
Exit(NewName);
Result := ExistingNames + ', ' + NewName;
end;
Note that the function result can be discarded. Any function may be used just like a procedure. This makes sense if the function has some side effect (e.g. it modifies a global variable) besides calculating the result. For example:
var
Count: Integer;
MyCount: Integer;
function CountMe: Integer;
begin
Inc(Count);
Result := Count;
end;
begin
Count := 10;
CountMe; // the function result is discarded, but the function is executed, Count is now 11
MyCount := CountMe; // use the result of the function, MyCount equals to Count which is now 12
end.
Use if .. then
or if .. then .. else
to run some code when some condition is satisfied. Unlike in the C-like languages, in Pascal you don’t have to wrap the condition in parenthesis.
var
A: Integer;
B: boolean;
begin
if A > 0 then
DoSomething;
if A > 0 then
begin
DoSomething;
AndDoSomethingMore;
end;
if A > 10 then
DoSomething
else
DoSomethingElse;
// equivalent to above
B := A > 10;
if B then
DoSomething
else
DoSomethingElse;
end;
The else
is paired with the last if
. So this works as you expect:
if A <> 0 then
if B <> 0 then
AIsNonzeroAndBToo
else
AIsNonzeroButBIsZero;
While the example with nested if
above is correct, it is often better to place the nested if
inside a begin
… end
block in such cases. This makes the code more obvious to the reader, and it will remain obvious even if you mess up the indentation. The improved version of the example is below. When you add or remove some else
clause in the code below, it’s obvious to which condition it will apply (to the A
test or the B
test), so it’s less error-prone.
if A <> 0 then
begin
if B <> 0 then
AIsNonzeroAndBToo
else
AIsNonzeroButBIsZero;
end;
The logical operators are called and
, or
, not
, xor
. Their meaning is probably obvious (search for "exclusive or" if you’re unsure what xor does:)). They take boolean arguments, and return a boolean. They can also act as bit-wise operators when both arguments are integer values, in which case they return an integer.
The relational (comparison) operators are =
, <>
, >
, <
, <=
, >=
. If you’re accustomed to C-like languages, note that in Pascal you compare two values (check are they equal) using a single equality character A = B
(unlike in C where you use A == B
). The special assignment operator in Pascal is :=
.
The logical (or bit-wise) operators have a higher precedence than relational operators. You may need to use parenthesis around some expressions to have the desired order of the calculations.
For example this is a compilation error:
var
A, B: Integer;
begin
if A = 0 and B <> 0 then ... // INCORRECT example
The above fails to compile, because the compiler first wants to perform a bit-wise and
in the middle of the expression: (0 and B)
. This is a bit-wise operation which returns an integer value. Then the compiler applies =
operator which yields a boolean value A = (0 and B)
. And finally the "type mismatch" error is risen after trying to compare the boolean value A = (0 and B)
and integer value 0
.
This is correct:
var
A, B: Integer;
begin
if (A = 0) and (B <> 0) then ...
The short-circuit evaluation is used. Consider this expression:
if MyFunction(X) and MyOtherFunction(Y) then...
-
It’s guaranteed that
MyFunction(X)
will be evaluated first. -
And if
MyFunction(X)
returnsfalse
, then the value of expression is known (the value offalse and whatever
is alwaysfalse
), andMyOtherFunction(Y)
will not be executed at all. -
Analogous rule is for
or
expression. There, if the expression is known to betrue
(because the 1st operand istrue
), the 2nd operand is not evaluated. -
This is particularly useful when writing expressions like
if (A <> nil) and A.IsValid then...
This will work OK, even when
A
isnil
. The keywordnil
is a pointer equal to zero (when represented as a number). It is called a null pointer in many other programming languages.
If a different action should be executed depending on the value of some expression, then the case .. of .. end
statement is useful.
case SomeValue of
0: DoSomething;
1: DoSomethingElse;
2: begin
IfItsTwoThenDoThis;
AndAlsoDoThis;
end;
3..10: DoSomethingInCaseItsInThisRange;
11, 21, 31: AndDoSomethingForTheseSpecialValues;
else DoSomethingInCaseOfUnexpectedValue;
end;
The else
clause is optional (and corresponds to default
in C-like languages). When no condition matches, and there’s no else
, then nothing happens.
In you come from C-like languages, and compare this with switch
statement in these languages, you will notice that there is no automatic fall-through. This is a deliberate blessing in Pascal. You don’t have to remember to place break
instructions. In every execution, at most one branch of the case
is executed, that’s it.
Enumerated type in Pascal is a very nice, opaque type. You will probably use it much more often than enums in other languages:)
type
TAnimalKind = (akDuck, akCat, akDog);
The convention is to prefix the enum names with a two-letter shortcut of type name, hence ak
= shortcut for "Animal Kind". This is a useful convention, since the enum names are in the unit (global) namespace. So by prefixing them with ak
prefix, you minimize the chances of collisions with other identifiers.
Note
|
The collisions in names are not a show-stopper. It’s Ok for different units to define the same identifier. But it’s a good idea to try to avoid the collisions anyway, to keep code simple to understand and grep. |
Note
|
You can avoid placing enum names in the global namespace by compiler directive {$scopedenums on} . This means you will have to access them qualified by a type name, like TAnimalKind.akDuck . The need for ak prefix disappears in this situation, and you will probably just call the enums Duck, Cat, Dog . This is similar to C# enums.
|
The fact that enumerated type is opaque means that it cannot be just assigned to and from an integer. However, for special use, you can use Ord(MyAnimalKind)
to forcefully convert enum to int, or typecast TAnimalKind(MyInteger)
to forcefully convert int to enum. In the latter case, make sure to check first whether MyInteger
is in good range (0 to Ord(High(TAnimalKind))
).
Enumerated and ordinal types can be used as array indexes:
type
TArrayOfTenStrings = array [0..9] of string;
TArrayOfTenStrings1Based = array [1..10] of string;
TMyNumber = 0..9;
TAlsoArrayOfTenStrings = array [TMyNumber] of string;
TAnimalKind = (akDuck, akCat, akDog);
TAnimalNames = array [TAnimalKind] of string;
They can also be used to create sets (a bit-fields internally):
type
TAnimalKind = (akDuck, akCat, akDog);
TAnimals = set of TAnimalKind;
var
A: TAnimals;
begin
A := [];
A := [akDuck, akCat];
A := A + [akDog];
A := A * [akCat, akDog];
Include(A, akDuck);
Exclude(A, akDuck);
end;
link:modern_pascal_code_samples/loops.lpr[role=include]
About the repeat
and while
loops:
There are two differences between these loop types:
-
The loop condition has an opposite meaning. In
while .. do
you tell it when to continue, but inrepeat .. until
you tell it when to stop. -
In case of
repeat
, the condition is not checked at the beginning. So therepeat
loop always runs at least once.
About the for I := …
loops:
The for I := .. to .. do …
construction it similar to the C-like for
loop. However, it’s more constrained, as you cannot specify arbitrary actions/tests to control the loop iteration. This is strictly for iterating over a consecutive numbers (or other ordinal types). The only flexibility you have is that you can use downto
instead of to
, to make numbers go downward.
In exchange, it looks clean, and is very optimized in execution. In particular, the expressions for the lower and higher bound are only calculated once, before the loop starts.
Note that the value of the loop counter variable (I
in this example) should be considered undefined after the loop has finished, due to possible optimizations. Accessing the value of I
after the loop may cause a compiler warning. Unless you exit the loop prematurely by Break
or Exit
: in such case, the counter variable is guaranteed to retain the last value.
About the for I in …
loops:
The for I in .. do ..
is similar to foreach
construct in many modern languages. It works intelligently on many built-in types:
-
It can iterate over all values in the array (example above).
-
It can iterate over all possible values of an enumerated type:
var AK: TAnimalKind; begin for AK in TAnimalKind do...
-
It can iterate over all items included in the set:
var Animals: TAnimals; AK: TAnimalKind; begin Animals := [akDog, akCat]; for AK in Animals do ...
-
And it works on custom list types, generic or not, like
TObjectList
orTFPGObjectList
.link:modern_pascal_code_samples/for_in_list.lpr[role=include]
We didn’t yet explain the concept of classes, so the last example may not be obvious to you yet — just carry on, it will make sense later:)
To simply output strings in Pascal, use the Write
or WriteLn
routine. The latter automatically adds a newline at the end.
This is a "magic" routine in Pascal. It takes a variable number of arguments and they can have any type. They are all converted to strings when displaying, with a special syntax to specify padding and number precision.
WriteLn('Hello world!');
WriteLn('You can output an integer: ', 3 * 4);
WriteLn('You can pad an integer: ', 666:10);
WriteLn('You can output a float: ', Pi:1:4);
To explicitly use newline in the string, use the LineEnding
constant (from FPC RTL). (The Castle Game Engine defines also a shorter NL
constant.) Pascal strings do not interpret any special backslash sequences, so writing
WriteLn('One line.\nSecond line.'); // INCORRECT example
doesn’t work like some of you would think. This will work:
WriteLn('One line.' + LineEnding + 'Second line.');
or just this:
WriteLn('One line.');
WriteLn('Second line.');
Note that this will only work in console applications. Make sure you have {$apptype CONSOLE}
(and not {$apptype GUI}
) defined in your main program file. On some operating systems it actually doesn’t matter and will work always (Unix), but on some operating systems trying to write something from a GUI application is an error (Windows).
In the Castle Game Engine: use WriteLnLog
or WriteLnWarning
, never WriteLn
, to print debug information. They will be always directed to some useful output. On Unix, standard output. On Windows GUI application, log file. On Android, the Android logging facility (visible when you use adb logcat
). The use of WriteLn
should be limited to the cases when you write a command-line application (like a 3D model converter / generator) and you know that the standard output is available.
To convert an arbitrary number of arguments to a string (instead of just directly outputting them), you have a couple of options.
-
You can convert particular types to strings using specialized functions like
IntToStr
andFloatToStr
. Furthermore, you can concatenate strings in Pascal simply by adding them. So you can create a string like this:'My int number is ' + IntToStr(MyInt) + ', and the value of Pi is ' + FloatToStr(Pi)
.-
Advantage: Absolutely flexible. There are many
XxxToStr
overloaded versions and friends (likeFormatFloat
), covering many types. Most of them are in theSysUtils
unit. -
Another advantage: Consistent with the reverse functions. To convert a string (for example, user input) back to an integer or float, you use
StrToInt
,StrToFloat
and friends (likeStrToIntDef
). -
Disadvantage: A long concatenation of many
XxxToStr
calls and strings doesn’t look nice.
-
-
The
Format
function, used likeFormat('%d %f %s', [MyInt, MyFloat, MyString])
. This is likesprintf
function in the C-like languages. It inserts the arguments into the placeholders in the pattern. The placeholders may use special syntax to influence formatting, e.g.%.4f
results in a floating-point format with 4 digits after the decimal point.-
Advantage: The separation of pattern string from arguments looks clean. If you need to change the pattern string without touching the arguments (e.g. when translating), you can do it easily.
-
Another advantage: No compiler magic. You can use the same syntax to pass any number of arguments of an arbitrary type in your own routines (declare parameter as an
array of const
). You can then pass these arguments downward toFormat
, or deconstruct the list of parameters and do anything you like with them. -
Disadvantage: Compiler does not check whether the pattern matches the arguments. Using a wrong placeholder type will result in an exception at runtime (
EConvertError
exception, not anything nasty like Access Violation (Segmentation Fault) error).
-
-
WriteStr(TargetString, …)
routine behaves much likeWrite(…)
, except that the result is saved to theTargetString
.-
Advantage: It supports all the features of
Write
, including the special syntax for formatting likePi:1:4
. -
Disadvantage: The special syntax for formatting is a "compiler magic", implemented specifically for routines like this. This is sometimes troublesome, e.g. you cannot create your own routine
MyStringFormatter(…)
that would also allow the special syntax likePi:1:4
. For this reason (and also because it wasn’t implemented for a long time in major Pascal compilers), this construction is not very popular.
-
Units allow you to group common stuff (anything that can be declared), for usage by other units and programs. They are equivalent to modules and packages in other languages. They have an interface section, where you declare what is available for other units and programs, and then the implementation.
link:modern_pascal_code_samples/myunit.pas[role=include]
A program can use a unit by a uses
keyword:
link:modern_pascal_code_samples/myunit_test.lpr[role=include]
Save the unit file MyUnit
as myunit.pas
. That is, lowercase with .pas
extension.
Note
|
Other conventions are possible. E.g. FPC allows other file extensions for units. And some people use Using a different case is also possible. On Windows file systems, the letter case doesn’t matter. But on Unix file systems is does matter and FPC allows only to use the exact same case as was specified in Pascal All in all, we recommend the simple above rule all lowercase, |
Save the program
to a file with:
-
.dpr
extension (short for "Delphi Project"), if you want the project to be compatible with both FPC/Lazarus and Delphi, -
.lpr
extension (short for "Lazarus Project"), if you want to use only FPC/Lazarus.
Note
|
Other conventions are possible and used by some projects. E.g. some projects use .pas for main program file. Some projects use .pp for units or programs. There are reasonable reasons for this (e.g. for FPC programs, that don’t use Lazarus LCL, neither description "Lazarus Project" nor "Delphi Project" are strictly correct)… But for the sake of simplicity, we recommend the above conventions (.dpr or .lpr ), as they cover the most common established practices.
|
A unit may also contain initialization
and finalization
sections. This is the code executed when the program starts and ends.
link:modern_pascal_code_samples/initialization_finalization.pas[role=include]
One unit can also use another unit. Another unit can be used in the interface section, or only in the implementation section. The former allows to define new public stuff (procedures, types…) on top of another unit’s stuff. The latter is more limited (if you use a unit only in the implementation section, you can use its identifiers only in your implementation).
link:modern_pascal_code_samples/anotherunit.pas[role=include]
It is not allowed to have circular unit dependencies in the interface. That is, two units cannot use each other in the interface section.
The reason is that in order to "understand"
the interface section of a unit, the compiler must first "understand" all the units it uses in the interface section. Pascal language follows this rule strictly, and it allows a fast compilation and fully automatic detection on the compiler side what units need to be recompiled. There is no need to use complicated Makefile
files for a simple task of compilation in Pascal, and there is no need to recompile everything just to make sure that all dependencies are updated correctly.
It is OK to make a circular dependency between units when at least one "usage" is only in the implementation. So it’s OK for unit A
to use unit B
in the interface, and then unit B
to use unit A
in the implementation.
Different units may define the same identifier. To keep the code simple to read and search, you should usually avoid it, but it’s not always possible.
In such cases, the last unit on the uses
clause "wins", which means that the identifiers it introduces hide the same identifiers introduced by earlier units.
You can always explicitly define a unit of a given identifier, by using it like MyUnit.MyIdentifier
. This is the usual solution when the identifier you want to use from MyUnit
is hidden by another unit. Of course you can also rearrange the order of units on your uses clause, although this can affect other declarations than the one you’re trying to fix.
{$mode objfpc}{$H+}{$J-}
program showcolor;
// Both Graphics and GoogleMapsEngine units define TColor type.
uses Graphics, GoogleMapsEngine;
var
{ This doesn't work like we want, as TColor ends up
being defined by GoogleMapsEngine. }
// Color: TColor;
{ This works Ok. }
Color: Graphics.TColor;
begin
Color := clYellow;
WriteLn(Red(Color), ' ', Green(Color), ' ', Blue(Color));
end.
In case of units, remember that they have two uses
clauses: one in the interface, and another one in the implementation. The rule later units hide the stuff from earlier units is applied here consistently, which means that units used in the implementation section can hide identifiers from units used in the interface section. However, remember that when reading the interface
section, only the units used in the interface matter. This may create a confusing situation, where two seemingly-equal declarations are considered different by the compiler:
{$mode objfpc}{$H+}{$J-}
unit UnitUsingColors;
// INCORRECT example
interface
uses Graphics;
procedure ShowColor(const Color: TColor);
implementation
uses GoogleMapsEngine;
procedure ShowColor(const Color: TColor);
begin
// WriteLn(ColorToString(Color));
end;
end.
The unit Graphics
(from Lazarus LCL) defines the TColor
type. But the compiler will fail to compile the above unit, claiming that you don’t implement a procedure ShowColor
that matches the interface declaration. The problem is that unit GoogleMapsEngine
also defines a TColor
type. And it is used only in the implementation
section, therefore it shadows the TColor
definition only in the implementation. The equivalent version of the above unit, where the error is obvious, looks like this:
{$mode objfpc}{$H+}{$J-}
unit UnitUsingColors;
// INCORRECT example.
// This is what the compiler "sees" when trying to compile previous example
interface
uses Graphics;
procedure ShowColor(const Color: Graphics.TColor);
implementation
uses GoogleMapsEngine;
procedure ShowColor(const Color: GoogleMapsEngine.TColor);
begin
// WriteLn(ColorToString(Color));
end;
end.
The solution is trivial in this case, just change the implementation to explicitly use TColor
from Graphics
unit. You could fix it also by moving the GoogleMapsEngine
usage, to the interface section and earlier than Graphics
, although this could result in other consequences in real-world cases, when UnitUsingColors
would define more things.
{$mode objfpc}{$H+}{$J-}
unit UnitUsingColors;
interface
uses Graphics;
procedure ShowColor(const Color: TColor);
implementation
uses GoogleMapsEngine;
procedure ShowColor(const Color: Graphics.TColor);
begin
// WriteLn(ColorToString(Color));
end;
end.
Sometimes you want to take an identifier from one unit, and expose it in a new unit. The end result should be that using the new unit will make the identifier available in the namespace.
Sometimes this is necessary to preserve backward compatibility with previous unit versions. Sometimes it’s nice to "hide" an internal unit this way.
This can be done by redefining the identifier in your new unit.
{$mode objfpc}{$H+}{$J-}
unit MyUnit;
interface
uses Graphics;
type
{ Expose TColor from Graphics unit as TMyColor. }
TMyColor = TColor;
{ Alternatively, expose it under the same name.
Qualify with unit name in this case, otherwise
we would refer to ourselves with "TColor = TColor" definition. }
TColor = Graphics.TColor;
const
{ This works with constants too. }
clYellow = Graphics.clYellow;
clBlue = Graphics.clBlue;
implementation
end.
Note that this trick cannot be done as easily with global procedures, functions and variables. With procedures and functions, you could expose a constant pointer to a procedure in another unit (see Callbacks (aka events, aka pointers to functions, aka procedural variables)), but that looks quite dirty.
The usual solution is then to create a trivial "wrapper" functions that underneath simply call the functions from the internal unit, passing the parameters and return values around.
To make this work with global variables, one can use global (unit-level) properties, see Properties.
We have classes. At the basic level, a class is just a container for
-
fields (which is fancy name for "a variable inside a class"),
-
methods (which is fancy name for "a procedure or function inside a class"),
-
and properties (which is a fancy syntax for something that looks like a field, but is in fact a pair of methods to get and set something; more in Properties).
-
Actually, there are more possibilities, described in More stuff inside classes and nested classes.
type
TMyClass = class
MyInt: Integer; // this is a field
property MyIntProperty: Integer read MyInt write MyInt; // this is a property
procedure MyMethod; // this is a method
end;
procedure TMyClass.MyMethod;
begin
WriteLn(MyInt + 10);
end;
We have inheritance and virtual methods.
link:modern_pascal_code_samples/inheritance.lpr[role=include]
By default methods are not virtual, declare them with virtual
to make them. Overrides must be marked with override
, otherwise you will get a warning. To hide a method without overriding (usually you don’t want to do this, unless you now what you’re doing) use reintroduce
.
To test the class of an instance at runtime, use the is
operator. To typecast the instance to a specific class, use the as
operator.
link:modern_pascal_code_samples/is_as.lpr[role=include]
Instead of casting using X as TMyClass
, you can also use the unchecked typecast TMyClass(X)
. This is faster, but results in an undefined behavior if the X
is not, in fact, a TMyClass
descendant. So don’t use the TMyClass(X)
typecast, or use it only in a code where it’s blindingly obvious that it’s correct, for example right after testing with is
:
if A is TMyClass then
(A as TMyClass).CallSomeMethodOfMyClass;
// below is marginally faster
if A is TMyClass then
TMyClass(A).CallSomeMethodOfMyClass;
Properties are a very nice "syntax sugar" to
-
Make something that looks like a field (can be read and set) but underneath is realized by calling a getter and setter methods. The typical usage is to perform some side-effect (e.g. redraw the screen) each time some value changes.
-
Make something that looks like a field, but is read-only. In effect, it’s like a constant or a parameter-less function.
type
TWebPage = class
private
FURL: string;
FColor: TColor;
function SetColor(const Value: TColor);
public
{ No way to set it directly.
Call the Load method, like Load('http://www.freepascal.org/'),
to load a page and set this property. }
property URL: string read FURL;
procedure Load(const AnURL: string);
property Color: TColor read FColor write SetColor;
end;
procedure TWebPage.Load(const AnURL: string);
begin
FURL := AnURL;
NetworkingComponent.LoadWebPage(AnURL);
end;
function TWebPage.SetColor(const Value: TColor);
begin
if FColor <> Value then
begin
FColor := Value;
// for example, cause some update each time value changes
Repaint;
// as another example, make sure that some underlying instance,
// like a "RenderingComponent" (whatever that is),
// has a synchronized value of Color.
RenderingComponent.Color := Value;
end;
end;
Note that instead of specifying a method, you can also specify a field (typically a private field) to directly get or set. In the example above, the Color
property uses a setter method SetColor
. But for getting the value, the Color
property refers directly to the private field FColor
. Directly referring to a field is faster than implementing trivial getter or setter methods (faster for you, and faster at execution).
When declaring a property you specify:
-
Whether it can be read, and how (by directly reading a field, or by using a "getter" method).
-
And, in a similar manner, whether it can be set, and how (by directly writing to a designated field, or by calling a "setter" method).
The compiler checks that the types and parameters of indicated fields and methods match with the property type. For example, to read an Integer
property you have to either provide an Integer
field, or a parameter-less method that returns an Integer
.
Technically, for the compiler, the "getter" and "setter" methods are just normal methods and they can do absolutely anything (including side-effects or randomization). But it’s a good convention to design properties to behave more-or-less like fields:
-
The getter function should have no visible side-effects (e.g. it should not read some input from file / keyboard). It should be deterministic (no randomization, not even pseudo-randomization :). Reading a property many times should be valid, and return the same value, if nothing changed in-between.
Note that it’s OK for getter to have some invisible side-effect, for example to cache a value of some calculation (known to produce the same results for given instance), to return it faster next time. This is in fact one of the cool possibilities of a "getter" function.
-
The setter function should always set the requested value, such that calling the getter yields it back. Do not reject invalid values silently in the "setter" (raise an exception if you must). Do not convert or scale the requested value. The idea is that after
MyClass.MyProperty := 123;
the programmer can expect thatMyClass.MyProperty = 123
. -
The read-only properties are often used to make some field read-only from the outside. Again, the good convention is to make it behave like a constant, at least constant for this object instance with this state. The value of the property should not change unexpectedly. Make it a function, not a property, if using it has a side effect or returns something random.
-
The "backing" field of a property is almost always private, since the idea of a property is to encapsulate all outside access to it.
-
It’s technically possible to make set-only properties, but I have not yet seen a good example of such thing:)
Note
|
Properties can also be defined outside of class, at a unit level. They serve an analogous purpose then: look like a global variable, but are backed by a getter and setter routines. |
Published properties are the basis of a serialization (also known as streaming components) in Pascal. Serialization means that the instance data is recorded into a stream (like a file), from which it can be later restored.
Serialization is what happens when Lazarus reads (or writes) the component state from an xxx.lfm
file. (In Delphi, the equivalent file has .dfm
extension.) You can also use this mechanism explicitly, using routines like ReadComponentFromTextStream
from the LResources
unit. You can also use other serialization algorithms, e.g. FpJsonRtti
unit (serializing to JSON).
In the Castle Game Engine: Use the CastleComponentSerialize
unit (based on FpJsonRtti
) to serialize our user-interface and transformation component hierarchies.
At each property, you can declare some additional things that will be helpful for any serialization algorithm:
-
You can specify the property default value (using the
default
keyword). Note that you are still required to initialize the property in the constructor to this exact default value (it is not done automatically). Thedefault
declaration is merely an information to the serialization algorithm: "when the constructor finishes, the given property has the given value". -
Whether the property should be stored at all (using the
stored
keyword).
We have exceptions. They can be caught with try … except … end
clauses, and we have finally sections like try … finally … end
.
link:modern_pascal_code_samples/exception_finally.lpr[role=include]
Note that the finally
clause is executed even if you exit the block using the Exit
(from function / procedure / method) or Break
or Continue
(from loop body).
See the Exceptions chapter for more in-depth description of exceptions.
As in most object-oriented languages, we have visibility specifiers to hide fields / methods / properties.
The basic visibility levels are:
public
-
everyone can access it, including the code in other units.
private
-
only accessible in this class.
protected
-
only accessible in this class and descendants.
The explanation of private
and protected
visibility above is not precisely true. The code in the same unit can overcome their limits, and access the private
and protected
stuff freely. Sometimes this is a nice feature, allows you to implement tightly-connected classes. Use strict private
or strict protected
to secure your classes more tightly. See the Private and strict private.
By default, if you don’t specify the visibility, then the visibility of declared stuff is public
. The exception is for classes compiled with {$M+}
, or descendants of classes compiled with {$M+}
, which includes all descendants of TPersistent
, which also includes all descendants of TComponent
(since TComponent
descends from TPersistent
). For them, the default visibility specifier is published
, which is like public
, but in addition the streaming system knows to handle this.
Not every field and property type is allowed in the published
section (not every type can be streamed, and only classes can be streamed from simple fields). Just use public
if you don’t care about streaming but want something available to all users.
The special keyword Self
can be used within the class implementation to explicitly refer to your own instance. It is equivalent to this
from C++, Java and similar languages.
Within a method implementation, if you call another method, then by default you call the method of your own class. In the example code below, TMyClass2.MyOtherMethod
calls MyMethod
, which ends up calling TMyClass2.MyMethod
.
link:modern_pascal_code_samples/method_calls_inheritance_1.lpr[role=include]
If the method is not defined in a given class, then it calls the method of an ancestor class. In effect, when you call MyMethod
on an instance of TMyClass2
, then
-
The compiler looks for
TMyClass2.MyMethod
. -
If not found, it looks for
TMyClass1.MyMethod
. -
If not found, it looks for
TObject.MyMethod
. -
if not found, then the compilation fails.
You can test it by commenting out the TMyClass2.MyMethod
definition in the example above. In effect, TMyClass1.MyMethod
will be called by TMyClass2.MyOtherMethod
.
Sometimes, you don’t want to call the method of your own class. You want to call the method of an ancestor (or ancestor’s ancestor, and so on). To do this, add the keyword inherited
before the call to MyMethod
, like this:
inherited MyMethod;
This way you force the compiler to start searching from an ancestor class. In our example, it means that compiler is searching for MyMethod
inside TMyClass1.MyMethod
, then TObject.MyMethod
, and then gives up. It does not even consider using the implementation of TMyClass2.MyMethod
.
Tip
|
Go ahead, change the implementation of TMyClass2.MyOtherMethod above to use inherited MyMethod , and see the difference in the output.
|
The inherited
call is often used to call the ancestor method of the same name. This way the descendants can enhance the ancestors (keeping the ancestor functionality, instead of replacing the ancestor functionality). Like in the example below.
link:modern_pascal_code_samples/method_calls_inherited.lpr[role=include]
Since using inherited
to call a method with the same name, with the same arguments, is a very often case, there is a special shortcut for it: you can just write inherited;
(inherited
keyword followed immediately by a semicolon, instead of a method name). This means "call an inherited method with the same name, passing it the same arguments as the current method".
Tip
|
In the above example, all the inherited …; calls could be replaced by a simple inherited; .
|
Note 1: The inherited;
is really just a shortcut for calling the ancestor’s method with the same variables passed in. If you have modified your own parameter (which is possible, if the parameter is not const
), then the ancestor’s method can receive different input values from your descendant. Consider this:
procedure TMyClass2.MyMethod(A: Integer);
begin
WriteLn('TMyClass2.MyMethod beginning ', A);
A := 456;
{ This calls TMyClass1.MyMethod with A = 456,
regardless of the A value passed to this method (TMyClass2.MyMethod). }
inherited;
WriteLn('TMyClass2.MyMethod ending ', A);
end;
Note 2: You usually want to make the MyMethod
virtual when many classes (along the "inheritance chain") define it. More about the virtual methods in the section below. But the inherited
keyword works regardless if the method is virtual or not. The inherited
always means that the compiler starts searching for the method in an ancestor, and it makes sense for both virtual and not virtual methods.
By default, the methods are not virtual. This is similar to C++, and unlike Java.
When a method is not virtual, the compiler determines which method to call based on the currently declared class type, not based on the actually created class type. The difference seems subtle, but it’s important when your variable is declared to have a class like TFruit
, but it may be in fact a descendant class like TApple
.
The idea of the object-oriented programming is that the descendant class is always as good as the ancestor, so the compiler allows to use a descendant class always when the ancestor is expected. When your method is not virtual, this can have undesired consequences. Consider the example below:
link:modern_pascal_code_samples/without_virtual_methods.lpr[role=include]
This example will print
We have a fruit with class TApple We eat it: Eating a fruit
In effect, the call Fruit.Eat
called the TFruit.Eat
implementation, and nothing calls the TApple.Eat
implementation.
If you think about how the compiler works, this is natural: when you wrote the Fruit.Eat
, the Fruit
variable was declared to hold a class TFruit
. So the compiler was searching for the method called Eat
within the TFruit
class. If the TFruit
class would not contain such method, the compiler would search within an ancestor (TObject
in this case). But the compiler cannot search within descendants (like TApple
), as it doesn’t know whether the actual class of Fruit
is TApple
, TFruit
, or some other TFruit
descendant (like a TOrange
, not shown in the example above).
In other words, the method to be called is determined at compile-time.
Using the virtual methods changes this behavior. If the Eat
method would be virtual (an example of it is shown below), then the actual implementation to be called is determined at runtime. If the Fruit
variable will hold an instance of the class TApple
(even if it’s declared as TFruit
), then the Eat
method will be searched within the TApple
class first.
In Object Pascal, to define a method as virtual, you need to
-
Mark its first definition (in the top-most ancestor) with the
virtual
keyword. -
Mark all the other definitions (in the descendants) with the
override
keyword. All the overridden versions must have exactly the same parameters (and return the same types, in case of functions).
link:modern_pascal_code_samples/with_virtual_methods.lpr[role=include]
This example will print
We have a fruit with class TApple We eat it: Eating an apple
Internally, virtual methods work by having so-called virtual method table associated with each class. This table is a list of pointers to the implementations of virtual methods for this class. When calling the Eat
method, the compiler looks into a virtual method table associated with the actual class of Fruit
, and uses a pointer to the Eat
implementation stored there.
If you don’t use the override
keyword, the compiler will warn you that you’re hiding (obscuring) the virtual method of an ancestor with a non-virtual definition. If you’re sure that this is what you want, you can add a reintroduce
keyword. But in most cases, you will rather want to keep the method virtual, and add the override
keyword, thus making sure that it’s always invoked correctly.
The class instances have to be manually freed, otherwise you get memory leaks. I advise using FPC -gl -gh
options to detect memory leaks (see https://castle-engine.io/manual_optimization.php#section_memory ).
Note that this doesn’t concern raised exceptions. Although you do create a class when raising an exception (and it’s a perfectly normal class, and you can create your own classes for this purpose too). But this class instance is freed automatically.
To free the class instance, it’s best to call FreeAndNil(A)
from SysUtils
unit on your class instance. It checks whether A
is nil
, if not — calls its destructor, and sets A
to nil
. So calling it many times in a row is not an error.
It is more-or-less a shortcut for
if A <> nil then
begin
A.Destroy;
A := nil;
end;
Actually, that’s an oversimplification, as FreeAndNil
does a useful trick and sets the variable A
to nil
before calling the destructor on a suitable reference. This helps to prevent a certain class of bugs — the idea is that the "outside" code should never access a half-destructed instance of the class.
Often you will also see people using the A.Free
method, which is like doing
if A <> nil then
A.Destroy;
This frees the A
, unless it’s nil
.
Note that in normal circumstances, you should never call a method on an instance which may be nil
. So the call A.Free
may look suspicious at the first sight, if A
can be nil
. However, the Free
method is an exception to this rule. It does something dirty in the implementation — namely, checks whether Self <> nil
.
Note
|
This trick (officially allowing the method to be used with In the implementation of such method, as long as We discourage from using this trick in your own code (for virtual or non-virtual methods) as it is counter-intuitive to normal usage. In general all instance methods should be able to assume that they work on valid (non-nil) instance and can access fields and call any other methods (virtual or not). |
We advise using FreeAndNil(A)
always, without exceptions, and never to call directly the Free
method or Destroy
destructor.
The Castle Game Engine does it like that. It helps to keep a nice assertion that all references are either nil, or point to valid instances. But note that using FreeAndNil(A)
doesn’t guarantee this assertion. For example, if you copy the instance reference, and call FreeAndNil(A)
on one copy, the other copy will be a non-nil dangling pointer.
A := TMyClass.Create;
B := A;
FreeAndNil(A);
// B now contains a dangling pointer
More about dealing with this in the later section about "Free notification".
Still, FreeAndNil(A)
takes care of the most trivial cases, so it’s a good habit to use it IMHO. You will appreciate it when debuggging some errors, it is nice to easily observe "X
is already freed, because X
is nil
now".
In many situations, the need to free the instance is not much problem. You just write a destructor, that matches a constructor, and deallocates everything that was allocated in the constructor (or, more completely, in the whole lifetime of the class). Be careful to only free each thing once. Usually it’s a good idea to set the freed reference to nil
, usually it’s most comfortable to do it by calling the FreeAndNil(A)
.
So, like this:
uses SysUtils;
type
TGun = class
end;
TPlayer = class
Gun1, Gun2: TGun;
constructor Create;
destructor Destroy; override;
end;
constructor TPlayer.Create;
begin
inherited;
Gun1 := TGun.Create;
Gun2 := TGun.Create;
end;
destructor TPlayer.Destroy;
begin
FreeAndNil(Gun1);
FreeAndNil(Gun2);
inherited;
end;
To avoid the need to explicitly free the instance, one can also use the TComponent
feature of "ownership". An object that is owned will be automatically freed by the owner. The mechanism is smart and it will never free an already freed instance (so things will also work correctly if you manually free the owned object earlier). We can change the previous example to this:
uses SysUtils, Classes;
type
TGun = class(TComponent)
end;
TPlayer = class(TComponent)
Gun1, Gun2: TGun;
constructor Create(AOwner: TComponent); override;
end;
constructor TPlayer.Create(AOwner: TComponent);
begin
inherited;
Gun1 := TGun.Create(Self);
Gun2 := TGun.Create(Self);
end;
Note that we need to override a virtual TComponent
constructor here. So we cannot change the constructor parameters. (Actually, you can — declare a new constructor with reintroduce
. But be careful, as some functionality, e.g. streaming, will still use the virtual constructor, so make sure it works right in either case.)
Note that you can always use nil
value for the owner. This way the "ownership" mechanism will not be used for this component. It makes sense if you need to use the TComponent
descendant, but you want to always manually free it. To do this, you would create a component descendant like this: ManualGun := TGun.Create(nil);
.
Another mechanism for automatic freeing is the OwnsObjects
functionality (by default already true
!) of list-classes like TFPGObjectList
or TObjectList
. So we can also write:
uses SysUtils, Classes, FGL;
type
TGun = class
end;
TGunList = specialize TFPGObjectList<TGun>;
TPlayer = class
Guns: TGunList;
Gun1, Gun2: TGun;
constructor Create;
destructor Destroy; override;
end;
constructor TPlayer.Create;
begin
inherited;
// Actually, the parameter true (OwnsObjects) is already the default
Guns := TGunList.Create(true);
Gun1 := TGun.Create;
Guns.Add(Gun1);
Gun2 := TGun.Create;
Guns.Add(Gun2);
end;
destructor TPlayer.Destroy;
begin
{ We have to take care to free the list.
It will automatically free its contents. }
FreeAndNil(Guns);
{ No need to free the Gun1, Gun2 anymore. It's a nice habit to set to "nil"
their references now, as we know they are freed. In this simple class,
with so simple destructor, it's obvious that they cannot be accessed
anymore -- but doing this pays off in case of larger and more complicated
destructors.
Alternatively, we could avoid declaring Gun1 and Gun2,
and instead use Guns[0] and Guns[1] in own code.
Or create a method like Gun1 that returns Guns[0]. }
Gun1 := nil;
Gun2 := nil;
inherited;
end;
Beware that the list classes "ownership" mechanism is simple, and you will get an error if you free the instance using some other means, while it’s also contained within a list. Use the Extract
method to remove something from a list without freeing it, thus taking the responsibility to free it yourself.
In the Castle Game Engine: The descendants of TX3DNode
have automatic memory management when inserted as children of another TX3DNode
. The root X3D node, TX3DRootNode
, is in turn usually owned by TCastleSceneCore
. Some other things also have a simple ownership mechanism — look for parameters and properties called OwnsXxx
.
As you saw in the examples above, when the class is destroyed, its destructor
called Destroy
is called.
In theory, you could have multiple destructors, but in practice it’s almost never a good idea. It’s much easier to have only one destructor called Destroy
, which is in turn called by the Free
method, which is in turn called by the FreeAndNil
procedure.
The Destroy
destructor in the TObject
is defined as a virtual method, so you should always mark it with the override
keyword in all your classes (since all classes descend from TObject
). This makes the Free
method work correctly. Recall how the virtual methods work from the Virtual methods, override and reintroduce.
Note
|
This information about destructors is, indeed, inconsistent with the constructors. It’s normal that a class has multiple constructors. Usually they are all called Also, the This all gives you a bit of extra flexibility when defining constructors. It is often not necessary to make them virtual, so by default you’re not forced to do it. Note, however, that this changes for |
If you copy a reference to the instance, such that you have two references to the same memory, and then one of them is freed — the other one becomes a "dangling pointer". It should not be accessed, as it points to a memory that is no longer allocated. Accessing it may result in a runtime error, or garbage being returned (as the memory may be reused for other stuff in your program).
Using the FreeAndNil
to free the instance doesn’t help here. FreeAndNil
sets to nil
only the reference it got — there’s no way for it to set all other references automatically. Consider this code:
var
Obj1, Obj2: TObject;
begin
Obj1 := TObject.Create;
Obj2 := Obj1;
FreeAndNil(Obj1);
// what happens if we access Obj1 or Obj2 here?
end;
-
At the end of this block, the
Obj1
isnil
. If some code has to access it, it can reliably useif Obj1 <> nil then …
to avoid calling methods on a freed instance, likeif Obj1 <> nil then WriteLn(Obj1.ClassName);
Trying to access a field of a
nil
instance results in a predictable exception at runtime. So even if some code will not checkObj1 <> nil
, and will blindly accessObj1
field, you will get a clear exception at runtime.Same goes for calling a virtual method, or calling a non-virtual method that accessed a field of a
nil
instance. -
With
Obj2
, things are less predictable. It’s notnil
, but it’s invalid. Trying to access a field of a non-nil invalid instance results in an unpredictable behavior — maybe an access violation exception, maybe a garbage data returned.
There are various solutions to it:
-
One solution is to, well, be careful and read the documentation. Don’t assume anything about the lifetime of the reference, if it’s created by other code. If a class
TCar
has a field pointing to some instance ofTWheel
, it’s a convention that the reference to wheel is valid as long as the reference to car exists, and the car will free its wheels inside its destructor. But that’s just a convention, the documentation should mention if there’s something more complicated going on. -
In the above example, right after freeing the
Obj1
instance, you can simply set theObj2
variable explicitly tonil
. That’s trivial in this simple case. -
The most future-proof solution is to use
TComponent
class "free notification" mechanism. One component can be notified when another component is freed, and thus set its reference tonil
.Thus you get something like a weak reference. It can cope with various usage scenarios, for example you can let the code from outside of the class to set your reference, and the outside code can also free the instance at anytime.
This requires both classes to descend from
TComponent
. Using it in general boils down to callingFreeNotification
,RemoveFreeNotification
, and overridingNotification
.Here’s a complete example, showing how to use this mechanism, together with constructor / destructor and a setter property. Sometimes it can be done simpler, but this is the full-blown version that is always correct:)
type TControl = class(TComponent) end; TContainer = class(TComponent) private FSomeSpecialControl: TControl; procedure SetSomeSpecialControl(const Value: TControl); protected procedure Notification(AComponent: TComponent; Operation: TOperation); override; public destructor Destroy; override; property SomeSpecialControl: TControl read FSomeSpecialControl write SetSomeSpecialControl; end; implementation procedure TContainer.Notification(AComponent: TComponent; Operation: TOperation); begin inherited; if (Operation = opRemove) and (AComponent = FSomeSpecialControl) then { set to nil by SetSomeSpecialControl to clean nicely } SomeSpecialControl := nil; end; procedure TContainer.SetSomeSpecialControl(const Value: TControl); begin if FSomeSpecialControl <> Value then begin if FSomeSpecialControl <> nil then FSomeSpecialControl.RemoveFreeNotification(Self); FSomeSpecialControl := Value; if FSomeSpecialControl <> nil then FSomeSpecialControl.FreeNotification(Self); end; end; destructor TContainer.Destroy; begin { set to nil by SetSomeSpecialControl, to detach free notification } SomeSpecialControl := nil; inherited; end;
In Castle Game Engine we encourage to use TFreeNotificationObserver
from CastleClassUtils
unit instead of directly calling FreeNotification
, RemoveFreeNotification
and overriding Notification
.
In general using TFreeNotificationObserver
looks a bit simpler than using FreeNotification
mechanism directly (though I admit it is a matter of taste). But in particular when the same class instance must be observed because of multiple reasons then TFreeNotificationObserver
is much simpler to use (directly using FreeNotification
in this case can get complicated, as you have to watch to not unregister the notification too soon).
This is the example code using TFreeNotificationObserver
, to achieve the same effect as example in the previous section:
type
TControl = class(TComponent)
end;
TContainer = class(TComponent)
private
FSomeSpecialControlObserver: TFreeNotificationObserver;
FSomeSpecialControl: TControl;
procedure SetSomeSpecialControl(const Value: TControl);
procedure SomeSpecialControlFreeNotification(const Sender: TFreeNotificationObserver);
public
constructor Create(AOwner: TComponent); override;
property SomeSpecialControl: TControl
read FSomeSpecialControl write SetSomeSpecialControl;
end;
implementation
uses CastleComponentSerialize;
constructor TContainer.Create(AOwner: TComponent);
begin
inherited;
FSomeSpecialControlObserver := TFreeNotificationObserver.Create(Self);
FSomeSpecialControlObserver.OnFreeNotification := {$ifdef FPC}@{$endif} SomeSpecialControlFreeNotification;
end;
procedure TContainer.SetSomeSpecialControl(const Value: TControl);
begin
if FSomeSpecialControl <> Value then
begin
FSomeSpecialControl := Value;
FSomeSpecialControlObserver.Observed := Value;
end;
end;
procedure TContainer.SomeSpecialControlFreeNotification(const Sender: TFreeNotificationObserver);
begin
// set property to nil when the referenced component is freed
SomeSpecialControl := nil;
end;
Exceptions allow to interrupt the normal execution of the code.
-
At any point within the program, you can raise an exception using the
raise
keyword. In effect the lines of code following theraise …
call will not execute. -
An exception may be caught using a
try … except … end
construction. Catching an exception means that you somehow "deal" with exception, and the following code should execute as usual, the exception is no longer propagated upward.Note: If an exception is raised but never caught, it will cause the entire application to stop with an error.
-
But in LCL applications, the exceptions are always caught around events (and cause LCL dialog box) if you don’t catch them earlier.
-
In Castle Game Engine applications using
CastleWindow
, we similarly always catch exceptions around your events (and display proper dialog box). -
So it is not so easy to make an exception that is not caught anywhere (not caught in your code, LCL code, CGE code…).
-
-
Although an exception breaks the execution, you can use the
try … finally … end
construction to execute some code always, even if the code was interrupted by an exception.The
try … finally … end
construction also works when code is interrupted byBreak
orContinue
orExit
keywords. The point is to always execute code in thefinally
section.
An "exception" is, in general, any class instance.
-
The compiler does not enforce any particular class. You just must call
raise XXX
whereXXX
is an instance of any class. Any class (so, anything descending fromTObject
) is fine. -
It is a standard convention for exception classes to descend from a special
Exception
class. TheException
class extendsTObject
, adding a stringMessage
property and a constructor to easily set this property. All exceptions raised by the standard library descend fromException
. We advise to follow this convention. -
Exception classes (by convention) have names that start with
E
, notT
. LikeESomethingBadHappened
. -
The compiler will automatically free exception object when it is handled. Don’t free it yourself.
In most cases, you just construct the object at the same time when you call
raise
, likeraise ESomethingBadHappened.Create('Description of what bad thing happened.')
.
If you want to raise your own exception, declare it and call raise …
when appropriate:
type
EInvalidParameter = class(Exception);
function ReadParameter: String;
begin
Result := Readln;
if Pos(' ', Result) <> 0 then
raise EInvalidParameter.Create('Invalid parameter, space is not allowed');
end;
Note that the expression following the raise
should be a valid class instance to raise. You will almost always create the exception instance here.
You can also use the CreateFmt
constructor, which is a comfortable shortcut to Create(Format(MessageFormat, MessageArguments))
. This is a common way to provide more information to the exception message. We can improve the previous example like this:
type
EInvalidParameter = class(Exception);
function ReadParameter: String;
begin
Result := Readln;
if Pos(' ', Result) <> 0 then
raise EInvalidParameter.CreateFmt('Invalid parameter %s, space is not allowed', [Result]);
end;
You can catch an exception like this:
var
Parameter1, Parameter2, Parameter3: String;
begin
try
WriteLn('Input 1st parameter:');
Parameter1 := ReadParameter;
WriteLn('Input 2nd parameter:');
Parameter2 := ReadParameter;
WriteLn('Input 3rd parameter:');
Parameter3 := ReadParameter;
except
// capture EInvalidParameter raised by one of the above ReadParameter calls
on EInvalidParameter do
WriteLn('EInvalidParameter exception occurred');
end;
end;
To improve the above example, we can declare the name for the exception instance (we will use E
in the example). This way we can print the exception message:
try
...
except
on E: EInvalidParameter do
WriteLn('EInvalidParameter exception occurred with message: ' + E.Message);
end;
One could also test for multiple exception classes:
try
...
except
on E: EInvalidParameter do
WriteLn('EInvalidParameter exception occurred with message: ' + E.Message);
on E: ESomeOtherException do
WriteLn('ESomeOtherException exception occurred with message: ' + E.Message);
end;
You can also react to any exception raised, if you don’t use any on
expression:
try
...
except
WriteLn('Warning: Some exception occurred');
end;
// WARNING: DO NOT FOLLOW THIS EXAMPLE WITHOUT READING A WARNING BELOW
// ABOUT "CAPTURING ALL EXCEPTIONS"
In general you should only catch exceptions of a specific class, that signal a particular problem that you know what to do with. Be careful with catching exceptions of a general type (like catching any Exception
or any TObject
), as you may easily catch too much, and later cause troubles when debugging other problems. As in all programming languages with exceptions, the good rule to follow is to never capture an exception that you do not know how to handle. In particular, do not capture an exception just as a simple workaround of the problem, without investigating first why the exception occurs.
-
Does the exception indicate a problem in user input? Then you should report it to user.
-
Does the exception indicate a bug in your code? Then you should fix the code, to avoid the exception from happening at all.
Another way to capture all exceptions is to use:
try
...
except
on E: TObject do
WriteLn('Warning: Some exception occurred');
end;
// WARNING: DO NOT FOLLOW THIS EXAMPLE WITHOUT READING A WARNING ABOVE
// ABOUT "CAPTURING ALL EXCEPTIONS"
Although usually it is enough to capture Exception
:
try
...
except
on E: Exception do
WriteLn('Warning: Some exception occurred: ' + E.ClassName + ', message: ' + E.Message);
end;
// WARNING: DO NOT FOLLOW THIS EXAMPLE WITHOUT READING A WARNING ABOVE
// ABOUT "CAPTURING ALL EXCEPTIONS"
You can "re-raise" the exception in the except … end
block, if you decide so. You can just do raise E
if the exception instance is E
, you can also just use parameter-less raise
. For example:
try
...
except
on E: EInvalidSoundFile do
begin
if E.InvalidUrl = 'http://example.com/blablah.wav' then
WriteLn('Warning: loading http://example.com/blablah.wav failed, ignore it')
else
raise;
end;
end;
Note that, although the exception is an instance of an object, you should never manually free it after raising. The compiler will generate proper code that makes sure to free the exception object once it’s handled.
Often you use try .. finally .. end
construction to free an instance of some object, regardless if an exception occurred when using this object. The way to write it looks like this:
procedure MyProcedure;
var
MyInstance: TMyClass;
begin
MyInstance := TMyClass.Create;
try
MyInstance.DoSomething;
MyInstance.DoSomethingElse;
finally
FreeAndNil(MyInstance);
end;
end;
This works reliably always, and does not cause memory leaks, even if MyInstance.DoSomething
or MyInstance.DoSomethingElse
raise an exception.
Note that this takes into account that local variables, like MyInstance
above, have undefined values (may contain random "memory garbage") before the first assignment. That is, writing something like this would not be valid:
// INCORRECT EXAMPLE:
procedure MyProcedure;
var
MyInstance: TMyClass;
begin
try
CallSomeOtherProcedure;
MyInstance := TMyClass.Create;
MyInstance.DoSomething;
MyInstance.DoSomethingElse;
finally
FreeAndNil(MyInstance);
end;
end;
The above example is not valid: if an exception occurs within TMyClass.Create
(a constructor may also raise an exception), or within the CallSomeOtherProcedure
, then the MyInstance
variable is not initialized. Calling FreeAndNil(MyInstance)
will try to call destructor of MyInstance
, which will most likely crash with Access Violation (Segmentation Fault) error. In effect, one exception causes another exception, which will make the error report not very useful: you will not see the message of the original exception.
Sometimes it is justified to fix the above code by first initializing all local variables to nil
(on which calling FreeAndNil
is safe, and will not do anything). This makes sense if you free a lot of class instances. So the two code examples below work equally well:
procedure MyProcedure;
var
MyInstance1: TMyClass1;
MyInstance2: TMyClass2;
MyInstance3: TMyClass3;
begin
MyInstance1 := TMyClass1.Create;
try
MyInstance1.DoSomething;
MyInstance2 := TMyClass2.Create;
try
MyInstance2.DoSomethingElse;
MyInstance3 := TMyClass3.Create;
try
MyInstance3.DoYetAnotherThing;
finally
FreeAndNil(MyInstance3);
end;
finally
FreeAndNil(MyInstance2);
end;
finally
FreeAndNil(MyInstance1);
end;
end;
It is probably more readable in the form below:
procedure MyProcedure;
var
MyInstance1: TMyClass1;
MyInstance2: TMyClass2;
MyInstance3: TMyClass3;
begin
MyInstance1 := nil;
MyInstance2 := nil;
MyInstance3 := nil;
try
MyInstance1 := TMyClass1.Create;
MyInstance1.DoSomething;
MyInstance2 := TMyClass2.Create;
MyInstance2.DoSomethingElse;
MyInstance3 := TMyClass3.Create;
MyInstance3.DoYetAnotherThing;
finally
FreeAndNil(MyInstance3);
FreeAndNil(MyInstance2);
FreeAndNil(MyInstance1);
end;
end;
Note
|
In this simple example, you could also make a valid argument that the code should be split into 3 separate procedures, one calling each other. |
The final section in the try .. finally .. end
block executes in most possible scenarios when you leave the main code. Consider this:
try
A;
finally
B;
end;
So B
will execute if
-
The
A
raised (and didn’t catch) an exception. -
Or you will call
Exit
or (if you’re in the loop)Break
orContinue
right after callingA
. -
Or none of the above happened, and the code in
A
just executed without any exception, and you didn’t callExit
,Break
orContinue
either.
The only way to really avoid the B
being executed is to unconditionally interrupt the application process using Halt
or some platform-specific APIs (like libc exit on Unix) inside A
. Which generally shall not be done — it’s more flexible to use exceptions to interrupt the application, because it allows some other code to have a chance to clean up.
Note
|
The try .. finally .. end doesn’t catch the exception. The exception will still propagate upward, and can be caught by the try .. except .. end block outside of this one.
|
An example of try .. finally .. end
together with Exit
calls:
procedure MyProcedure;
begin
try
WriteLn('Do something');
Exit;
WriteLn('This will not happen');
finally
WriteLn('This will happen regardless if we have left the block through Exception, Exit, Continue, Break, etc.');
end;
WriteLn('This will not happen');
end;
See the Exceptions chapter for more in-depth description of exceptions including how to raise
them and use try … except … end
to catch them.
-
In case of Lazarus LCL, the exceptions raised during events (various callbacks assigned to
OnXxx
properties of LCL components) will be captured and will result in a nice dialog message, that allows the user to continue and stop the application. This means that your own exceptions do not "get out" fromApplication.ProcessMessages
, so they do not automatically break the application. You can configure what happens usingTApplicationProperties.OnException
. -
Similarly in case of Castle Game Engine with
CastleWindow
: the exception is internally captured and results in nice error message. So exceptions do not "get out" fromApplication.ProcessMessages
. Again, you can configure what happens usingApplication.OnException
. -
Some other GUI libraries may do a similar thing to above.
-
In case of other applications, you can configure how the exception is displayed by assigning a global callback to
OnHaltProgram
.
Modern programs should use TStream
class and its many descendants to do input / output. It has many useful descendants, like TFileStream
, TMemoryStream
, TStringStream
.
link:modern_pascal_code_samples/file_stream.lpr[role=include]
In the Castle Game Engine: You should use the Download
function to create a stream that obtains data from any URL. Regular files, HTTP and HTTPS resources, Android assets and more are supported this way. Moreover, to open the resource inside your game data (in the data
subdirectory) use the special castle-data:/xxx
URL. Examples:
EnableNetwork := true;
S := Download('https://castle-engine.io/latest.zip');
S := Download('file:///home/michalis/my_binary_file.data');
S := Download('castle-data:/gui/my_image.png');
To read text files, we advise using the TTextReader
class. It provides a line-oriented API, and wraps a TStream
inside. The TTextReader
constructor can take a ready URL, or you can pass there your custom TStream
source.
Text := TTextReader.Create('castle-data:/my_data.txt');
try
while not Text.Eof do
WriteLnLog('NextLine', Text.ReadLn);
finally
FreeAndNil(Text);
end;
The language and run-time library offer various flexible containers. There are a number of non-generic classes (like TList
and TObjectList
from the Contnrs
unit), there are also dynamic arrays (array of TMyType
). But to get the most flexibility and type-safety, I advise using generic containers for most of your needs.
The generic containers give you a lot of helpful methods to add, remove, iterate, search, sort… The compiler also knows (and checks) that the container holds only items of the appropriate type.
There are three libraries providing generics containers in FPC now:
-
Generics.Collections
unit and friends (since FPC >= 3.2.0) -
FGL
unit -
GVector
unit and friends (together infcl-stl
)
We advise using the Generics.Collections
unit. The generic containers it implements are
-
packed with useful features,
-
very efficient (in particular important for accessing dictionaries by keys),
-
compatible between FPC and Delphi,
-
the naming is consistent with other parts of the standard library (like the non-generic containers from the
Contnrs
unit).
In the Castle Game Engine: We use the Generics.Collections
intensively throughout the engine, and advise you to use Generics.Collections
in your applications too!
Most important classes from the Generics.Collections
unit are:
- TList
-
A generic list of types.
- TObjectList
-
A generic list of object instances. It can "own" children, which means that it will free them automatically.
- TDictionary
-
A generic dictionary.
- TObjectDictionary
-
A generic dictionary, that can "own" the keys and/or values.
Here’s how to you use a simple generic TObjectList
:
link:modern_pascal_code_samples/generics_lists.lpr[role=include]
Note that some operations require comparing two items, like sorting and searching (e.g. by Sort
and IndexOf
methods). The Generics.Collections
containers use for this a comparer. The default comparer is reasonable for all types, even for records (in which case it compares memory contents, which is a reasonable default at least for searching using IndexOf
).
When sorting the list you can provide a custom comparer as a parameter. The comparer is a class implementing the IComparer
interface. In practice, you usually define the appropriate callback, and use TComparer<T>.Construct
method to wrap this callback into an IComparer
instance. An example of doing this is below:
link:modern_pascal_code_samples/generics_sorting.lpr[role=include]
The TDictionary
class implements a dictionary, also known as a map (key → value), also known as an associative array. Its API is a bit similar to the C# TDictionary
class. It has useful iterators for keys, values, and pairs of key→value.
An example code using a dictionary:
link:modern_pascal_code_samples/generics_dictionary.lpr[role=include]
The TObjectDictionary
can additionally own the dictionary keys and/or values, which means that they will be automatically freed. Be careful to only own keys and/or values if they are object instances. If you set to "owned" some other type, like an Integer
(for example, if your keys are Integer
, and you include doOwnsKeys
), you will get a nasty crash when the code executes.
An example code using the TObjectDictionary
is below. Compile this example with memory leak detection, like fpc -gl -gh generics_object_dictionary.lpr
, to see that everything is freed when program exits.
link:modern_pascal_code_samples/generics_object_dictionary.lpr[role=include]
If you prefer using the FGL
unit instead of Generics.Collections
, the most important classes from the FGL
unit are:
- TFPGList
-
A generic list of types.
- TFPGObjectList
-
A generic list of object instances. It can "own" children.
- TFPGMap
-
A generic dictionary.
In FGL
unit, the TFPGList
can be only used for types for which the equality operator (=) is defined. For TFPGMap
the "greater than" (>) and "less than" (<) operators must be defined for the key type. If you want to use these lists with types that don’t have built-in comparison operators (e.g. with records), you have to overload their operators as shown in the Operator overloading.
In the Castle Game Engine we include a unit CastleGenericLists
that adds TGenericStructList
and TGenericStructMap
classes. They are similar to TFPGList
and TFPGMap
, but they do not require a definition of the comparison operators for the appropriate type (instead, they compare memory contents, which is often appropriate for records or method pointers). But the CastleGenericLists
unit is deprecated since the engine version 6.3, as we advise using Generics.Collections
instead.
If you want to know more about the generics, see Generics.
Copying the class instances by a simple assignment operator copies the reference.
var
X, Y: TMyObject;
begin
X := TMyObject.Create;
Y := X;
// X and Y are now two pointers to the same data
Y.MyField := 123; // this also changes X.MyField
FreeAndNil(X);
end;
To copy the class instance contents, the standard approach is to derive your class from TPersistent
, and override its Assign
method. Once it’s implemented properly in TMyObject
, you use it like this:
var
X, Y: TMyObject;
begin
X := TMyObject.Create;
Y := TMyObject.Create;
Y.Assign(X);
Y.MyField := 123; // this does not change X.MyField
FreeAndNil(X);
FreeAndNil(Y);
end;
To make it work, you need to implement the Assign
method to actually copy the fields you want. You should carefully implement the Assign
method, to copy from a class that may be a descendant of the current class.
link:modern_pascal_code_samples/persistent.lpr[role=include]
Sometimes it’s more comfortable to alternatively override the AssignTo
method in the source class, instead of overriding the Assign
method in the destination class.
Be careful when you call inherited
in the overridden Assign
implementation. There are two situations:
- Your class is a direct descendant of the
TPersistent
class. (Or, it’s not a direct descendant ofTPersistent
, but no ancestor has overridden theAssign
method.) -
In this case, your class should use the
inherited
keyword (to call theTPersistent.Assign
) only if you cannot handle the assignment in your code. - Your class descends from some class that has already overridden the
Assign
method. -
In this case, your class should always use the
inherited
keyword (to call the ancestorAssign
). In general, callinginherited
in overridden methods is usually a good idea.
To understand the reason behind the above rule (when you should call, and when you should not call inherited
from the Assign
implementation), and how it relates to the AssignTo
method, let’s look at the TPersistent.Assign
and TPersistent.AssignTo
implementations:
procedure TPersistent.Assign(Source: TPersistent);
begin
if Source <> nil then
Source.AssignTo(Self)
else
raise EConvertError...
end;
procedure TPersistent.AssignTo(Destination: TPersistent);
begin
raise EConvertError...
end;
Note
|
This is not the exact implementation of TPersistent . I copied the FPC standard library code, but then I simplified it to hide unimportant details about the exception message.
|
The conclusions you can get from the above are:
-
If neither
Assign
norAssignTo
are overridden, then calling them will result in an exception. -
Also, note that there is no code in
TPersistent
implementation that automatically copies all the fields (or all the published fields) of the classes. That’s why you need to do that yourself, by overridingAssign
in all the classes. You can use RTTI (runtime type information) for that, but for simple cases you will probably just list the fields to be copied manually.
When you have a class like TApple
, your TApple.Assign
implementation usually deals with copying fields that are specific to the TApple
class (not to the TApple
ancestor, like TFruit
). So, the TApple.Assign
implementation usually checks whether Source is TApple
at the beginning, before copying apple-related fields. Then, it calls inherited
to allow TFruit
to handle the rest of the fields.
Assuming that you implemented TFruit.Assign
and TApple.Assign
following the standard pattern (as shown in the example above), the effect is like this:
-
If you pass
TApple
instance toTApple.Assign
, it will work and copy all the fields. -
If you pass
TOrange
instance toTApple.Assign
, it will work and only copy the common fields shared by bothTOrange
andTApple
. In other words, the fields defined atTFruit
. -
If you pass
TWerewolf
instance toTApple.Assign
, it will raise an exception (becauseTApple.Assign
will callTFruit.Assign
which will callTPersistent.Assign
which raises an exception).
Note
|
Remember that when descending from TPersistent , the default visibility specifier is published , to allow streaming of TPersistent descendants. Not all field and property types are allowed in the published section. If you get errors related to it, and you don’t care about streaming, just change the visibility to public . See the Visibility specifiers.
|
Inside a larger routine (function, procedure, method) you can define a helper routine.
The local routine can freely access (read and write) all the parameters of a parent, and all the local variables of the parent that were declared above it. This is very powerful. It often allows to split long routines into a couple of small ones without much effort (as you don’t have to pass around all the necessary information in the parameters). Be careful to not overuse this feature — if many nested functions use (and even change) the same variable of the parent, the code may get hard to follow.
These two examples are equivalent:
function SumOfSquares(const N: Integer): Integer;
function Square(const Value: Integer): Integer;
begin
Result := Value * Value;
end;
var
I: Integer;
begin
Result := 0;
for I := 0 to N do
Result := Result + Square(I);
end;
Another version, where we let the local routine Square
to access I
directly:
function SumOfSquares(const N: Integer): Integer;
var
I: Integer;
function Square: Integer;
begin
Result := I * I;
end;
begin
Result := 0;
for I := 0 to N do
Result := Result + Square;
end;
Local routines can go to any depth — which means that you can define a local routine within another local routine. So you can go wild (but please don’t go too wild, or the code will get unreadable:).
They allow to call a function indirectly, through to a variable. The variable can be assigned at runtime to point to any function with matching parameter types and return types.
The callback can be:
-
Normal, which means it can point to any normal routine (not a method, not local).
link:modern_pascal_code_samples/callbacks.lpr[role=include]
-
A method: declare with
of object
at the end.link:modern_pascal_code_samples/callbacks_of_object.lpr[role=include]
Note that you cannot pass global procedures / functions as methods. They are incompatible. If you have to provide an
of object
callback, but don’t want to create a dummy class instance, you can pass Class methods as methods.type TMyMethod = function (const A, B: Integer): Integer of object; TMyClass = class class function Add(const A, B: Integer): Integer class function Multiply(const A, B: Integer): Integer end; var M: TMyMethod; begin M := @TMyClass(nil).Add; M := @TMyClass(nil).Multiply; end;
Unfortunately, you need to write ugly
@TMyClass(nil).Add
instead of just@TMyClass.Add
. -
A (possibly) local routine: declare with
is nested
at the end, and make sure to use{$modeswitch nestedprocvars}
directive for the code. These go hand-in-hand with Local (nested) routines.
Delphi and new FPC versions (>= 3.3.1) support anynomous functions.
Example:
link:modern_pascal_code_samples/anon_functions_list_map_foreach.dpr[role=include]
More information:
-
Delphi documentation: https://docwiki.embarcadero.com/RADStudio/Sydney/en/Anonymous_Methods_in_Delphi
-
FPC forum post: https://forum.lazarus.freepascal.org/index.php/topic,59468.0.html
-
FPC feature changelog: https://wiki.freepascal.org/FPC_New_Features_Trunk#Support_for_Function_References_and_Anonymous_Functions
To get FPC 3.3.1, we recommend to use FpcUpDeluxe: https://castle-engine.io/fpcupdeluxe .
A powerful feature of any modern language. The definition of something (typically, of a class) can be parameterized with another type. The most typical example is when you need to create a container (a list, dictionary, tree, graph…): you can define a list of type T, and then specialize it to instantly get a list of integers, a list of strings, a list of TMyRecord, and so on.
The generics in Pascal work much like generics in C++. Which means that they are "expanded" at the specialization time, a little like macros (but much safer than macros; for example, the identifiers are resolved at the time of generic definition, not at specialization, so you cannot "inject" any unexpected behavior when specializing the generic). In effect this means that they are very fast (can be optimized for each particular type) and work with types of any size. You can use a primitive type (integer, float) as well as a record, as well as a class when specializing a generic.
link:modern_pascal_code_samples/generics.lpr[role=include]
Generics are not limited to classes, you can have generic functions and procedures as well:
link:modern_pascal_code_samples/generic_functions.lpr[role=include]
See also the Containers (lists, dictionaries) using generics about important standard classes using generics.
Methods (and global functions and procedures) with the same name are allowed, as long as they have different parameters. At compile time, the compiler detects which one you want to use, knowing the parameters you pass.
By default, the overloading uses the FPC approach, which means that all the methods in given namespace (a class or a unit) are equal, and hide the other methods in namespaces with less priority. For example, if you define a class with methods Foo(Integer)
and Foo(string)
, and it descends from a class with method Foo(Float)
, then the users of your new class will not be able to access the method Foo(Float)
easily (they still can --- if they typecast the class to its ancestor type). To overcome this, use the overload
keyword.
You can use simple preprocessor directives for
-
conditional compilation (code depending on platform, or some custom switches),
-
to include one file in another,
-
you can also use parameter-less macros.
Note that macros with parameters are not allowed. In general, you should avoid using the preprocessor stuff… unless it’s really justified. The preprocessing happens before parsing, which means that you can "break" the normal syntax of the Pascal language. This is a powerful, but also somewhat dirty, feature.
{$mode objfpc}{$H+}{$J-}
unit PreprocessorStuff;
interface
{$ifdef FPC}
{ This is only defined when compiled by FPC, not other compilers (like Delphi). }
procedure Foo;
{$endif}
{ Define a NewLine constant. Here you can see how the normal syntax of Pascal
is "broken" by preprocessor directives. When you compile on Unix
(includes Linux, Android, macOS), the compiler sees this:
const NewLine = #10;
When you compile on Windows, the compiler sees this:
const NewLine = #13#10;
On other operating systems, the code will fail to compile,
because a compiler sees this:
const NewLine = ;
It's a *good* thing that the compilation fails in this case -- if you
will have to port the program to an OS that is not Unix, not Windows,
you will be reminded by a compiler to choose the newline convention
on that system. }
const
NewLine =
{$ifdef UNIX} #10 {$endif}
{$ifdef MSWINDOWS} #13#10 {$endif} ;
{$define MY_SYMBOL}
{$ifdef MY_SYMBOL}
procedure Bar;
{$endif}
{$define CallingConventionMacro := unknown}
{$ifdef UNIX}
{$define CallingConventionMacro := cdecl}
{$endif}
{$ifdef MSWINDOWS}
{$define CallingConventionMacro := stdcall}
{$endif}
procedure RealProcedureName; CallingConventionMacro; external 'some_external_library';
implementation
{$include some_file.inc}
// $I is just a shortcut for $include
{$I some_other_file.inc}
end.
Include files have commonly the .inc
extension, and are used for two purposes:
-
The include file may only contain other compiler directives, that "configure" your source code. For example you could create a file
myconfig.inc
with these contents:{$mode objfpc} {$H+} {$J-} {$modeswitch advancedrecords} {$ifndef VER3} {$error This code can only be compiled using FPC version at least 3.x.} {$endif}
Now you can include this file using
{$I myconfig.inc}
in all your sources. -
The other common use is to split a large unit into many files, while still keeping it a single unit as far as the language rules are concerned. Do not overuse this technique — your first instinct should be to split a single unit into multiple units, not to split a single unit into multiple include files. Never the less, this is a useful technique.
-
It allows to avoid "exploding" the number of units, while still keeping your source code files short. For example, it may be better to have a single unit with "commonly used UI controls" than to create one unit for each UI control class, as the latter approach would make the typical "uses" clause long (since a typical UI code will depend on a couple of UI classes). But placing all these UI classes in a single
myunit.pas
file would make it a long file, unhandy to navigate, so splitting it into multiple include files may make sense. -
It allows to have a cross-platform unit interface with platform-dependent implementation easily. Basically you can do
{$ifdef UNIX} {$I my_unix_implementation.inc} {$endif} {$ifdef MSWINDOWS} {$I my_windows_implementation.inc} {$endif}
Sometimes this is better than writing a long code with many
{$ifdef UNIX}
,{$ifdef MSWINDOWS}
intermixed with normal code (variable declarations, routine implementation). The code is more readable this way. You can even use this technique more aggressively, by using the-Fi
command-line option of FPC to include some subdirectories only for specific platforms. Then you can have many version of include file{$I my platform_specific_implementation.inc}
and you simply include them, letting the compiler find the correct version.
-
Record is just a container for other variables. It’s like a much, much simplified class: there is no inheritance or virtual methods. It is like a structure in C-like languages.
If you use the {$modeswitch advancedrecords}
directive, records can have methods and visibility specifiers. In general, language features that are available for classes, and do not break the simple predictable memory layout of a record, are then possible.
link:modern_pascal_code_samples/records.lpr[role=include]
In modern Object Pascal, your first instinct should be to design a class
, not a record
— because classes are packed with useful features, like constructors and inheritance.
But records are still very useful when you need speed or a predictable memory layout:
-
Records do not have any constructor or destructor. You just define a variable of a record type. It has undefined contents (memory garbage) at the beginning (except auto-managed types, like strings; they are guaranteed to be initialized to be empty, and finalized to free the reference count). So you have to be more careful when dealing with records, but it gives you some performance gain.
-
Arrays of records are nicely linear in memory, so they are cache-friendly.
-
The memory layout of records (size, padding between fields) is clearly defined in some situations: when you request the C layout, or when you use
packed record
. This is useful:-
to communicate with libraries written in other programming languages, when they expose an API based on records,
-
to read and write binary files,
-
to make dirty low-level tricks (like unsafe typecasting one type to another, being aware of their memory representation).
-
-
Records can also have
case
parts, which work like unions in C-like languages. They allows to treat the same memory piece as a different type, depending on your needs. As such, this allows for greater memory efficiency in some cases. And it allows for more dirty, low-level unsafe tricks:)
The concept variant may refer to 3 distinct (though, deep down related) things in Pascal:
Variant records allow to define a section at the end of your record where the same memory can be accessed by a few different names/types.
This is described on https://en.wikipedia.org/wiki/Tagged_union on Wikipedia. "Union" is more common name for this in other languages. See also https://www.freepascal.org/docs-html/ref/refsu15.html .
Example:
link:modern_pascal_code_samples/variant_in_record.dpr[role=include]
Variant
is a special type in Pascal that underneath can hold values of various types. Moreover, operators are defined to allow operating on them and converting their values at run-time.
The effect is a bit similar to scripting programming languages with dynamic typing.
Do not use them without consideration: things are a bit less safe (you don’t control types, conversions happen implicitly). Also there’s a small performance hit, since all operations need to check and synchronize the types at run-time.
But sometimes it does make sense. Namely, when you have to process data that intrinsically indeed may have different types, and you only know those types at runtime. E.g. when you want to process result of SQL select * from some_table
in a generic database viewer (not knowing table structure at compile-time).
link:modern_pascal_code_samples/variant_types.dpr[role=include]
Note
|
Technically, Variant is realized using TVarData internal type, which is a record with variants. So these concepts are connected. But you should not need to know this, you should not use TVarData explicitly.
|
When you use array of const
special parameter type, it is passed as an array of TVarRec
. See
-
TVarRec
in FPC: https://www.freepascal.org/docs-html/rtl/system/tvarrec.html -
TVarRec
in Delphi: https://docwiki.embarcadero.com/Libraries/Sydney/en/System.TVarRec
This is useful to pass to a routine parameters of arbitrary (not known at compile-time) types. For example, to implement routines like standard Format
(similar to sprintf
in C) or Castle Game Game WriteLnLog
/ WriteLnWarning
.
link:modern_pascal_code_samples/array_of_const.dpr[role=include]
In the old days, Turbo Pascal introduced another syntax for class-like functionality, using the object
keyword. It’s somewhat of a blend between the concept of a record
and a modern class
.
-
The old-style objects can be allocated / freed, and during that operation you can call their constructor / destructor.
-
But they can also be simply declared and used, like records. A simple
record
orobject
type is not a reference (pointer) to something, it’s simply the data. This makes them comfortable for small data, where calling allocation / free would be bothersome. -
Old-style objects offer inheritance and virtual methods, although with small differences from the modern classes. Be careful — bad things will happen if you try to use an object without calling its constructor, and the object has virtual methods.
It’s discouraged to use the old-style objects in most cases. Modern classes provide much more functionality. And when needed, records (including advanced records) can be used for performance. These concepts are usually a better idea than old-style objects.
You can create a pointer to any other type. The pointer to type TMyRecord
is declared as ^TMyRecord
, and by convention is called PMyRecord
. This is a traditional example of a linked list of integers using records:
type
PMyRecord = ^TMyRecord;
TMyRecord = record
Value: Integer;
Next: PMyRecord;
end;
Note that the definition is recursive (type PMyRecord
is defined using type TMyRecord
, while TMyRecord
is defined using PMyRecord
). It is allowed to define a pointer type to a not-yet-defined type, as long as it will be resolved within the same type
block.
You can allocate and free pointers using the New
/ Dispose
methods, or (more low-level, not type-safe) GetMem
/ FreeMem
methods. You dereference the pointer (to access the stuff pointed by) you append the ^
operator (e.g. MyInteger := MyPointerToInteger^
). To make the inverse operation, which is to get a pointer of an existing variable, you prefix it with @
operator (e.g. MyPointerToInteger := @MyInteger
).
There is also an untyped Pointer
type, similar to void*
in C-like languages. It is completely unsafe, and can be typecasted to any other pointer type.
Remember that a class instance is also in fact a pointer, although it doesn’t require any ^
or @
operators to use it.
A linked list using classes is certainly possible, it would simply be this:
type
TMyClass = class
Value: Integer;
Next: TMyClass;
end;
You can override the meaning of many language operators, for example to allow addition and multiplication of your custom types. Like this:
link:modern_pascal_code_samples/operator_overloading.lpr[role=include]
You can override operators on classes too. Since you usually create new instances of your classes inside the operator function, the caller must remember to free the result.
link:modern_pascal_code_samples/operator_overloading_classes.lpr[role=include]
You can override operators on records too. This is usually easier than overloading them for classes, as the caller doesn’t have to deal then with memory management.
link:modern_pascal_code_samples/operator_overloading_records.lpr[role=include]
For records, it’s advised to use {$modeswitch advancedrecords}
and override operators as class operator
inside the record. This allows to use generic classes that depend on some operator existence (like TFPGList
, that depends on equality operator being available) with such records. Otherwise the "global" definition of an operator (not inside the record) would not be found (because it’s not available at the code that implements the TFPGList
), and you could not specialize a list like specialize TFPGList<TMyRecord>
.
link:modern_pascal_code_samples/operator_overloading_records_lists.lpr[role=include]
The private
visibility specifier means that the field (or method) is not accessible outside of this class. But it allows an exception: all the code defined in the same unit can break this, and access private fields and methods. A C++ programmer would say that in Pascal all classes within a single unit are friends. This is often useful, and doesn’t break your encapsulation, since it’s limited to a unit.
However, if you create larger units, with many classes (that are not tightly integrated with each other), it’s safer to use strict private
. It means that the field (or method) is not accessible outside of this class — period. No exceptions.
In a similar manner, there’s protected
visibility (visible to descendants, or friends in the same unit) and strict protected
(visible to descendants, period).
You can open a section of constants (const
) or types (type
) within a class. This way, you can even define a class within a class. The visibility specifiers work as always, in particular the nested class can be private (not visible to the outside world), which is often useful.
Note that to declare a field after a constant or type you will need to open a var
block.
type
TMyClass = class
private
type
TInternalClass = class
Velocity: Single;
procedure DoSomething;
end;
var
FInternalClass: TInternalClass;
public
const
DefaultVelocity = 100.0;
constructor Create;
destructor Destroy; override;
end;
constructor TMyClass.Create;
begin
inherited;
FInternalClass := TInternalClass.Create;
FInternalClass.Velocity := DefaultVelocity;
FInternalClass.DoSomething;
end;
destructor TMyClass.Destroy;
begin
FreeAndNil(FInternalClass);
inherited;
end;
{ note that method definition is prefixed with
"TMyClass.TInternalClass" below. }
procedure TMyClass.TInternalClass.DoSomething;
begin
end;
These are methods you can call having a class reference (TMyClass
), not necessarily a class instance.
type
TEnemy = class
procedure Kill;
class procedure KillAll;
end;
var
E: TEnemy;
begin
E := TEnemy.Create;
try
E.Kill;
finally FreeAndNil(E) end;
TEnemy.KillAll;
end;
Note that they can be virtual — it makes sense, and is sometimes very useful, when combined with Class references.
The class methods can also be limited by the Visibility specifiers, like private
or protected
. Just like regular methods.
Note that a constructor always acts like a class method when called in a normal fashion (MyInstance := TMyClass.Create(…);
). Although it’s possible to also call a constructor from within the class itself, like a normal method, and then it acts like a normal method. This is a useful feature to "chain" constructors, when one constructor (e.g. overloaded to take an integer parameter) does some job, and then calls another constructor (e.g. parameter-less).
Class reference allows you to choose the class at runtime, for example to call a class method or constructor without knowing the exact class at compile-time. It is a type declared as class of TMyClass
.
type
TMyClass = class(TComponent)
end;
TMyClass1 = class(TMyClass)
end;
TMyClass2 = class(TMyClass)
end;
TMyClassRef = class of TMyClass;
var
C: TMyClass;
ClassRef: TMyClassRef;
begin
// Obviously you can do this:
C := TMyClass.Create(nil); FreeAndNil(C);
C := TMyClass1.Create(nil); FreeAndNil(C);
C := TMyClass2.Create(nil); FreeAndNil(C);
// In addition, using class references, you can also do this:
ClassRef := TMyClass;
C := ClassRef.Create(nil); FreeAndNil(C);
ClassRef := TMyClass1;
C := ClassRef.Create(nil); FreeAndNil(C);
ClassRef := TMyClass2;
C := ClassRef.Create(nil); FreeAndNil(C);
end;
Class references can be combined with virtual class methods. This gives a similar effect as using classes with virtual methods — the actual method to be executed is determined at runtime.
type
TMyClass = class(TComponent)
class procedure DoSomething; virtual; abstract;
end;
TMyClass1 = class(TMyClass)
class procedure DoSomething; override;
end;
TMyClass2 = class(TMyClass)
class procedure DoSomething; override;
end;
TMyClassRef = class of TMyClass;
var
C: TMyClass;
ClassRef: TMyClassRef;
begin
ClassRef := TMyClass1;
ClassRef.DoSomething;
ClassRef := TMyClass2;
ClassRef.DoSomething;
{ And this will cause an exception at runtime,
since DoSomething is abstract in TMyClass. }
ClassRef := TMyClass;
ClassRef.DoSomething;
end;
If you have an instance, and you would like to get a reference to its class (not the declared class, but the final descendant class used at its construction), you can use the ClassType
property. The declared type of ClassType
is TClass
, which stands for class of TObject
. Often you can safely typecast it to something more specific, when you know that the instance is something more specific than TObject
.