0% found this document useful (0 votes)

444 views

Delphi 5 Object Pascal Language Guide PDF

Uploaded by

microserver

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

444 views

Delphi 5 Object Pascal Language Guide PDF

Uploaded by

microserver

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 234

Object Pascal

Language Guide

Borland

Delphi 5
for Windows 98, Windows 95, & Windows NT
Inprise Corporation
100 Enterprise Way, Scotts Valley, CA 95066-3249

Refer to the file DEPLOY.TXT located in the root directory of your Delphi 5 product for a complete list of files that you
can distribute in accordance with the Delphi 5 License Statement and Limited Warranty.
Inprise may have patents and/or pending patent applications covering subject matter in this document. The
furnishing of this document does not give you any license to these patents.
COPYRIGHT 1983, 1999 Inprise Corporation. All rights reserved. All Inprise and Borland brand and product names
are trademarks or registered trademarks of Inprise Corporation. Other brand and product names are trademarks or
registered trademarks of their respective holders.
Printed in the U.S.A.
HDE1350WW21002 3E2R899
9900010203-9 8 7 6 5 4 3 2 1
PDF

Contents
Chapter 1

Introduction

Reserved words . . . . . . . . . .
Directives. . . . . . . . . . . . . .
Numerals . . . . . . . . . . . . . .
Labels . . . . . . . . . . . . . . . .
Character strings . . . . . . . . .
Comments and compiler directives .
Expressions . . . . . . . . . . . . . .
Operators. . . . . . . . . . . . . .
Arithmetic operators . . . . .
Boolean operators . . . . . . .
Logical (bitwise) operators . .
String operators . . . . . . . .
Pointer operators. . . . . . . .
Set operators . . . . . . . . . .
Relational operators . . . . . .
Class operators . . . . . . . . .
The @ operator . . . . . . . . .
Operator precedence rules . .
Function calls . . . . . . . . . . .
Set constructors . . . . . . . . . .
Indexes . . . . . . . . . . . . . . .
Typecasts . . . . . . . . . . . . . .
Value typecasts . . . . . . . . .
Variable typecasts . . . . . . .
Declarations and statements . . . . .
Declarations . . . . . . . . . . . .
Statements . . . . . . . . . . . . .
Simple statements . . . . . . . . .
Assignment statements . . . .
Procedure and function calls .
Goto statements . . . . . . . .
Structured statements. . . . . . .
Compound statements . . . .
With statements . . . . . . . .
If statements . . . . . . . . . .
Case statements . . . . . . . .
Control loops . . . . . . . . . .
Repeat statements . . . . . . .
While statements. . . . . . . .
For statements . . . . . . . . .
Blocks and scope . . . . . . . . . . .
Blocks . . . . . . . . . . . . . . . .
Scope . . . . . . . . . . . . . . . .
Naming conflicts . . . . . . . .

1-1

Whats in this manual? . . . . . . . . . . . .

Delphi and Object Pascal . . . . . . . . .
Typographical conventions . . . . . . . .
Other sources of information . . . . . . . . .
Software registration and technical support

.
.
.
.
.

1-1
1-1
1-2
1-2
1-2

Part I

Basic language description

Chapter 2

Overview

2-1

Program organization . . . . . . . . . . .
Pascal source files . . . . . . . . . . .
Other files used to build applications
Compiler-generated files . . . . . . .
Example programs. . . . . . . . . . . . .
A simple console application . . . . .
A more complicated example . . . . .
A Windows application . . . . . . . .

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.

2-1
2-1
2-2
2-3
2-3
2-3
2-4
2-5

Chapter 3

Programs and units

3-1

Program structure and syntax . . . . . .

The program heading . . . . . . . . .
The program uses clause . . . . . . .
The block . . . . . . . . . . . . . . . .
Unit structure and syntax . . . . . . . . .
The unit heading . . . . . . . . . . . .
The interface section . . . . . . . . . .
The implementation section. . . . . .
The initialization section. . . . . . . .
The finalization section . . . . . . . .
Unit references and the uses clause . . .
The syntax of a uses clause . . . . . .
Multiple and indirect unit references
Circular unit references . . . . . . . .

3-1
3-2
3-2
3-2
3-3
3-3
3-4
3-4
3-4
3-5
3-5
3-5
3-6
3-7

Chapter 4

Syntactic elements
Fundamental syntactic elements .
Special symbols . . . . . . . . .
Identifiers . . . . . . . . . . . .
Qualified identifiers . . . .

4-1
.
.
.
.

.
.
.
.

4-1
4-2
4-2
4-2

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 4-3
. 4-3
. 4-4
. 4-4
. 4-4
. 4-5
. 4-5
. 4-6
. 4-6
. 4-7
. 4-8
. 4-9
. 4-9
4-10
4-10
4-11
4-11
4-12
4-13
4-13
4-13
4-14
4-14
4-14
4-16
4-16
4-16
4-16
4-17
4-17
4-18
4-19
4-19
4-20
4-21
4-23
4-24
4-24
4-25
4-25
4-27
4-27
4-27
4-28

Chapter 5

Declaring types . . . . . . . .
Variables . . . . . . . . . . . .
Declaring variables . . . .
Absolute addresses . .
Dynamic variables . . .
Thread-local variables .
Declared constants . . . . . .
True constants . . . . . . .
Constant expressions .
Resource strings . . . .
Typed constants . . . . . .
Array constants . . . .
Record constants . . . .
Procedural constants .
Pointer constants. . . .

Data types, variables, and constants 5-1

About types. . . . . . . . . . . . . . . . .
Simple types . . . . . . . . . . . . . . . .
Ordinal types . . . . . . . . . . . . . .
Integer types. . . . . . . . . . . . .
Character types . . . . . . . . . . .
Boolean types . . . . . . . . . . . .
Enumerated types . . . . . . . . .
Subrange types . . . . . . . . . . .
Real types . . . . . . . . . . . . . . . .
String types . . . . . . . . . . . . . . . . .
Short strings. . . . . . . . . . . . . . .
Long strings . . . . . . . . . . . . . . .
WideString . . . . . . . . . . . . . . .
About extended character sets . .
Working with null-terminated strings
Using pointers, arrays, and string
constants . . . . . . . . . . . . . .
Mixing Pascal strings and
null-terminated strings . . . . . .
Structured types . . . . . . . . . . . . . .
Sets . . . . . . . . . . . . . . . . . . . .
Arrays . . . . . . . . . . . . . . . . . .
Static arrays . . . . . . . . . . . . .
Dynamic arrays . . . . . . . . . . .
Array types and assignments . . .
Records . . . . . . . . . . . . . . . . .
Variant parts in records . . . . . .
File types . . . . . . . . . . . . . . . .
Pointers and pointer types . . . . . . . .
Overview of pointers . . . . . . . . .
Pointer types . . . . . . . . . . . . . .
Character pointers . . . . . . . . .
Other standard pointer types . . .
Procedural types . . . . . . . . . . . . . .
Procedural types in statements and
expressions . . . . . . . . . . . . . .
Variant types . . . . . . . . . . . . . . . .
Variant type conversions . . . . . . .
Variants in expressions . . . . . . . .
Variant arrays . . . . . . . . . . . . . .
OleVariant . . . . . . . . . . . . . . . .
Type compatibility and identity . . . . .
Type identity . . . . . . . . . . . . . .
Type compatibility . . . . . . . . . . .
Assignment-compatibility . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 5-1
. 5-2
. 5-2
. 5-3
. 5-4
. 5-5
. 5-6
. 5-7
. 5-8
. 5-9
. 5-11
. 5-11
. 5-12
. 5-12
. 5-12

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 5-14
. 5-15
. 5-16
. 5-16
. 5-17
. 5-17
. 5-20
. 5-20
. 5-21
. 5-23
. 5-24
. 5-24
. 5-26
. 5-26
. 5-26
. 5-27

.
.
.
.
.
.
.
.
.
.

. 5-28
. 5-29
. 5-30
. 5-32
. 5-32
. 5-33
. 5-33
. 5-33
. 5-34
. 5-34

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

5-35
5-36
5-36
5-37
5-37
5-38
5-38
5-38
5-39
5-40
5-40
5-41
5-41
5-42
5-42

Declaring procedures and functions . . . .

Procedure declarations . . . . . . . . . .
Function declarations . . . . . . . . . . .
Calling conventions . . . . . . . . . . . .
Forward and interface declarations . . .
External declarations . . . . . . . . . . .
Linking to .OBJ files . . . . . . . . . .
Importing functions from DLLs . . .
Overloading procedures and functions .
Local declarations . . . . . . . . . . . . .
Nested routines . . . . . . . . . . . .
Parameters . . . . . . . . . . . . . . . . . . .
Parameter semantics . . . . . . . . . . .
Value and variable parameters . . . .
Constant parameters . . . . . . . . .
Out parameters. . . . . . . . . . . . .
Untyped parameters. . . . . . . . . .
String parameters . . . . . . . . . . . . .
Array parameters . . . . . . . . . . . . .
Open array parameters . . . . . . . .
Variant open array parameters . . . .
Default parameters . . . . . . . . . . . .
Default parameters and overloaded
routines . . . . . . . . . . . . . . . .
Default parameters in forward and
interface declarations . . . . . . . .
Calling procedures and functions . . . . . .
Open array constructors . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 6-1
. 6-2
. 6-3
. 6-4
. 6-5
. 6-6
. 6-6
. 6-7
. 6-7
. 6-8
. 6-9
. 6-9
6-10
6-10
6-11
6-11
6-12
6-13
6-13
6-13
6-15
6-16

Chapter 6

Procedures and functions

. . . . 5-13
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

6-1

. . 6-17
. . 6-17
. . 6-17
. . 6-18

Chapter 7

Classes and objects

Class types . . . . . . . . . . . . . . . . . .
Inheritance and scope . . . . . . . . . .
TObject and TClass . . . . . . . . . .
Compatibility of class types . . . . .
Object types . . . . . . . . . . . . . .
Visibility of class members . . . . . . .
Private, protected, and public
members . . . . . . . . . . . . . . .
Published members. . . . . . . . . .
Automated members . . . . . . . . .
Forward declarations and mutually
dependent classes. . . . . . . . . . . .
Fields . . . . . . . . . . . . . . . . . . . . .
Methods. . . . . . . . . . . . . . . . . . . .
Method implementations . . . . . . . .
Inherited . . . . . . . . . . . . . . . .
Self . . . . . . . . . . . . . . . . . . .
Method binding . . . . . . . . . . . . .
Static methods. . . . . . . . . . . . .
Virtual and dynamic methods. . . .
Abstract methods . . . . . . . . . . .
Overloading methods . . . . . . . . . .
Constructors . . . . . . . . . . . . . . .
Destructors . . . . . . . . . . . . . . . .
Message handlers . . . . . . . . . . . .
Implementing message handlers . .
Message dispatching . . . . . . . . .
Properties . . . . . . . . . . . . . . . . . . .
Property access . . . . . . . . . . . . . .
Array properties . . . . . . . . . . . . .
Index specifiers . . . . . . . . . . . . . .
Storage specifiers . . . . . . . . . . . . .
Property overrides and redeclarations .
Class references . . . . . . . . . . . . . . .
Class-reference types. . . . . . . . . . .
Constructors and class references . .
Class operators . . . . . . . . . . . . . .
The is operator . . . . . . . . . . . .
The as operator . . . . . . . . . . . .
Class methods . . . . . . . . . . . . . .
Exceptions . . . . . . . . . . . . . . . . . .
Declaring exception types . . . . . . . .
Raising and handling exceptions . . . .
Try...except statements . . . . . . . .

Re-raising exceptions . . . . . . . . .
Nested exceptions . . . . . . . . . . .
Try...finally statements . . . . . . . .
Standard exception classes and routines

7-1
.
.
.
.
.
.

.
.
.
.
.
.

7-1
7-2
7-3
7-3
7-3
7-4

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.

7-28
7-29
7-30
7-30

.
.
.
.
.
.
.
.
.
.
.
.

. 8-1
. 8-3
. 8-4
. 8-4
. 8-5
. 8-5
. 8-5
. 8-6
. 8-6
. 8-6
. 8-7
. 8-7

Chapter 8

Standard routines and I/O

File input and output . . . . . . . .
Text files . . . . . . . . . . . . .
Untyped files. . . . . . . . . . .
Text-file device drivers . . . . . . .
Device functions . . . . . . . . .
The Open function . . . . . .
The InOut function . . . . .
The Flush function . . . . . .
The Close function . . . . . .
Handling null-terminated strings .
Wide-character strings . . . . .
Other standard routines . . . . . .

. . . 7-5
. . . 7-5
. . . 7-5
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.

. 7-6
. 7-7
. 7-8
. 7-8
. 7-8
. 7-9
. 7-9
. 7-9
. 7-10
. 7-11
. 7-12
. 7-12
. 7-14
. 7-15
. 7-15
. 7-15
. 7-16
. 7-16
. 7-18
. 7-19
. 7-20
. 7-20
. 7-22
. 7-22
. 7-22
. 7-23
. 7-23
. 7-24
. 7-24
. 7-25
. 7-25
. 7-25
. 7-26

8-1
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

Part II

Special topics
Chapter 9

Dynamic-link libraries and packages 9-1

Calling DLLs . . . . . . . . . . . . . . . . .
Static loading . . . . . . . . . . . . . .
Dynamic loading. . . . . . . . . . . .
Writing DLLs . . . . . . . . . . . . . . . . .
The exports clause. . . . . . . . . . . . .
Library initialization code . . . . . . . .
Global variables in a DLL . . . . . . . .
DLLs and System variables . . . . . . .
Exceptions and runtime errors in DLLs.
The shared-memory manager . . . . . .
Packages . . . . . . . . . . . . . . . . . . . .
Package declarations and source files . .
Naming packages . . . . . . . . . . .
The requires clause . . . . . . . . . .
The contains clause . . . . . . . . . .
Compiling packages . . . . . . . . . . .
Generated files . . . . . . . . . . . . .
Package-specific compiler directives
Package-specific command-line
compiler switches . . . . . . . . . .

iii

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 9-1
. 9-1
. 9-2
. 9-3
. 9-4
. 9-4
. 9-5
. 9-5
. 9-6
. 9-6
. 9-7
. 9-7
. 9-8
. 9-8
. 9-8
. 9-9
. 9-9
. 9-9

. . 9-10

Chapter 10

Object interfaces

Set types . . . . . . .
Static array types . .
Dynamic array types
Record types . . . . .
File types . . . . . . .
Procedural types. . .
Class types . . . . . .
Class reference types
Variant types . . . . .

10-1

Interface types . . . . . . . . . . . . . . . .
IUnknown and inheritance . . . . . . .
Interface identification . . . . . . . . . .
Calling conventions . . . . . . . . . . .
Interface properties. . . . . . . . . . . .
Forward declarations . . . . . . . . . .
Implementing interfaces . . . . . . . . . .
Method resolution clauses. . . . . . . .
Changing inherited implementations .
Implementing interfaces by delegation
Delegating to an interface-type
property . . . . . . . . . . . . . . .
Delegating to a class-type property .
Interface references . . . . . . . . . . . . .
Interface assignment-compatibility. . .
Interface typecasts . . . . . . . . . . . .
Interface querying . . . . . . . . . .
Automation objects . . . . . . . . . . . . .
Dispatch interface types . . . . . . . . .
Dispatch interface methods . . . . .
Dispatch interface properties . . . .
Accessing Automation objects . . . . .
Automation object method-call
syntax. . . . . . . . . . . . . . . . .
Dual interfaces . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.

. 10-1
. 10-2
. 10-2
. 10-3
. 10-3
. 10-3
. 10-4
. 10-5
. 10-5
. 10-6

.
.
.
.
.
.
.
.
.
.
.

. 10-6
. 10-7
. 10-8
. 10-9
. 10-9
. 10-9
10-10
10-10
10-11
10-11
10-11

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

. 11-6
. 11-7
. 11-7
. 11-7
. 11-8
. 11-9
. 11-9
.11-10
.11-10

Parameters and function results. . .

Parameter passing. . . . . . . . .
Register saving conventions .
Function results . . . . . . . . . .
Method calls . . . . . . . . . . . .
Constructors and destructors.
Exit procedures . . . . . . . . . . . .

.
.
.
.
.
.
.

The asm statement . . . . . . . . . . . . . .

Register use . . . . . . . . . . . . . . . .
Assembler statement syntax . . . . . . . . .
Labels . . . . . . . . . . . . . . . . . . . .
Instruction opcodes . . . . . . . . . . . .
RET instruction sizing. . . . . . . . .
Automatic jump sizing . . . . . . . .
Assembler directives . . . . . . . . . . .
Operands . . . . . . . . . . . . . . . . . .
Expressions . . . . . . . . . . . . . . . . . .
Differences between Object Pascal and
assembler expressions. . . . . . . . . .
Expression elements . . . . . . . . . . .
Constants . . . . . . . . . . . . . . . .
Registers . . . . . . . . . . . . . . . .
Symbols . . . . . . . . . . . . . . . . .
Expression classes . . . . . . . . . . . . .
Expression types. . . . . . . . . . . . . .
Expression operators . . . . . . . . . . .
Assembler procedures and functions . . . .

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

. 13-7
. 13-8
. 13-8
13-10
13-10
13-12
13-13
13-14
13-16

12-1
12-1
12-1
12-3
12-3
12-3
12-4
12-4

Chapter 13

Inline assembler code

11-1
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

Program control

Chapter 11
Delphis memory manager
Variables. . . . . . . . .
Internal data formats . . .
Integer types . . . . . .
Character types . . . . .
Boolean types . . . . . .
Enumerated types . . .
Real types . . . . . . . .
The Real48 type . . .
The Single type . . .
The Double type . .
The Extended type .
The Comp type . . .
The Currency type .
Pointer types . . . . . .
Short string types. . . .
Long string types . . . .
Wide string types . . . .

.
.
.
.
.
.
.
.
.

Chapter 12

. . 10-12
. . 10-12

Memory management

.
.
.
.
.
.
.
.
.

. 11-1
. 11-2
. 11-2
. 11-2
. 11-3
. 11-3
. 11-3
. 11-3
. 11-4
. 11-4
. 11-4
. 11-5
. 11-5
. 11-5
. 11-5
. 11-5
. 11-5
. 11-6

13-1
13-1
13-2
13-2
13-2
13-3
13-4
13-4
13-5
13-6
13-7

Appendix A

Object Pascal grammar

Index

A-1
I-1

Tables
4.1
4.2
4.3
4.4
4.5
4.6
4.7
4.8
4.9
4.10
4.11
5.1
5.2
5.3
5.4
5.5
5.6
5.7
5.8
6.1

Reserved words . . . . . . . . . . .
Directives . . . . . . . . . . . . . . .
Binary arithmetic operators . . . .
Unary arithmetic operators . . . . .
Boolean operators . . . . . . . . . .
Logical (bitwise) operators . . . . .
String operators . . . . . . . . . . .
Character-pointer operators . . . .
Set operators . . . . . . . . . . . . .
Relational operators . . . . . . . . .
Precedence of operators. . . . . . .
Generic integer types for 32-bit
implementations of Object Pascal .
Fundamental integer types . . . . .
Fundamental real types . . . . . . .
Generic real types . . . . . . . . . .
String types. . . . . . . . . . . . . .
Selected pointer types declared in
System and SysUtils . . . . . . . . .
Variant type conversion rules . . .
Types for integer constants . . . . .
Calling conventions . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.

. 4-3
. 4-3
. 4-6
. 4-6
. 4-7
. 4-8
. 4-9
. 4-9
. 4-10
. 4-10
. 4-12

.
.
.
.
.

.
.
.
.

. 5-26
. 5-31
. 5-39
. 6-5

8.1
8.2
8.3
9.1
9.2
9.3
11.1
11.2
11.3
11.4
11.5
13.1
13.2
13.3
13.4

5-3
5-3
5-8
5-9
5-9

13.5
13.6
13.7

Input and output procedures and

functions . . . . . . . . . . . . . . . . .
Null-terminated string functions . . .
Other standard routines . . . . . . . .
Compiled package files . . . . . . . .
Package-specific compiler directives .
Package-specific command-line
compiler switches. . . . . . . . . . . .
Long string dynamic memory layout
Wide string dynamic memory layout
Dynamic array memory layout . . . .
Type alignment masks . . . . . . . . .
Virtual method table layout . . . . . .
Built-in assembler reserved words . .
String examples and their values . . .
CPU registers . . . . . . . . . . . . . .
Symbols recognized by the built-in
assembler . . . . . . . . . . . . . . . .
Predefined type symbols. . . . . . . .
Precedence of built-in assembler
expression operators . . . . . . . . . .
Definitions of built-in assembler
expression operators . . . . . . . . . .

.
.
.
.
.

. 8-1
. 8-6
. 8-7
. 9-9
. 9-9

.
.
.
.
.
.
.
.
.

. 9-10
. 11-5
. 11-6
. 11-7
. 11-7
.11-10
. 13-7
. 13-9
13-10

. .13-11
. 13-14
. 13-14
. 13-15

Chapter

Introduction

Chapter1

This manual is about the Object Pascal programming language as it is used in Delphi.

Whats in this manual?

The first seven chapters describe most of the language elements used in ordinary
programming. Chapter 8 summarizes standard routines for file I/O and string
manipulation.
The next chapters describe language extensions and restrictions for dynamic-link
libraries and Delphi packages (Chapter 9), and for object interfaces and COM
(Chapter 10). The final three chapters address advanced topics: memory
management (Chapter 11), program control (Chapter 12), and assembly-language
routines within Object Pascal programs (Chapter 13).

Delphi and Object Pascal

Most Delphi developers write and compile their code in Delphis integrated
development environment (IDE). Delphi handles many details of setting up projects
and source files, such as maintenance of dependency information among units.
Delphi also places constraints on program organization that are not, strictly
speaking, part of the Object Pascal language specification. For example, Delphi
enforces certain file- and program-naming conventions that you can avoid if you
write your programs outside of the IDE and compile them from the command
prompt.
This manual generally assumes that you are working in Delphis IDE and that you
are building applications that use the Visual Component Library (VCL).
Occasionally, however, Delphi-specific rules are distinguished from rules that apply
to all Object Pascal programming.

Introduction

1-1

Other sources of information

Typographical conventions
Identifiersthat is, names of constants, variables, types, fields, properties,
procedures, functions, programs, units, libraries, and packagesappear in italics in
the text. Object Pascal operators, reserved words, and directives are in boldface type.
Example code and text that you would type literally (into a file or at the command
prompt) are in monospaced type.
In displayed program listings, reserved words and directives appear in boldface, just
as they do in the text:
function Calculate(X, Y: Integer): Integer;
begin

end;

This is how Delphis Code editor displays reserved words and directives, if you have
the Syntax Highlight option turned on.
Some program listings, like the example above, contain ellipsis marks (... or ). The
ellipses represent additional code that would be included in an actual file. They are
not meant to be copied literally.
In syntax descriptions, italics indicate placeholders for which, in real code, you would
substitute syntactically valid constructions. For example, the heading of the function
declaration above could be represented as
function functionName(argumentList): returnType;
Syntax descriptions can also contain ellipsis marks (...) and subscripts:
function functionName(arg1, ..., argn): ReturnType;

Other sources of information

Delphis online Help system provides information about the IDE and user interface
as well as the most up-to-date reference material for the VCL. Many programming
topics, such as database development, are covered in depth in the Developers Guide.
For an overview of the Delphi documentation set, see the Quick Start manual that
came with your copy of Delphi.

Software registration and technical support

Inprise offers a range of support plans to fit the needs of individual developers,
consultants, and corporations. To receive help with this product, return the
registration card and select the plan that best suits your needs. For additional
information about technical support and other Inprise services, contact your local
sales representative or visit us online at http://www.inprise.com/.
For information about year 2000 issues and our products, see the following URL:
http://www.inprise.com/devsupport/y2000/.

1-2

Object Pascal Language Guide

Part

I
Basic language description

Part I

The chapters in Part I present the essential language elements required for most
programming tasks. These chapters include:
Chapter 2, Overview
Chapter 3, Programs and units
Chapter 4, Syntactic elements
Chapter 5, Data types, variables, and constants
Chapter 6, Procedures and functions
Chapter 7, Classes and objects
Chapter 8, Standard routines and I/O

Basic language description

Chapter

Overview

Chapter2

Object Pascal is a high-level, compiled, strongly typed language that supports

structured and object-oriented design. Its benefits include easy-to-read code, quick
compilation, and the use of multiple unit files for modular programming.
Object Pascal has special features that support Delphis component framework and
RAD environment. For the most part, descriptions and examples in this manual
assume that you are using Object Pascal to develop Delphi applications.

Program organization
Programs are usually divided into source-code modules called units. Each program
begins with a heading, which specifies a name for the program. The heading is
followed by an optional uses clause, then a block of declarations and statements. The
uses clause lists units that are linked into the program; these units, which can be
shared by different programs, often have uses clauses of their own.
The uses clause provides the compiler with information about dependencies among
modules. Because this information is stored in the modules themselves, Object Pascal
programs do not require makefiles, header files, or preprocessor include directives.
(Delphis Project Manager generates a makefile each time a project is loaded in the
IDE, but saves these files only for project groups that include more than one project.)
For further discussion of program structure and dependencies, see Chapter 3,
Programs and units.

Pascal source files

The compiler expects to find Pascal source code in files of three kinds:
unit source files, which end with the .PAS extension,
project files, which end with the .DPR extension, and
package source files, which end with the .DPK extension.
Overview

2-1

Program organization

Unit source files contain most of the code in an application. Each Delphi application
has a single project file and several unit files; the project filewhich corresponds to
the main program file in traditional Pascalorganizes the unit files into an
application. Delphi automatically maintains a project file for each application.
If you are compiling a program from the command line, you can put all your source
code into unit (.PAS) files. But if you use the Delphi IDE to build your application,
you must have a project (.DPR) file.
Package source files are similar to project files, but they are used to construct special
dynamic-link libraries called packages. For more information about packages, see
Chapter 9, Dynamic-link libraries and packages.

Other files used to build applications

In addition to source-code modules, Delphi uses several non-Pascal files to build
applications. These files are maintained automatically by Delphi and include
form files, which end with the .DFM extension,
resource files, which end with the .RES extension, and
project options files, which end with the .DOF extension.
A form (.DFM) file is either a text file or a compiled Windows resource file that can
contain bitmaps, strings, and so forth. Each form file represents a single Delphi form,
which usually corresponds to a window or dialog box in a Windows application. The
Delphi IDE allows you to view and edit form files as text, and to save form files as
either text or binary. Although the default behavior is to save form files as text, they
are usually not edited manually; it is more common to use Delphis visual design
tools for this purpose. Each Delphi project has at least one form, and each form has an
associated unit (.PAS) file that, by default, has the same name as the form file.
In addition to form files, each Delphi project uses a standard Windows resource
(.RES) file to hold the bitmap for the applications icon. By default, this file has the
same name as the project (.DPR) file. To change an applications icon, use Delphis
Project Options dialog.
A project options (.DOF) file contains compiler and linker settings, search directories,
version information, and so forth. Each project has an associated project options file
with the same name as the project (.DPR) file. Usually, the options in this file are set
from Delphis Project Options dialog.
Various tools in the Delphi IDE store data in files of other types. Desktop settings
(.DSK) files contain information about the arrangement of windows and other
configuration options; .DSK files can be project-specific or environment-wide. The
Integrated Translation Environment generates .RPS and .DFN files that contain
information about resource localization. The Data Module Designer maintains
diagram descriptions in .DTI files. These files have no direct effect on compilation.

2-2

Object Pascal Language Guide

Example programs

Compiler-generated files
The first time you build an application or a standard dynamic-link library, the
compiler produces a .DCU (Delphi compiled unit) file for each new unit used in your
project; all the .DCU files in your project are then linked to create a single .EXE
(executable) or .DLL file. The first time you build a package, the compiler produces a
.DCU file for each new unit contained in the package, and then creates both a .DCP
and a .BPL file. (For more information about dynamic-link libraries and packages, see
Chapter 9, Dynamic-link libraries and packages.) If you use the GD switch, the
linker generates a map file and a .DRC file; the .DRC file, which contains string
resources, can be compiled into a resource file.
When you rebuild a project, individual units are not recompiled unless their source
(.PAS) files have changed since the last compilation, or their .DCU files cannot be
found, or you explicitly tell the compiler to reprocess them. In fact, it is not necessary
for a units source file to be present at all, as long as the compiler can find the .DCU
file.

Example programs
The examples that follow illustrate basic features of Object Pascal and Delphi
programming. The first two examples are not Delphi applications, but you can
compile them from the command line.

A simple console application

The program below is a simple console application that you can compile and run
from the command prompt.
program Greeting;
{$APPTYPE CONSOLE}
var MyMessage: string;
begin
MyMessage := 'Hello world!';
Writeln(MyMessage);
end.

The first line declares a program called Greeting. The {$APPTYPE CONSOLE} directive tells
the compiler that this is a console application, to be run from the command line. The
next line declares a variable called MyMessage, which holds a string. (Object Pascal
has genuine string data types.) The program then assigns the string Hello world! to
the variable MyMessage, and sends the contents of MyMessage to the standard output
using the Writeln procedure. (Writeln is defined implicitly in the System unit, which
the compiler automatically includes in every application.)

Overview

2-3

Example programs

If you have Delphi installed and your Path includes the Delphi\Bin directory (where
DCC32.EXE and DCC32.CFG reside), you can type this program into a file called
GREETING.PAS or GREETING.DPR and compile it by entering
DCC32 GREETING

on the command line. The resulting executable (GREETING.EXE) prints the message
Hello world!
Aside from its simplicity, this example differs in several important ways from
programs that you are likely to write with Delphi. First, it is a console application.
Delphi is typically used to write Windows applications with graphical interfaces;
hence, in a Delphi application you would not ordinarily call Writeln. Moreover, the
entire example program (save for Writeln) is in a single file. In a Delphi application,
the program headingthe first line of the examplewould be placed in a separate
project file that would not contain any of the actual application logic, other than a
few calls to methods defined in unit files.

A more complicated example

The next example shows a program that is divided into two files: a project file and a
unit file. The project file, which you can save as GREETING.DPR, looks like this:
program Greeting;
{$APPTYPE CONSOLE}
uses Unit1;
begin
PrintMessage('Hello World!');
end.

The first line declares a program called Greeting, which, once again, is a console
application. The uses Unit1; clause tells the compiler that Greeting includes a unit
called Unit1. Finally, the program calls the PrintMessage procedure, passing to it the
string Hello World! Where does the PrintMessage procedure come from? Its
defined in Unit1. Heres the source code for Unit1, which you can save in a file called
UNIT1.PAS:
unit Unit1;
interface
procedure PrintMessage(msg: string);
implementation
procedure PrintMessage(msg: string);
begin
Writeln(msg);
end;
end.

2-4

Object Pascal Language Guide

Example programs

Unit1 defines a procedure called PrintMessage that takes a single string as an

argument and sends the string to the standard output. (In Pascal, routines that do not
return a value are called procedures. Routines that return a value are called functions.)
Notice that PrintMessage is declared twice in Unit1. The first declaration, under the
reserved word interface, makes PrintMessage available to other modules (such as
Greeting) that use Unit1. The second declaration, under the reserved word
implementation, actually defines PrintMessage.
You can now compile Greeting from the command line by entering
DCC32 GREETING

Theres no need to include Unit1 as a command-line argument. When the compiler

processes GREETING.DPR, it automatically looks for unit files that the Greeting
program depends on. The resulting executable (GREETING.EXE) does the same
thing as our first example: it prints the message Hello world!

A Windows application
Our next example is a Windows application built with Delphis Visual Component
Library (VCL). This program uses Delphi-generated form and resource files, so you
wont be able to compile it from the source code alone. But it illustrates important
features of Object Pascal. In addition to multiple units, the program uses classes and
objects, which are discussed in Chapter 7, Classes and objects.
The program includes a project file and two new unit files. First, the project file:
program Greeting; { comments are enclosed in braces }
uses
Forms,
Unit1 { the unit for Form1 },
Unit2 { the unit for Form2 };
{$R *.RES} { this directive links the project's resource file }
begin
{ calls to Application }
Application.Initialize;
Application.CreateForm(TForm1, Form1);
Application.CreateForm(TForm2, Form2);
Application.Run;
end.

Once again, our program is called Greeting. It uses three units: Forms, which is part of
the VCL; Unit1, which is associated with the applications main form (Form1); and
Unit2, which is associated with another form (Form2).
The program makes a series of calls to an object named Application, which is an
instance of the TApplication class defined in the Forms unit. (Every Delphi project has
an automatically generated Application object.) Two of these calls invoke a
TApplication method named CreateForm. The first call to CreateForm creates Form1, an

Overview

2-5

Example programs

instance of the TForm1 class defined in Unit1. The second call to CreateForm creates
Form2, an instance of the TForm2 class defined in Unit2.
Unit1 looks like this:
unit Unit1;
interface
uses { these units are part of Delphi's Visual Component Library (VCL) }
Windows, Messages, SysUtils, Classes, Graphics, Controls, Forms, Dialogs, StdCtrls;
type
TForm1 = class(TForm)
Button1: TButton;
procedure Button1Click(Sender: TObject);
end;
var
Form1: TForm1;
implementation
uses Unit2; { this is where Form2 is defined }
{$R *.DFM} { this directive links Unit1's form file }
procedure TForm1.Button1Click(Sender: TObject);
begin
Form1.Hide;
Form2.Show;
end;
end.

Unit1 creates a class named TForm1 (derived from the VCLs TForm) and an instance
of this class, Form1. TForm1 includes a buttonButton1, an instance of TButtonand
a procedure named TForm1.Button1Click that is called at runtime whenever the user
presses Button1. TForm1.Button1Click does two things: it hides Form1 (the call to
Form1.Hide) and it displays Form2 (the call to Form2.Show). Form2 is defined in Unit2:
unit Unit2;
interface
uses
Windows, Messages, SysUtils, Classes, Graphics, Controls, Forms, Dialogs,
StdCtrls;
type
TForm2 = class(TForm)
Label1: TLabel;
CancelButton: TButton;

2-6

Object Pascal Language Guide

Example programs

procedure CancelButtonClick(Sender: TObject);

procedure FormClose(Sender: TObject; var Action: TCloseAction);
end;
var
Form2: TForm2;
implementation
uses Unit1;
{$R *.DFM}
procedure TForm2.CancelButtonClick(Sender: TObject);
begin
Form2.Close;
end;
procedure TForm2.Form2Close(Sender: TObject; var Action: TCloseAction);
begin
Form1.Show;
end;
end.

Unit2 creates a class named TForm2 and an instance of this class, Form2. TForm2
includes a button (CancelButton, an instance of TButton) and a label (Label1, an
instance of TLabel). You cant see this from the source code, but Label1 displays a
caption that reads Hello world! The caption is defined in Form2s form file,
UNIT2.DFM.
Unit2 defines two procedures. TForm2.CancelButtonClick is called at runtime
whenever the user presses CancelButton; it closes Form2. TForm2.FormClose is called at
runtime whenever Form2 closes; it reopens Form1. These procedures (along with
Unit1s TForm1.Button1Click) are known as event handlers because they respond to
events that occur while the program is running. Event handlers are assigned to
specific events by the form (.DFM) files for Form1 and Form2.
When the Greeting program starts, Form1 is displayed and Form2 is invisible. (By
default, only the first form created in the project file is visible at runtime. This is
called the projects main form.) When the user presses the button on Form1, Form1
disappears and is replaced by Form2, which displays the Hello world! greeting.
When the user closes Form2 (by pressing CancelButton or the Close button on the title
bar), Form1 reappears.

Overview

2-7

2-8

Object Pascal Language Guide

Chapter

Programs and units

Chapter3

A program is constructed from source-code modules called units. Each unit is stored
in its own file and compiled separately; compiled units (.DCU files) are linked to
create an application. Units allow you to
divide large programs into modules that can be edited separately.
create libraries that you can share among programs.
distribute libraries to other developers without making the source code available.
In traditional Pascal programming, all source code, including the main program, is
stored in .PAS files. Delphi uses a project (.DPR) file to store the main program,
while most other source code resides in unit (.PAS) files. Each applicationor
projectconsists of a single project file and one or more unit files. (Strictly speaking,
you neednt explicitly use any units in a project, but all programs automatically use
the System unit.) To build a project, the compiler needs either a source file or a
previously compiled DCU for each unit.

Program structure and syntax

A program contains
a program heading,
a uses clause (optional), and
a block of declarations and statements.
The program heading specifies a name for the program. The uses clause lists units
used by the program. The block contains declarations and statements that are
executed when the program runs. The Delphi IDE expects to find these three
elements in a single project (.DPR) file.

Programs and units

3-1

Program structure and syntax

The example below shows the project file for a program called Editor.
1
2
3
4
5
6
7
8
9
10
11
12
13
14

program Editor;
uses
Forms,
REAbout in 'REABOUT.PAS' {AboutBox},
REMain in 'REMain.pas' {MainForm};
{$R *.RES}
begin
Application.Title := 'Text Editor';
Application.CreateForm(TMainForm, MainForm);
Application.Run;
end.

Line 1 contains the program heading. The uses clause is on lines 3 through 6. Line 8 is
a compiler directive that links the projects resource file into the program. Lines 10
through 14 contain the block of statements that are executed when the program runs.
Finally, the project file, like all source files, ends with a period.
This is in fact a fairly typical project file. Project files are usually short, since most of a
programs logic resides in its unit files. Project files are generated and maintained by
Delphi, and it is seldom necessary to edit them manually.

The program heading

The program heading specifies the programs name. It consists of the reserved word
program, followed by a valid identifier, followed by a semicolon. For Delphi
applications, the identifier must match the project file name. In the example above,
since the program is called Editor, the project file should be called EDITOR.DPR.
In standard Pascal, a program heading can include parameters after the program
name:
program Calc(input, output);

Delphis compiler ignores these parameters.

The program uses clause

The uses clause lists units that are incorporated into the program. These units may in
turn have uses clauses of their own. For more information about the uses clause, see
Unit references and the uses clause on page 3-5.

The block
The block contains a simple or structured statement that is executed when the
program runs. In most Delphi programs, the block consists of a compound
statementbracketed between the reserved words begin and endwhose

3-2

Object Pascal Language Guide

Unit structure and syntax

component statements are simply method calls to the projects Application object.
(Every Delphi project has an Application variable that holds an instance of
TApplication, TWebApplication, or TServiceApplication.) The block can also contain
declarations of constants, types, variables, procedures, and functions; these
declarations must precede the statement part of the block.

Unit structure and syntax

A unit consists of types (including classes), constants, variables, and routines
(functions and procedures). Each unit is defined in its own unit (.PAS) file.
A unit file begins with a unit heading, which is followed by the interface,
implementation, initialization, and finalization sections. The initialization and
finalization sections are optional. A skeleton unit file looks like this:
unit Unit1;
interface
uses { List of units goes here }
{ Interface section goes here }
implementation
uses { List of units goes here }
{ Implementation section goes here }
initialization
{ Initialization section goes here }
finalization
{ Finalization section goes here }
end.

The unit must conclude with the word end followed by a period.

The unit heading

The unit heading specifies the units name. It consists of the reserved word unit,
followed by a valid identifier, followed by a semicolon. For Delphi applications, the
identifier must match the unit file name. Thus, the unit heading
unit MainForm;

would occur in a source file called MAINFORM.PAS, and the file containing the
compiled unit would be MAINFORM.DCU.
Unit names must be unique within a project. Even if their unit files are in different
directories, two units with the same name cannot be used in a single program.

Programs and units

3-3

Unit structure and syntax

The interface section

The interface section of a unit begins with the reserved word interface and continues
until the beginning of the implementation section. The interface section declares
constants, types, variables, procedures, and functions that are available to clients
that is, to other units or programs that use the unit where they are declared. These
entities are called public because a client can access them as if they were declared in
the client itself.
The interface declaration of a procedure or function includes only the routines
heading. The block of the procedure or function follows in the implementation
section. Thus procedure and function declarations in the interface section work like
forward declarations, although the forward directive isnt used.
The interface declaration for a class must include declarations for all class members.
The interface section can include its own uses clause, which must appear
immediately after the word interface. For information about the uses clause, see
Unit references and the uses clause on page 3-5.

The implementation section

The implementation section of a unit begins with the reserved word implementation
and continues until the beginning of the initialization section or, if there is no
initialization section, until the end of the unit. The implementation section defines
procedures and functions that are declared in the interface section. Within the
implementation section, these procedures and functions may be defined and called in
any order. You can omit parameter lists from public procedure and function
headings when you define them in the implementation section; but if you include a
parameter list, it must match the declaration in the interface section exactly.
In addition to definitions of public procedures and functions, the implementation
section can declare constants, types (including classes), variables, procedures, and
functions that are private to the unitthat is, inaccessible to clients.
The implementation section can include its own uses clause, which must appear
immediately after the word implementation. For information about the uses clause,
see Unit references and the uses clause on page 3-5.

The initialization section

The initialization section is optional. It begins with the reserved word initialization
and continues until the beginning of the finalization section or, if there is no
finalization section, until the end of the unit. The initialization section contains
statements that are executed, in the order in which they appear, on program start-up.
So, for example, if you have defined data structures that need to be initialized, you
can do this in the initialization section.
The initialization sections of units used by a client are executed in the order in which
the units appear in the clients uses clause.

3-4

Object Pascal Language Guide

Unit references and the uses clause

The finalization section

The finalization section is optional and can appear only in units that have an
initialization section. The finalization section begins with the reserved word
finalization and continues until the end of the unit. It contains statements that are
executed when the main program terminates. Use the finalization section to free
resources that are allocated in the initialization section.
Finalization sections are executed in the opposite order from initializations. For
example, if your application initializes units A, B, and C, in that order, it will finalize
them in the order C, B, and A.
Once a units initialization code starts to execute, the corresponding finalization
section is guaranteed to execute when the application shuts down. The finalization
section must therefore be able to handle incompletely initialized data, since, if a
runtime error occurs, the initialization code might not execute completely.

Unit references and the uses clause

A uses clause lists units used by the program, library, or unit in which the clause
appears. (For information about libraries, see Chapter 9, Dynamic-link libraries and
packages.) A uses clause can occur in
the project file for a program or library,
the interface section of a unit, and
the implementation section of a unit.
Most project files contain a uses clause, as do the interface sections of most units. The
implementation section of a unit can contain its own uses clause as well.
The System unit is used automatically by every Delphi application and cannot be
listed explicitly in the uses clause. (System implements routines for file I/O, string
handling, floating point operations, dynamic memory allocation, and so forth.) Other
standard library units, such as SysUtils, must be included in the uses clause. In most
cases, Delphi places all necessary units in the uses clause when it generates and
maintains a source file.
For more information about the placement and content of the uses clause, see
Multiple and indirect unit references on page 3-6 and Circular unit references on
page 3-7.

The syntax of a uses clause

A uses clause consists of the reserved word uses, followed by one or more commadelimited unit names, followed by a semicolon. Examples:
uses Forms, Main;
uses Windows, Messages, SysUtils, Strings, Classes, Unit2, MyUnit;

Programs and units

3-5

Unit references and the uses clause

In the uses clause of a program or library, any unit name may be followed by the
reserved word in and the name of a source file, with or without a directory path, in
single quotation marks; directory paths can be absolute or relative. Examples:
uses Windows, Messages, SysUtils, Strings in 'C:\Classes\Strings.pas', Classes;
uses
Forms,
Main,
Extra in '..\EXTRA\EXTRA.PAS';

Include in ... after a unit name when you need to specify the units source file. Since
the Delphi IDE expects unit names to match the names of the source files in which
they reside, there is usually no reason to do this. Using in is necessary only when the
location of the source file is unclear, for example when
You have used a source file that is in a different directory from the project file, and
that directory is not in the compilers search path or Delphis Library search path.
Different directories in the compilers search path have identically named units.
You are compiling a console application from the command line, and you have
named a unit with an identifier that doesnt match the name of its source file.
Delphi also relies on the in ... construction to determine which units are part of a
project. Only units that appear in a project (.DPR) files uses clause followed by in
and a file name are considered to be part of the project; other units in the uses clause
are used by the project without belonging to it. This distinction has no effect on
compilation, but it affects IDE tools like the Project Manager and Project Browser.
In the uses clause of a unit, you cannot use in to tell the compiler where to find a
source file. Every unit must be in the compilers search path, Delphis Library search
path, or the same directory as the unit that uses it. Moreover, unit names must match
the names of their source files.

Multiple and indirect unit references

The order in which units appear in the uses clause determines the order of their
initialization (see The initialization section on page 3-4) and affects the way
identifiers are located by the compiler. If two units declare a variable, constant, type,
procedure, or function with the same name, the compiler uses the one from the unit
listed last in the uses clause. (To access the identifier from the other unit, you would
have to add a qualifier: UnitName.Identifier.)
A uses clause need include only units used directly by the program or unit in which
the clause appears. That is, if unit A references constants, types, variables,
procedures, or functions that are declared in unit B, then A must use B explicitly. If B
in turn references identifiers from unit C, then A is indirectly dependent on C; in this
case, C neednt be included in a uses clause in A, but the compiler must still be able to
find both B and C in order to process A.

3-6

Object Pascal Language Guide

Unit references and the uses clause

The example below illustrates indirect dependency.

program Prog;
uses Unit2;
const a = b;

unit Unit2;
interface
uses Unit1;
const b = c;

unit Unit1;
interface
const c = 1;

In this example, Prog depends directly on Unit2, which depends directly on Unit1.
Hence Prog is indirectly dependent on Unit1. Because Unit1 does not appear in Progs
uses clause, identifiers declared in Unit1 are not available to Prog.
To compile a client module, the compiler needs to locate all units that the client
depends on, directly or indirectly. Unless the source code for these units has
changed, however, the compiler needs only their .DCU files, not their source (.PAS)
files.
When changes are made in the interface section of a unit, other units that depend on
it must be recompiled. But when changes are made only in the implementation or
other sections of a unit, dependent units dont have to be recompiled. The compiler
tracks these dependencies automatically and recompiles units only when necessary.

Circular unit references

When units reference each other directly or indirectly, the units are said to be
mutually dependent. Mutual dependencies are allowed as long as there are no
circular paths connecting the uses clause of one interface section to the uses clause of
another. In other words, starting from the interface section of a unit, it must never be
possible to return to that unit by following references through interface sections of
other units. For a pattern of mutual dependencies to be valid, each circular reference
path must lead through the uses clause of at least one implementation section.
In the simplest case of two mutually dependent units, this means that the units
cannot list each other in their interface uses clauses. So the following example leads
to a compilation error:
unit Unit1;
interface
uses Unit2;

unit Unit2;
interface
uses Unit1;

Programs and units

3-7

Unit references and the uses clause

However, the two units can legally reference each other if one of the references is
moved to the implementation section:
unit Unit1;
interface
uses Unit2;

unit Unit2;
interface

implementation
uses Unit1;

To reduce the chance of circular references, its a good idea to list units in the
implementation uses clause whenever possible. Only when identifiers from another
unit are used in the interface section is it necessary to list that unit in the interface
uses clause.

3-8

Object Pascal Language Guide

Chapter

Syntactic elements

Chapter4

Object Pascal uses the ASCII character set, including the letters A through Z and a
through z, the digits 0 through 9, and other standard characters. It is not
case-sensitive. The space character (ASCII 32) and the control characters (ASCII 0
through 31including ASCII 13, the return or end-of-line character) are called blanks.
Fundamental syntactic elements, called tokens, combine to form expressions,
declarations, and statements. A statement describes an algorithmic action that can be
executed within a program. An expression is a syntactic unit that occurs within a
statement and denotes a value. A declaration defines an identifier (such as the name of
a function or variable) that can be used in expressions and statements, and, where
appropriate, allocates memory for the identifier.

Fundamental syntactic elements

On the simplest level, a program is a sequence of tokens delimited by separators. A
token is the smallest meaningful unit of text in a program. A separator is either a blank
or a comment. Strictly speaking, it is not always necessary to place a separator
between two tokens; for example, the code fragment
Size:=20;Price:=10;

is perfectly legal. Convention and readability, however, dictate that we write this as
Size := 20;
Price := 10;

Tokens are categorized as special symbols, identifiers, reserved words, directives, numerals,
labels, and character strings. A separator can be part of a token only if the token is a
character string. Adjacent identifiers, reserved words, numerals, and labels must
have one or more separators between them.

Syntactic elements

4-1

Fundamental syntactic elements

Special symbols
Special symbols are non-alphanumeric characters, or pairs of such characters, that
have fixed meanings. The following single characters are special symbols.
# $ & ' ( ) * + , . / : ; < = > @ [ ] ^ { }
The following character pairs are also special symbols.
(* (. *) .) .. // := <= >= <>
The left bracket[is equivalent to the character pair of left parenthesis and
period(.; the right bracket]is equivalent to the character pair of period and
right parenthesis.) . The left-parenthesisplusasterisk and asterisk-plusright-parenthesis(* *)are equivalent to the left and right brace{ }.
Notice that !, " (double quotation marks), %, ?, \, _ (underscore), |(pipe), and ~ (tilde)
are not special characters.

Identifiers
Identifiers denote constants, variables, fields, types, properties, procedures,
functions, programs, units, libraries, and packages. An identifier can be of any
length, but only the first 255 characters are significant. An identifier must begin with
a letter or an underscore (_) and cannot contain spaces; letters, digits, and
underscores are allowed after the first character. Reserved words cannot be used as
identifiers.
Since Object Pascal is case-insensitive, an identifier like CalculateValue could be
written in any of these ways:
CalculateValue
calculateValue
calculatevalue
CALCULATEVALUE

Qualified identifiers
When you use an identifier that has been declared in more than one place, it is
sometimes necessary to qualify the identifier. The syntax for a qualified identifier is
identifier1.identifier2
where identifier1 qualifies identifier2. For example, if two units each declare a variable
called CurrentValue, you can specify that you want to access the CurrentValue in Unit2
by writing
Unit2.CurrentValue

Qualifiers can be iterated. For example,

Form1.Button1.Click

calls the Click method in Button1 of Form1.

If you dont qualify an identifier, its interpretation is determined by the rules of scope
described in Blocks and scope on page 4-27.

4-2

Object Pascal Language Guide

Fundamental syntactic elements

Reserved words
The following reserved words cannot be redefined or used as identifiers.
Table 4.1

Reserved words

and

downto

string

array

else

inherited

out

then

end

initialization

packed

threadvar

asm

except

inline

procedure

begin

exports

interface

program

try

case

file

property

type

class

finalization

label

raise

unit

const

finally

library

record

until

constructor

for

mod

repeat

uses

destructor

function

nil

resourcestring

var

dispinterface

goto

not

set

while

div

object

shl

with

implementation

shr

xor

In addition to the words in Table 4.1, private, protected, public, published, and
automated act as reserved words within object type declarations, but are otherwise
treated as directives. The words at and on also have special meanings.

Directives
Directives have special meanings in Object Pascal, but, unlike reserved words,
appear only in contexts where user-defined identifiers cannot occur. Hence
although it is inadvisable to do soyou can define an identifier that looks exactly
like a directive.
Table 4.2

Directives

absolute

dynamic

name

protected

abstract

export

near

public

resident
safecall

assembler

external

nodefault

published

stdcall

automated

far

overload

read

stored

cdecl

forward

override

readonly

virtual

contains

implements

package

write

default

index

pascal

reintroduce

writeonly

dispid

message

private

requires

Syntactic elements

4-3

Fundamental syntactic elements

Numerals
Integer and real constants can be represented in decimal notation as sequences of
digits without commas or spaces, and prefixed with the + or operator to indicate
sign. Values default to positive (so that, for example, 67258 is equivalent to +67258) and
must be within the range of the largest predefined real or integer type.
Numerals with decimal points or exponents denote reals, while other numerals denote
integers. When the character E or e occurs within a real, it means times ten to the power
of. For example, 7E2 means 7 102, and 12.25e+6 and 12.25e6 both mean 12.25 106.
The dollar-sign prefix indicates a hexadecimal numeralfor example, $8F.
Hexadecimals must be within the range $00000000 to $FFFFFFFF. The sign of a
hexadecimal is determined by the leftmost (most significant) bit of its binary
representation.
For more information about real and integer types, see Chapter 5, Data types,
variables, and constants. For information about the data types of numerals, see
True constants on page 5-38.

Labels
A label is a sequence of no more than four digitsthat is, a numeral between 0 and
9999. Leading zeros are not significant. Identifiers can also function as labels.
Labels are used in goto statements. For more information about goto statements and
labels, see Goto statements on page 4-18.

Character strings
A character string, also called a string literal or string constant, consists of a quoted
string, a control string, or a combination of quoted and control strings. Separators can
occur only within quoted strings.
A quoted string is a sequence of up to 255 characters from the extended ASCII
character set, written on one line and enclosed by apostrophes. A quoted string with
nothing between the apostrophes is a null string. Two sequential apostrophes in a
quoted string denote a single character, namely an apostrophe. For example,
'BORLAND'
'You''ll see'
''''
''
' '

{
{
{
{
{

BORLAND }
You'll see }
' }
null string }
a space }

A control string is a sequence of one or more control characters, each of which consists
of the # symbol followed by an unsigned integer constant from 0 to 255 (decimal or
hexadecimal) and denotes the corresponding ASCII character. The control string
#89#111#117

is equivalent to the quoted string

'You'

4-4

Object Pascal Language Guide

Comments and compiler directives

You can combine quoted strings with control strings to form larger character strings.
For example, you could use
'Line 1'#13#10'Line 2'

to put a carriage-returnline-feed between Line 1 and Line 2. However, you

cannot concatenate two quoted strings in this way, since a pair of sequential
apostrophes is interpreted as a single character. (To concatenate quoted strings, use
the + operator described in String operators on page 4-9, or simply combine them
into a single quoted string.)
A character strings length is the number of characters in the string. A character string
of any length is compatible with any string type, and with the PChar type when
extended syntax is enabled ({$X+}). A character string of length 1 is compatible with
any character type, and a character string of length n 1 is compatible with packed
arrays of n characters. For more information about string types, see Chapter 5, Data
types, variables, and constants.

Comments and compiler directives

Comments are ignored by the compiler, except when they function as separators
(delimiting adjacent tokens) or compiler directives.
There are several ways to construct comments:
{ Text between a left brace and a right brace constitutes a comment. }
(* Text between a left-parenthesis-plus-asterisk and an
asterisk-plus-right-parenthesis also constitutes a comment. *)
// Any text between a double-slash and the end of the line constitutes a comment.

A comment that contains a dollar sign ($) immediately after the opening { or (* is a
compiler directive. For example,
{$WARNINGS OFF}

tells the compiler not to generate warning messages.

Expressions
An expression is a construction that returns a value. For example,
X
@X
15
InterestRate
Calc(X,Y)
X * Y
Z / (1 - Z)
X = 1.5
C in Range1
not Done
['a','b','c']
Char(48)

{
{
{
{
{
{
{
{
{
{
{
{

variable }
address of a variable }
integer constant }
variable }
function call }
product of X and Y }
quotient of Z and (1 - Z) }
Boolean }
Boolean }
negation of a Boolean }
set }
value typecast }

Syntactic elements

4-5

Expressions

The simplest expressions are variables and constants (described in Chapter 5, Data
types, variables, and constants). More complex expressions are built from simpler
ones using operators, function calls, set constructors, indexes, and typecasts.

Operators
Operators behave like predefined functions that are part of the Object Pascal
language. For example, the expression (X + Y) is built from the variables X and Y
called operandswith the + operator; when X and Y represent integers or reals, (X + Y)
returns their sum. Operators include @, not, ^, *, /, div, mod, and, shl, shr, as, +, , or,
xor, =, >, <, <>, <=, >=, in, and is.
The operators @, not, and ^ are unary (taking one operand). All other operators are
binary (taking two operands), except that + and can function as either unary or
binary. A unary operator always precedes its operand (for example, -B), except for ^,
which follows its operand (for example, P^). A binary operator is placed between its
operands (for example, A = 7).
Some operators behave differently depending on the type of data passed to them. For
example, not performs bitwise negation on an integer operand and logical negation
on a Boolean operand. Such operators appear below under multiple categories.
Except for ^, is, and in, all operators can take operands of type Variant. For details,
see Variant types on page 5-29.
The sections that follow assume some familiarity with Object Pascal data types. For
information about data types, see Chapter 5, Data types, variables, and constants.
For information about operator precedence in complex expressions, see Operator
precedence rules on page 4-12.

Arithmetic operators
Arithmetic operators, which take real or integer operands, include +, , *, /, div, and
mod.
Table 4.3
Operator

Operation

Operand types

Result type

Example

addition

integer, real

X + Y

subtraction

integer, real

Result - 1

multiplication

integer, real

P * InterestRate

real division

integer, real

real

X / 2

div

integer division

integer

Total div UnitSize

mod

remainder

integer

Y mod 6

Example

Table 4.4

4-6

Binary arithmetic operators

Unary arithmetic operators

Operator

Operation

Operand type

Result type

sign identity

integer, real

sign negation

integer, real

-X

Object Pascal Language Guide

Expressions

The following rules apply to arithmetic operators.

The value of x/y is of type Extended, regardless of the types of x and y. For other
arithmetic operators, the result is of type Extended whenever at least one operand
is a real; otherwise, the result is of type Int64 when at least one operand is of type
Int64; otherwise, the result is of type Integer. If an operands type is a subrange of
an integer type, it is treated as if it were of the integer type.
The value of x div y is the value of x/y rounded in the direction of zero to the
nearest integer.
The mod operator returns the remainder obtained by dividing its operands. In
other words, x mod y = x (x div y) * y.
A runtime error occurs when y is zero in an expression of the form x/y, x div y, or
x mod y.

Boolean operators
The Boolean operators not, and, or, and xor take operands of any Boolean type and
return a value of type Boolean.
Table 4.5

Boolean operators

Operator

Operation

Operand types

Result type

Example

not

negation

Boolean

not (C in MySet)

and

conjunction

Boolean

Done and (Total > 0)

disjunction

Boolean

A or B

xor

exclusive disjunction

Boolean

A xor B

These operations are governed by standard rules of Boolean logic. For example, an
expression of the form x and y is True if and only if both x and y are True.

Complete versus short-circuit Boolean evaluation

The Delphi compiler supports two modes of evaluation for the and and or operators:
complete evaluation and short-circuit (partial) evaluation. Complete evaluation means
that each conjunct or disjunct is evaluated, even when the result of the entire
expression is already determined. Short-circuit evaluation means strict left-to-right
evaluation that stops as soon as the result of the entire expression is determined. For
example, if the expression A and B is evaluated under short-circuit mode when A is
False, the compiler wont evaluate B; it knows that the entire expression is False as
soon as it evaluates A.
Short-circuit evaluation is usually preferable because it guarantees minimum
execution time and, in most cases, minimum code size. Complete evaluation is
sometimes convenient when one operand is a function with side effects that alter the
execution of the program.

Syntactic elements

4-7

Expressions

Short-circuit evaluation also allows the use of constructions that might otherwise
result in illegal runtime operations. For example, the following code iterates through
the string S, up to the first comma.
while (I <= Length(S)) and (S[I] <> ',') do
begin

Inc(I);
end;

In a case where S has no commas, the last iteration increments I to a value which is
greater than the length of S. When the while condition is next tested, complete
evaluation results in an attempt to read S[I], which could cause a runtime error.
Under short-circuit evaluation, in contrast, the second part of the while condition
(S[I] <> ',')is not evaluated after the first part fails.
Use the $B compiler directive to control evaluation mode. The default state is {$B},
which enables short-circuit evaluation. To enable complete evaluation locally, add
the {$B+} directive to your code. You can also switch to complete evaluation on a
project-wide basis by selecting Complete Boolean Evaluation in the Compiler
Options dialog.

Logical (bitwise) operators

The following logical operators perform bitwise manipulation on integer operands.
For example, if the value stored in X (in binary) is 001101 and the value stored in Y is
100001, the statement
Z := X or Y;

assigns the value 101101 to Z.

Table 4.6
Operator

Logical (bitwise) operators

Operation

Operand types

Result type

Examples

not

bitwise negation

integer

not X

and

bitwise and

integer

X and Y

bitwise or

integer

X or Y

xor

bitwise xor

integer

X xor Y

shl

bitwise shift left

integer

X shl 2

shr

bitwise shift right

integer

Y shl I

The following rules apply to bitwise operators.

The result of a not operation is of the same type as the operand.
If the operands of an and, or, or xor operation are both integers, the result is of the
predefined integer type with the smallest range that includes all possible values of
both types.
The operations x shl y and x shr y shift the value of x to the left or right by y bits,
which is equivalent to multiplying or dividing x by 2y; the result is of the same
type as x. For example, if N stores the value 01101 (decimal 13), then N shl 1
returns 11010 (decimal 26).

4-8

Object Pascal Language Guide

Expressions

String operators
The relational operators =, <>, <, >, <=, and >= all take string operands (see
Relational operators on page 4-10). The + operator concatenates two strings.
Table 4.7

String operators

Operator

Operation

Operand types

Result type

Example

concatenation

string, packed string, character

string

S + '. '

The following rules apply to string concatenation.

The operands for + can be strings, packed strings (packed arrays of type Char), or
characters. However, if one operand is of type WideChar, the other operand must
be a long string.
The result of a + operation is compatible with any string type. However, if the
operands are both short strings or characters, and their combined length is greater
than 255, the result is truncated to the first 255 characters.

Pointer operators
The relational operators <, >, <=, and >= can take operands of type PChar (see
Relational operators on page 4-10). The following operators also take pointers as
operands. For more information about pointers, see Pointers and pointer types on
page 5-24.
Table 4.8

Character-pointer operators

Operator Operation

Operand types

Result type

Example

pointer addition

character pointer, integer

character pointer

P + I

pointer subtraction

character pointer, integer

P - Q

pointer dereference

pointer

base type of pointer

equality

pointer

Boolean

P = Q

inequality

pointer

Boolean

P <> Q

The ^ operator dereferences a pointer. Its operand can be a pointer of any type except
the generic Pointer, which must be typecast before dereferencing.
P = Q is True just in case P and Q point to the same address; otherwise, P <> Q is True.
You can use the + and operators to increment and decrement the offset of a
character pointer. You can also use to calculate the difference between the offsets of
two character pointers. The following rules apply.
If I is an integer and P is a character pointer, then P + I adds I to the address given
by P; that is, it returns a pointer to the address I characters after P. (The expression
I + P is equivalent to P + I.) P I subtracts I from the address given by P; that is, it
returns a pointer to the address I characters before P.
If P and Q are both character pointers, then P Q computes the difference between
the address given by P (the higher address) and the address given by Q (the lower
address); that is, it returns an integer denoting the number of characters between P
and Q. P + Q is not defined.

Syntactic elements

4-9

Expressions

Set operators
The following operators take sets as operands.
Table 4.9
Operator

Set operators
Operation

Operand types

Result type

Example

union

set

Set1 + Set2

difference

set

S - T

intersection

set

S * T

subset

set

Boolean

Q <= MySet

superset

set

Boolean

S1 >= S2

equality

set

Boolean

S2 = MySet

inequality

set

Boolean

MySet <> S1

membership

ordinal, set

Boolean

A in Set1

The following rules apply to +, , and *.

An ordinal O is in X + Y if and only if O is in X or Y (or both). O is in X Y if and
only if O is in X but not in Y. O is in X * Y if and only if O is in both X and Y.
The result of a +, , or * operation is of the type set of A..B, where A is the smallest
ordinal value in the result set and B is the largest.
The following rules apply to <=, >=, =, <>, and in.
X <= Y is True just in case every member of X is a member of Y; Z >= W is
equivalent to W <= Z. U = V is True just in case U and V contain exactly the same
members; otherwise, U <> V is True.
For an ordinal O and a set S, O in S is True just in case O is a member of S.

Relational operators
Relational operators are used to compare two operands. The operators =, <>, <=, and
>= also apply to sets (see Set operators on page 4-10); = and <> also apply to
pointers (see Pointer operators on page 4-9).
Table 4.10

4-10

Relational operators
Result
type

Example

simple, class, class reference, interface, string,

packed string

Boolean

I = Max

inequality

simple, class, class reference, interface, string,

packed string

Boolean

X <> Y

less-than

simple, string, packed string, PChar

Boolean

X < Y

greater-than

simple, string, packed string, PChar

Boolean

Len > 0

less-than-orequal-to

simple, string, packed string, PChar

Boolean

Cnt <= I

greater-thanor-equal-to

simple, string, packed string, PChar

Boolean

I >= 1

Operator

Operation

Operand types

equality

Object Pascal Language Guide

Expressions

For most simple types, comparison is straightforward. For example, I = J is True just
in case I and J have the same value, and I <> J is True otherwise. The following rules
apply to relational operators.
Operands must be of compatible types, except that a real and an integer can be
compared.
Strings are compared according to the ordering of the extended ASCII character
set. Character types are treated as strings of length 1.
Two packed strings must have the same number of components to be compared.
When a packed string with n components is compared to a string, the packed
string is treated as a string of length n.
The operators <, >, <=, and >= apply to PChar operands only if the two pointers
point within the same character array.
The operators = and <> can take operands of class and class-reference types. With
operands of a class type, = and <> are evaluated according the rules that apply to
pointers: C = D is True just in case C and D point to the same instance object, and C
<> D is True otherwise. With operands of a class-reference type, C = D is True just
in case C and D denote the same class, and C <> D is True otherwise. For more
information about classes, see Chapter 7, Classes and objects.

Class operators
The operators as and is take classes and instance objects as operands; as operates on
interfaces as well. For more information, see Chapter 7, Classes and objects and
Chapter 10, Object interfaces.
The relational operators = and <> also operate on classes. See Relational operators
on page 4-10.

The @ operator
The @ operator returns the address of a variable, or of a function, procedure, or
method; that is, @ constructs a pointer to its operand. For more information about
pointers, see Pointers and pointer types on page 5-24. The following rules apply to @.
If X is a variable, @X returns the address of X. (Special rules apply when X is a
procedural variable; see Procedural types in statements and expressions on
page 5-28.) The type of @X is Pointer if the default {$T} compiler directive is in
effect. In the {$T+} state, @X is of type ^T, where T is the type of X.
If F is a routine (a function or procedure), @F returns Fs entry point. The type of
@F is always Pointer.
When @ is applied to a method defined in a class, the method identifier must be
qualified with the class name. For example,
@TMyClass.DoSomething

points to the DoSomething method of TMyClass. For more information about

classes and methods, see Chapter 7, Classes and objects.

Syntactic elements

4-11

Expressions

Operator precedence rules

In complex expressions, rules of precedence determine the order in which operations
are performed.
Table 4.11

Precedence of operators

Operators

Precedence

@, not

first (highest)

*, /, div, mod, and, shl, shr, as

second

+, , or, xor

third

=, <>, <, >, <=, >=, in, is

fourth (lowest)

An operator with higher precedence is evaluated before an operator with lower

precedence, while operators of equal precedence associate to the left. Hence the
expression
X + Y * Z

multiplies Y times Z, then adds X to the result; * is performed first, because is has a
higher precedence than +. But
X - Y + Z

first subtracts Y from X, then adds Z to the result; and + have the same precedence,
so the operation on the left is performed first.
You can use parentheses to override these precedence rules. An expression within
parentheses is evaluated first, then treated as a single operand. For example,
(X + Y) * Z

multiplies Z times the sum of X and Y.

Parentheses are sometimes needed in situations where, at first glance, they seem not
to be. For example, consider the expression
X = Y or X = Z

The intended interpretation of this is obviously

(X = Y) or (X = Z)

Without parentheses, however, the compiler follows operator precedence rules and
reads it as
(X = (Y or X)) = Z

which results in a compilation error unless Z is Boolean.

Parentheses often make code easier to write and to read, even when they are, strictly
speaking, superfluous. Thus the first example above could be written as
X + (Y * Z)

Here the parentheses are unnecessary (to the compiler), but they spare both
programmer and reader from having to think about operator precedence.

4-12

Object Pascal Language Guide

Expressions

Function calls
Because functions return a value, function calls are expressions. For example, if youve
defined a function called Calc that takes two integer arguments and returns an integer,
then the function call Calc(24, 47) is an integer expression. If I and J are integer variables,
then I + Calc(J, 8) is also an integer expression. Examples of function calls include
Sum(A, 63)
Maximum(147, J)
Sin(X + Y)
Eof(F)
Volume(Radius, Height)
GetValue
TSomeObject.SomeMethod(I,J);

For more information about functions, see Chapter 6, Procedures and functions.

Set constructors
A set constructor denotes a set-type value. For example,
[5, 6, 7, 8]

denotes the set whose members are 5, 6, 7, and 8. The set constructor
[ 5..8 ]

could also denote the same set.

The syntax for a set constructor is
[ item1, ..., itemn ]
where each item is either an expression denoting an ordinal of the sets base type or a
pair of such expressions with two dots (..) in between. When an item has the form x..y,
it is shorthand for all the ordinals in the range from x to y, inclusive; but if x is greater
than y, then x..y denotes nothing and [x..y] is the empty set. The set constructor [ ]
denotes the empty set, while [x] denotes the set whose only member is the value of x.
Examples of set constructors:
[red, green, MyColor]
[1, 5, 10..K mod 12, 23]
['A'..'Z', 'a'..'z', Chr(Digit + 48)]

For more information about sets, see Sets on page 5-16.

Indexes
Strings, arrays, array properties, and pointers to strings or arrays can be indexed. For
example, if FileName is a string variable, the expression FileName[3] returns the third
character in the string denoted by FileName, while FileName[I + 1] returns the
character immediately after the one indexed by I. For information about strings, see
String types on page 5-9. For information about arrays and array properties, see
Arrays on page 5-16 and Array properties on page 7-18.

Syntactic elements

4-13

Expressions

Typecasts
It is sometimes useful to treat an expression as if it belonged to different type. A
typecast allows you to do this by, in effect, temporarily changing an expressions
type. For example, Integer('A') casts the character A as an integer.
The syntax for a typecast is
typeIdentifier(expression)
If the expression is a variable, the result is called a variable typecast; otherwise, the
result is a value typecast. While their syntax is the same, different rules apply to the
two kinds of typecast.

Value typecasts
In a value typecast, the type identifier and the cast expression must both be ordinal
types or both be pointer types. Examples of value typecasts include
Integer('A')
Char(48)
Boolean(0)
Color(2)
Longint(@Buffer)

The resulting value is obtained by converting the expression in parentheses. This

may involve truncation or extension if the size of the specified type differs from that
of the expression. The expressions sign is always preserved.
The statement
I := Integer('A');

assigns the value of Integer('A')that is, 65to the variable I.

A value typecast cannot be followed by qualifiers and cannot appear on the left side
of an assignment statement.

Variable typecasts
You can cast any variable to any type, provided their sizes are the same and you do
not mix integers with reals. (To convert numeric types, rely on standard functions
like Int and Trunc.) Examples of variable typecasts include
Char(I)
Boolean(Count)
TSomeDefinedType(MyVariable)

Variable typecasts can appear on either side of an assignment statement. Thus

var MyChar: char;

Shortint(MyChar) := 122;

assigns the character z (ASCII 122) to MyChar.

4-14

Object Pascal Language Guide

Expressions

You can cast variables to a procedural type. For example, given the declarations
type
var
F:
P:
N:

Func = function(X: Integer): Integer;

Func;
Pointer;
Integer;

you can make the following assignments.

F := Func(P);
Func(P) := F;
@F := P;
P := @F;
N := F(N);
N := Func(P)(N);

{
{
{
{
{
{

Assign procedural value

Assign procedural value
Assign pointer value in
Assign pointer value in
Call function via F }
Call function via P }

in P
in F
P to
F to

to F }
to P }
F }
P }

Variable typecasts can also be followed by qualifiers, as illustrated in the following

example.
type
TByteRec = record
Lo, Hi: Byte;
end;
TWordRec = record
Low, High: Word;
end;
PByte = ^Byte;
var
B: Byte;
W: Word;
L: Longint;
P: Pointer;
begin
W := $1234;
B := TByteRec(W).Lo;
TByteRec(W).Hi := 0;
L := $01234567;
W := TWordRec(L).Low;
B := TByteRec(TWordRec(L).Low).Hi;
B := PByte(L)^;
end;

In this example, TByteRec is used to access the low- and high-order bytes of a word,
and TWordRec to access the low- and high-order words of a long integer. You could
call the predefined functions Lo and Hi for the same purpose, but a variable typecast
has the advantage that it can be used on the left side of an assignment statement.
For information about typecasting pointers, see Pointers and pointer types on
page 5-24. For information about casting class and interface types, see The as
operator on page 7-24 and Interface typecasts on page 9.

Syntactic elements

4-15

Declarations and statements

Aside from the uses clause (and reserved words like implementation that demarcate
parts of a unit), a program consists entirely of declarations and statements, which are
organized into blocks.

Declarations
The names of variables, constants, types, fields, properties, procedures, functions,
programs, units, libraries, and packages are called identifiers. (Numeric constants like
26057 are not identifiers.) Identifiers must be declared before you can use them; the
only exceptions are a few predefined types, routines, and constants that the compiler
understands automatically, the variable Result when it occurs inside a function block,
and the variable Self when it occurs inside a method implementation.
A declaration defines an identifier and, where appropriate, allocates memory for it.
For example,
var Size: Extended;

declares a variable called Size that holds an Extended (real) value, while
function DoThis(X, Y: string): Integer;

declares a function called DoThis that takes two strings as arguments and returns an
integer. Each declaration ends with a semicolon. When you declare several variables,
constants, types, or labels at the same time, you need only write the appropriate
reserved word once:
var
Size: Extended;
Quantity: Integer;
Description: string;

The syntax and placement of a declaration depend on the kind of identifier you are
defining. In general, declarations can occur only at the beginning of a block or at the
beginning of the interface or implementation section of a unit (after the uses clause).
Specific conventions for declaring variables, constants, types, functions, and so forth
are explained in the chapters on those topics.

Statements
Statements define algorithmic actions within a program. Simple statementslike
assignments and procedure callscan combine to form loops, conditional
statements, and other structured statements.
Multiple statements within a block, and in the initialization or finalization section of
a unit, are separated by semicolons.

Simple statements
A simple statement doesnt contain any other statements. Simple statements include
assignments, calls to procedures and functions, and goto jumps.

4-16

Object Pascal Language Guide

Declarations and statements

Assignment statements
An assignment statement has the form
variable := expression
where variable is any variable referenceincluding a variable, variable typecast,
dereferenced pointer, or component of a structured variableand expression is any
assignment-compatible expression. (Within a function block, variable can be replaced
with the name of the function being defined. See Chapter 6, Procedures and
functions.) The := symbol is sometimes called the assignment operator.
An assignment statement replaces the current value of variable with the value of
expression. For example,
I := 3;

assigns the value 3 to the variable I. The variable reference on the left side of the
assignment can appear in the expression on the right. For example,
I := I + 1;

increments the value of I. Other assignment statements include

X := Y + Z;
Done := (I >= 1) and (I < 100);
Hue1 := [Blue, Succ(C)];
I := Sqr(J) - I * K;
Shortint(MyChar) := 122;
TByteRec(W).Hi := 0;
MyString[I] := 'A';
SomeArray[I + 1] := P^;
TMyObject.SomeProperty := True;

Procedure and function calls

A procedure call consists of the name of a procedure (with or without qualifiers),
followed by a parameter list (if required). Examples include
PrintHeading;
Transpose(A, N, M);
Find(Smith, William);
Writeln('Hello world!');
DoSomething();
Unit1.SomeProcedure;
TMyObject.SomeMethod(X,Y);

Function calls, like calls to procedures, can be treated as statements in their own right:
MyFunction(X);

When you use a function call in this way, its return value is discarded.
For more information about procedures and functions, see Chapter 6, Procedures
and functions.

Syntactic elements

4-17

Declarations and statements

Goto statements
A goto statement, which has the form
goto label
transfers program execution to the statement marked by the specified label. To mark
a statement, you must first declare the label. Then precede the statement you want to
mark with the label and a colon:
label: statement
Declare labels like this:
label label;
You can declare several labels at once:
label label1, ..., labeln;
A label can be any valid identifier or any numeral between 0 and 9999.
The label declaration, marked statement, and goto statement must belong to the same
block. (See Blocks and scope on page 4-27.) Hence it is not possible to jump into or
out of a procedure or function. Do not mark more than one statement in a block with
the same label.
For example,
label StartHere;

StartHere: Beep;
goto StartHere;

creates an infinite loop that calls the Beep procedure repeatedly.

The goto statement is generally discouraged in structured programming. It is,
however, sometimes used as a way of exiting from nested loops, as in the following
example.
procedure FindFirstAnswer;
var X, Y, Z, Count: Integer;
label FoundAnAnswer;
begin
Count := SomeConstant;
for X := 1 to Count do
for Y := 1 to Count do
for Z := 1 to Count do
if ... { some condition holds on X, Y, and Z } then
goto FoundAnAnswer;
{code to execute if no answer is found }
Exit;
FoundAnAnswer:
{ code to execute when an answer is found }
end;

4-18

Object Pascal Language Guide

Declarations and statements

Notice that we are using goto to jump out of a nested loop. Never jump into a loop or
other structured statement, since this can have unpredictable effects.

Structured statements
Structured statements are built from other statements. Use a structured statement
when you want to execute other statements sequentially, conditionally, or
repeatedly.
A compound or with statement simply executes a sequence of constituent
statements.
A conditional statementthat is, an if or case statementexecutes at most one of
its constituents, depending on specified criteria.
Loop statementsincluding repeat, while, and for loopsexecute a sequence of
constituent statements repeatedly.
A special group of statementsincluding raise, try...except, and try...finally
constructionscreate and handle exceptions. For information about exception
generation and handling, see Exceptions on page 7-25.

Compound statements
A compound statement is a sequence of other (simple or structured) statements to be
executed in the order in which they are written. The compound statement is
bracketed by the reserved words begin and end, and its constituent statements are
separated by semicolons. For example:
begin
Z := X;
X := Y;
Y := Z;
end;

The last semicolon before end is optional. So we could have written this as
begin
Z := X;
X := Y;
Y := Z
end;

Compound statements are essential in contexts where Object Pascal syntax requires a
single statement. In addition to program, function, and procedure blocks, they occur
within other structured statements, such as conditionals or loops. For example:
begin
I := SomeConstant;
while I > 0 do
begin

I := I - 1;
end;
end;

Syntactic elements

4-19

Declarations and statements

You can write a compound statement that contains only a single constituent
statement; like parentheses in a complex term, begin and end sometimes serve to
disambiguate and to improve readability. You can also use an empty compound
statement to create a block that does nothing:
begin
end;

With statements
A with statement is a shorthand for referencing the fields of a record or the fields,
properties, and methods of an object. The syntax of a with statement is
with obj do statement
or
with obj1, ..., objn do statement
where obj is a variable reference denoting an object or record, and statement is any
simple or structured statement. Within statement, you can refer to fields, properties,
and methods of obj using their identifiers alonewithout qualifiers.
For example, given the declarations
type TDate = record
Day: Integer;
Month: Integer;
Year: Integer;
end;
var OrderDate: TDate;

you could write the following with statement.

with OrderDate do
if Month = 12 then
begin
Month := 1;
Year := Year + 1;
end
else
Month := Month + 1;

This is equivalent to
if OrderDate.Month = 12 then
begin
OrderDate.Month := 1;
OrderDate.Year := OrderDate.Year + 1;
end
else
OrderDate.Month := OrderDate.Month + 1;

If the interpretation of obj involves indexing arrays or dereferencing pointers, these

actions are performed once, before statement is executed. This makes with statements
efficient as well as concise. It also means that assignments to a variable within

4-20

Object Pascal Language Guide

Declarations and statements

statement cannot affect the interpretation of obj during the current execution of the
with statement.
Each variable reference or method name in a with statement is interpreted, if
possible, as a member of the specified object or record. If there is another variable or
method of the same name that you want to access from the with statement, you need
to prepend it with a qualifier, as in the following example.
with OrderDate do
begin
Year := Unit1.Year

end;

When multiple objects or records appear after with, the entire statement is treated
like a series of nested with statements. Thus
with obj1, obj2, ..., objn do statement
is equivalent to
with obj1 do
with obj2 do

with objn do
statement
In this case, each variable reference or method name in statement is interpreted, if
possible, as a member of objn; otherwise it is interpreted, if possible, as a member of
objn1; and so forth. The same rule applies to interpreting the objs themselves, so that,
for instance, if objn is a member of both obj1 and obj2, it is interpreted as obj2.objn.

If statements
There are two forms of if statement: if...then and the if...then...else. The syntax of an
if...then statement is
if expression then statement
where expression returns a Boolean value. If expression is True, then statement is
executed; otherwise it is not. For example,
if J <> 0 then Result := I/J;

The syntax of an if...then...else statement is

if expression then statement1 else statement2
where expression returns a Boolean value. If expression is True, then statement1 is
executed; otherwise statement2 is executed. For example,
if J = 0 then
Exit
else
Result := I/J;

Syntactic elements

4-21

Declarations and statements

The then and else clauses contain one statement each, but it can be a structured
statement. For example,
if J <> 0 then
begin
Result := I/J;
Count := Count + 1;
end
else if Count = Last then
Done := True
else
Exit;

Notice that there is never a semicolon between the then clause and the word else.
You can place a semicolon after an entire if statement to separate it from the next
statement in its block, but the then and else clauses require nothing more than a
space or carriage return between them. Placing a semicolon immediately before else
(in an if statement) is a common programming error.
A special difficulty arises in connection with nested if statements. The problem arises
because some if statements have else clauses while others do not, but the syntax for
the two kinds of statement is otherwise the same. In a series of nested conditionals
where there are fewer else clauses than if statements, it may not seem clear which
else clauses are bound to which ifs. Consider a statement of the form
if expression1 then if expression2 then statement1 else statement2;
There would appear to be two ways to parse this:
if expression1 then [ if expression2 then statement1 else statement2 ];
if expression1 then [ if expression2 then statement1 ] else statement2;
The compiler always parses in the first way. That is, in real code, the statement
if ... { expression1 } then
if ... { expression2 } then
... { statement1 }
else
... { statement2 } ;

is equivalent to
if ... { expression1 } then
begin
if ... { expression2 } then
... { statement1 }
else
... { statement2 }
end;

The rule is that nested conditionals are parsed starting from the innermost
conditional, with each else bound to the nearest available if on its left. To force the

4-22

Object Pascal Language Guide

Declarations and statements

compiler to read our example in the second way, you would have to write it
explicitly as
if ... { expression1 } then
begin
if ... { expression2 } then
... { statement1 }
end
else
... { statement2 } ;

Case statements
The case statement provides a readable alternative to complex nested if conditionals.
A case statement has the form
case selectorExpression of
caseList1: statement1;

caseListn: statementn;
end
where selectorExpression is any expression of an ordinal type (string types are invalid)
and each caseList is one of the following:
A numeral, declared constant, or other expression that the compiler can evaluate
without executing your program. It must be of an ordinal type compatible with
selectorExpression. Thus 7, True, 4 + 5 * 3, 'A', and Integer('A') can all be used as
caseLists, but variables and most function calls cannot. (A few built-in functions
like Hi and Lo can occur in a caseList. See Constant expressions on page 5-39.)
A subrange having the form First..Last, where First and Last both satisfy the
criterion above and First is less than or equal to Last.
A list having the form item1, ..., itemn, where each item satisfies one of the criteria
above.
Each value represented by a caseList must be unique in the case statement; subranges
and lists cannot overlap. A case statement can have a final else clause:
case selectorExpression of
caseList1: statement1;

caseListn: statementn;
else
statement;
end
When a case statement is executed, at most one of its constituent statements is
executed. Whichever caseList has a value equal to that of selectorExpression determines
the statement to be used. If none of the caseLists has the same value as
selectorExpression, then the statement in the else clause (if there is one) is executed.

Syntactic elements

4-23

Declarations and statements

The case statement

case I of
1..5: Caption := 'Low';
6..9: Caption := 'High';
0, 10..99: Caption := 'Out of range';
else
Caption := '';
end;

is equivalent to the nested conditional

if I in [1..5] then
Caption := 'Low'
else if I in [6..10] then
Caption := 'High'
else if (I = 0) or (I in [10..99]) then
Caption := 'Out of range'
else
Caption := '';

Other examples of case statements:

case MyColor of
Red: X := 1;
Green: X := 2;
Blue: X := 3;
Yellow, Orange, Black: X := 0;
end;
case Selection of
Done: Form1.Close;
Compute: CalculateTotal(UnitCost, Quantity);
else
Beep;
end;

Control loops
Loops allow you to execute a sequence of statements repeatedly, using a control
condition or variable to determine when the execution stops. Object Pascal has three
kinds of control loop: repeat statements, while statements, and for statements.
You can use the standard Break and Continue procedures to control the flow of a
repeat, while, or for statement. Break terminates the statement in which it occurs,
while Continue begins executing the next iteration of the sequence. For more
information about these procedures, see the online Help.

Repeat statements
The syntax of a repeat statement is
repeat statement1; ...; statementn; until expression
where expression returns a Boolean value. (The last semicolon before until is
optional.) The repeat statement executes its sequence of constituent statements
continually, testing expression after each iteration. When expression returns True, the

4-24

Object Pascal Language Guide

Declarations and statements

repeat statement terminates. The sequence is always executed at least once because
expression is not evaluated until after the first iteration.
Examples of repeat statements include
repeat
K := I mod J;
I := J;
J := K;
until J = 0;
repeat
Write('Enter a value (0..9): ');
Readln(I);
until (I >= 0) and (I <= 9);

While statements
A while statement is similar to a repeat statement, except that the control condition is
evaluated before the first execution of the statement sequence. Hence, if the condition
is false, the statement sequence is never executed.
The syntax of a while statement is
while expression do statement
where expression returns a Boolean value and statement can be a compound statement.
The while statement executes its constituent statement repeatedly, testing expression
before each iteration. As long as expression returns True, execution continues.
Examples of while statements include
while Data[I] <> X do I := I + 1;
while I > 0 do
begin
if Odd(I) then Z := Z * X;
I := I div 2;
X := Sqr(X);
end;
while not Eof(InputFile) do
begin
Readln(InputFile, Line);
Process(Line);
end;

For statements
A for statement, unlike a repeat or while statement, requires you to specify explicitly
the number of iterations you want the loop to go through. The syntax of a for
statement is
for counter := initialValue to finalValue do statement
or
for counter := initialValue downto finalValue do statement

Syntactic elements

4-25

Declarations and statements

where
counter is a local variable (declared in the block containing the for statement) of
ordinal type, without any qualifiers.
initialValue and finalValue are expressions that are assignment-compatible with
counter.
statement is a simple or structured statement that does not change the value of counter.
The for statement assigns the value of initialValue to counter, then executes statement
repeatedly, incrementing or decrementing counter after each iteration. (The for...to
syntax increments counter, while the for...downto syntax decrements it.) When
counter returns the same value as finalValue, statement is executed once more and the
for statement terminates. In other words, statement is executed once for every value
in the range from initialValue to finalValue. If initialValue is equal to finalValue,
statement is executed exactly once. If initialValue is greater than finalValue in a for...to
statement, or less than finalValue in a for...downto statement, then statement is never
executed. After the for statement terminates, the value of counter is undefined.
For purposes of controlling execution of the loop, the expressions initialValue and
finalValue are evaluated only once, before the loop begins. Hence the for...to
statement is almost, but not quite, equivalent to this while construction:
begin
counter := initialValue;
while counter <= finalValue do
begin
statement;
counter := Succ(counter);
end;
end
The difference between this construction and the for...to statement is that the while
loop re-evaluates finalValue before each iteration. This can result in noticeably slower
performance if finalValue is a complex expression, and it also means that changes to
the value of finalValue within statement can affect execution of the loop.
Examples of for statements:
for I := 2 to 63 do
if Data[I] > Max then
Max := Data[I];
for I := ListBox1.Items.Count - 1 downto 0 do
ListBox1.Items[I] := UpperCase(ListBox1.Items[I]);
for I := 1 to 10 do
for J := 1 to 10 do
begin
X := 0;
for K := 1 to 10 do
X := X + Mat1[I, K] * Mat2[K, J];
Mat[I, J] := X;
end;
for C := Red to Blue do Check(C);

4-26

Object Pascal Language Guide

Blocks and scope

Declarations and statements are organized into blocks, which define local namespaces
(or scopes) for labels and identifiers. Blocks allow a single identifier, such as a variable
name, to have different meanings in different parts of a program. Each block is part
of the declaration of a program, function, or procedure; each program, function, or
procedure declaration has one block.

Blocks
A block consists of a series of declarations followed by a compound statement. All
declarations must occur together at the beginning of the block. So the form of a block is
declarations
begin
statements
end
The declarations section can include, in any order, declarations for variables, constants
(including resource strings), types, procedures, functions, and labels. In a program
block, the declarations section can also include one or more exports clauses (see
Chapter 9, Dynamic-link libraries and packages).
For example, in a function declaration like
function UpperCase(const S: string): string;
var
Ch: Char;
L: Integer;
Source, Dest: PChar;
begin

end;

the first line of the declaration is the function heading and all of the succeeding lines
make up the block. Ch, L, Source, and Dest are local variables; their declarations apply
only to the UpperCase function block and overridein this block onlyany
declarations of the same identifiers that may occur in the program block or in the
interface or implementation section of a unit.

Scope
An identifier, such as a variable or function name, can be used only within the scope
of its declaration. The location of a declaration determines its scope. An identifier
declared within the declaration of a program, function, or procedure has a scope
limited to the block in which it is declared. An identifier declared in the interface
section of a unit has a scope that includes any other units or programs that use the
unit where the declaration occurs. Identifiers with narrower scopeespecially
identifiers declared in functions and proceduresare sometimes called local, while
identifiers with wider scope are called global.

Syntactic elements

4-27

Blocks and scope

The rules that determine identifier scope are summarized below.

If the identifier is declared in ...

its scope extends ...

the declaration of a program, function, or

procedure

from the point where it is declared to the end of

the current block, including all blocks enclosed
within that scope.

the interface section of a unit

from the point where it is declared to the end of

the unit, and to any other unit or program that
uses that unit. (See Chapter 3, Programs and
units.)

the implementation section of a unit, but not

within the block of any function or procedure

from the point where it is declared to the end of

the implementation section. The identifier is
available to any function or procedure within
that implementation section.

the definition of a record type (that is, the

identifier is the name of a field in the record)

from the point of its declaration to the end of the

field-type definition. (See Records on
page 5-20.)

the definition of a class (that is, the identifier is

the name of a property or method in the class)

from the point of its declaration to the end of the

class-type definition, and also includes
descendants of the class and the blocks of all
methods in the class and its descendants. (See
Chapter 7, Classes and objects.)

Naming conflicts
When one block encloses another, the former is called the outer block and the latter the
inner block. If an identifier declared in an outer block is redeclared in an inner block,
the inner declaration overrides the outer one and determines the meaning of the
identifier for the duration of the inner block. For example, if you declare a variable
called MaxValue in the interface section of a unit, and then declare another variable
with the same name in a function declaration within that unit, any unqualified
occurrences of MaxValue in the function block are governed by the second, local
declaration. Similarly, a function declared within another function creates a new,
inner scope in which identifiers used by the outer function can be redeclared locally.
The use of multiple units further complicates the definition of scope. Each unit listed
in a uses clause imposes a new scope that encloses the remaining units used and the
program or unit containing the uses clause. The first unit in a uses clause represents
the outermost scope and each succeeding unit represents a new scope inside the
previous one. If two or more units declare the same identifier in their interface
sections, an unqualified reference to the identifier selects the declaration in the
innermost scopethat is, in the unit where the reference itself occurs, or, if that unit
doesnt declare the identifier, in the last unit in the uses clause that does declare the
identifier.
The System unit is used automatically by every program or unit. The declarations in
System, along with the predefined types, routines, and constants that the compiler
understands automatically, always have the outermost scope.
You can override these rules of scope and by-pass an inner declaration by using a
qualified identifier (see Qualified identifiers on page 4-2) or a with statement (see
With statements on page 4-20).

4-28

Object Pascal Language Guide

Chapter

Data types, variables, and constants

Chapter5

A type is essentially a name for a kind of data. When you declare a variable you must
specify its type, which determines the set of values the variable can hold and the
operations that can be performed on it. Every expression returns data of a particular
type, as does every function. Most functions and procedures require parameters of
specific types.
Object Pascal is a strongly typed language, which means that it distinguishes a
variety of data types and does not always allow you to substitute one type for
another. This is usually beneficial because it lets the compiler treat data intelligently
and validate your code more thoroughly, preventing hard-to-diagnose runtime
errors. When you need greater flexibility, however, there are mechanisms to
circumvent strong typing. These include typecasting (see Typecasts on page 4-14),
pointers (see Pointers and pointer types on page 5-24), variants (see Variant types
on page 5-29), variant parts in records (see Variant parts in records on page 5-21),
and absolute addressing of variables (see Absolute addresses on page 5-37).

About types
There are several ways to categorize Object Pascal data types:
Some types are predefined (or built-in); the compiler recognizes these automatically,
without the need for a declaration. Almost all of the types documented in this
language reference are predefined. Other types are created by declaration; these
include user-defined types and the types defined in Delphis libraries.
Types can be classified as either fundamental or generic. The range and format of a
fundamental type is the same in all implementations of Object Pascal, regardless
of the underlying CPU and operating system. The range and format of a generic
type is platform-specific and could vary across different implementations. Most
predefined types are fundamental, but a handful of integer, character, string, and
pointer types are generic. Its a good idea to use generic types when possible, since
they provide optimal performance and portability. However, changes in storage
Data types, variables, and constants

5-1

Simple types

format from one implementation of a generic type to the next could cause
compatibility problemsfor example, if you are streaming data to a file.
Types can be classified as simple, string, structured, pointer, procedural, or variant. In
addition, type identifiers themselves can be regarded as belonging to a special
type because they can be passed as parameters to certain functions (such as
High, Low, and SizeOf).
The outline below shows the taxonomy of Object Pascal data types.
simple
ordinal
integer
character
Boolean
enumerated
subrange
real
string
structured
set
array
record
file
class
class reference
interface
pointer
procedural
variant
type identifier
The standard function SizeOf operates on all variables and type identifiers. It returns
an integer representing the amount of memory (in bytes) used to store data of the
specified type. For example, SizeOf(Longint) returns 4, since a Longint variable uses
four bytes of memory.
Type declarations are illustrated in the sections that follow. For general information
about type declarations, see Declaring types on page 5-35.

Simple types
Simple types, which include ordinal types and real types, define ordered sets of values.

Ordinal types
Ordinal types include integer, character, Boolean, enumerated, and subrange types. An
ordinal type defines an ordered set of values in which each value except the first has
a unique predecessor and each value except the last has a unique successor. Further,

5-2

Object Pascal Language Guide

Simple types

each value has an ordinality, which determines the ordering of the type. For integer
types, the ordinality of a value is the value itself; for all other ordinal types except
subranges, the first value has ordinality 0, the next value has ordinality 1, and so
forth. If a value has ordinality n, its predecessor has ordinality n1 and its successor
has ordinality n+1.
Several predefined functions operate on ordinal values and type identifiers. The most
important of them are summarized below.
Function

Parameter

Return value

Remarks

Ord

ordinal expression

ordinality of expressions
value

Does not take Int64

arguments.

Pred

ordinal expression

predecessor of expressions
value

Do not use on properties

that have a write procedure.

Succ

ordinal expression

successor of expressions
value

Do not use on properties

that have a write procedure.

High

ordinal type identifier or

variable of ordinal type

highest value in type

Also operates on short-string

types and arrays.

Low

ordinal type identifier or

variable of ordinal type

lowest value in type

Also operates on short-string

types and arrays.

For example, High(Byte) returns 255 because the highest value of type Byte is 255, and
Succ(2) returns 3 because 3 is the successor of 2.
The standard procedures Inc and Dec increment and decrement the value of an
ordinal variable. For example, Inc(I) is equivalent to I := Succ(I) and, if I is an
integer variable, to I := I + 1.

Integer types
An integer type represents a subset of the whole numbers. The generic integer types
are Integer and Cardinal; use these whenever possible, since they result in the best
performance for the underlying CPU and operating system. The table below gives
their ranges and storage formats for the current 32-bit Object Pascal compiler.
Table 5.1

Generic integer types for 32-bit implementations of Object Pascal

Type

Range

Format

Integer

2147483648..2147483647

signed 32-bit

Cardinal

0..4294967295

unsigned 32-bit

Fundamental integer types include Shortint, Smallint, Longint, Int64, Byte, Word, and
Longword.
Table 5.2

Fundamental integer types

Type

Range

Format

Shortint

128..127

signed 8-bit

Smallint

32768..32767

signed 16-bit

Longint

2147483648..2147483647

signed 32-bit

Data types, variables, and constants

5-3

Simple types

Table 5.2

Fundamental integer types (continued)

Type

Range
63

Format

Int64

2 ..2 1

Byte

0..255

unsigned 8-bit

Word

0..65535

unsigned 16-bit

Longword

0..4294967295

unsigned 32-bit

signed 64-bit

In general, arithmetic operations on integers return a value of type Integerwhich, in

its current implementation, is equivalent to the 32-bit Longint. Operations return a
value of type Int64 only when performed on an Int64 operand. Hence the following
code produces incorrect results.
var
I:
J:

I :=
J :=

Integer;
Int64;
High(Integer);
I + 1;

To get an Int64 return value in this situation, cast I as Int64:

J := Int64(I) + 1;

For more information, see Arithmetic operators on page 4-6.

Note

Most standard routines that take integer arguments truncate Int64 values to 32 bits.
However, the High, Low, Succ, Pred, Inc, Dec, IntToStr, and IntToHex routines fully
support Int64 arguments. Also, the Round, Trunc, StrToInt64, and StrToInt64Def
functions return Int64 values. A few routinesincluding Ordcannot take Int64
values at all.
When you increment the last value or decrement the first value of an integer type, the
result wraps around the beginning or end of the range. For example, the Shortint type
has the range 128..127; hence, after execution of the code
var I: Shortint;

I := High(Shortint);
I := I + 1;

the value of I is 128. If compiler range-checking is enabled, however, this code

generates a runtime error.

Character types
The fundamental character types are AnsiChar and WideChar. AnsiChar values are
byte-sized (8-bit) characters ordered according to the extended ANSI character set.
WideChar values are word-sized (16-bit) characters ordered according to the Unicode
character set. The first 256 Unicode characters correspond to the ANSI characters.
The generic character type is Char, which is equivalent to AnsiChar. Because the
implementation of Char is subject to change, its a good idea to use the standard

5-4

Object Pascal Language Guide

Simple types

function SizeOf rather than a hard-coded constant when writing programs that may
need to handle characters of different sizes.
A string constant of length 1, such as 'A', can denote a character value. The
predefined function Chr returns the character value for any integer in the range of
AnsiChar or WideChar; for example, Chr(65) returns the letter A.
Character values, like integers, wrap around when decremented or incremented past
the beginning or end of their range (unless range-checking is enabled). For example,
after execution of the code
var
Letter: Char;
I: Integer;
begin
Letter := High(Letter);
for I := 1 to 66 do
Inc(Letter);
end;

Letter has the value A (ASCII 65).

For more information about Unicode characters, see About extended character sets
on page 5-12 and Working with null-terminated strings on page 5-12.

Boolean types
The four predefined Boolean types are Boolean, ByteBool, WordBool, and LongBool.
Boolean is the preferred type. The others exist to provide compatibility with different
languages and the Windows environment.
A Boolean variable occupies one byte of memory, a ByteBool variable also occupies
one byte, a WordBool variable occupies two bytes (one word), and a LongBool variable
occupies four bytes (two words).
Boolean values are denoted by the predefined constants True and False. The
following relationships hold.
Boolean

ByteBool, WordBool, LongBool

False < True

False <> True

Ord(False) = 0

Ord(True) = 1

Ord(True) <> 0

Succ(False) = True

Pred(True) = False

Pred(False) = True

A value of type ByteBool, LongBool, or WordBool is considered True when its ordinality
is nonzero. If such a value appears in a context where a Boolean is expected, the
compiler automatically converts any value of nonzero ordinality to True.

Data types, variables, and constants

5-5

Simple types

The remarks above refer to the ordinality of Boolean valuesnot to the values
themselves. In Object Pascal, Boolean expressions cannot be equated with integers or
reals. Hence, if X is an integer variable, the statement
if X then ...;

generates a compilation error. Casting the variable to a Boolean type is unreliable,

but each of the following alternatives will work.
if X <> 0 then ...;

{ use longer expression that returns Boolean value }

var OK: Boolean

{ use Boolean variable }

if X <> 0 then OK := True;

if OK then ...;

Enumerated types
An enumerated type defines an ordered set of values by simply listing identifiers that
denote these values. The values have no inherent meaning, and their ordinality
follows the sequence in which the identifiers are listed.
To declare an enumerated type, use the syntax
type typeName = (val1, ..., valn)
where typeName and each val are valid identifiers. For example, the declaration
type Suit = (Club, Diamond, Heart, Spade);

defines an enumerated type called Suit whose possible values are Club, Diamond,
Heart, and Spade.
When you declare an enumerated type, you are declaring each val to be a constant of
type typeName. If the val identifiers are used for another purpose within the same
scope, naming conflicts occur. For example, suppose you declare the type
type TSound = (Click, Clack, Clock);

Unfortunately, Click is also the name of a method defined for TControl and all of the
objects in Delphis VCL that descend from it. So if youre writing a Delphi application
and you create an event handler like
procedure TForm1.DBGrid1Enter(Sender: TObject);
var Thing: TSound;
begin

Thing := Click;

end;

youll get a compilation error; the compiler interprets Click within the scope of the
procedure as a reference to TForms Click method. You can work around this by
qualifying the identifier; thus, if TSound is declared in MyUnit, you would use
Thing := MyUnit.Click;

5-6

Object Pascal Language Guide

Simple types

A better solution, however, is to choose constant names that are not likely to conflict
with other identifiers. Examples:
type
TSound = (tsClick, tsClack, tsClock);
TMyColor = (mcRed, mcBlue, mcGreen, mcYellow, mcOrange);
Answer = (ansYes, ansNo, ansMaybe);

You can use the (val1, ..., valn) construction directly in variable declarations, as if it
were a type name:
var MyCard: (Club, Diamond, Heart, Spade);

But if you declare MyCard this way, you cant declare another variable within the
same scope using these constant identifiers. Thus
var Card1: (Club, Diamond, Heart, Spade);
var Card2: (Club, Diamond, Heart, Spade);

generates a compilation error. But

var Card1, Card2: (Club, Diamond, Heart, Spade);

compiles cleanly, as does

type Suit = (Club, Diamond, Heart, Spade);
var
Card1: Suit;
Card2: Suit;

Subrange types
A subrange type represents a subset of the values in another ordinal type (called the
base type). Any construction of the form Low..High, where Low and High are constant
expressions of the same ordinal type and Low is less than High, identifies a subrange
type that includes all values between Low and High. For example, if you declare the
enumerated type
type TColors = (Red, Blue, Green, Yellow, Orange, Purple, White, Black);

you can then define a subrange type like

type TMyColors = Green..White;

Here TMyColors includes the values Green, Yellow, Orange, Purple, and White.
You can use numeric constants and characters (string constants of length 1) to define
subrange types:
type
SomeNumbers = -128..127;
Caps = 'A'..'Z';

When you use numeric or character constants to define a subrange, the base type is
the smallest integer or character type that contains the specified range.
The Low..High construction itself functions as a type name, so you can use it directly
in variable declarations. For example,
var SomeNum: 1..500;

declares an integer variable whose value can be anywhere in the range from 1 to 500.

Data types, variables, and constants

5-7

Simple types

The ordinality of each value in a subrange is preserved from the base type. (In the
first example above, if Color is a variable that holds the value Green, Ord(Color) returns
2 regardless of whether Color is of type TColors or TMyColors.) Values do not wrap
around the beginning or end of a subrange, even if the base is an integer or character
type; incrementing or decrementing past the boundary of a subrange simply converts
the value to the base type. Hence, while
type Percentile = 0..99;
var I: Percentile;

I := 100;

produces an error,

I := 99;
Inc(I);

assigns the value 100 to I (unless compiler range-checking is enabled).

The use of constant expressions in subrange definitions introduces a syntactic
difficulty. In any type declaration, when the first meaningful character after = is a left
parenthesis, the compiler assumes that an enumerated type is being defined. Hence
the code
const
X = 50;
Y = 10;
type
Scale = (X - Y) * 2..(X + Y) * 2;

produces an error. Work around this problem by rewriting the type declaration to
avoid the leading parenthesis:
type
Scale = 2 * (X - Y)..(X + Y) * 2;

Real types
A real type defines a set of numbers that can be represented with floating-point
notation. The table below gives the ranges and storage formats for the fundamental
real types.
Table 5.3

5-8

Fundamental real types

Type

Range

Real48

2.9 x 1039 .. 1.7 x 1038

Significant digits
45

1112

Size in bytes
6

Single

1.5 x 10

Double

5.0 x 10324 .. 1.7 x 10308

1516

Extended

3.6 x 104951 .. 1.1 x 104932

1920

Comp

263+1 .. 263 1

1920

Currency

922337203685477.5808.. 922337203685477.5807

1920

.. 3.4 x 10

Object Pascal Language Guide

String types

The generic type Real, in its current implementation, is equivalent to Double.

Table 5.4

Note

Generic real types

Type

Range

Real

5.0 x 10324 .. 1.7 x 10308

Significant digits
1516

Size in bytes
8

The six-byte Real48 type was called Real in earlier versions of Object Pascal. If you are
recompiling code that uses the older, six-byte Real type, you may want to change it to
Real48. You can also use the {$REALCOMPATIBILITY ON} compiler directive to
turn Real back into the six-byte type.
The following remarks apply to fundamental real types.
Real48 is maintained for backward compatibility. Since its storage format is not
native to the Intel CPU family, it results in slower performance than other
floating-point types.
Extended offers greater precision than other real types but is less portable. Be
careful using Extended if you are creating data files to share across platforms.
The Comp (computational) type is native to the Intel CPU and represents a 64-bit
integer. It is classified as a real, however, because it does not behave like an
ordinal type. (For example, you cannot increment or decrement a Comp value.)
Comp is maintained for backward compatibility only. Use the Int64 type for better
performance.
Currency is a fixed-point data type that minimizes rounding errors in monetary
calculations. It is stored as a scaled 64-bit integer with the four least-significant
digits implicitly representing decimal places. When mixed with other real types in
assignments and expressions, Currency values are automatically divided or
multiplied by 10000.

String types
A string represents a sequence of characters. Object Pascal supports the following
predefined string types.
Table 5.5

String types

Type

Maximum length

Memory required

Used for

ShortString

255 characters

2 to 256 bytes

backward compatibility

AnsiString

~231 characters

4 bytes to 2GB

8-bit (ANSI) characters

WideString

~230 characters

4 bytes to 2GB

Unicode characters;
COM servers and interfaces

AnsiString, sometimes called the long string, is the preferred type for most purposes.
String types can be mixed in assignments and expressions; the compiler
automatically performs required conversions. But strings passed by reference to a

Data types, variables, and constants

5-9

String types

function or procedure (as var and out parameters) must be of the appropriate type.
Strings can be explicitly cast to a different string type (see Typecasts on page 4-14).
The reserved word string functions like a generic type identifier. For example,
var S: string;

creates a variable S that holds a string. In the default {$H+} state, the compiler
interprets string (when it appears without a bracketed number after it) as AnsiString.
Use the {$H} directive to turn string into ShortString.
The standard function Length returns the number of characters in a string. The
SetLength procedure adjusts the length of a string. See the online Help for details.
Comparison of strings is defined by the ordering of the characters in corresponding
positions. Between strings of unequal length, each character in the longer string
without a corresponding character in the shorter string takes on a greater-than value.
For example, AB is greater than A; that is, 'AB' > 'A' returns True. Zero-length
strings hold the lowest values.
You can index a string variable just as you would an array. If S is a string variable
and i an integer expression, S[i] represents the ith characteror, strictly speaking,
the ith bytein S. For a ShortString or AnsiString, S[i] is of type AnsiChar; for a
WideString, S[i] is of type WideChar. The statement MyString[2] := 'A'; assigns the
value A to the second character of MyString. The following code uses the standard
UpCase function to convert MyString to uppercase.
var I: Integer;
begin
I := Length(MyString);
while I > 0 do
begin
MyString[I] := UpCase(MyString[I]);
I := I - 1;
end;
end;

Be careful indexing strings in this way, since overwriting the end of a string can cause
access violations. Also, avoid passing long-string indexes as var parameters, because
this results in inefficient code.
You can assign the value of a string constantor any other expression that returns a
stringto a variable. The length of the string changes dynamically when the
assignment is made. Examples:
MyString
MyString
MyString
MyString
MyString

:=
:=
:=
:=
:=

'Hello world!';
'Hello ' + 'world';
MyString + '!';
' ';
{ space }
'';
{ empty string }

For more information, see Character strings on page 4-4 and String operators on
page 4-9.

5-10

Object Pascal Language Guide

String types

Short strings
A ShortString is 0 to 255 characters long. While the length of a ShortString can change
dynamically, its memory is a statically allocated 256 bytes; the first byte stores the
length of the string, and the remaining 255 bytes are available for characters. If S is a
ShortString variable, Ord(S[0]), like Length(S), returns the length of S; assigning a
value to S[0], like calling SetLength, changes the length of S. ShortString uses 8-bit
ANSI characters and is maintained for backward compatibility only.
Object Pascal supports short-string typesin effect, subtypes of ShortStringwhose
maximum length is anywhere from 0 to 255 characters. These are denoted by a
bracketed numeral appended to the reserved word string. For example,
var MyString: string[100];

creates a variable called MyString whose maximum length is 100 characters. This is
equivalent to the declarations
type CString = string[100];
var MyString: CString;

Variables declared in this way allocate only as much memory as the type requires
that is, the specified maximum length plus one byte. In our example, MyString uses
101 bytes, as compared to 256 bytes for a variable of the predefined ShortString type.
When you assign a value to a short-string variable, the string is truncated if it exceeds
the maximum length for the type.
The standard functions High and Low operate on short-string type identifiers and
variables. High returns the maximum length of the short-string type, while Low
returns zero.

Long strings
AnsiString, also called a long string, represents a dynamically allocated string whose
maximum length is limited only by available memory. It uses 8-bit ANSI characters.
A long-string variable is a pointer occupying four bytes of memory. When the
variable is emptythat is, when it contains a zero-length stringthe pointer is nil
and the string uses no additional storage. When the variable is nonempty, it points to
a dynamically allocated block of memory that contains the string value, a 32-bit
length indicator, and a 32-bit reference count. This memory is allocated on the heap,
but its management is entirely automatic and requires no user code.
Because long-string variables are pointers, two or more of them can reference the same
value without consuming additional memory. The compiler exploits this to conserve
resources and execute assignments faster. Whenever a long-string variable is destroyed
or assigned a new value, the reference count of the old string (the variables previous
value) is decremented and the reference count of the new value (if there is one) is
incremented; if the reference count of a string reaches zero, its memory is deallocated.
This process is called reference-counting. When indexing is used to change the value of a
single character in a string, a copy of the string is made ifbut only ifits reference
count is greater than one. This is called copy-on-write semantics.

Data types, variables, and constants

5-11

String types

WideString
The WideString type represents a dynamically allocated string of 16-bit Unicode
characters. In most respects it is similar to AnsiString, but it is less efficient because it
does not implement reference-counting and copy-on-write semantics.
WideString is compatible with the COM BSTR type. Delphi has COM support
features that convert AnsiString values to WideString, but if you make calls to the
COM API, you may need to explicitly cast or convert your strings to WideString.

About extended character sets

Windows supports single-byte and multibyte character sets as well as Unicode. With a
single-byte character set (SBCS), each byte in a string represents one character. The
ANSI character set used by most Western versions of Windows is a single-byte
character set.
In a multibyte character set (MBCS), some characters are represented by one byte and
others by more than one byte. The first byte of a multibyte character is called the lead
byte. In general, the lower 128 characters of a multibyte character set map to the 7-bit
ASCII characters, and any byte whose ordinal value is greater than 127 is the lead
byte of a multibyte character. Only single-byte characters can contain the null value
(#0). Multibyte character setsespecially double-byte character sets (DBCS)are
widely used for Asian languages.
In the Unicode character set, each character is represented by two bytes. Thus a
Unicode string is a sequence not of individual bytes but of two-byte words. Unicode
characters and strings are also called wide characters and wide character strings. The
first 256 Unicode characters map to the ANSI character set.
Object Pascal supports single-byte and multibyte characters and strings through the
Char, PChar, AnsiChar, PAnsiChar, and AnsiString types. Indexing of multibyte strings
is not reliable, since S[i] represents the ith byte (not necessarily the ith character) in S.
However, Delphis standard string-handling functions have multibyte-enabled
counterparts that also implement locale-specific ordering for characters. (Names of
multibyte functions usually start with Ansi-. For example, the multibyte version of
StrPos is AnsiStrPos.) Multibyte character support is operating-system dependent and
based on the current Windows locale.
Object Pascal supports Unicode characters and strings through the WideChar,
PWideChar, and WideString types.

Working with null-terminated strings

Many programming languages, including C and C++, lack a dedicated string data type.
These languages, and environments like Windows that are built with them, rely on nullterminated strings. A null-terminated string is a zero-based array of characters that ends
with NULL (#0); since the array has no length indicator, the first NULL character marks
the end of the string. You can use Object Pascal constructions and special routines in the

5-12

Object Pascal Language Guide

String types

SysUtils unit (see Chapter 8, Standard routines and I/O) to handle null-terminated
strings when you need to share data with systems that use them.
For example, the following type declarations could be used to store null-terminated
strings.
type
TIdentifier = array[0..15] of Char;
TFileName = array[0..259] of Char;
TMemoText = array[0..1023] of WideChar;

You can assign a string constant to a statically allocated zero-based character array.
(Dynamic arrays wont work for this purpose.) If you initialize an array constant with
a string that is shorter than the declared length of the array, the remaining characters
are set to #0. For more information about arrays, see Arrays on page 5-16.

Using pointers, arrays, and string constants

To manipulate null-terminated strings, it is often necessary to use pointers. (See
Pointers and pointer types on page 5-24.) String constants are assignmentcompatible with the PChar and PWideChar types, which represent pointers to
null-terminated arrays of Char and WideChar values. For example,
var P: PChar;

P := 'Hello world!';

points P to an area of memory that contains a null-terminated copy of Hello world!

This is equivalent to
const TempString: array[0..12] of Char = 'Hello world!'#0;
var P: PChar;

P := @TempString;

You can also pass string constants to any function that takes value or const
parameters of type PChar or PWideCharfor example StrUpper('Hello world!'). As
with assignments to a PChar, the compiler generates a null-terminated copy of the
string and gives the function a pointer to that copy. Finally, you can initialize PChar
or PWideChar constants with string literals, alone or in a structured type. Examples:
const
Message: PChar = 'Program terminated';
Prompt: PChar = 'Enter values: ';
Digits: array[0..9] of PChar = (
'Zero', 'One', 'Two', 'Three', 'Four',
'Five', 'Six', 'Seven', 'Eight', 'Nine');

Zero-based character arrays are compatible with PChar and PWideChar. When you
use a character array in place of a pointer value, the compiler converts the array to a
pointer constant whose value corresponds to the address of the first element of the
array. For example,

Data types, variables, and constants

5-13

String types

var
MyArray: array[0..32] of Char;
MyPointer: PChar;
begin
MyArray := 'Hello';
MyPointer := MyArray;
SomeProcedure(MyArray);
SomeProcedure(MyPointer);
end;

This code calls SomeProcedure twice with the same value.

A character pointer can be indexed as if it were an array. In the example above,
MyPointer[0] returns H. The index specifies an offset added to the pointer before it is
dereferenced. (For PWideChar variables, the index is automatically multiplied by
two.) Thus, if P is a character pointer, P[0] is equivalent to P^ and specifies the first
character in the array, P[1] specifies the second character in the array, and so forth;
P[-1] specifies the character immediately to the left of P[0]. The compiler performs no
range checking on these indexes.
The StrUpper function illustrates the use of pointer indexing to iterate through a
null-terminated string:
function StrUpper(Dest, Source: PChar; MaxLen: Integer): PChar;
var
I: Integer;
begin
I := 0;
while (I < MaxLen) and (Source[I] <> #0) do
begin
Dest[I] := UpCase(Source[I]);
Inc(I);
end;
Dest[I] := #0;
Result := Dest;
end;

Mixing Pascal strings and null-terminated strings

You can mix long strings (AnsiString values) and null-terminated strings (PChar
values) in expressions and assignments, and you can pass PChar values to functions
or procedures that take long-string parameters. The assignment S := P, where S is a
string variable and P is a PChar expression, copies a null-terminated string into a long
string.
In a binary operation, if one operand is a long string and the other a PChar, the PChar
operand is converted to a long string.
You can cast a PChar value as a long string. This is useful when you want to perform
a string operation on two PChar values. For example,
S := string(P1) + string(P2);

5-14

Object Pascal Language Guide

Structured types

You can also cast a long string as a null-terminated string. The following rules apply.
If S is a long-string expression, PChar(S) casts S as a null-terminated string; it
returns a pointer to the first character in S. For example, if Str1 and Str2 are long
strings, you could call the Win32 API MessageBox function like this:
MessageBox(0, PChar(Str1), PChar(Str2), MB_OK);

(MessageBox is declared in the Windows interface unit.)

You can also use Pointer(S) to cast a long string to an untyped pointer. But if S is
empty, the typecast returns nil.
When you cast a long-string variable to a pointer, the pointer remains valid until
the variable is assigned a new value or goes out of scope. If you cast any other
long-string expression to a pointer, the pointer is valid only within the statement
where the typecast is performed.
When you cast a long-string expression to a pointer, the pointer should usually be
considered read-only. You can safely use the pointer to modify the long string
only when all of the following conditions are satisfied.
The expression cast is a long-string variable.
The string is not empty.
The string is uniquethat is, has a reference count of one. To guarantee that the
string is unique, call the SetLength, SetString, or UniqueString procedure.
The string has not been modified since the typecast was made.
The characters modified are all within the string. Be careful not to use an
out-of-range index on the pointer.
The same rules apply when mixing WideString values with PWideChar values.

Structured types
Instances of a structured type hold more than one value. Structured types include
sets, arrays, records, and files as well as class, class-reference, and interface types. (For
information about class and class-reference types, see Chapter 7, Classes and
objects. For information about interfaces, see Chapter 10, Object interfaces.)
Except for sets, which hold ordinal values only, structured types can contain other
structured types; a type can have unlimited levels of structuring.
By default, the values in a structured type are aligned on word or double-word
boundaries for faster access. When you declare a structured type, you can include the
reserved word packed to implement compressed data storage. For example,
type TNumbers = packed array[1..100] of Real;

Using packed slows data access and, in the case of a character array, affects type
compatibility. For more information, see Chapter 11, Memory management.

Data types, variables, and constants

5-15

Structured types

Sets
A set is a collection of values of the same ordinal type. The values have no inherent
order, nor is it meaningful for a value to be included twice in a set.
The range of a set type is the power set of a specific ordinal type, called the base type;
that is, the possible values of the set type are all the subsets of the base type,
including the empty set. The base type can have no more than 256 possible values,
and their ordinalities must fall between 0 and 255. Any construction of the form
set of baseType
where baseType is an appropriate ordinal type, identifies a set type.
Because of the size limitations for base types, set types are usually defined with
subranges. For example, the declarations
type
TSomeInts = 1..250;
TIntSet = set of TSomeInts;

create a set type called TIntSet whose values are collections of integers in the range
from 1 to 250. You could accomplish the same thing with
type TIntSet = set of 1..250;

Given this declaration, you can create a sets like this:

var Set1, Set2: TIntSet;

Set1 := [1, 3, 5, 7, 9];

Set2 := [2, 4, 6, 8, 10]

You can also use the set of ... construction directly in variable declarations:
var MySet: set of 'a'..'z';

MySet := ['a','b','c'];

Other examples of set types include

set of Byte
set of (Club, Diamond, Heart, Spade)
set of Char;

The in operator tests set membership:

if 'a' in MySet then ... { do something } ;

Every set type can hold the empty set, denoted by []. For more information about
sets, see Set constructors on page 4-13 and Set operators on page 4-10.

Arrays
An array represents an indexed collection of elements of the same type (called the base
type). Because each element has a unique index, arrays, unlike sets, can meaningfully
contain the same value more than once. Arrays can be allocated statically or dynamically.

5-16

Object Pascal Language Guide

Structured types

Static arrays
Static array types are denoted by constructions of the form
array[indexType1, ..., indexTypen] of baseType
where each indexType is an ordinal type whose range does not exceed 2GB. Since the
indexTypes index the array, the number of elements an array can hold is limited by
the product of the sizes of the indexTypes. In practice, indexTypes are usually integer
subranges.
In the simplest case of a one-dimensional array, there is only a single indexType. For
example,
var MyArray: array[1..100] of Char;

declares a variable called MyArray that holds an array of 100 character values. Given
this declaration, MyArray[3] denotes the third character in MyArray. If you create a
static array but dont assign values to all its elements, the unused elements are still
allocated and contain random data; they are like uninitialized variables.
A multidimensional array is an array of arrays. For example,
type TMatrix = array[1..10] of array[1..50] of Real;

is equivalent to
type TMatrix = array[1..10, 1..50] of Real;

Whichever way TMatrix is declared, it represents an array of 500 real values. A

variable MyMatrix of type TMatrix can be indexed like this: MyMatrix[2,45]; or like
this: MyMatrix[2][45]. Similarly,
packed array[Boolean,1..10,TShoeSize] of Integer;

is equivalent to
packed array[Boolean] of packed array[1..10] of packed array[TShoeSize] of Integer;

The standard functions Low and High operate on array type identifiers and variables.
They return the low and high bounds of the arrays first index type. The standard
function Length returns the number of elements in the arrays first dimension.
A one-dimensional, packed, static array of Char values is called a packed string. Packedstring types are compatible with string types and with other packed-string types that
have the same number of elements. See Type compatibility and identity on page 5-33.
An array type of the form array[0..x] of Char is called a zero-based character array. Zerobased character arrays are used to store null-terminated strings and are compatible with
PChar values. See Working with null-terminated strings on page 5-12.

Dynamic arrays
Dynamic arrays do not have a fixed size or length. Instead, memory for a dynamic
array is reallocated when you assign a value to the array or pass it to the SetLength
procedure. Dynamic-array types are denoted by constructions of the form
array of baseType

Data types, variables, and constants

5-17

Structured types

For example,
var MyFlexibleArray: array of Real;

declares a one-dimensional dynamic array of reals. The declaration does not allocate
memory for MyFlexibleArray. To create the array in memory, call SetLength. For
example, given the declaration above,
SetLength(MyFlexibleArray, 20);

allocates an array of 20 reals, indexed 0 to 19. Dynamic arrays are always

integer-indexed, always starting from 0.
Dynamic-array variables are implicitly pointers and are managed by the same
reference-counting technique used for long strings. To deallocate a dynamic array,
assign nil to a variable that references the array or pass the variable to Finalize; either
of these methods disposes of the array, provided there are no other references to it.
Dynamic arrays of length 0 have the value nil. Do not apply the dereference operator
(^) to a dynamic-array variable or pass it to the New or Dispose procedure.
If X and Y are variables of the same dynamic-array type, X := Y points X to the same
array as Y. (There is no need to allocate memory for X before performing this
operation.) Unlike strings and static arrays, dynamic arrays are not automatically
copied before they are written to. For example, after this code executes
var
A, B: array of Integer;
begin
SetLength(A, 1);
A[0] := 1;
B := A;
B[0] := 2;
end;

the value of A[0] is 2. (If A and B were static arrays, A[0] would still be 1.)
Assigning to a dynamic-array index (for example, MyFlexibleArray[2] := 7) does not
reallocate the array. Out-of-range indexes are not reported at compile time.
When dynamic-array variables are compared, their references are compared, not
their array values. Thus, after execution of the code
var
A, B: array of Integer;
begin
SetLength(A, 1);
SetLength(B, 1);
A[0] := 2;
B[0] := 2;
end;

A = B returns False but A[0] = B[0] returns True.

To truncate a dynamic array, pass it to the Copy function and assign the result back to
the array variable. For example, if A is a dynamic array, A := Copy(A, 0, 20) truncates
all but the first 20 elements of A.

5-18

Object Pascal Language Guide

Structured types

Once a dynamic array has been allocated, you can pass it to the standard functions
Length, High, and Low. Length returns the number of elements in the array, High
returns the arrays highest index (that is, Length1), and Low returns 0. In the case of a
zero-length array, High returns 1 (with the anomalous consequence that High < Low).
Note

In some function and procedure declarations, array parameters are represented as

array of baseType, without any index types specified. For example,
function CheckStrings(A: array of string): Boolean;

This indicates that the function operates on all arrays of the specified base type,
regardless of their size, how they are indexed, or whether they are allocated statically
or dynamically. See Open array parameters on page 6-13.

Multidimensional dynamic arrays

To declare multidimensional dynamic arrays, use iterated array of ... constructions.
For example,
type TMessageGrid = array of array of string;
var Msgs: TMessageGrid;

declares a two-dimensional array of strings. To instantiate this array, call SetLength

with two integer arguments. For example, if I and J are integer-valued variables,
SetLength(Msgs,I,J);

allocates an I-by-J array, and Msgs[0,0] denotes an element of that array.

You can create multidimensional dynamic arrays that are not rectangular. The first
step is to call SetLength, passing it parameters for the first n dimensions of the array.
For example,
var Ints: array of array of Integer;
SetLength(Ints,10);

allocates ten rows for Ints but no columns. Later, you can allocate the columns one at
a time (giving them different lengths); for example
SetLength(Ints[2], 5);

makes the third column of Ints five integers long. At this point (even if the other
columns havent been allocated) you can assign values to the third columnfor
example, Ints[2,4] := 6.
The following example uses dynamic arrays (and the IntToStr function declared in
the SysUtils unit) to create a triangular matrix of strings.
var
A : array of array of string;
I, J : Integer;
begin
SetLength(A, 10);
for I := Low(A) to High(A) do
begin
SetLength(A[I], I);
for J := Low(A[I]) to High(A[I]) do
A[I,J] := IntToStr(I) + ',' + IntToStr(J) + ' ';
end;
end;

Data types, variables, and constants

5-19

Structured types

Array types and assignments

Arrays are assignment-compatible only if they are of the same type. Because Pascal
uses name-equivalence for types, the following code will not compile.
var
Int1: array[1..10] of Integer;
Int2: array[1..10] of Integer;

Int1 := Int2;

To make the assignment work, declare the variables as

var Int1, Int2: array[1..10] of Integer;

or
type IntArray = array[1..10] of Integer;
var
Int1: IntArray;
Int2: IntArray;

Records
A record (analogous to a structure in some languages) represents a heterogeneous set
of elements. Each element is called a field; the declaration of a record type specifies a
name and type for each field. The syntax of a record type declaration is
type recordTypeName = record
fieldList1: type1;

fieldListn: typen;
end
Where recordTypeName is a valid identifier, each type denotes a type, and each fieldList
is a valid identifier or a comma-delimited list of identifiers. The final semicolon is
optional.
For example, the following declaration creates a record type called TDateRec.
type
TDateRec = record
Year: Integer;
Month: (Jan, Feb, Mar, Apr, May, Jun,
Jul, Aug, Sep, Oct, Nov, Dec);
Day: 1..31;
end;

Each TDateRec contains three fields: an integer value called Year, a value of an
enumerated type called Month, and another integer between 1 and 31 called Day. The
identifiers Year, Month, and Day are the field designators for TDateRec, and they behave
like variables. The TDateRec type declaration, however, does not allocate any
memory for the Year, Month, and Day fields; memory is allocated when you
instantiate the record, like this:
var Record1, Record2: TDateRec;

5-20

Object Pascal Language Guide

Structured types

This variable declaration creates two instances of TDateRec, called Record1 and
Record2.
You can access the fields of a record by qualifying the field designators with the
records name:
Record1.Year := 1904;
Record1.Month := Jun;
Record1.Day := 16;

Or use a with statement:

with Record1 do
begin
Year := 1904;
Month := Jun;
Day := 16;
end;

You can now copy the values of Record1s fields to Record2:

Record2 := Record1;

Because the scope of a field designator is limited to the record in which it occurs, you
dont have to worry about naming conflicts between field designators and other
variables.
Instead of defining record types, you can use the record ... construction directly in
variable declarations:
var S: record
Name: string;
Age: Integer;
end;

However, a declaration like this largely defeats the purpose of records, which is to
avoid repetitive coding of similar groups of variables. Moreover, separately declared
records of this kind will not be assignment-compatible, even if their structures are
identical.

Variant parts in records

A record type can have a variant part, which looks like a case statement. The variant
part must follow the other fields in the record declaration.
To declare a record type with a variant part, use the following syntax.
type recordTypeName = record
fieldList1: type1;

fieldListn: typen;
case tag: ordinalType of
constantList1: (variant1);

constantListn: (variantn);
end;

Data types, variables, and constants

5-21

Structured types

The first part of the declarationup to the reserved word caseis the same as that of
a standard record type. The remainder of the declarationfrom case to the optional
final semicolonis called the variant part. In the variant part,
tag is optional and can be any valid identifier. If you omit tag, omit the colon (:)
after it as well.
ordinalType denotes an ordinal type.
Each constantList is a constant denoting a value of type ordinalType, or a
comma-delimited list of such constants. No value can be represented more than
once in the combined constantLists.
Each variant is a comma-delimited list of declarations resembling the fieldList: type
constructions in the main part of the record type. That is, a variant has the form
fieldList1: type1;

fieldListn: typen;
where each fieldList is a valid identifier or comma-delimited list of identifiers, each
type denotes a type, and the final semicolon is optional. The types must not be long
strings, dynamic arrays, variants (that is, Variant types), or interfaces, nor can they
be structured types that contain long strings, dynamic arrays, variants, or
interfaces; but they can be pointers to these types.
Records with variant parts are complicated syntactically but deceptively simple
semantically. The variant part of a record contains several variants which share the
same space in memory. You can read or write to any field of any variant at any time;
but if you write to a field in one variant and then to a field in another variant, you may
be overwriting your own data. The tag, if there is one, functions as an extra field (of
type ordinalType) in the non-variant part of the record.
Variant parts have two purposes. First, suppose you want to create a record type that
has fields for different kinds of data, but you know that you will never need to use all
of the fields in a single record instance. For example,
type
TEmployee = record
FirstName, LastName: string[40];
BirthDate: TDate;
case Salaried: Boolean of
True: (AnnualSalary: Currency);
False: (HourlyWage: Currency);
end;

The idea here is that every employee has either a salary or an hourly wage, but not
both. So when you create an instance of TEmployee, there is no reason to allocate
enough memory for both fields. In this case, the only difference between the variants
is in the field names, but the fields could just as easily have been of different types.
Consider some more complicated examples:

5-22

Object Pascal Language Guide

Structured types

type
TPerson = record
FirstName, LastName: string[40];
BirthDate: TDate;
case Citizen: Boolean of
True: (Birthplace: string[40]);
False: (Country: string[20];
EntryPort: string[20];
EntryDate, ExitDate: TDate);
end;
type
TShapeList = (Rectangle, Triangle, Circle, Ellipse, Other);
TFigure = record
case TShapeList of
Rectangle: (Height, Width: Real);
Triangle: (Side1, Side2, Angle: Real);
Circle: (Radius: Real);
Ellipse, Other: ();
end;

For each record instance, the compiler allocates enough memory to hold all the fields
in the largest variant. The optional tag and the constantLists (like Rectangle, Triangle,
and so forth in the last example above) play no role in the way the compiler manages
the fields; they are there only for the convenience of the programmer.
The second reason for variant parts is that they let you treat the same data as
belonging to different types, even in cases where the compiler would not allow a
typecast. For example, if you have a 64-bit Real as the first field in one variant and a
32-bit Integer as the first field in another, you can assign a value to the Real field and
then read back the first 32 bits of it as the value of the Integer field (passing it, say, to a
function that requires integer parameters).

File types
A file is an ordered set of elements of the same type. Standard I/O routines use the
predefined TextFile or Text type, which represents a file containing characters
organized into lines. For more information about file input and output, see
Chapter 8, Standard routines and I/O.
To declare a file type, use the syntax
type fileTypeName = file of type
where fileTypeName is any valid identifier and type is a fixed-size type. Pointer
typeswhether implicit or explicitare not allowed, so a file cannot contain
dynamic arrays, long strings, classes, objects, pointers, variants, other files, or
structured types that contain any of these.

Data types, variables, and constants

5-23

Pointers and pointer types

For example,
type
PhoneEntry = record
FirstName, LastName: string[20];
PhoneNumber: string[15];
Listed: Boolean;
end;
PhoneList = file of PhoneEntry;

declares a file type for recording names and telephone numbers.

You can also use the file of ... construction directly in a variable declaration. For
example,
var List1: file of PhoneEntry;

The word file by itself indicates an untyped file:

var DataFile: file;

For more information, see Untyped files on page 8-4.

Files are not allowed in arrays or records.

Pointers and pointer types

A pointer is a variable that denotes a memory address. When a pointer holds the
address of another variable, we say that it points to the location of that variable in
memory or to the data stored there. In the case of an array or other structured type, a
pointer holds the address of the first element in the structure.
Pointers are typed to indicate the kind of data stored at the addresses they hold. The
general-purpose Pointer type can represent a pointer to any data, while more specialized
pointer types reference only specific types of data. Pointers occupy four bytes of memory.

Overview of pointers
To see how pointers work, look at the following example.
1
2
3
4
5
6
7
8

var
X, Y: Integer;
P: ^Integer;
begin
X := 17;
P := @X;
Y := P^;
end;

// X and Y are Integer variables

// P points to an Integer
// assign a value to X
// assign the address of X to P
// dereference P; assign the result to Y

Line 2 declares X and Y as variables of type Integer. Line 3 declares P as a pointer to

an Integer value; this means that P can point to the location of X or Y. Line 5 assigns a
value to X, and line 6 assigns the address of X (denoted by @X) to P. Finally, line 7
retrieves the value at the location pointed to by P (denoted by ^P) and assigns it to Y.
After this code executes, X and Y have the same value, namely 17.

5-24

Object Pascal Language Guide

Pointers and pointer types

The @ operator, which we have used here to take the address of a variable, also
operates on functions and procedures. For more information, see The @ operator
on page 4-11 and Procedural types in statements and expressions on page 5-28.
The symbol ^ has two purposes, both of which are illustrated in our example. When
it appears before a type identifier
^typeName
it denotes a type that represents pointers to variables of type typeName. When it
appears after a pointer variable
pointer^
it dereferences the pointer; that is, it returns the value stored at the memory address
held by the pointer.
Our example may seem like a roundabout way of copying the value of one variable
to anothersomething that we could have accomplished with a simple assignment
statement. But pointers are useful for several reasons. First, understanding pointers
will help you to understand Object Pascal, since pointers often operate behind the
scenes in code where they dont appear explicitly. Any data type that requires large,
dynamically allocated blocks of memory uses pointers. Long-string variables, for
instance, are implicitly pointers, as are class variables. Moreover, some advanced
programming techniques require the use of pointers.
Finally, pointers are sometimes the only way to circumvent Object Pascals strict data
typing. By referencing a variable with an all-purpose Pointer, casting the Pointer to a
more specific type, and then dereferencing it, you can treat the data stored by any
variable as if it belonged to any type. For example, the following code assigns data
stored in a real variable to an integer variable.
type
PInteger = ^Integer;
var
R: Single;
I: Integer;
P: Pointer;
PI: PInteger;
begin

P := @R;
PI := PInteger(P);
I := PI^;
end;

Of course, reals and integers are stored in different formats. This assignment simply
copies raw binary data from R to I, without converting it.
In addition to assigning the result of an @ operation, you can use several standard
routines to give a value to a pointer. The New and GetMem procedures assign a
memory address to an existing pointer, while the Addr and Ptr functions return a
pointer to a specified address or variable.
Dereferenced pointers can be qualified and can function as qualifiers, as in the
expression P1^.Data^.

Data types, variables, and constants

5-25

Pointers and pointer types

The reserved word nil is a special constant that can be assigned to any pointer. When
nil is assigned to a pointer, the pointer doesnt reference anything.

Pointer types
You can declare a pointer to any type, using the syntax
type pointerTypeName = ^type
When you define a record or other data type, its a common practice also to define a
pointer to that type. This makes it easy to manipulate instances of the type without
copying large blocks of memory.
Standard pointer types exist for many purposes. The most versatile is Pointer, which
can point to data of any kind. But a Pointer variable cannot be dereferenced; placing
the ^ symbol after a Pointer variable causes a compilation error. To access the data
referenced by a Pointer variable, first cast it to another pointer type and then
dereference it.

Character pointers
The fundamental types PAnsiChar and PWideChar represent pointers to AnsiChar and
WideChar values, respectively. The generic PChar represents a pointer to a Char (that
is, in its current implementation, to an AnsiChar). These character pointers are used to
manipulate null-terminated strings. (See Working with null-terminated strings on
page 5-12.)

Other standard pointer types

The System and SysUtils units declare many standard pointer types. While these
types are not built-in, they are commonly used in Delphi programming.
Table 5.6

5-26

Selected pointer types declared in System and SysUtils

Pointer type

Points to variables of type

PAnsiString, PString

AnsiString

PByteArray

ByteArray (declared in SysUtils). Used to typecast dynamically

allocated memory for array access.

PCurrency

Currency

PExtended

Extended

POleVariant

OleVariant

PShortString

ShortString. Useful when porting legacy code that uses PString type.

PTextBuf

TextBuf (declared in SysUtils). TextBuf is the internal buffer type in a

TTextRec file record.)

PVarRec

TVarRec (declared in System)

PVariant

Variant

PWideString

WideString

PWordArray

TWordArray (declared in SysUtils). Used to typecast dynamically

allocated memory for arrays of 2-byte values.

Object Pascal Language Guide

Procedural types

Procedural types
Procedural types allow you to treat procedures and functions as values that can be
assigned to variables or passed to other procedures and functions. For example,
suppose you define a function called Calc that takes two integer parameters and
returns an integer:
function Calc(X,Y: Integer): Integer;

You can assign the Calc function to the variable F:

var F: function(X,Y: Integer): Integer;
F := Calc;

If you take any procedure or function heading and remove the identifier after the
word procedure or function, whats left is the name of a procedural type. You can
use such type names directly in variable declarations (as in the example above) or to
declare new types:
type
TIntegerFunction = function: Integer;
TProcedure = procedure;
TStrProc = procedure(const S: string);
TMathFunc = function(X: Double): Double;
var
F: TIntegerFunction;
{ F is a parameterless function that returns an integer }
Proc: TProcedure;
{ Proc is a parameterless procedure }
SP: TStrProc;
{ SP is a procedure that takes a string parameter }
M: TMathFunc;
{ M is a function that takes a Double (real) parameter
and returns a Double }
procedure FuncProc(P: TIntegerFunction); { FuncProc is a procedure whose only parameter
is a parameterless integer-valued function }

The variables above are all procedure pointersthat is, pointers to the address of a
procedure or function. If you want to reference a method of an instance object (see
Chapter 7, Classes and objects), you need to add the words of object to the
procedural type name. For example
type
TMethod = procedure of object;
TNotifyEvent = procedure(Sender: TObject) of object;

These types represent method pointers. A method pointer is really a pair of pointers;
the first stores the address of a method, and the second stores a reference to the object
the method belongs to. Given the declarations
type
TNotifyEvent = procedure(Sender: TObject) of object;
TMainForm = class(TForm)
procedure ButtonClick(Sender: TObject);

end;
var
MainForm: TMainForm;
OnClick: TNotifyEvent

Data types, variables, and constants

5-27

Procedural types

we could make the following assignment.

OnClick := MainForm.ButtonClick;

Two procedural types are compatible if they have

the same calling convention,
the same return value (or no return value), and
the same number of parameters, with identically typed parameters in
corresponding positions. (Parameter names do not matter.)
Procedure pointer types are always incompatible with method pointer types. The
value nil can be assigned to any procedural type.
Nested procedures and functions (routines declared within other routines) cannot be
used as procedural values, nor can predefined procedures and functions. If you want
to use a predefined routine like Length as a procedural value, write a wrapper for it:
function FLength(S: string): Integer;
begin
Result := Length(S);
end;

Procedural types in statements and expressions

When a procedural variable is on the left side of an assignment statement, the
compiler expects a procedural value on the right. The assignment makes the variable
on the left a pointer to the function or procedure indicated on the right. In other
contexts, however, using a procedural variable results in a call to the referenced
procedure or function. You can even use a procedural variable to pass parameters:
var
F: function(X: Integer): Integer;
I: Integer;
function SomeFunction(X: Integer): Integer;

F := SomeFunction; // assign SomeFunction to F

I := F(4);
// call function; assign result to I

In assignment statements, the type of the variable on the left determines the
interpretation of procedure or method pointers on the right. For example,
var
F, G: function: Integer;
I: Integer;
function SomeFunction: Integer;

F := SomeFunction; // assign SomeFunction to F

G := F;
// copy F to G
I := G;
// call function; assign result to I

The first statement assigns a procedural value to F. The second statement copies that
value to another variable. The third statement makes a call to the referenced function

5-28

Object Pascal Language Guide

Variant types

and assigns the result to I. Because I is an integer variable, not a procedural one, the
last assignment actually calls the function (which returns an integer).
In some situations it is less clear how a procedural variable should be interpreted.
Consider the statement
if F = MyFunction then ...;

In this case, the occurrence of F results in a function call; the compiler calls the
function pointed to by F, then calls the function MyFunction, then compares the
results. The rule is that whenever a procedural variable occurs within an expression,
it represents a call to the referenced procedure or function. In a case where F
references a procedure (which doesnt return a value), or where F references a
function that requires parameters, the statement above causes a compilation error. To
compare the procedural value of F with MyFunction, use
if @F = @MyFunction then ...;

@F converts F into an untyped pointer variable that contains an address, and

@MyFunction returns the address of MyFunction.
To get the memory address of a procedural variable (rather than the address stored
in it), use @@. For example, @@F returns the address of F.
The @ operator can also be used to assign an untyped pointer value to a procedural
variable. For example,
var StrComp: function(Str1, Str2: PChar): Integer;

@StrComp := GetProcAddress(KernelHandle, 'lstrcmpi');

calls the Windows GetProcAddress function and points StrComp to the result.
Any procedural variable can hold the value nil, which means that it points to
nothing. But attempting to call a nil-valued procedural variable is an error. To test
whether a procedural variable is assigned, use the standard function Assigned:
if Assigned(OnClick) then OnClick(X);

Variant types
Sometimes it is necessary to manipulate data whose type varies or cannot be
determined at compile time. In these cases, one option is to use variables and
parameters of type Variant, which represent values that can change type at runtime.
Variants, as they are called, offer greater flexibility but consume more memory than
regular variables, and operations on them are slower than on statically bound types.
Moreover, illicit operations on variants often result in runtime errors, where similar
mistakes with regular variables would have been caught at compile time.
Variants can hold values of any type except records, sets, static arrays, files, classes,
class references, pointers, and Int64. In other words, with the exception of Int64,
variants can hold anything but structured types and pointers. They can hold COM
and CORBA objects, whose methods and properties can be accessed through them.
(See Chapter 10, Object interfaces.) They can hold dynamic arrays, and they can

Data types, variables, and constants

5-29

Variant types

hold a special kind of static array called a variant array. (See Variant arrays on
page 5-32.) Variants can mix with other variants and with integer, real, string, and
Boolean values in expressions and assignments; the compiler automatically performs
type conversions.
Variants that contain strings cannot be indexed. That is, if V is a variant that holds a
string value, the construction V[1] is illegitimate.
A variant occupies 16 bytes of memory and consists of a type code and a value, or
pointer to a value, of the type specified by the code. All variants are initialized on
creation to the special value Unassigned. The special value Null indicates unknown or
missing data.
The standard function VarType returns a variants type code. The varTypeMask
constant is a bit mask used to extract the code from VarTypes return value, so that,
for example,
VarType(V) and varTypeMask = varDouble

returns True if V contains a Double or an array of Double. (The mask simply hides the
first bit, which indicates whether the variant holds an array.) The TVarData record
type defined in the System unit can be used to typecast variants and gain access to
their internal representation. See the online Help on VarType for a list if codes, and
note that new type codes may be added in future implementations of Object Pascal.

Variant type conversions

All integer, real, string, character, and Boolean types (except Int64) are
assignment-compatible with Variant. Expressions can be explicitly cast as variants,
and the VarAsType and VarCast standard routines can be used to change the internal
representation of a variant. The following code demonstrates the use of variants and
some of the automatic conversions performed when variants are mixed with other
types.
var
V1, V2, V3, V4, V5: Variant;
I: Integer;
D: Double;
S: string;
begin
V1 := 1; { integer value }
V2 := 1234.5678; { real value }
V3 := 'Hello world!'; { string value }
V4 := '1000'; { string value }
V5 := V1 + V2 + V4; { real value 2235.5678}
I := V1; { I = 1 (integer value) }
D := V2; { D = 1234.5678 (real value) }
S := V3; { S = 'Hello world!' (string value) }
I := V4; { I = 1000 (integer value) }
S := V5; { S = '2235.5678' (string value) }
end;

5-30

Object Pascal Language Guide

Variant types

The compiler performs type conversions according to the following rules.

Table 5.7

Variant type conversion rules

Target
integer
Source

real

string

character Boolean

integer

converts
integer
formats

converts to
real

converts to
string
representation

same as
string
(left)

returns False if 0,
True otherwise

real

rounds to
nearest integer

converts real
formats

converts to
string
representation
using
Windows
regional
settings

same as
string
(left)

returns False if 0,
True otherwise

string

converts to
integer,
truncating if
necessary;
raises
exception if
string is not
numeric

converts to
real using
Windows
regional
settings; raises
exception if
string is not
numeric

converts
string/
character
formats

same as
string
(left)

returns False if
string is false
(noncasesensitive) or a
numeric string
that evaluates to
0, True if string is
true or a
nonzero numeric
string; raises
exception
otherwise

character

same as string
(above)

same as
string-tostring

same as string
(above)

Boolean

False = 0,
True = 1
(255 if Byte)

False = 0,
True = 1

same as
string
(left)

False = False,
True = True

Unassigned

returns 0

returns empty
string

same as
string
(left)

returns False

Null

raises
exception

same as
string
(left)

raises exception

Out-of-range assignments often result in the target variable getting the highest value
in its range. Invalid assignments or casts raise the EVariantError exception.
Special conversion rules apply to the TDateTime real type declared in the System unit.
When a TDateTime is converted to any other type, it treated as a normal Double. When
an integer, real, or Boolean is converted to a TDateTime, it is first converted to a
Double, then read as a date-time value. When a string is converted to a TDateTime, it is
interpreted as a date-time value using the Windows regional settings. When an
Unassigned value is converted to TDateTime, it is treated like the real or integer
value 0. Converting a Null value to TDateTime raises an exception.

Data types, variables, and constants

5-31

Variant types

If a variant references a COM object, any attempt to convert it reads the objects
default property and converts that value to the requested type. If the object has no
default property, an exception is raised.

Variants in expressions
All operators except ^, is, and in take variant operands. Operations on variants
return Variant values; they return Null if one or both operands is Null, and raise an
exception if one or both operands is Unassigned. In a binary operation, if only one
operand is a variant, the other is converted to a variant.
The return type of an operation is determined by its operands. In general, the same
rules that apply to operands of statically bound types apply to variants. For example,
if V1 and V2 are variants that hold an integer and a real value, then V1 + V2 returns a
real-valued variant. (See Operators on page 4-6.) With variants, however, you can
perform binary operations on combinations of values that would not be allowed
using statically typed expressions. When possible, the compiler converts mismatched
variants using the rules summarized in Table 5.7. For example, if V3 and V4 are
variants that hold a numeric string and an integer, the expression V3 + V4 returns an
integer-valued variant; the numeric string is converted to an integer before the
operation is performed.

Variant arrays
You cannot assign an ordinary static array to a variant. Instead, create a variant array
by calling either of the standard functions VarArrayCreate or VarArrayOf. For
example,
V: Variant;

V := VarArrayCreate([0,9], varInteger);

creates a variant array of integers (of length 10) and assigns it to the variant V. The
array can be indexed using V[0], V[1], and so forth, but it is not possible to pass a
variant array element as a var parameter. Variant arrays are always indexed with
integers.
The second parameter in the call to VarArrayCreate is the type code for the arrays
base type. For a list of these codes, see the online Help on VarType. Never pass the
code varString to VarArrayCreate; to create a variant array of strings, use varOleStr.
Variants can hold variant arrays of different sizes, dimensions, and base types. The
elements of a variant array can be of any type allowed in variants except ShortString
and AnsiString, and if the base type of the array is Variant, its elements can even be
heterogeneous. Use the VarArrayRedim function to resize a variant array. Other
standard routines that operate on variant arrays include VarArrayDimCount,
VarArrayLowBound, VarArrayHighBound, VarArrayRef, VarArrayLock, and
VarArrayUnlock.

5-32

Object Pascal Language Guide

Type compatibility and identity

When a variant containing a variant array is assigned to another variant or passed as

a value parameter, the entire array is copied. Dont perform such operations
unnecessarily, since they are memory-inefficient.

OleVariant
The OleVariant type represents variants that contain only COM-compatible types.
When a Variant is assigned to an OleVariant, incompatible types are converted to
their compatible counterparts. For example, if a variant containing an AnsiString is
assigned to an OleVariant, the AnsiString becomes a WideString.

Type compatibility and identity

To understand which operations can be performed on which expressions, we need to
distinguish several kinds of compatibility among types and values. These include
type identity, type compatibility, and assignment-compatibility.

Type identity
Type identity is almost straightforward. When one type identifier is declared using
another type identifier, without qualification, they denote the same type. Thus, given
the declarations
type
T1
T2
T3
T4

=
=
=
=

Integer;
T1;
Integer;
T2;

T1, T2, T3, T4, and Integer all denote the same type. To create distinct types, repeat the
word type in the declaration. For example,
type TMyInteger = type Integer;

creates a new type called TMyInteger which is not identical to Integer.

Language constructions that function as type names denote a different type each time
they occur. Thus the declarations
type
TS1 = set of Char;
TS2 = set of Char;

create two distinct types, TS1 and TS2. Similarly, the variable declarations
var
S1: string[10];
S2: string[10];

create two variables of distinct types. To create variables of the same type, use
var S1, S2: string[10];

Data types, variables, and constants

5-33

Type compatibility and identity

or
type MyString = string[10];
var
S1: MyString;
S2: MyString;

Type compatibility
Every type is compatible with itself. Two distinct types are compatible if they satisfy
at least one of the following conditions.
They are both real types.
They are both integer types.
One type is a subrange of the other.
Both types are subranges of the same type.
Both are set types with compatible base types.
Both are packed-string types with the same number of components.
One is a string type and the other is a string, packed-string, or Char type.
One type is Variant and the other is an integer, real, string, character, or Boolean
type.
Both are class, class-reference, or interface types, and one type is derived from the
other.
One type is PChar or PWideChar and the other is a zero-based character array of the
form array[0..n] of Char.
One type is Pointer (an untyped pointer) and the other is any pointer type.
Both types are (typed) pointers to the same type and the {$T+} compiler directive
is in effect.
Both are procedural types with the same result type, the same number of
parameters, and type-identity between parameters in corresponding positions.

Assignment-compatibility
Assignment-compatibility is not a symmetric relation. An expression of type T2 can
be assigned to a variable of type T1 if the value of the expression falls in the range of
T1 and at least one of the following conditions is satisfied.
T1 and T2 are of the same type, and it is not a file type or structured type that
contains a file type at any level.
T1 and T2 are compatible ordinal types.
T1 and T2 are both real types.
T1 is a real type and T2 is an integer type.

5-34

Object Pascal Language Guide

Declaring types

T1 is PChar or any string type and the expression is a string constant.

T1 and T2 are both string types.
T1 is a string type and T2 is a Char or packed-string type.
T1 is a long string and T2 is PChar.
T1 and T2 are compatible packed-string types.
T1 and T2 are compatible set types.
T1 and T2 are compatible pointer types.
T1 and T2 are both class, class-reference, or interface types and T2 is a derived
from T1.
T1 is an interface type and T2 is a class type that implements T1.
T1 is PChar or PWideChar and T2 is a zero-based character array of the form
array[0..n] of Char.
T1 and T2 are compatible procedural types. (A function or procedure identifier is
treated, in certain assignment statements, as an expression of a procedural type.
See Procedural types in statements and expressions on page 5-28.)
T1 is Variant and T2 is an integer, real, string, character, Boolean, or interface type.
T1 is an integer, real, string, character, or Boolean type and T2 is Variant.
T1 is the IUnknown or IDispatch interface type and T2 is Variant. (The variants type
code must be varEmpty, varUnknown, or varDispatch if T1 is IUnknown, and
varEmpty or varDispatch if T1 is IDispatch.)

Declaring types
A type declaration specifies an identifier that denotes a type. The syntax for a type
declaration is
type newTypeName = type
where newTypeName is a valid identifier. For example, given the type declaration
type TMyString = string;

you can make the variable declaration

var S: TMyString;

A type identifiers scope doesnt include the type declaration itself (except for pointer
types). So you cannot, for example, define a record type that uses itself recursively.
When you declare a type that is identical to an existing type, the compiler treats the
new type identifier as an alias for the old one. Thus, given the declarations
type TValue = Real;
var
X: Real;
Y: TValue;

Data types, variables, and constants

5-35

Variables

X and Y are of the same type; at runtime, there is no way to distinguish TValue from
Real. This is usually of little consequence, but if your purpose in defining a new type
is to utilize runtime type informationfor example, to associate a Delphi property
editor with properties of a particular typethe distinction between different name
and different type becomes important. In this case, use the syntax
type newTypeName = type type
For example,
type TValue = type Real;

forces the compiler to create a new, distinct type called TValue.

Variables
A variable is an identifier whose value can change at runtime. Put differently, a
variable is a name for a location in memory; you can use the name to read or write to
the memory location. Variables are like containers for data, and, because they are
typed, they tell the compiler how to interpret the data they hold.

Declaring variables
The basic syntax for a variable declaration is
var identifierList: type;
where identifierList is a comma-delimited list of valid identifiers and type is any valid
type. For example,
var I: Integer;

declares a variable I of type Integer, while

var X, Y: Real;

declares two variablesX and Yof type Real.

Consecutive variable declarations do not have to repeat the reserved word var:
var
X, Y, Z: Double;
I, J, K: Integer;
Digit: 0..9;
Okay: Boolean;

Variables declared within a procedure or function are sometimes called local, while
other variables are called global. Global variables can be initialized at the same time
they are declared, using the syntax
var identifier: type = constantExpression;
where constantExpression is any constant expression representing a value of type type.
(For more information about constant expressions, see Constant expressions on
page 5-39.) Thus the declaration

5-36

Object Pascal Language Guide

Variables

var I: Integer = 7;

is equivalent to the declaration and statement

var I: Integer;

I := 7;

Multiple variable declarations (such as var X, Y, Z: Real;) cannot include

initializations, nor can declarations of variant and file-type variables.
If you dont explicitly initialize a global variable, the compiler initializes it to 0. Local
variables, in contrast, cannot be initialized in their declarations and contain random
data until a value is assigned to them.
When you declare a variable, you are allocating memory which is freed
automatically when the variable is no longer used. In particular, local variables exist
only until the program exits from the function or procedure in which they are
declared. For more information about variables and memory management, see
Chapter 11, Memory management.

Absolute addresses
To declare a variable that resides at a specified memory address, put the word
absolute after the type name, followed by an address. Example:
var CrtMode: Byte absolute $0040;

This technique is useful only in low-level programming, for example when writing
device drivers.
To create a new variable that resides at the same address as an existing variable, use
the name of the existing variable (instead of an address) after the word absolute. For
example,
var
Str: string[32];
StrLen: Byte absolute Str;

specifies that the variable StrLen should start at the same address as Str. Since the first
byte of a short string contains the strings length, the value of StrLen is the length of
Str.
You cannot initialize a variable in an absolute declaration.

Dynamic variables
You can create dynamic variables by calling the GetMem or New procedure. Such
variables are allocated on the heap and are not managed automatically. Once you
create one, it is your responsibility ultimately to free the variables memory; use
FreeMem to destroy variables created by GetMem and Dispose to destroy variables
created by New. Other standard routines that operate on dynamic variables include
ReallocMem, Initialize, StrAlloc, and StrDispose.
Long strings and dynamic arrays are also heap-allocated dynamic variables, but their
memory is managed automatically.

Data types, variables, and constants

5-37

Declared constants

Thread-local variables
Thread-local (or thread) variables are used in multithreaded applications. A thread-local
variable is like a global variable, except that each thread of execution gets its own
private copy of the variable, which cannot be accessed from other threads. Thread-local
variables are declared with threadvar instead of var. For example,
threadvar X: Integer;

Thread-variable declarations
cannot occur within a procedure or function.
cannot include initializations.
cannot specify the absolute directive.
Reference-counted variables (such as long strings, dynamic arrays, or interfaces) are
not thread-safe, even if they are declared with threadvar. Do not use dynamic thread
variables, since there is in general no way to free the heap-allocated memory created
by each thread of execution. Finally, do not create pointer- or procedural-type thread
variables.

Declared constants
Several different language constructions are referred to as constants. There are
numeric constants (also called numerals) like 17, and string constants (also called
character strings or string literals) like 'Hello world!'; for information about numeric
and string constants, see Chapter 4, Syntactic elements. Every enumerated type
defines constants that represent the values of that type. There are predefined
constants like True, False, and nil. Finally, there are constants that, like variables, are
created individually by declaration.
Declared constants are either true constants or typed constants. These two kinds of
constant are superficially similar, but they are governed by different rules and used
for different purposes.

True constants
A true constant is a declared identifier whose value cannot change. For example,
const MaxValue = 237;

declares a constant called MaxValue that returns the integer 237. The syntax for
declaring a true constant is
const identifier = constantExpression
where identifier is any valid identifier and constantExpression is an expression that the
compiler can evaluate without executing your program. (See Constant expressions
on page 5-39 for more information.)

5-38

Object Pascal Language Guide

Declared constants

If constantExpression returns an ordinal value, you can specify the type of the declared
constant using a value typecast. For example
const MyNumber = Int64(17);

declares a constant called MyNumber, of type Int64, that returns the integer 17.
Otherwise, the type of the declared constant is the type of the constantExpression.
If constantExpression is a character string, the declared constant is compatible with
any string type. If the character string is of length 1, it is also compatible with any
character type.
If constantExpression is a real, its type is Extended. If it is an integer, its type is given
by the table below.
Table 5.8

Types for integer constants

Range of constant
(hexadecimal)

Range of constant
(decimal)

Type

$8000000000000000..$80000001

263..2147483649

Int64

$80000000..$8001

2147483648..32769

Integer

$8000..$81

32768..129

Smallint

$80..1

128..1

Shortint

0..$7F

0..127

$80..$FF

128..255

Byte

$0100..$7FFF

256..32767

0..32767

$8000..$FFFF

32768..65535

Word

$10000..$7FFFFFFF

65536..2147483647

0..2147483647

$80000000..$FFFFFFFF

2147483648..4294967295

Cardinal

$100000000..$7FFFFFFFFFFFFFFF

4294967296..2 1

Int64

Here are some examples of constant declarations:

const
Min = 0;
Max = 100;
Center = (Max - Min) div 2;
Beta = Chr(225);
NumChars = Ord('Z') - Ord('A') + 1;
Message = 'Out of memory';
ErrStr = ' Error: ' + Message + '. ';
ErrPos = 80 - Length(ErrStr) div 2;
Ln10 = 2.302585092994045684;
Ln10R = 1 / Ln10;
Numeric = ['0'..'9'];
Alpha = ['A'..'Z', 'a'..'z'];
AlphaNum = Alpha + Numeric;

Constant expressions
A constant expression is an expression that the compiler can evaluate without
executing the program in which it occurs. Constant expressions include numerals;

Data types, variables, and constants

5-39

Declared constants

character strings; true constants; values of enumerated types; the special constants
True, False, and nil; and expressions built exclusively from these elements with
operators, typecasts, and set constructors. Constant expressions cannot include
variables, pointers, or function calls, except calls to the following predefined
functions:
Abs
Chr
Hi

High
Length
Lo

Low
Odd
Ord

Pred
Round
SizeOf

Succ
Swap
Trunc

This definition of a constant expression is used in several places in Object Pascals

syntax specification. Constant expressions are required for initializing global
variables, defining subrange types, specifying default parameter values, writing case
statements, and declaring both true and typed constants.
Examples of constant expressions:
100
'A'
256 - 1
(2.5 + 1) / (2.5 - 1)
'Borland' + ' ' + 'Delphi'
Chr(32)
Ord('Z') - Ord('A') + 1

Resource strings
Resource strings are stored as resources and linked into the executable or library so
that they can be modified without recompiling the program. For more information,
see the online Help topics on localizing applications.
Resource strings are declared like other true constants, except that the word const is
replaced by resourcestring. The expression to the right of the = symbol must be a
constant expression and must return a string value. For example,
resourcestring
CreateError = 'Cannot create file %s';
OpenError = 'Cannot open file %s';
LineTooLong = 'Line too long';
ProductName = 'Borland Delphi\000\000';
SomeResourceString = SomeTrueConstant;

{ for explanations of format specifiers, }

{ see 'Format strings' in the online Help }

The compiler automatically resolves naming conflicts among resource strings in

different libraries.

Typed constants
Typed constants, unlike true constants, can hold values of array, record, procedural,
and pointer types. Typed constants cannot occur in constant expressions.
In the default {$J+} compiler state, typed constants can have new values assigned to
them; they behave essentially like initialized variables. But if the {$J} compiler

5-40

Object Pascal Language Guide

Declared constants

directive is in effect, typed constants cannot change value at runtime; they are, in
effect, read-only variables.
Declare a typed constant like this:
const identifier: type = value
where identifier is any valid identifier, type is any type except files and variants, and
value is an expression of type type. For example,
const Max: Integer = 100;

In most cases, value must be a constant expression; but if type is an array, record,
procedural, or pointer type, special rules apply.

Array constants
To declare an array constant, enclose the values of the arrays elements, separated by
commas, in parentheses at the end of the declaration. These values must be
represented by constant expressions. For example,
const Digits: array[0..9] of Char = ('0', '1', '2', '3', '4', '5', '6', '7', '8', '9');

declares a typed constant called Digits that holds an array of characters.

Zero-based character arrays often represent null-terminated strings, and for this
reason string constants can be used to initialize character arrays. So the declaration
above can be more conveniently represented as
const Digits: array[0..9] of Char = '0123456789';

To define a multidimensional array constant, enclose the values of each dimension in

a separate set of parentheses, separated by commas. For example,
type TCube = array[0..1, 0..1, 0..1] of Integer;
const Maze: TCube = (((0, 1), (2, 3)), ((4, 5), (6,7)));

creates an array called Maze where

Maze[0,0,0] = 0
Maze[0,0,1] = 1
Maze[0,1,0] = 2
Maze[0,1,1] = 3
Maze[1,0,0] = 4
Maze[1,0,1] = 5
Maze[1,1,0] = 6
Maze[1,1,1] = 7
Array constants cannot contain file-type values at any level.

Record constants
To declare a record constant, specify the value of each fieldas fieldName: value,
with the field assignments separated by semicolonsin parentheses at the end of the
declaration. The values must be represented by constant expressions. The fields must
be listed in the order in which they appear in the record type declaration, and the tag
field, if there is one, must have a value specified; if the record has a variant part, only
the variant selected by the tag field can be assigned values.

Data types, variables, and constants

5-41

Declared constants

Examples:
type
TPoint = record
X, Y: Single;
end;
TVector = array[0..1] of TPoint;
TMonth = (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec);
TDate = record
D: 1..31;
M: TMonth;
Y: 1900..1999;
end;
const
Origin: TPoint = (X: 0.0; Y: 0.0);
Line: TVector = ((X: -3.1; Y: 1.5), (X: 5.8; Y: 3.0));
SomeDay: TDate = (D: 2; M: Dec; Y: 1960);

Record constants cannot contain file-type values at any level.

Procedural constants
To declare a procedural constant, specify the name of a function or procedure that is
compatible with the declared type of the constant. For example,
function Calc(X, Y: Integer): Integer;
begin

end;
type TFunction = function(X, Y: Integer): Integer;
const MyFunction: TFunction = Calc;

Given these declarations, you can use the procedural constant MyFunction in a
function call:
I := MyFunction(5, 7)

You can also assign the value nil to a procedural constant.

Pointer constants
When you declare a pointer constant, you must initialize it to a value that can be
resolvedat least as a relative addressat compile time. There are three ways to do
this: with the @ operator, with nil, and (if the constant is of type PChar) with a string
literal. For example, if I is a global variable of type Integer, you can declare a constant like
const PI: ^Integer = @I;

The compiler can resolve this because global variables are part of the code segment.
So are functions and global constants:
const PF: Pointer = @MyFunction;

Because string literals are allocated as global constants, you can initialize a PChar
constant with a string literal:
const WarningStr: PChar = 'Warning!';

Addresses of local (stack-allocated) and dynamic (heap-allocated) variables cannot

be assigned to pointer constants.

5-42

Object Pascal Language Guide

Chapter

Procedures and functions

Chapter6

Procedures and functionsreferred to collectively as routinesare self-contained

statement blocks that can be called from different locations in a program. A function
is a routine that returns a value when it executes. A procedure is a routine that does
not return a value.
Function calls, because they return a value, can be used as expressions in
assignments and operations. For example,
I := SomeFunction(X);

calls SomeFunction and assigns the result to I. Function calls cannot appear on the left
side of an assignment statement.
Both function and procedure calls can be used as complete statements. For example,
DoSomething;

calls the DoSomething routine; if DoSomething is a function, its return value is

discarded.
Procedures and functions can call themselves recursively.

Declaring procedures and functions

When you declare a procedure or function, you specify its name, the number and
type of parameters it takes, and, in the case of a function, the type of its return value;
this part of the declaration is sometimes called the prototype, heading, or header. Then
you write a block of code that executes whenever the procedure or function is called;
this part is sometimes called the routines body or block.
The standard procedure Exit can occur within the body of any procedure or function.
Exit halts execution of the routine where it occurs and immediately passes program
control back to the point from which the routine was called.

Procedures and functions

6-1

Declaring procedures and functions

Procedure declarations
A procedure declaration has the form
procedure procedureName(parameterList); directives;
localDeclarations;
begin
statements
end;
where procedureName is any valid identifier, statements is a sequence of statements
that execute when the procedure is called, and (parameterList), directives;, and
localDeclarations; are optional.
For information about the parameterList, see Parameters on page 6-9.
For information about directives, see Calling conventions on page 6-4, Forward
and interface declarations on page 6-5, External declarations on page 6-6, and
Overloading procedures and functions on page 6-7. If you include more than
one directive, separate them with semicolons.
For information about localDeclarations, which declares local identifiers, see Local
declarations on page 6-8.
Here is an example of a procedure declaration:
procedure NumString(N: Integer; var S: string);
var
V: Integer;
begin
V := Abs(N);
S := '';
repeat
S := Chr(V mod 10 + Ord('0')) + S;
V := V div 10;
until V = 0;
if N < 0 then S := '-' + S;
end;

Given this declaration, you can call the NumString procedure like this:
NumString(17, MyString);

This procedure call assigns the value 17 to MyString (which must be a string
variable).
Within a procedures statement block, you can use variables and other identifiers
declared in the localDeclarations part of the procedure. You can also use the parameter
names from the parameter list (like N and S in the example above); the parameter list
defines a set of local variables, so dont try to redeclare the parameter names in the
localDeclarations section. Finally, you can use any identifiers within whose scope the
procedure declaration falls.

6-2

Object Pascal Language Guide

Declaring procedures and functions

Function declarations
A function declaration is like a procedure declaration except that it specifies a return
type and a return value. Function declarations have the form
function functionName(parameterList): returnType; directives;
localDeclarations;
begin
statements
end;
where functionName is any valid identifier, returnType is any type, statements is a
sequence of statements that execute when the function is called, and (parameterList),
directives;, and localDeclarations; are optional.
For information about the parameterList, see Parameters on page 6-9.
For information about directives, see Calling conventions on page 6-4, Forward
and interface declarations on page 6-5, External declarations on page 6-6, and
Overloading procedures and functions on page 6-7. If you include more than
one directive, separate them with semicolons.
For information about localDeclarations, which declares local identifiers, see Local
declarations on page 6-8.
The functions statement block is governed by the same rules that apply to
procedures. Within the statement block, you can use variables and other identifiers
declared in the localDeclarations part of the function, parameter names from the
parameter list, and any identifiers within whose scope the function declaration falls.
In addition, the function name itself acts as a special variable that holds the functions
return value, as does the predefined variable Result.
For example,
function WF: Integer;
begin
WF := 17;
end;

defines a constant function called WF that takes no parameters and always returns
the integer value 17. This declaration is equivalent to
function WF: Integer;
begin
Result := 17;
end;

Here is a more complicated function declaration:

function Max(A: array of Real; N: Integer): Real;
var
X: Real;
I: Integer;
begin
X := A[0];
for I := 1 to N - 1 do
if X < A[I] then X := A[I];
Max := X;
end;

Procedures and functions

6-3

Declaring procedures and functions

You can assign a value to Result or to the function name repeatedly within a
statement block, as long as you assign only values that match the declared return
type. When execution of the function terminates, whatever value was last assigned to
Result or to the function name becomes the functions return value. For example,
function Power(X: Real; Y: Integer): Real;
var
I: Integer;
begin
Result := 1.0;
I := Y;
while I > 0 do
begin
if Odd(I) then Result := Result * X;
I := I div 2;
X := Sqr(X);
end;
end;

Result and the function name always represent the same value. Hence
function MyFunction: Integer;
begin
MyFunction := 5;
Result := Result * 2;
MyFunction := Result + 1;
end;

returns the value 11. But Result is not completely interchangeable with the function
name. When the function name appears on the left side of an assignment statement,
the compiler assumes that it is being used (like Result) to track the return value; when
the function name appears anywhere else in the statement block, the compiler
interprets it as a recursive call to the function itself. Result, on the other hand, can be
used as a variable in operations, typecasts, set constructors, indexes, and calls to
other routines.
Result is implicitly declared in every function, so do not try to redeclare it.
If execution terminates without an assignment being made to Result or the function
name, then the functions return value is undefined.

Calling conventions
When you declare a procedure or function, you can specify a calling convention using
one of the directives register, pascal, cdecl, stdcall, and safecall. For example,
function MyFunction(X, Y: Real): Real; cdecl;

Calling conventions determine the order in which parameters are passed to the
routine. They also affect the removal of parameters from the stack, the use of registers
for passing parameters, and error and exception handling. The default calling
convention is register.

6-4

Object Pascal Language Guide

Declaring procedures and functions

The register and pascal conventions pass parameters from left to right; that is, the
leftmost parameter is evaluated and passed first and the rightmost parameter is
evaluated and passed last. The cdecl, stdcall, and safecall conventions pass
parameters from right to left.
For all conventions except cdecl, the procedure or function removes parameters
from the stack upon returning. With the cdecl convention, the caller removes
parameters from the stack when the call returns.
The register convention uses up to three CPU registers to pass parameters, while
the other conventions pass all parameters on the stack.
The safecall convention implements COM error and exception handling.
The table below summarizes calling conventions.
Table 6.1

Calling conventions

Directive

Parameter order

Clean-up

Passes parameters in registers?

Left-to-right

Routine

Yes

pascal

Left-to-right

Routine

cdecl

Right-to-left

Caller

stdcall

Right-to-left

Routine

safecall

Right-to-left

Routine

The default register convention is the most efficient, since it usually avoids creation
of a stack frame. (Access methods for published properties must use register.) The
cdecl convention is useful when you call functions from DLLs written in C or C++,
while stdcall and safecall are used for Windows API calls. The safecall convention
must be used for declaring dual-interface methods (see Chapter 10, Object
interfaces). The pascal convention is maintained for backward compatibility. For
more information on calling conventions, see Chapter 12, Program control.
The directives near, far, and export refer to calling conventions in 16-bit Windows
programming. They have no effect in 32-bit applications and are maintained for
backward compatibility only.

Forward and interface declarations

The forward directive replaces the block, including local variable declarations and
statements, in a procedure or function declaration. For example,
function Calculate(X, Y: Integer): Real; forward;

declares a function called Calculate. Somewhere after the forward declaration, the
routine must be redeclared in a defining declaration that includes a block. The defining
declaration for Calculate might look like this:
function Calculate;
{ declarations }
begin
{ statement block }
end;

Procedures and functions

6-5

Declaring procedures and functions

Ordinarily, a defining declaration does not have to repeat the routines parameter list
or return type, but if it does repeat them, they must match those in the forward
declaration exactly (except that default parameters can be omitted). If the forward
declaration specifies an overloaded procedure or function (see Overloading
procedures and functions on page 6-7), then the defining declaration must repeat
the parameter list.
Between a forward declaration and its defining declaration, you can place nothing
except other declarations. The defining declaration can be an external or assembler
declaration, but it cannot be another forward declaration.
The purpose of a forward declaration is to extend the scope of a procedure or
function identifier to an earlier point in the source code. This allows other procedures
and functions to call the forward-declared routine before it is actually defined.
Besides letting you organize your code more flexibly, forward declarations are
sometimes necessary for mutual recursions.
The forward directive is not allowed in the interface section of a unit. Procedure and
function headers in the interface section, however, behave like forward declarations
and must have defining declarations in the implementation section. A routine
declared in the interface section is available from anywhere else in the unit and from
any other unit or program that uses the unit where it is declared.

External declarations
The external directive, which replaces the block in a procedure or function
declaration, allows you to call procedures and functions that are compiled separately
from your program.

Linking to .OBJ files

To call routines from a separately compiled .OBJ file, first link the .OBJ file to your
application using the $L (or $LINK) compiler directive. For example,
{$L BLOCK.OBJ}

links BLOCK.OBJ into the program or unit in which it occurs. Next, declare the
functions and procedures that you want to call:
procedure MoveWord(var Source, Dest; Count: Integer); external;
procedure FillWord(var Dest; Data: Integer; Count: Integer); external;

Now you can call the MoveWord and FillWord routines from BLOCK.OBJ.
Declarations like the ones above are frequently used to access external routines
written in assembly language. You can also place assembly-language routines
directly in your Object Pascal source code; for more information, see Chapter 13,
Inline assembler code.

6-6

Object Pascal Language Guide

Declaring procedures and functions

Importing functions from DLLs

To import routines from a dynamic-link library, attach a directive of the form
external stringConstant;
to the end of a normal procedure or function header, where stringConstant is the
name of the .DLL file in single quotation marks. For example,
function SomeFunction(S: string): string; external 'strlib.dll';

imports a function called SomeFunction from STRLIB.DLL.

You can import a routine under a different name from the one it has in the DLL. If
you do this, specify the original name in the external directive:
external stringConstant1 name stringConstant2;
where the first stringConstant gives the name of the .DLL file and the second
stringConstant is the routines original name. For example, the following declaration
imports a function from USER32.DLL (part of the Windows API).
function MessageBox(HWnd: Integer; Text, Caption: PChar; Flags: Integer): Integer;
stdcall; external 'user32.dll' name 'MessageBoxA';

The functions original name is MessageBoxA, but it is imported as MessageBox.

Instead of a name, you can use a number to identify the routine you want to import:
external stringConstant index integerConstant;
where integerConstant is the routines index in the DLL export table.
In your importing declaration, be sure to match the exact spelling and case of the
routines name. Later, when you call the imported routine, the name is
case-insensitive.
For more information about DLLs, see Chapter 9, Dynamic-link libraries and
packages.

Overloading procedures and functions

You can declare more than one routine in the same scope with the same name. This is
called overloading. Overloaded routines must be declared with the overload directive
and must have distinguishing parameter lists. For example, consider the declarations
function Divide(X, Y: Real): Real; overload;
begin
Result := X/Y;
end;
function Divide(X, Y: Integer): Integer; overload;
begin
Result := X div Y;
end;

These declarations create two functions, both called Divide, that take parameters of
different types. When you call Divide, the compiler determines which function to

Procedures and functions

6-7

Declaring procedures and functions

invoke by looking at the actual parameters passed in the call. For example,
Divide(6.0, 3.0) calls the first Divide function, because its arguments are real-valued.
You can pass to an overloaded routine parameters that are not identical in type with
those in any of the routines declarations, but that are assignment-compatible with the
parameters in more than one declaration. This happens most frequently when a routine
is overloaded with different integer types or different real typesfor example,
procedure Store(X: Longint); overload;
procedure Store(X: Shortint); overload;

In these cases, when it is possible to do so without ambiguity, the compiler invokes

the routine whose parameters are of the type with the smallest range that
accommodates the actual parameters in the call. (Remember that real-valued
constant expressions are always of type Extended.)
Overloaded routines must be distinguished by the number of parameters they take
or the types of their parameters. Hence the following pair of declarations causes a
compilation error.
function Cap(S: string): string; overload;

procedure Cap(var Str: string); overload;

But the declarations

function Func(X: Real; Y: Integer): Real; overload;

function Func(X: Integer; Y: Real): Real; overload;

are legal.
When an overloaded routine is declared in a forward or interface declaration, the
defining declaration must repeat the routines parameter list.
If you use default parameters in overloaded routines, be careful of ambiguous
parameter signatures. For more information, see Default parameters and
overloaded routines on page 6-17.
You can limit the potential effects of overloading by qualifying a routines name when
you call it. For example, Unit1.MyProcedure(X, Y) can call only routines declared in Unit1;
if no routine in Unit1 matches the name and parameter list in the call, an error results.
For information about distributing overloaded methods in a class hierarchy, see
Overloading methods on page 7-12. For information about exporting overloaded
routines from a DLL, see The exports clause on page 9-4.

Local declarations
The body of a function or procedure often begins with declarations of local variables
used in the routines statement block. These declarations can also include constants,
types, and other routines. The scope of a local identifier is limited to the routine
where it is declared.

6-8

Object Pascal Language Guide

Parameters

Nested routines
Functions and procedures sometimes contain other functions and procedures within
the local-declarations section of their blocks. For example, the following declaration
of a procedure called DoSomething contains a nested procedure.
procedure DoSomething(S: string);
var
X, Y: Integer;
procedure NestedProc(S: string);
begin

end;
begin

NestedProc(S);

end;

The scope of a nested routine is limited to the procedure or function in which it is

declared. In our example, NestedProc can be called only within DoSomething.
For real examples of nested routines, look at the DateTimeToString procedure, the
ScanDate function, and other routines in the SysUtils unit.

Parameters
Most procedure and function headers include a parameter list. For example, in the
header
function Power(X: Real; Y: Integer): Real;

the parameter list is (X: Real; Y: Integer).

A parameter list is a sequence of parameter declarations separated by semicolons and
enclosed in parentheses. Each declaration is a comma-delimited series of parameter
names, followed in most cases by a colon and a type identifier, and in some cases by
the = symbol and a default value. Parameter names must be valid identifiers. Any
declaration can be preceded by one of the reserved words var, const, and out.
Examples:
(X, Y: Real)
(var S: string; X: Integer)
(HWnd: Integer; Text, Caption: PChar; Flags: Integer)
(const P; I: Integer)

The parameter list specifies the number, order, and type of parameters that must be
passed to the routine when it is called. If a routine does not take any parameters, omit
the identifier list and the parentheses in its declaration:
procedure UpdateRecords;
begin

end;

Procedures and functions

6-9

Parameters

Within the procedure or function body, the parameter names (X and Y in the first
example above) can be used as local variables. Do not redeclare the parameter names
in the local declarations section of the procedure or function body.

Parameter semantics
Parameters are categorized in several ways:
Every parameter is classified as value, variable, constant, or out. Value parameters
are the default; the reserved words var, const, and out indicate variable, constant,
and out parameters, respectively.
Value parameters are always typed, while constant, variable, and out parameters
can be either typed or untyped.
Special rules apply to array parameters. See Array parameters on page 6-13.
Files and instances of structured types that contain files can be passed only as
variable (var) parameters.

Value and variable parameters

Most parameters are either value parameters (the default) or variable (var)
parameters. Value parameters are passed by value, while variable parameters are
passed by reference. To see what this means, consider the following functions.
function DoubleByValue(X: Integer): Integer;
begin
X := X * 2;
Result := X;
end;

// X is a value parameter

function DoubleByRef(var X: Integer): Integer;

begin
X := X * 2;
Result := X;
end;

// X is a variable parameter

These functions return the same result, but only the second oneDoubleByRefcan
change the value of a variable passed to it. Suppose we call the functions like this:
var
I, J, V, W: Integer;
begin
I := 4;
V := 4;
J := DoubleByValue(I);
W := DoubleByRef(V);
end;

// J = 8, I = 4
// W = 8, V = 8

After this code executes, the variable I, which was passed to DoubleByValue, has the
same value we initially assigned to it. But the variable V, which was passed to
DoubleByRef, has a different value.
A value parameter acts like a local variable that gets initialized to the value passed in
the procedure or function call. If you pass a variable as a value parameter, the

6-10

Object Pascal Language Guide

Parameters

procedure or function creates a copy of it; changes made to the copy have no effect on
the original variable and are lost when program execution returns to the caller.
A variable parameter, on the other hand, acts like a pointer rather than a copy.
Changes made to the parameter within the body of a function or procedure persist
after program execution returns to the caller and the parameter name itself has gone
out of scope.
Even if the same variable is passed in two or more var parameters, no copies are
made. This is illustrated in the following example.
procedure AddOne(var X, Y: Integer);
begin
X := X + 1;
Y := Y + 1;
end;
var I: Integer;
begin
I := 1;
AddOne(I, I);
end;

After this code executes, the value of I is 3.

If a routines declaration specifies a var parameter, you must pass an assignable
expressionthat is, a variable, typed constant (in the {$J+} state), dereferenced
pointer, field, or indexed variableto the routine when you call it. To use our
previous examples, DoubleByRef(7) produces an error, although DoubleByValue(7) is
legal.
Indexes and pointer dereferences passed in var parametersfor example,
DoubleByRef(MyArray[I])are evaluated once, before execution of the routine.

Constant parameters
A constant (const) parameter is like a local constant or read-only variable. Constant
parameters are similar to value parameters, except that you cant assign a value to a
constant parameter within the body of a procedure or function, nor can you pass one
as a var parameter to another routine. (But when you pass an object reference as a
constant parameter, you can still modify the objects properties.)
Using const allows the compiler to optimize code for structured- and string-type
parameters. It also provides a safeguard against unintentionally passing a parameter
by reference to another routine.
Here, for example, is the header for the CompareStr function in the SysUtils unit:
function CompareStr(const S1, S2: string): Integer;

Because S1 and S2 are not modified in the body of CompareStr, they can be declared
as constant parameters.

Out parameters
An out parameter, like a variable parameter, is passed by reference. With an out
parameter, however, the initial value of the referenced variable is discarded by the

Procedures and functions

6-11

Parameters

routine it is passed to. The out parameter is for output only; that is, it tells the
function or procedure where to store output, but doesnt provide any input.
For example, consider the procedure heading
procedure GetInfo(out Info: SomeRecordType);

When you call GetInfo, you must pass it a variable of type SomeRecordType:
var MyRecord: SomeRecordType;

GetInfo(MyRecord);

But youre not using MyRecord to pass any data to the GetInfo procedure; MyRecord is
just a container where you want GetInfo to store the information it generates. The call
to GetInfo immediately frees the memory used by MyRecord, before program control
passes to the procedure.
Out parameters are frequently used with distributed-object models like COM and
CORBA. In addition, you should use out parameters when you pass an uninitialized
variable to a function or procedure.

Untyped parameters
You can omit type specifications when declaring var, const, and out parameters.
(Value parameters must be typed.) For example,
procedure TakeAnything(const C);

declares a procedure called TakeAnything that accepts a parameter of any type. When
you call such a routine, you cannot pass it a numeral or untyped numeric constant.
Within a procedure or function body, untyped parameters are incompatible with
every type. To operate on an untyped parameter, you must cast it. In general, the
compiler cannot verify that operations on untyped parameters are valid.
The following example uses untyped parameters in a function called Equal that
compares a specified number of bytes of any two variables.
function Equal(var Source, Dest; Size: Integer): Boolean;
type
TBytes = array[0..MaxInt - 1] of Byte;
var
N: Integer;
begin
N := 0;
while (N < Size) and (TBytes(Dest)[N] = TBytes(Source)[N]) do
Inc(N);
Equal := N = Size;
end;

Given the declarations

type
TVector = array[1..10] of Integer;
TPoint = record
X, Y: Integer;
end;

6-12

Object Pascal Language Guide

Parameters

var
Vec1, Vec2: TVector;
N: Integer;
P: TPoint;

you could make the following calls to Equal:

Equal(Vec1, Vec2, SizeOf(TVector))
Equal(Vec1, Vec2, SizeOf(Integer) * N)
Equal(Vec1[1], Vec1[6], SizeOf(Integer) * 5)
Equal(Vec1[1], P, 4)

//
//
//
//

compare
compare
compare
compare

Vec1 to
first N
first 5
Vec1[1]

Vec2
elements of Vec1 and Vec2
to last 5 elements of Vec1
to P.X and Vec1[2] to P.Y

String parameters
When you declare routines that take short-string parameters, you cannot include
length specifiers in the parameter declarations. That is, the declaration
procedure Check(S: string[20]);

// syntax error

causes a compilation error. But

type TString20 = string[20];
procedure Check(S: TString20);

is valid. The special identifier OpenString can be used to declare routines that take
short-string parameters of varying length:
procedure Check(S: OpenString);

When the {$H} and {$P+} compiler directives are both in effect, the reserved word
string is equivalent to OpenString in parameter declarations.
Short strings, OpenString, $H, and $P are supported for backward compatibility only.
In new code, you can avoid these considerations by using long strings.

Array parameters
When you declare routines that take array parameters, you cannot include index type
specifiers in the parameter declarations. That is, the declaration
procedure Sort(A: array[1..10] of Integer);

// syntax error

causes a compilation error. But

type TDigits = array[1..10] of Integer;
procedure Sort(A: TDigits);

is valid. For most purposes, however, open array parameters are a better solution.

Open array parameters

Open array parameters allow arrays of different sizes to be passed to the same
procedure or function. To define a routine with an open array parameter, use the
syntax array of type (rather than array[X..Y] of type) in the parameter declaration.

Procedures and functions

6-13

Parameters

For example,
function Find(A: array of Char): Integer;

declares a function called Find that takes a character array of any size and returns an
integer.
Note

The syntax of open array parameters resembles that of dynamic array types, but they
do not mean the same thing. The example above creates a function that takes any
array of Char elements, including (but not limited to) dynamic arrays. To declare
parameters that must be dynamic arrays, you need to specify a type identifier:
type TDynamicCharArray = array of Char;
function Find(A: TDynamicCharArray): Integer;

For information about dynamic arrays, see Dynamic arrays on page 5-17.
Within the body of a routine, open array parameters are governed by the following rules.
They are always zero-based. The first element is 0, the second element is 1, and so
forth. The standard Low and High functions return 0 and Length1, respectively.
The SizeOf function returns the size of the actual array passed to the routine.
They can be accessed by element only. Assignments to an entire open array
parameter are not allowed.
They can be passed to other procedures and functions only as open array
parameters or untyped var parameters. They cannot be passed to SetLength.
Instead of an array, you can pass a variable of the open array parameters base
type. It will be treated as an array of length 1.
When you pass an array as an open array value parameter, the compiler creates a
local copy of the array within the routines stack frame. Be careful not to overflow the
stack by passing large arrays.
The following examples use open array parameters to define a Clear procedure that
assigns zero to each element in an array of reals and a Sum function that computes
the sum of the elements in an array of reals.
procedure Clear(var A: array of Real);
var
I: Integer;
begin
for I := 0 to High(A) do A[I] := 0;
end;
function Sum(const A: array of Real): Real;
var
I: Integer;
S: Real;
begin
S := 0;
for I := 0 to High(A) do S := S + A[I];
Sum := S;
end;

When you call routines that use open array parameters, you can pass open array
constructors to them. See Open array constructors on page 6-18.

6-14

Object Pascal Language Guide

Parameters

Variant open array parameters

Variant open array parameters allow you to pass an array of differently-typed
expressions to a single procedure or function. To define a routine with a variant open
array parameter, specify array of const as the parameters type. Thus
procedure DoSomething(A: array of const);

declares a procedure called DoSomething that can operate on heterogeneous arrays.

The array of const construction is equivalent to array of TVarRec. TVarRec, declared
in the System unit, represents a record with a variant part that can hold values of
integer, Boolean, character, real, string, pointer, class, class reference, interface, and
variant types. TVarRecs VType field indicates the type of each element in the array.
Some types are passed as pointers rather than values; in particular, long strings are
passed as Pointer and must be typecast to string. See the online Help on TVarRec for
details.
The following example uses a variant open array parameter in a function that creates
a string representation of each element passed to it and concatenates the results into a
single string. The string-handling routines called in this function are defined in
SysUtils.
function MakeStr(const Args: array of const): string;
const
BoolChars: array[Boolean] of Char = ('F', 'T');
var
I: Integer;
begin
Result := '';
for I := 0 to High(Args) do
with Args[I] do
case VType of
vtInteger:
Result := Result + IntToStr(VInteger);
vtBoolean:
Result := Result + BoolChars[VBoolean];
vtChar:
Result := Result + VChar;
vtExtended: Result := Result + FloatToStr(VExtended^);
vtString:
Result := Result + VString^;
vtPChar:
Result := Result + VPChar;
vtObject:
Result := Result + VObject.ClassName;
vtClass:
Result := Result + VClass.ClassName;
vtAnsiString: Result := Result + string(VAnsiString);
vtCurrency: Result := Result + CurrToStr(VCurrency^);
vtVariant:
Result := Result + string(VVariant^);
vtInt64:
Result := Result + IntToStr(VInt64^);
end;
end;

We can call this function using an open array constructor (see Open array
constructors on page 6-18). For example,
MakeStr(['test', 100, ' ', True, 3.14159, TForm])

returns the string test100 T3.14159TForm.

Procedures and functions

6-15

Parameters

Default parameters
You can specify default parameter values in a procedure or function heading. Default
values are allowed only for typed const and value parameters. To provide a default
value, end the parameter declaration with the = symbol followed by a constant
expression that is assignment-compatible with the parameters type.
For example, given the declaration
procedure FillArray(A: array of Integer; Value: Integer = 0);

the following procedure calls are equivalent.

FillArray(MyArray);
FillArray(MyArray, 0);

A multiple-parameter declaration cannot specify a default value. Thus, while

function MyFunction(X: Real = 3.5; Y: Real = 3.5): Real;

is legal,
function MyFunction(X, Y: Real = 3.5): Real;

// syntax error

is not.
Parameters with default values must occur at the end of the parameter list. That is, all
parameters following the first declared default value must also have default values.
So the following declaration is illegal.
procedure MyProcedure(I: Integer = 1; S: string);

// syntax error

Default values specified in a procedural type override those specified in an actual

routine. Thus, given the declarations
type TResizer = function(X: Real; Y: Real = 1.0): Real;
function Resizer(X: Real; Y: Real = 2.0): Real;
var
F: TResizer;
N: Real;

the statements
F := Resizer;
F(N);

result in the values (N, 1.0) being passed to Resizer.

Default parameters are limited to values that can be specified by a constant
expression. (See Constant expressions on page 5-39.) Hence parameters of a
dynamic-array, procedural, class, class-reference, or interface type can have no value
other than nil as their default. Parameters of a record, variant, file, static-array, or
object type cannot have default values at all.
For information about calling routines with default parameter values, see Calling
procedures and functions on page 6-17.

6-16

Object Pascal Language Guide

Calling procedures and functions

Default parameters and overloaded routines

If you use default parameter values in an overloaded routine, avoid ambiguous
parameter signatures. Consider, for example, the following.
procedure Confused(I: Integer); overload;

procedure Confused(I: Integer; J: Integer = 0); overload;

Confused(X);
// Which procedure is called?

In fact, neither procedure is called. This code generates a compilation error.

Default parameters in forward and interface declarations

If a routine has a forward declaration or appears in the interface section of a unit,
default parameter valuesif there are anymust be specified in the forward or
interface declaration. In this case, the default values can be omitted from the defining
(implementation) declaration; but if the defining declaration includes default values,
they must match those in the forward or interface declaration exactly.

Calling procedures and functions

When you call a procedure or function, program control passes from the point where
the call is made to the body of the routine. You can make the call using the routines
declared name (with or without qualifiers) or using a procedural variable that points
to the routine. In either case, if the routine is declared with parameters, your call to it
must pass parameters that correspond in order and type to the routines parameter
list. The parameters you pass to a routine are called actual parameters, while the
parameters in the routines declaration are called formal parameters.
When calling a routine, remember that
expressions used to pass typed const and value parameters must be
assignment-compatible with the corresponding formal parameters.
expressions used to pass var and out parameters must be identically typed with
the corresponding formal parameters, unless the formal parameters are untyped.
only assignable expressions can be used to pass var and out parameters.
if a routines formal parameters are untyped, numerals and true constants with
numeric values cannot be used as actual parameters.
When you call a routine that uses default parameter values, all actual parameters
following the first accepted default must also use the default values; calls of the form
SomeFunction(,,X) are not legal.
You can omit parentheses when passing all and only the default parameters to a
routine. For example, given the procedure
procedure DoSomething(X: Real = 1.0; I: Integer = 0; S: string = '');

the following calls are equivalent.

DoSomething();
DoSomething;

Procedures and functions

6-17

Calling procedures and functions

Open array constructors

Open array constructors allow you to construct arrays directly within function and
procedure calls. They can be passed only as open array parameters or variant open
array parameters.
An open array constructor, like a set constructor, is a sequence of expressions
separated by commas and enclosed in brackets. For example, given the declarations
var I, J: Integer;
procedure Add(A: array of Integer);

you could call the Add procedure with the statement

Add([5, 7, I, I + J]);

This is equivalent to
var Temp: array[0..3] of Integer;

Temp[0] := 5;
Temp[1] := 7;
Temp[2] := I;
Temp[3] := I + J;
Add(Temp);

Open array constructors can be passed only as value or const parameters. The
expressions in a constructor must be assignment-compatible with the base type of the
array parameter. In the case of a variant open array parameter, the expressions can be
of different types.

6-18

Object Pascal Language Guide

Chapter

Classes and objects

Chapter7

A class, or class type, defines a structure consisting of fields, methods, and properties.
Instances of a class type are called objects. The fields, methods, and properties of a
class are called its components or members.
A field is essentially a variable that is part of an object. Like the fields of a record, a
classs fields represent data items that exist in each instance of the class.
A method is a procedure or function associated with a class. Most methods
operate on objectsthat is, instances of a class. Some methods (called class
methods) operate on class types themselves.
A property is an interface to data associated with an object (often stored in a field).
Properties have access specifiers, which determine how their data are read and
modified. From other parts of a programoutside of the object itselfa property
appears in most respects like a field.
Objects are dynamically allocated blocks of memory whose structure is determined
by their class type. Each object has a unique copy of every field defined in the class,
but all instances of a class share the same methods. Objects are created and destroyed
by special methods called constructors and destructors.
A variable of a class type is actually a pointer that references an object. Hence more
than one variable can refer to the same object. Like other pointers, class-type
variables can hold the value nil. But you dont have to explicitly dereference a classtype variable to access the object it points to. For example, SomeObject.Size := 100
assigns the value 100 to the Size property of the object referenced by SomeObject; you
would not write this as SomeObject^.Size := 100.

Class types
A class type must be declared and given a name before it can be instantiated. (You
cannot define a class type within a variable declaration.) Declare classes only in the
outermost scope of a program or unit, not in a procedure or function declaration.
Classes and objects

7-1

Class types

A class type declaration has the form

type className = class (ancestorClass)
memberList
end;
where className is any valid identifier, (ancestorClass) is optional, and memberList
declares membersthat is, fields, methods, and propertiesof the class. If you omit
(ancestorClass), then the new class inherits directly from the predefined TObject class.
If you include (ancestorClass) and memberList is empty, you can omit end. A class type
declaration can also include a list of interfaces implemented by the class; see
Implementing interfaces on page 10-4.
Methods appear in a class declaration as function or procedure headings, with no
body. Defining declarations for each method occur elsewhere in the program.
For example, here is the declaration of the TListColumns class from the ComCtrls unit
of Delphis VCL.
type
TListColumns = class(TCollection)
private
FOwner: TCustomListView;
function GetItem(Index: Integer): TListColumn;
procedure SetItem(Index: Integer; Value: TListColumn);
protected
function GetOwner: TPersistent; override;
procedure Update(Item: TCollectionItem); override;
public
constructor Create(AOwner: TCustomListView);
function Add: TListColumn;
property Owner: TCustomListView read FOwner;
property Items[Index: Integer]: TListColumn read GetItem write SetItem; default;
end;

TListColumns descends from TCollection (in the Classes unit), inheriting most of its
members. But it definesor redefinesseveral methods and properties, including its
constructor method, Create. Its destructor, Destroy, is inherited without change from
TCollection, and so is not redeclared. Each member is declared as private, protected, or
public (this class has no published members); for explanations of these terms, see
Visibility of class members on page 7-4.
Given this declaration, we can create a TListColumns with
var ListColumns: TListColumns;
ListColumns := TListColumns.Create(SomeListView);

where SomeListView is a variable that holds a TCustomListView object.

Inheritance and scope

When you declare a class, you can specify its immediate ancestor. For example,
type TSomeControl = class(TWinControl);

declares a class called TSomeControl that descends from TWinControl. A class type
automatically inherits all of the members from its immediate ancestor. Each class can

7-2

Object Pascal Language Guide

Class types

declare new members and can redefine inherited ones, but a class cannot remove
members defined in an ancestor. Hence TSomeControl contains all of the members
defined in TWinControl and in each of TWinControls ancestors.
The scope of a members identifier starts at the point where the member is declared,
continues to the end of the class declaration, and extends over all descendants of the
class and the blocks of all methods defined in the class and its descendants.

TObject and TClass

The TObject class, declared in the System unit, is the ultimate ancestor of all other classes.
TObject defines only a handful of methods, including a basic constructor and destructor.
In addition to TObject, the System unit declares the class-reference type TClass:
TClass = class of TObject;

For more information about TObject, see the online VCL reference. For more
information about class-reference types, see Class references on page 7-22.
If the declaration of a class type doesnt specify an ancestor, the class inherits directly
from TObject. Thus
type TMyClass = class

end;

is equivalent to
type TMyClass = class(TObject)

end;

The latter form is recommended for readability.

Compatibility of class types

A class type is assignment-compatible with its ancestors. Hence a variable of a class type
can reference an instance of any descendant type. For example, given the declarations
type
TFigure = class(TObject);
TRectangle = class(TFigure);
TSquare = class(TRectangle);
var
Fig: TFigure;

the variable Fig can be assigned values of type TFigure, TRectangle, and TSquare.

Object types
As an alternative to class types, you can declare object types using the syntax
type objectTypeName = object (ancestorObjectType)
memberList
end;
where objectTypeName is any valid identifier, (ancestorObjectType) is optional, and
memberList declares fields, methods, and properties. If (ancestorObjectType) is

Classes and objects

7-3

Class types

omitted, then the new type has no ancestor. Object types cannot have published
members.
Since object types do not descend from TObject, they provide no built-in constructors,
destructors, or other methods. You can create instances of an object type using the
New procedure and destroy them with the Dispose procedure, or you can simply
declare variables of an object type, just as you would with records.
Object types are supported for backward compatibility only. Their use is not
recommended.

Visibility of class members

Every member of a class has an attribute called visibility, which is indicated by one of
the reserved words private, protected, public, published, or automated. For
example,
published property Color: TColor read GetColor write SetColor;

declares a published property called Color. Visibility determines where and how a
member can be accessed, with private representing the least accessibility, protected
representing an intermediate level of accessibility, and public, published, and
automated representing the greatest accessibility.
If a members declaration appears without its own visibility specifier, the member
has the same visibility as the one that precedes it. Members at the beginning of a class
declaration that dont have a specified visibility are by default published, provided
the class is compiled in the {$M+} state or is derived from a class compiled in the
{$M+} state; otherwise, such members are public.
For readability, it is best to organize a class declaration by visibility, placing all the
private members together, followed by all the protected members, and so forth. This
way each visibility reserved word appears at most once and marks the beginning of a
new section of the declaration. So a typical class declaration should like this:
type
TMyClass = class(TControl)
private
{ private declarations here}
protected
{ protected declarations here }
public
{ public declarations here }
published
{ published declarations here }
end;

You can increase the visibility of a member in a descendant class by redeclaring it,
but you cannot decrease its visibility. For example, a protected property can be made
public in a descendant, but not private. Moreover, published members cannot
become public in a descendant class. For more information, see Property overrides
and redeclarations on page 7-20.

7-4

Object Pascal Language Guide

Class types

Private, protected, and public members

A private member is invisible outside of the unit or program where its class is
declared. In other words, a private method cannot be called from another module,
and a private field or property cannot be read or written to from another module. By
placing related class declarations in the same module, you can give the classes access
to one anothers private members without making those members more widely
accessible.
A protected member is visible anywhere in the module where its class is declared and
from any descendant class, regardless of the module where the descendant class
appears. In other words, a protected method can be called, and a protected field or
property read or written to, from the definition of any method belonging to a class
that descends from the one where the protected member is declared. Members that
are intended for use only in the implementation of derived classes are usually
protected.
A public member is visible wherever its class can be referenced.

Published members
Published members have the same visibility as public members. The difference is that
runtime type information (RTTI) is generated for published members. RTTI allows an
application to query the fields and properties of an object dynamically and to locate
its methods. Delphi uses RTTI to access the values of properties when saving and
loading form (.DFM) files, to display properties in the Object Inspector, and to
associate specific methods (called event handlers) with specific properties (called
events).
Published properties are restricted to certain data types. Ordinal, string, class,
interface, and method-pointer types can be published. So can set types, provided the
upper and lower bounds of the base type have ordinal values between 0 and 31. (In
other words, the set must fit in a byte, word, or double word.) Any real type except
Real48 can be published. Array properties cannot be published.
All methods are publishable, but a class cannot publish two or more overloaded
methods with the same name. Fields can be published only if they are of a class or
interface type.
A class cannot have published members unless it is compiled in the {$M+} state or
descends from a class compiled in the {$M+} state. Most classes with published
members derive from TPersistent, which is compiled in the {$M+} state, so it is
seldom necessary to use the $M directive.

Automated members
Automated members have the same visibility as public members. The difference is
that Automation type information (required for Automation servers) is generated for
automated members. Automated members typically appear only in classes derived
from the TAutoObject class in the OleAuto unit. This unit, and the automated reserved
word itself, are maintained for backward compatibility. The TAutoObject class in the
ComObj unit does not use automated.

Classes and objects

7-5

Class types

The following restrictions apply to methods and properties declared as automated.

The types of all properties, array property parameters, method parameters, and
function results must be automatable. The automatable types are Byte, Currency,
Real, Double, Longint, Integer, Single, Smallint, AnsiString, WideString, TDateTime,
Variant, OleVariant, WordBool, and all interface types.
Method declarations must use the default register calling convention. They can be
virtual, but not dynamic.
Property declarations can include access specifiers (read and write) but other
specifiers (index, stored, default, and nodefault) are not allowed. Access
specifiers must list a method identifier that uses the default register calling
convention; field identifiers are not allowed.
Property declarations must specify a type. Property overrides are not allowed.
The declaration of an automated method or property can include a dispid directive,
which must be followed by an integer constant that specifies an Automation dispatch
ID for the member. Otherwise, the compiler automatically assigns the member a
dispatch ID that is one larger than the largest dispatch ID used by any method or
property in the class and its ancestors. Specifying an already used ID in a dispid
directive causes an error.
For more information about Automation, see Automation objects on page 10-10.

Forward declarations and mutually dependent classes

If the declaration of a class type ends with the word class and a semicolonthat is, if
it has the form
type className = class;
with no ancestor or class members listed after the word classthen it is a forward
declaration. A forward declaration must be resolved by a defining declaration of the
same class within the same type declaration section. In other words, between a
forward declaration and its defining declaration, nothing can occur except other type
declarations.
Forward declarations allow mutually dependent classes. For example,
type
TFigure = class; // forward declaration
TDrawing = class
Figure: TFigure;

end;
TFigure = class // defining declaration
Drawing: TDrawing;

end;

7-6

Object Pascal Language Guide

Fields

Do not confuse forward declarations with complete declarations of types that derive
from TObject without declaring any class members.
type
TFirstClass = class;
TSecondClass = class
end;

// this is a forward declaration

// this is a complete class declaration
//

TThirdClass = class(TObject); // this is a complete class declaration

Fields
A field is like a variable that belongs to an object. Fields can be of any type, including
class types. (That is, fields can hold object references.) Fields are usually private.
To define a field member of a class, simply declare the field as you would a variable.
All field declarations must occur before any property or method declarations. For
example, the following declaration creates a class called TNumber whose only
member, other than the methods is inherits from TObject, is an integer field called Int.
type TNumber = class
Int: Integer;
end;

Fields are statically bound; that is, references to them are fixed at compile time. To
see what this means, consider the following code.
type
TAncestor = class
Value: Integer;
end;
TDescendant = class(TAncestor)
Value: string; // hides the inherited Value field
end;
var
MyObject: TAncestor;
begin
MyObject := TDescendant.Create;
MyObject.Value := 'Hello!'; // error
TDescendant(MyObject).Value := 'Hello!'; // works!
end;

Although MyObject holds an instance of TDescendant, it is declared as TAncestor. The

compiler therefore interprets MyObject.Value as referring to the (integer) field
declared in TAncestor. Both fields, however, exist in the TDescendant object; the
inherited Value is hidden by the new one, and can be accessed through a typecast.

Classes and objects

7-7

Methods

Methods
A method is a procedure or function associated with a class. A call to a method
specifies the object (or, if it is a class method, the class) that the method should
operate on. For example,
SomeObject.Free

calls the Free method in SomeObject.

Method implementations
Within a class declaration, methods appear as procedure and function headings,
which work like forward declarations. Somewhere after the class declaration, but
within the same module, each method must be implemented by a defining
declaration. For example, suppose the declaration of TMyClass includes a method
called DoSomething:
type
TMyClass = class(TObject)

procedure DoSomething;

end;

A defining declaration for DoSomething must occur later in the module:

procedure TMyClass.DoSomething;
begin

end;

While a class can be declared in either the interface or the implementation section of a
unit, defining declarations for a classs methods must be in the implementation section.
In the heading of a defining declaration, the method name is always qualified with
the name of the class to which it belongs. The heading can repeat the parameter list
from the class declaration; if it does so, the order, type, and names of the parameters
must match exactly, and, if the method is a function, so must the return value.

Inherited
The reserved word inherited plays a special role in implementing polymorphic
behavior. It can occur in method definitions, with or without an identifier after it.
If inherited is followed by a method identifier, it represents a normal method call,
except that the search for the method begins with the immediate ancestor of the
enclosing methods class. For example, when
inherited Create(...);

occurs in the definition of a method, it calls the inherited Create.

When inherited has no identifier after it, it refers to the inherited method with the
same name as the enclosing method. In this case, inherited can appear with or

7-8

Object Pascal Language Guide

Methods

without parameters; if no parameters are specified, it passes to the inherited method

the same parameters with which the enclosing method was called. For example,
inherited;

occurs frequently in the implementation of constructors. It calls the inherited

constructor with the same parameters that were passed to the descendant.

Self
Within the implementation of a method, the identifier Self references the object in
which the method is called. For example, here is the implementation of TCollections
Add method in the Classes unit of the VCL.
function TCollection.Add: TCollectionItem;
begin
Result := FItemClass.Create(Self);
end;

The Add method calls the Create method in the class referenced by the FItemClass
field, which is always a TCollectionItem descendant. TCollectionItem.Create takes a
single parameter of type TCollection, so Add passes it the TCollection instance object
where Add is called. This is illustrated in the following code.
var MyCollection: TCollection;

MyCollection.Add // MyCollection is passed to the TCollectionItem.Create method

Self is useful for a variety of reasons. For example, a member identifier declared in a
class type might be redeclared in the block of one of the classs methods. In this case,
you can access the original member identifier as Self.Identifier.
For information about Self in class methods, see Class methods on page 7-24.

Method binding
Methods can be static (the default), virtual, or dynamic. Virtual and dynamic methods
can be overridden, and they can be abstract. These designations come into play when a
variable of one class type holds a value of a descendant class type. They determine
which implementation is activated when a method is called.

Static methods
Methods are by default static. When a static method is called, the declared (compile-time)
type of the class or object variable used in the method call determines which
implementation to activate. In the following example, the Draw methods are static.
type
TFigure = class
procedure Draw;
end;
TRectangle = class(TFigure)
procedure Draw;
end;

Classes and objects

7-9

Methods

Given these declarations, the following code illustrates the effect of calling a static
method. In the second call to Figure.Draw, the Figure variable references an object of
class TRectangle, but the call invokes the implementation of Draw in TFigure, because
the declared type of the Figure variable is TFigure.
var
Figure: TFigure;
Rectangle: TRectangle;
begin
Figure := TFigure.Create;
Figure.Draw; // calls TFigure.Draw
Figure.Destroy;
Figure := TRectangle.Create;
Figure.Draw; // calls TFigure.Draw
TRectangle(Figure).Draw; // calls TRectangle.Draw
Figure.Destroy;
Rectangle := TRectangle.Create;
Rectangle.Draw; // calls TRectangle.Draw
Rectangle.Destroy;
end;

Virtual and dynamic methods

To make a method virtual or dynamic, include the virtual or dynamic directive in its
declaration. Virtual and dynamic methods, unlike static methods, can be overridden in
descendant classes. When an overridden method is called, the actual (runtime) type
of the class or object used in the method callnot the declared type of the variable
determines which implementation to activate.
To override a method, redeclare it with the override directive. An override
declaration must match the ancestor declaration in the order and type of its
parameters and in its result type (if any).
In the following example, the Draw method declared in TFigure is overridden in two
descendant classes.
type
TFigure = class
procedure Draw; virtual;
end;
TRectangle = class(TFigure)
procedure Draw; override;
end;
TEllipse = class(TFigure)
procedure Draw; override;
end;

Given these declarations, the following code illustrates the effect of calling a virtual
method through a variable whose actual type varies at runtime.
var
Figure: TFigure;
begin
Figure := TRectangle.Create;
Figure.Draw; // calls TRectangle.Draw
Figure.Destroy;

7-10

Object Pascal Language Guide

Methods

Figure := TEllipse.Create;
Figure.Draw; // calls TEllipse.Draw
Figure.Destroy;
end;

Only virtual and dynamic methods can be overridden. All methods, however, can be
overloaded; see Overloading methods on page 7-12.

Virtual versus dynamic

Virtual and dynamic methods are semantically equivalent. They differ only in the
implementation of method-call dispatching at runtime. Virtual methods optimize for
speed, while dynamic methods optimize for code size.
In general, virtual methods are the most efficient way to implement polymorphic
behavior. Dynamic methods are useful when a base class declares many overridable
methods which are inherited by many descendant classes in an application, but only
occasionally overridden.

Overriding versus hiding

If a method declaration specifies the same method identifier and parameter signature
as an inherited method, but doesnt include override, the new declaration merely
hides the inherited one without overriding it. Both methods exist in the descendant
class, where the method name is statically bound. For example,
type
T1 = class(TObject)
procedure Act; virtual;
end;
T2 = class(T1)
procedure Act; // Act is redeclared, but not overridden
end;
var
SomeObject: T1;
begin
SomeObject := T2.Create;
SomeObject.Act; // calls T1.Act
end;

Reintroduce
The reintroduce directive suppresses compiler warnings about hiding previously
declared virtual methods. For example,
procedure DoSomething; reintroduce; // the ancestor class also has a DoSomething method

Use reintroduce when you want to hide an inherited virtual method with a new one.

Abstract methods
An abstract method is a virtual or dynamic method that has no implementation in the
class where it is declared. Its implementation is deferred to a descendant class.

Classes and objects

7-11

Methods

Abstract methods must be declared with the directive abstract after virtual or
dynamic. For example,
procedure DoSomething; virtual; abstract;

You can call an abstract method only in a class or instance of a class in which the
method has been overridden.

Overloading methods
A method can be redeclared using the overload directive. In this case, if the
redeclared method has a different parameter signature from its ancestor, it overloads
the inherited method without hiding it. Calling the method in a descendant class
activates whichever implementation matches the parameters in the call.
If you overload a virtual method, use the reintroduce directive when you redeclare it
in descendant classes. For example,
type
T1 = class(TObject)
procedure Test(I: Integer); overload; virtual;
end;
T2 = class(T1)
procedure Test(S: string); reintroduce; overload;
end;

SomeObject := T2.Create;
SomeObject.Test('Hello!'); // calls T2.Test
SomeObject.Test(7);
// calls T1.Test

Within a class, you cannot publish multiple overloaded methods with the same
name. Maintenance of runtime type information requires a unique name for each
published member.
type
TSomeClass = class
published
function Func(P: Integer): Integer;
function Func(P: Boolean): Integer // error

Methods that serve as property read or write specifiers cannot be overloaded.

The implementation of an overloaded method must repeat the parameter list from
the class declaration. For more information about overloading, see Overloading
procedures and functions on page 6-7.

Constructors
A constructor is a special method that creates and initializes instance objects. The
declaration of a constructor looks like a procedure declaration, but it begins with the
word constructor. Examples:
constructor Create;
constructor Create(AOwner: TComponent);

7-12

Object Pascal Language Guide

Methods

Constructors must use the default register calling convention. Although the
declaration specifies no return value, when a constructor is called using a class
reference, it returns a reference to the object it creates.
A class can have more than one constructor, but most have only one. It is
conventional to call the constructor Create.
To create an object, call the constructor method in a class type. For example,
MyObject := TMyClass.Create;

This allocates storage for the new object on the heap, sets the values of all ordinal
fields to zero, assigns nil to all pointer and class-type fields, and makes all string
fields empty. Other actions specified in the constructor implementation are
performed next; typically, objects are initialized based on values passed as
parameters to the constructor. Finally, the constructor returns a reference to the
newly allocated and initialized object. The type of the returned value is the same as
the class type specified in the constructor call.
If an exception is raised during execution of a constructor that was invoked on a class
reference, the Destroy destructor is automatically called to destroy the unfinished object.
When a constructor is called using an object reference (rather than a class reference),
it does not create an object or return a value. Instead, the constructor operates on the
specified object, executing only the statements in the constructors implementation. A
constructor is typically invoked on an object reference in conjunction with the
reserved word inherited to execute an inherited constructor.
Here is an example of a class type and its constructor.
type
TShape = class(TGraphicControl)
private
FPen: TPen;
FBrush: TBrush;
procedure PenChanged(Sender: TObject);
procedure BrushChanged(Sender: TObject);
public
constructor Create(Owner: TComponent); override;
destructor Destroy; override;

end;
constructor TShape.Create(Owner: TComponent);
begin
inherited Create(Owner); // Initialize inherited parts
Width := 65; // Change inherited properties
Height := 65;
FPen := TPen.Create; // Initialize new fields
FPen.OnChange := PenChanged;
FBrush := TBrush.Create;
FBrush.OnChange := BrushChanged;
end;

The first action of a constructor is usually to call an inherited constructor to initialize

the objects inherited fields. The constructor then initializes the fields introduced in the

Classes and objects

7-13

Methods

descendant class. Because a constructor always clears the storage it allocates for a new
object, all fields start with a value of zero (ordinal types), nil (pointer and class types),
empty (string types), or Unassigned (variants). Hence there is no need to initialize fields
in a constructors implementation except to nonzero or nonempty values.
When invoked through a class-type identifier, a constructor declared as virtual is
equivalent to a static constructor. When combined with class-reference types,
however, virtual constructors allow polymorphic construction of objectsthat is,
construction of objects whose types arent known at compile time. (See Class
references on page 7-22.)

Destructors
A destructor is a special method that destroys the object where it is called and
deallocates its memory. The declaration of a destructor looks like a procedure
declaration, but it begins with the word destructor. Examples:
destructor Destroy;
destructor Destroy; override;

Destructors must use the default register calling convention. Although a class can
have more than one destructor, it is recommended that each class override the
inherited Destroy method and declare no other destructors.
To call a destructor, you must reference an instance object. For example,
MyObject.Destroy;

When a destructor is called, actions specified in the destructor implementation are

performed first. Typically, these consist of destroying any embedded objects and
freeing resources that were allocated by the object. Then the storage that was
allocated for the object is disposed of.
Here is an example of a destructor implementation.
destructor TShape.Destroy;
begin
FBrush.Free;
FPen.Free;
inherited Destroy;
end;

The last action in a destructors implementation is typically to call the inherited

destructor to destroy the objects inherited fields.
When an exception is raised during creation of an object, Destroy is automatically
called to dispose of the unfinished object. This means that Destroy must be prepared
to dispose of partially constructed objects. Because a constructor sets the fields of a
new object to zero or empty values before performing other actions, class-type and
pointer-type fields in a partially constructed object are always nil. A destructor
should therefore check for nil values before operating on class-type or pointer-type
fields. Calling the Free method (defined in TObject), rather than Destroy, offers a
convenient way of checking for nil values before destroying an object.

7-14

Object Pascal Language Guide

Methods

Message handlers
Message handlers are methods that implement responses to dynamically dispatched
messages. Delphis VCL uses message handlers to respond to Windows messages.
A message handler is created by including the message directive in a method
declaration, followed by an integer constant between 1 and 49151 which specifies the
message ID. For message handlers in VCL controls, the integer constant must be one
of the Windows message IDs defined, along with corresponding record types, in the
Messages unit. For example,
type
TTextBox = class(TCustomControl)
private
procedure WMChar(var Message: TWMChar); message WM_CHAR;

end;

A message handler must be a procedure that takes a single var parameter.

A message handler does not have to include the override directive to override an
inherited message handler. In fact, it doesnt have to specify the same method name
or parameter type as the method it overrides. The message ID alone determines
which message the method responds to and whether it is an override.

Implementing message handlers

The implementation of a message handler can call the inherited message handler, as
in this example:
procedure TTextBox.WMChar(var Message: TWMChar);
begin
if Chr(Message.CharCode) = #13 then
ProcessEnter
else
inherited;
end;

The inherited statement searches backward through the class hierarchy and invokes
the first message handler with the same ID as the current method, automatically
passing the message record to it. If no ancestor class implements a message handler
for the given ID, inherited calls the DefaultHandler method originally defined in
TObject.
The implementation of DefaultHandler in TObject simply returns without performing
any actions. By overriding DefaultHandler, a class can implement its own default
handling of messages. The DefaultHandler method for VCL controls calls the
Windows DefWindowProc function.

Message dispatching
Message handlers are seldom called directly. Instead, messages are dispatched to an
object using the Dispatch method inherited from TObject:
procedure Dispatch(var Message);

Classes and objects

7-15

Properties

The Message parameter passed to Dispatch must be a record whose first entry is a field
of type Cardinal containing a message ID. See the Messages unit for examples.
Dispatch searches backward through the class hierarchy (starting from the class of the
object where it is called) and invokes the first message handler for the ID passed to it.
If no message handler is found for the given ID, Dispatch calls DefaultHandler.

Properties
A property, like a field, defines an attribute of an object. But while a field is merely a
storage location whose contents can be examined and changed, a property associates
specific actions with reading or modifying its data. Properties provide control over
access to an objects attributes, and they allow attributes to be computed.
The declaration of a property specifies a name and a type, and includes at least one
access specifier. The syntax of a property declaration is
property propertyName[indexes]: type index integerConstant specifiers;
where
propertyName is any valid identifier.
[indexes] is optional and is a sequence of parameter declarations separated by
semicolons. Each parameter declaration has the form identifier1, ..., identifiern:
type. For more information, see Array properties on page 7-18.
the index integerConstant clause is optional. For more information, see Index
specifiers on page 7-19.
specifiers is a sequence of read, write, stored, default (or nodefault), and
implements specifiers. Every property declaration must have at least one read or
write specifier. (For information about implements, see Implementing interfaces
by delegation on page 10-6.)
Properties are defined by their access specifiers. Unlike fields, properties cannot be
passed as var parameters, nor can the @ operator be applied to a property. The reason
is that a property doesnt necessarily exist in memory. It could, for instance, have a
read method that retrieves a value from a database or generates a random value.

Property access
Every property has a read specifier, a write specifier, or both. These are called access
specifiers and they have the form
read fieldOrMethod
write fieldOrMethod
where fieldOrMethod is the name of a field or method declared in the same class as the
property or in an ancestor class.
If fieldOrMethod is declared in the same class, it must occur before the property
declaration. If it is declared in an ancestor class, it must be visible from the

7-16

Object Pascal Language Guide

Properties

descendant; that is, it cannot be a private field or method of an ancestor class

declared in a different unit.
If fieldOrMethod is a field, it must be of the same type as the property.
If fieldOrMethod is a method, it cannot be overloaded. Moreover, access methods
for a published property must use the default register calling convention.
In a read specifier, if fieldOrMethod is a method, it must be a parameterless
function whose result type is the same as the propertys type.
In a write specifier, if fieldOrMethod is a method, it must be a procedure that takes
a single value or const parameter of the same type as the property.
For example, given the declaration
property Color: TColor read GetColor write SetColor;

the GetColor method must be declared as

function GetColor: TColor;

and the SetColor method must be declared as one of these:

procedure SetColor(Value: TColor);
procedure SetColor(const Value: TColor);

(The name of SetColors parameter, of course, doesnt have to be Value.)

When a property is referenced in an expression, its value is read using the field or
method listed in the read specifier. When a property is referenced in an assignment
statement, its value is written using the field or method listed in the write specifier.
The example below declares a class called TCompass with a published property called
Heading. The value of Heading is read through the FHeading field and written through
the SetHeading procedure.
type
THeading = 0..359;
TCompass = class(TControl)
private
FHeading: THeading;
procedure SetHeading(Value: THeading);
published
property Heading: THeading read FHeading write SetHeading;

end;

Given this declaration, the statements

if Compass.Heading = 180 then GoingSouth;
Compass.Heading := 135;

correspond to
if Compass.FHeading = 180 then GoingSouth;
Compass.SetHeading(135);

In the TCompass class, no action is associated with reading the Heading property; the
read operation consists of retrieving the value stored in the FHeading field. On the
other hand, assigning a value to the Heading property translates into a call to the

Classes and objects

7-17

Properties

SetHeading method, which, presumably, stores the new value in the FHeading field as
well as performing other actions. For example, SetHeading might be implemented like
this:
procedure TCompass.SetHeading(Value: THeading);
begin
if FHeading <> Value then
begin
FHeading := Value;
Repaint; // update user interface to reflect new value
end;
end;

A property whose declaration includes only a read specifier is a read-only property,

and one whose declaration includes only a write specifier is a write-only property. It
is an error to assign a value to a read-only property or use a write-only property in an
expression.

Array properties
Array properties are indexed properties. They can represent things like items in a list,
child controls of a control, and pixels of a bitmap.
The declaration of an array property includes a parameter list that specifies the
names and types of the indexes. For example,
property Objects[Index: Integer]: TObject read GetObject write SetObject;
property Pixels[X, Y: Integer]: TColor read GetPixel write SetPixel;
property Values[const Name: string]: string read GetValue write SetValue;

The format of an index parameter list is the same as that of a procedures or

functions parameter list, except that the parameter declarations are enclosed in
brackets instead of parentheses. Unlike arrays, which can use only ordinal-type
indexes, array properties allow indexes of any type.
For array properties, access specifiers must list methods rather than fields. The
method in a read specifier must be a function that takes the number and type of
parameters listed in the propertys index parameter list, in the same order, and
whose result type is identical to the propertys type. The method in a write specifier
must be a procedure that takes the number and type of parameters listed in the
propertys index parameter list, in the same order, plus an additional value or const
parameter of the same type as the property.
For example, the access methods for the array properties above might be declared as
function GetObject(Index: Integer): TObject;
function GetPixel(X, Y: Integer): TColor;
function GetValue(const Name: string): string;
procedure SetObject(Index: Integer; Value: TObject);
procedure SetPixel(X, Y: Integer; Value: TColor);
procedure SetValue(const Name, Value: string);

7-18

Object Pascal Language Guide

Properties

An array property is accessed by indexing the property identifier. For example, the
statements
if Collection.Objects[0] = nil then Exit;
Canvas.Pixels[10, 20] := clRed;
Params.Values['PATH'] := 'C:\DELPHI\BIN';

correspond to
if Collection.GetObject(0) = nil then Exit;
Canvas.SetPixel(10, 20, clRed);
Params.SetValue('PATH', 'C:\DELPHI\BIN');

The definition of an array property can be followed by the default directive, in which
case the array property becomes the default property of the class. For example,
type
TStringArray = class
public
property Strings[Index: Integer]: string ...; default;

end;

If a class has a default property, you can access that property with the abbreviation
object[index], which is equivalent to object.property[index]. For example, given the
declaration above, StringArray.Strings[7] can be abbreviated to StringArray[7]. A class
can have only one default property. Changing or hiding the default property in
descendant classes may lead to unexpected behavior, since the compiler always
determines an objects default property statically.

Index specifiers
Index specifiers allow several properties to share the same access method while
representing different values. An index specifier consists of the directive index
followed by an integer constant between 2147483647 and 2147483647. If a property
has an index specifier, its read and write specifiers must list methods rather than
fields. For example,
type
TRectangle = class
private
FCoordinates: array[0..3] of Longint;
function GetCoordinate(Index: Integer): Longint;
procedure SetCoordinate(Index: Integer; Value: Longint);
public
property Left: Longint index 0 read GetCoordinate write SetCoordinate;
property Top: Longint index 1 read GetCoordinate write SetCoordinate;
property Right: Longint index 2 read GetCoordinate write SetCoordinate;
property Bottom: Longint index 3 read GetCoordinate write SetCoordinate;
property Coordinates[Index: Integer]: Longint read GetCoordinate write SetCoordinate;

end;

An access method for a property with an index specifier must take an extra value
parameter of type Integer. For a read function, it must be the last parameter; for a

Classes and objects

7-19

Properties

write procedure, it must be the second-to-last parameter (preceding the parameter

that specifies the property value). When a program accesses the property, the
propertys integer constant is automatically passed to the access method.
Given the declaration above, if Rectangle is of type TRectangle, then
Rectangle.Right := Rectangle.Left + 100;

corresponds to
Rectangle.SetCoordinate(2, Rectangle.GetCoordinate(0) + 100);

Storage specifiers
The optional stored, default, and nodefault directives are called storage specifiers.
They have no effect on program behavior, but control the way Delphi maintains
runtime type information (RTTI). Specifically, storage specifiers determine whether
Delphi saves the values of published properties in form (.DFM) files.
The stored directive must be followed by True, False, the name of a Boolean field, or
the name of a parameterless method that returns a Boolean value. For example,
property Name: TComponentName read FName write SetName stored False;

If a property has no stored directive, it is treated as if stored True were specified.

The default directive must be followed by a constant of the same type as the
property. For example,
property Tag: Longint read FTag write FTag default 0;

To override an inherited default value without specifying a new one, use the
nodefault directive. The default and nodefault directives are supported only for
ordinal types and for set types, provided the upper and lower bounds of the sets
base type have ordinal values between 0 and 31; if such a property is declared
without default or nodefault, it is treated as if nodefault were specified. For reals,
pointers, and strings, there is an implicit default value of 0, nil, and '' (the empty
string), respectively.
When Delphi saves a components state, it checks the storage specifiers of the
components published properties. If a propertys current value is different from its
default value (or if there is no default value) and the stored specifier is True, then the
propertys value is saved. Otherwise, the propertys value is not saved.
Note

Storage specifiers are not supported for array properties. The default directive has a
different meaning when used in an array property declaration. See Array
properties on page 7-18.

Property overrides and redeclarations

A property declaration that doesnt specify a type is called a property override.
Property overrides allow you to change a propertys inherited visibility or specifiers.
The simplest override consists only of the reserved word property followed by an
inherited property identifier; this form is used to change a propertys visibility. For

7-20

Object Pascal Language Guide

Properties

example, if an ancestor class declares a property as protected, a derived class can

redeclare it in a public or published section of the class. Property overrides can
include read, write, stored, default, and nodefault directives; any such directive
overrides the corresponding inherited directive. An override can replace an inherited
access specifier, add a missing specifier, or increase a propertys visibility, but it
cannot remove an access specifier or decrease a propertys visibility. An override can
include an implements directive, which adds to the list of implemented interfaces
without removing inherited ones.
The following declarations illustrate the use of property overrides.
type
TAncestor = class

protected
property Size: Integer read FSize;
property Text: string read GetText write SetText;
property Color: TColor read FColor write SetColor stored False;

end;
type
TDerived = class(TAncestor)

protected
property Size write SetSize;
published
property Text;
property Color stored True default clBlue;

end;

The override of Size adds a write specifier to allow the property to be modified. The
overrides of Text and Color change the visibility of the properties from protected to
published. The property override of Color also specifies that the property should be
filed if its value isnt clBlue.
A redeclaration of a property that includes a type identifier hides the inherited
property rather than overriding it. This means that a new property is created with the
same name as the inherited one. Any property declaration that specifies a type must
be a complete declaration, and must therefore include at least one access specifier.
Whether a property is hidden or overridden in a derived class, property look-up is
always static. That is, the declared (compile-time) type of the variable used to identify
an object determines the interpretation of its property identifiers. Hence, after the
following code executes, reading or assigning a value to MyObject.Value invokes
Method1 or Method2, even though MyObject holds an instance of TDescendant. But you
can cast MyObject to TDescendant to access the descendant classs properties and their
access specifiers.
type
TAncestor = class

property Value: Integer read Method1 write Method2;

end;

Classes and objects

7-21

Class references

TDescendant = class(TAncestor)

property Value: Integer read Method3 write Method4;

end;
var MyObject: TAncestor;

MyObject := TDescendant.Create;

Class references
Sometimes operations are performed on a class itself, rather than on instances of a
class (that is, objects). This happens, for example, when you call a constructor method
using a class reference. You can always refer to a specific class using its name, but at
times it is necessary to declare variables or parameters that take classes as values, and
in these situations you need class-reference types.

Class-reference types
A class-reference type, sometimes called a metaclass, is denoted by a construction of
the form
class of type
where type is any class type. The identifier type itself denotes a value whose type is
class of type. If type1 is an ancestor of type2, then class of type2 is assignmentcompatible with class of type1. Thus
type TClass = class of TObject;
var AnyObj: TClass;

declares a variable called AnyObj that can hold a reference to any class. (The
definition of a class-reference type cannot occur directly in a variable declaration or
parameter list.) You can assign the value nil to a variable of any class-reference type.
To see how class-reference types are used, look at the declaration of the constructor
for TCollection (in the VCLs Classes unit):
type TCollectionItemClass = class of TCollectionItem;

constructor Create(ItemClass: TCollectionItemClass);

This declaration says that to create a TCollection instance object, you must pass to the
constructor the name of a class descending from TCollectionItem.
Class-reference types are useful when you want to invoke a class method or virtual
constructor on a class or object whose actual type is unknown at compile time.

Constructors and class references

A constructor can be called using a variable of a class-reference type. This allows
construction of objects whose type isnt known at compile time.

7-22

Object Pascal Language Guide

Class references

For example,
type TControlClass = class of TControl;
function CreateControl(ControlClass: TControlClass;
const ControlName: string; X, Y, W, H: Integer): TControl;
begin
Result := ControlClass.Create(MainForm);
with Result do
begin
Parent := MainForm;
Name := ControlName;
SetBounds(X, Y, W, H);
Visible := True;
end;
end;

The CreateControl function requires a class-reference parameter to tell it what kind of

control to create. It uses this parameter to call the classs constructor. Because
class-type identifiers denote class-reference values, a call to CreateControl can specify
the identifier of the class to create an instance of. For example,
CreateControl(TEdit, 'Edit1', 10, 10, 100, 20);

Constructors called using class references are usually virtual. The constructor
implementation activated by the call depends on the runtime type of the class
reference.

Class operators
Every class inherits from TObject methods called ClassType and ClassParent that
return, respectively, a reference to the class of an object and of an objects immediate
ancestor. Both methods return a value of type TClass (where TClass = class of
TObject), which can be cast to a more specific type. Every class also inherits a method
called InheritsFrom that tests whether the object where it is called descends from a
specified class. These methods are used by the is and as operators, and it is seldom
necessary to call them directly.

The is operator
The is operator, which performs dynamic type checking, is used to verify the actual
runtime class of an object. The expression
object is class
returns True if object is an instance of the class denoted by class or one of its
descendants, and False otherwise. (If object is nil, the result is False.) If the declared
type of object is unrelated to classthat is, if the types are distinct and one is not an
ancestor of the othera compilation error results. For example,
if ActiveControl is TEdit then TEdit(ActiveControl).SelectAll;

This statement casts a variable to TEdit after first verifying that the object it references
is an instance of TEdit or one of its descendants.

Classes and objects

7-23

Class references

The as operator
The as operator performs checked typecasts. The expression
object as class
returns a reference to the same object as object, but with the type given by class. At
runtime, object must be an instance of the class denoted by class or one of its
descendants, or be nil; otherwise an exception is raised. If the declared type of object
is unrelated to classthat is, if the types are distinct and one is not an ancestor of the
othera compilation error results. For example,
with Sender as TButton do
begin
Caption := '&Ok';
OnClick := OkClick;
end;

The rules of operator precedence often require as typecasts to be enclosed in

parentheses. For example,
(Sender as TButton).Caption := '&Ok';

Class methods
A class method is a method (other than a constructor) that operates on classes instead
of objects. The definition of a class method must begin with the reserved word class.
For example,
type
TFigure = class
public
class function Supports(Operation: string): Boolean; virtual;
class procedure GetInfo(var Info: TFigureInfo); virtual;

end;

The defining declaration of a class method must also begin with class. For example,
class procedure TFigure.GetInfo(var Info: TFigureInfo);
begin

end;

In the defining declaration of a class method, the identifier Self represents the class
where the method is called (which could be a descendant of the class in which it is
defined). If the method is called in the class C, then Self is of the type class of C. Thus
you cannot use Self to access fields, properties, and normal (object) methods, but you
can use it to call constructors and other class methods.
A class method can be called through a class reference or an object reference. When it
is called through an object reference, the class of the object becomes the value of Self.

7-24

Object Pascal Language Guide

Exceptions

Exceptions
An exception is raised when an error or other event interrupts normal execution of a
program. The exception transfers control to an exception handler, which allows you to
separate normal program logic from error-handling. Because exceptions are objects,
they can be grouped into hierarchies using inheritance, and new exceptions can be
introduced without affecting existing code. An exception can carry information, such
as an error message, from the point where it is raised to the point where it is handled.
When an application uses the SysUtils unit, all runtime errors are automatically
converted into exceptions. Errors that would otherwise terminate an application
such as insufficient memory, division by zero, and general protection faultscan be
caught and handled.

Declaring exception types

Exception types are declared just like other classes. In fact, it is possible to use an
instance of any class as an exception, but it is recommended that exceptions be
derived from the Exception class defined in SysUtils.
You can group exceptions into families using inheritance. For example, the following
declarations in SysUtils define a family of exception types for math errors.
type
EMathError = class(Exception);
EInvalidOp = class(EMathError);
EZeroDivide = class(EMathError);
EOverflow = class(EMathError);
EUnderflow = class(EMathError);

Given these declarations, you can define a single EMathError exception handler that
also handles EInvalidOp, EZeroDivide, EOverflow, and EUnderflow.
Exception classes sometimes define fields, methods, or properties that convey
additional information about the error. For example,
type EInOutError = class(Exception)
ErrorCode: Integer;
end;

Raising and handling exceptions

To create an exception object, call the exception classs constructor within a raise
statement. For example,
raise EMathError.Create;

Classes and objects

7-25

Exceptions

In general, the form of a raise statement is

raise object at address
where object and at address are both optional. If object is omitted, the statement
re-raises the current exception; see Re-raising exceptions on page 7-28. When an
address is specified, it is usually a pointer to a procedure or function; use this option
to raise the exception from an earlier point in the stack than the one where the error
actually occurred.
When an exception is raisedthat is, referenced in a raise statementit is governed
by special exception-handling logic. A raise statement never returns control in the
normal way. Instead, it transfers control to the innermost exception handler that can
handle exceptions of the given class. (The innermost handler is the one whose
try...except block was most recently entered but has not yet exited.)
For example, the function below converts a string to an integer, raising an
ERangeError exception if the resulting value is outside a specified range.
function StrToIntRange(const S: string; Min, Max: Longint): Longint;
begin
Result := StrToInt(S); // StrToInt is declared in SysUtils
if (Result < Min) or (Result > Max) then
raise ERangeError.CreateFmt(
'%d is not within the valid range of %d..%d',
[Result, Min, Max]);
end;

Notice the CreateFmt method called in the raise statement. Exception and its
descendants have special constructors that provide alternative ways to create
exception messages and context IDs. See the online Help for details.
A raised exception is destroyed automatically after it is handled. Never attempt to
destroy a raised exception manually.
Note

Raising an exception in the initialization section of a unit may not produce the
intended result. Normal exception support comes from the SysUtils unit, which must
be initialized before such support is available. If an exception occurs during
initialization, all initialized unitsincluding SysUtilsare finalized and the
exception is re-raised. Then the System unit catches the exception and handles it,
usually by interrupting the program.

Try...except statements
Exceptions are handled within try...except statements. For example,
try
X := Y/Z;
except
on EZeroDivide do HandleZeroDivide;
end;

This statement attempts to divide Y by Z, but calls a routine named HandleZeroDivide

if an EZeroDivide exception is raised.

7-26

Object Pascal Language Guide

Exceptions

The syntax of a try...except statement is

try statements except exceptionBlock end
where statements is a sequence of statements (delimited by semicolons) and
exceptionBlock is either
another sequence of statements or
a sequence of exception handlers, optionally followed by
else statements
An exception handler has the form
on identifier: type do statement
where identifier: is optional (if included, identifier can be any valid identifier), type is a
type used to represent exceptions, and statement is any statement.
A try...except statement executes the statements in the initial statements list. If no
exceptions are raised, the exception block (exceptionBlock) is ignored and control
passes to the next part of the program.
If an exception is raised during execution of the initial statements list, either by a raise
statement in the statements list or by a procedure or function called from the
statements list, an attempt is made to handle the exception:
If any of the handlers in the exception block matches the exception, control passes
to the first such handler. An exception handler matches an exception just in case
the type in the handler is the class of the exception or an ancestor of that class.
If no such handler is found, control passes to the statement in the else clause, if
there is one.
If the exception block is just a sequence of statements without any exception
handlers, control passes to the first statement in the list.
If none of the conditions above is satisfied, the search continues in the exception
block of the next-most-recently entered try...except statement that has not yet exited.
If no appropriate handler, else clause, or statement list is found there, the search
propagates to the next-most-recently entered try...except statement, and so forth. If
the outermost try...except statement is reached and the exception is still not handled,
the program terminates.
When an exception is handled, the stack is traced back to the procedure or function
containing the try...except statement where the handling occurs, and control is
transferred to the executed exception handler, else clause, or statement list. This
process discards all procedure and function calls that occurred after entering the
try...except statement where the exception is handled. The exception object is then
automatically destroyed through a call to its Destroy destructor and control is passed
to the statement following the try...except statement. (If a call to the Exit, Break, or
Continue standard procedure causes control to leave the exception handler, the
exception object is still automatically destroyed.)
In the example below, the first exception handler handles division-by-zero
exceptions, the second one handles overflow exceptions, and the final one handles all
other math exceptions. EMathError appears last in the exception block because it is

Classes and objects

7-27

Exceptions

the ancestor of the other two exception classes; if it appeared first, the other two
handlers would never be invoked.
try

except
on EZeroDivide do HandleZeroDivide;
on EOverflow do HandleOverflow;
on EMathError do HandleMathError;
end;

An exception handler can specify an identifier before the name of the exception class.
This declares the identifier to represent the exception object during execution of the
statement that follows on...do. The scope of the identifier is limited to that statement.
For example,
try

except
on E: Exception do ErrorDialog(E.Message, E.HelpContext);
end;

If the exception block specifies an else clause, the else clause handles any exceptions
that arent handled by the blocks exception handlers. For example,
try

except
on EZeroDivide do HandleZeroDivide;
on EOverflow do HandleOverflow;
on EMathError do HandleMathError;
else
HandleAllOthers;
end;

Here, the else clause handles any exception that isnt an EMathError.
An exception block that contains no exception handlers, but instead consists only of a
list of statements, handles all exceptions. For example,
try

except
HandleException;
end;

Here, the HandleException routine handles any exception that occurs as a result of
executing the statements between try and except.

Re-raising exceptions
When the reserved word raise occurs in an exception block without an object
reference following it, it raises whatever exception is handled by the block. This
allows an exception handler to respond to an error in a limited way and then re-raise
the exception. Re-raising is useful when a procedure or function has to clean up after
an exception occurs but cannot fully handle the exception.

7-28

Object Pascal Language Guide

Exceptions

For example, the GetFileList function allocates a TStringList object and fills it with file
names matching a specified search path:
function GetFileList(const Path: string): TStringList;
var
I: Integer;
SearchRec: TSearchRec;
begin
Result := TStringList.Create;
try
I := FindFirst(Path, 0, SearchRec);
while I = 0 do
begin
Result.Add(SearchRec.Name);
I := FindNext(SearchRec);
end;
except
Result.Free;
raise;
end;
end;

GetFileList creates a TStringList object, then uses the FindFirst and FindNext functions
(defined in SysUtils) to initialize it. If the initialization failsfor example because the
search path is invalid, or because there is not enough memory to fill in the string
listGetFileList needs to dispose of the new string list, since the caller does not yet
know of its existence. For this reason, initialization of the string list is performed in a
try...except statement. If an exception occurs, the statements exception block
disposes of the string list, then re-raises the exception.

Nested exceptions
Code executed in an exception handler can itself raise and handle exceptions. As long
as these exceptions are also handled within the exception handler, they do not affect
the original exception. However, once an exception raised in an exception handler
propagates beyond that handler, the original exception is lost. This is illustrated by
the Tan function below.
type
ETrigError = class(EMathError);
function Tan(X: Extended): Extended;
begin
try
Result := Sin(X) / Cos(X);
except
on EMathError do
raise ETrigError.Create('Invalid argument to Tan');
end;
end;

If an EMathError exception occurs during execution of Tan, the exception handler

raises an ETrigError. Since Tan does not provide a handler for ETrigError, the
exception propagates beyond the original exception handler, causing the EMathError

Classes and objects

7-29

Exceptions

exception to be destroyed. To the caller, it appears as if the Tan function has raised an
ETrigError exception.

Try...finally statements
Sometimes you want to ensure that specific parts of an operation are completed,
whether or not the operation is interrupted by an exception. For example, when a
routine acquires control of a resource, it is often important that the resource be
released, regardless of whether the routine terminates normally. In these situations,
you can use a try...finally statement.
The following example shows how code that opens and processes a file can ensure
that the file is ultimately closed, even if an error occurs during execution.
Reset(F);
try
// process file F
finally
CloseFile(F);
end;

The syntax of a try...finally statement is

try statementList1 finally statementList2 end
where each statementList is a sequence of statements delimited by semicolons. The
try...finally statement executes the statements in statementList1 (the try clause). If
statementList1 finishes without raising exceptions, statementList2 (the finally clause) is
executed. If an exception is raised during execution of statementList1, control is
transferred to statementList2; once statementList2 finishes executing, the exception is
re-raised. If a call to the Exit, Break, or Continue procedure causes control to leave
statementList1, statementList2 is automatically executed. Thus the finally clause is
always executed, regardless of how the try clause terminates.
If an exception is raised but not handled in the finally clause, that exception is
propagated out of the try...finally statement, and any exception already raised in the
try clause is lost. The finally clause should therefore handle all locally raised
exceptions, so as not to disturb propagation of other exceptions.

Standard exception classes and routines

The SysUtils unit declares several standard routines for handling exceptions,
including ExceptObject, ExceptAddr, and ShowException. SysUtils and other VCL units
also include dozens of exception classes, all which (aside from OutlineError) derive
from Exception.
The Exception class has properties called Message and HelpContext that can be used to
pass an error description and a context ID for context-sensitive online
documentation. It also defines various constructor methods that allow you to specify
the description and context ID in different ways. See the online Help for details.

7-30

Object Pascal Language Guide

Chapter

Standard routines and I/O

Chapter8

This chapter discusses text and file I/O and summarizes standard library routines.
Many of the procedures and functions listed here are defined in the System unit,
which is implicitly compiled with every application. Others are built into the
compiler but are treated as if they were in the System unit.
Some standard routines are in units such as SysUtils, which must be listed in a uses
clause to make them available in programs. You cannot, however, list System in a
uses clause, nor should you modify the System unit or try to rebuild it explicitly.
For more information about the routines listed here, see the online Help.

File input and output

The table below lists input and output routines.
Table 8.1

Input and output procedures and functions

Procedure or
function

Description

Append

Opens an existing text file for appending.

AssignFile

Assigns the name of an external file to a file variable.

BlockRead

Reads one or more records from an untyped file.

BlockWrite

Writes one or more records into an untyped file.

ChDir

Changes the current directory.

CloseFile

Closes an open file.

Eof

Returns the end-of-file status of a file.

Eoln

Returns the end-of-line status of a text file.

Erase

Erases an external file.

FilePos

Returns the current file position of a typed or untyped file.

FileSize

Returns the current size of a file; not used for text files.

Standard routines and I/O

8-1

File input and output

Table 8.1

Input and output procedures and functions (continued)

Procedure or
function

Description

Flush

Flushes the buffer of an output text file.

GetDir

Returns the current directory of a specified drive.

IOResult

Returns an integer value that is the status of the last I/O function performed.

MkDir

Creates a subdirectory.

Read

Reads one or more values from a file into one or more variables.

Readln

Does what Read does and then skips to beginning of next line in the text file.

Rename

Renames an external file.

Reset

Opens an existing file.

Rewrite

Creates and opens a new file.

RmDir

Removes an empty subdirectory.

Seek

Moves the current position of a typed or untyped file to a specified component.

Not used with text files.

SeekEof

Returns the end-of-file status of a text file.

SeekEoln

Returns the end-of-line status of a text file.

SetTextBuf

Assigns an I/O buffer to a text file.

Truncate

Truncates a typed or untyped file at the current file position.

Write

Writes one or more values to a file.

Writeln

Does the same as Write, and then writes an end-of-line marker to the text file.

A file variable is any variable whose type is a file type. There are three classes of file:
typed, text, and untyped. The syntax for declaring file types is given in File types on
page 5-23.
Before a file variable can be used, it must be associated with an external file through a
call to the AssignFile procedure. An external file is typically a named disk file, but it
can also be a device, such as the keyboard or the display. The external file stores the
information written to the file or supplies the information read from the file.
Once the association with an external file is established, the file variable must be
opened to prepare it for input or output. An existing file can be opened via the
Reset procedure, and a new file can be created and opened via the Rewrite procedure.
Text files opened with Reset are read-only and text files opened with Rewrite and
Append are write-only. Typed files and untyped files always allow both reading and
writing regardless of whether they were opened with Reset or Rewrite.
Every file is a linear sequence of components, each of which has the component type
(or record type) of the file. The components are numbered starting with zero.
Files are normally accessed sequentially. That is, when a component is read using the
standard procedure Read or written using the standard procedure Write, the current
file position moves to the next numerically ordered file component. Typed files and
untyped files can also be accessed randomly through the standard procedure Seek,
which moves the current file position to a specified component. The standard
functions FilePos and FileSize can be used to determine the current file position and
the current file size.

8-2

Object Pascal Language Guide

File input and output

When a program completes processing a file, the file must be closed using the
standard procedure CloseFile. After a file is closed, its associated external file is
updated. The file variable can then be associated with another external file.
By default, all calls to standard I/O procedures and functions are automatically
checked for errors, and if an error occurs an exception is raised (or the program is
terminated if exception handling is not enabled). This automatic checking can be
turned on and off using the {$I+} and {$I} compiler directives. When I/O checking is
offthat is, when a procedure or function call is compiled in the {$I} statean I/O
error doesnt cause an exception to be raised; to check the result of an I/O operation,
you must call the standard function IOResult instead.
You must call the IOResult function to clear an error, even if you arent interested in
the error. If you dont clear an error and {$I+} is the current state, the next I/O
function call will fail with the lingering IOResult error.

Text files
This section summarizes I/O using file variables of the standard type Text.
When a text file is opened, the external file is interpreted in a special way: It is
considered to represent a sequence of characters formatted into lines, where each line
is terminated by an end-of-line marker (a carriage-return character, possibly
followed by a linefeed character). The type Text is distinct from the type file of Char.
For text files, there are special forms of Read and Write that let you read and write
values that are not of type Char. Such values are automatically translated to and from
their character representation. For example, Read(F, I), where I is a type Integer
variable, reads a sequence of digits, interprets that sequence as a decimal integer, and
stores it in I.
There are two standard text-file variables, Input and Output. The standard file
variable Input is a read-only file associated with the operating systems standard
input (typically the keyboard). The standard file variable Output is a write-only file
associated with the operating systems standard output (typically the display). Before
an application begins executing, Input and Output are automatically opened, as if the
following statements were executed:
AssignFile(Input, '');
Reset(Input);
AssignFile(Output, '');
Rewrite(Output);
Note

Text-oriented I/O is available only in console applicationsthat is, applications

compiled with the Generate console application option checked on the Linker page
of the Project Options dialog box or with the -cc command-line compiler option. In a
GUI (non-console) application, any attempt to read or write using Input or Output
will produce an I/O error.
Some of the standard I/O routines that work on text files dont need to have a file
variable explicitly given as a parameter. If the file parameter is omitted, Input or
Output is assumed by default, depending on whether the procedure or function is

Standard routines and I/O

8-3

Text-file device drivers

input- or output-oriented. For example, Read(X) corresponds to Read(Input, X) and

Write(X) corresponds to Write(Output, X).
If you do specify a file when calling one of the input or output routines that work on
text files, the file must be associated with an external file using AssignFile, and
opened using Reset, Rewrite, or Append. An exception is raised if you pass a file that
was opened with Reset to an output-oriented procedure or function. An exception is
also raised if you pass a file that was opened with Rewrite or Append to an inputoriented procedure or function.

Untyped files
Untyped files are low-level I/O channels used primarily for direct access to disk files
regardless of type and structuring. An untyped file is declared with the word file
and nothing more. For example,
var DataFile: file;

For untyped files, the Reset and Rewrite procedures allow an extra parameter to
specify the record size used in data transfers. For historical reasons, the default
record size is 128 bytes. A record size of 1 is the only value that correctly reflects the
exact size of any file. (No partial records are possible when the record size is 1.)
Except for Read and Write, all typed-file standard procedures and functions are also
allowed on untyped files. Instead of Read and Write, two procedures called BlockRead
and BlockWrite are used for high-speed data transfers.

Text-file device drivers

You can define your own text-file device drivers for your Windows programs. A textfile device driver is a set of four functions that completely implement an interface
between Object Pascals file system and some device.
The four functions that define each device driver are Open, InOut, Flush, and Close.
The function header of each function is
function DeviceFunc(var F: TTextRec): Integer;
where DeviceFunc is the name of the function (that is, Open, InOut, Flush, or Close). For
information about the TTextRec type, see the online Help. The return value of a
device-interface function becomes the value returned by IOResult. If the return value
is zero, the operation was successful.
To associate the device-interface functions with a specific file, you must write a
customized Assign procedure. The Assign procedure must assign the addresses of the
four device-interface functions to the four function pointers in the text-file variable.
In addition, it should store the fmClosed magic constant in the Mode field, store the
size of the text-file buffer in BufSize, store a pointer to the text-file buffer in BufPtr,
and clear the Name string.

8-4

Object Pascal Language Guide

Text-file device drivers

Assuming, for example, that the four device-interface functions are called DevOpen,
DevInOut, DevFlush, and DevClose, the Assign procedure might look like this:
procedure AssignDev(var F: Text);
begin
with TextRec(F) do
begin
Mode := fmClosed;
BufSize := SizeOf(Buffer);
BufPtr := @Buffer;
OpenFunc := @DevOpen;
InOutFunc := @DevInOut;
FlushFunc := @DevFlush;
CloseFunc := @DevClose;
Name[0] := #0;
end;
end;

The device-interface functions can use the UserData field in the file record to store
private information. This field isnt modified by the Delphi file system at any time.

Device functions
The functions that make up a text-file device driver are described below.

The Open function

The Open function is called by the Reset, Rewrite, and Append standard procedures to
open a text file associated with a device. On entry, the Mode field contains fmInput,
fmOutput, or fmInOut to indicate whether the Open function was called from Reset,
Rewrite, or Append.
The Open function prepares the file for input or output, according to the Mode value.
If Mode specified fmInOut (indicating that Open was called from Append), it must be
changed to fmOutput before Open returns.
Open is always called before any of the other device-interface functions. For that
reason, AssignDev only initializes the OpenFunc field, leaving initialization of the
remaining vectors up to Open. Based on Mode, Open can then install pointers to either
input- or output-oriented functions. This saves the InOut, Flush functions and the
CloseFile procedure from determining the current mode.

The InOut function

The InOut function is called by the Read, Readln, Write, Writeln, Eof, Eoln, SeekEof,
SeekEoln, and CloseFile standard routines whenever input or output from the device is
required.
When Mode is fmInput, the InOut function reads up to BufSize characters into BufPtr^,
and returns the number of characters read in BufEnd. In addition, it stores zero in
BufPos. If the InOut function returns zero in BufEnd as a result of an input request, Eof
becomes True for the file.

Standard routines and I/O

8-5

Handling null-terminated strings

When Mode is fmOutput, the InOut function writes BufPos characters from BufPtr^,
and returns zero in BufPos.

The Flush function

The Flush function is called at the end of each Read, Readln, Write, and Writeln. It can
optionally flush the text-file buffer.
If Mode is fmInput, the Flush function can store zero in BufPos and BufEnd to flush the
remaining (unread) characters in the buffer. This feature is seldom used.
If Mode is fmOutput, the Flush function can write the contents of the buffer exactly like
the InOut function, which ensures that text written to the device appears on the
device immediately. If Flush does nothing, the text doesnt appear on the device until
the buffer becomes full or the file is closed.

The Close function

The Close function is called by the CloseFile standard procedure to close a text file
associated with a device. (The Reset, Rewrite, and Append procedures also call Close if
the file they are opening is already open.) If Mode is fmOutput, then before calling
Close, the file system calls the InOut function to ensure that all characters have been
written to the device.

Handling null-terminated strings

Object Pascals extended syntax allows the Read, Readln, Str, and Val standard
procedures to be applied to zero-based character arrays, and allows the Write,
Writeln, Val, AssignFile, and Rename standard procedures to be applied to both zerobased character arrays and character pointers. In addition, the following functions
are provided for handling null-terminated strings. For more information about nullterminated strings, see Working with null-terminated strings on page 5-12.
Table 8.2

8-6

Null-terminated string functions

Function

Description

StrAlloc

Allocates a character buffer of a given size on the heap.

StrBufSize

Returns the size of a character buffer allocated using StrAlloc or StrNew.

StrCat

Concatenates two strings.

StrComp

Compares two strings.

StrCopy

Copies a string.

StrDispose

Disposes a character buffer allocated using StrAlloc or StrNew.

StrECopy

Copies a string and returns a pointer to the end of the string.

StrEnd

Returns a pointer to the end of a string.

StrFmt

Formats one or more values into a string.

StrIComp

Compares two strings without case sensitivity.

StrLCat

Concatenates two strings with a given maximum length of the resulting string.

StrLComp

Compares two strings for a given maximum length.

Object Pascal Language Guide

Other standard routines

Table 8.2

Null-terminated string functions (continued)

Function

Description

StrLCopy

Copies a string up to a given maximum length.

StrLen

Returns the length of a string.

StrLFmt

Formats one or more values into a string with a given maximum length.

StrLIComp

Compares two strings for a given maximum length without case sensitivity.

StrLower

Converts a string to lowercase.

StrMove

Moves a block of characters from one string to another.

StrNew

Allocates a string on the heap.

StrPCopy

Copies a Pascal string to a null-terminated string.

StrPLCopy

Copies a Pascal string to a null-terminated string with a given maximum length.

StrPos

Returns a pointer to the first occurrence of a given substring within a string.

StrRScan

Returns a pointer to the last occurrence of a given character within a string.

StrScan

Returns a pointer to the first occurrence of a given character within a string.

StrUpper

Converts a string to uppercase.

Standard string-handling functions have multibyte-enabled counterparts that also

implement locale-specific ordering for characters. Names of multibyte functions start
with Ansi-. For example, the multibyte version of StrPos is AnsiStrPos. Multibyte
character support is operating-system dependent and based on the current Windows
locale.

Wide-character strings
The System unit provides three functions, WideCharToString, WideCharLenToString,
and StringToWideChar, that can be used to convert null-terminated wide character
strings to single- or double-byte long strings.
For more information about wide-character strings, see About extended character
sets on page 5-12.

Other standard routines

The table below lists frequently used procedures and functions found in Delphis
libraries. This is not an exhaustive inventory of standard routines. For more
information about these and other routines, see the online Help.
Table 8.3

Other standard routines

Procedure or
function

Description

Abort

Ends the process without reporting an error.

Addr

Returns a pointer to a specified object.

AllocMem

Allocates a memory block and initializes each byte to zero.

Standard routines and I/O

8-7

Other standard routines

Table 8.3

8-8

Other standard routines (continued)

Procedure or
function

Description

ArcTan

Calculates the arctangent of the given number.

Assert

Tests whether a boolean expression is True.

Assigned

Tests for a nil (unassigned) pointer or procedural variable.

Beep

Generates a standard beep using the computer speaker.

Break

Causes control to exit a for, while, or repeat statement.

ByteToCharIndex

Returns the position of the character containing a specified byte in a string.

Chr

Returns the character for a specified ASCII value.

Terminates the association between a file variable and an external file.

CompareMem

Performs a binary comparison of two memory images.

CompareStr

Compares strings case sensitively.

CompareText

Compares strings by ordinal value and is not case sensitive.

Continue

Returns control to the next iteration of for, while, or repeat statements.

Copy

Returns a substring of a string or a segment of a dynamic array.

Cos

Calculates the cosine of an angle.

CurrToStr

Converts a currency variable to a string.

Date

Returns the current date.

DateTimeToStr

Converts a variable of type TDateTime to a string.

DateToStr

Converts a variable of type TDateTime to a string.

Dec

Decrements an ordinal variable.

Dispose

Releases memory allocated for a dynamic variable.

ExceptAddr

Returns the address at which the current exception was raised.

Exit

Exits from the current procedure.

Exp

Calculates the exponential of X.

FillChar

Fills contiguous bytes with a specified value.

Finalize

Uninitializes a dynamically allocated variable.

FloatToStr

Converts a floating point value to a string.

FloatToStrF

Converts a floating point value to a string, using specified format.

FmtLoadStr

Returns formatted output using a resourced format string.

FmtStr

Assembles a formatted string from a series of arrays.

Format

Assembles a string from a format string and a series of arrays.

FormatDateTime

Formats a date-and-time value.

FormatFloat

Formats a floating point value.

FreeMem

Disposes of a dynamic variable.

GetMem

Creates a dynamic variable and a pointer to the address of the block.

GetParentForm

Returns the form or property page that contains a specified control.

Halt

Initiates abnormal termination of a program.

Returns the high-order byte of an expression as an unsigned value.

High

Returns the highest value in the range of a type, array, or string.

Inc

Increments an ordinal variable.

Object Pascal Language Guide

Other standard routines

Table 8.3

Other standard routines (continued)

Procedure or
function

Description

Initialize

Initializes a dynamically allocated variable.

Insert

Inserts a substring at a specified point in a string.

Int

Returns the integer part of a real number.

IntToStr

Converts an integer to a string.

Length

Returns the length of a string or array.

Returns the low-order byte of an expression as an unsigned value.

Low

Returns the lowest value in the range of a type, array, or string.

LowerCase

Converts an ASCII string to lowercase.

MaxIntValue

Returns the largest signed value in an integer array.

MaxValue

Returns the largest signed value in an array.

MinIntValue

Returns the smallest signed value in an integer array.

MinValue

Returns smallest signed value in an array.

New

Creates a new dynamic variable and references it with a specified pointer.

Now

Returns the current date and time.

Ord

Returns the ordinal value of an ordinal-type expression.

Pos

Returns the index of the first character of a specified substring in a string.

Pred

Returns the predecessor of an ordinal value.

Ptr

Converts a specified address to a pointer.

Random

Generates random numbers within a specified range.

ReallocMem

Reallocates a dynamic variable.

Round

Returns the value of a real rounded to the nearest whole number.

SetLength

Sets the dynamic length of a string variable or array.

SetString

Sets the contents and length of the given string.

ShowException

Displays an exception message with its address.

ShowMessage

Displays a message box with an unformatted string and an OK button.

ShowMessageFmt

Displays a message box with a formatted string and an OK button.

Sin

Returns the sine of an angle in radians.

SizeOd

Returns the number of bytes occupied by a variable or type.

Sqr

Returns the square of a number.

Sqrt

Returns the square root of a number.

Str

Formats a string and returns it to a variable.

StrToCurr

Converts a string to a currency value.

StrToDate

Converts a string to a date format (TDateTime).

StrToDateTime

Converts a string to a TDateTime.

StrToFloat

Converts a string to a floating-point value.

StrToInt

Converts a string to an integer.

StrToTime

Converts a string to a time format (TDateTime).

StrUpper

Returns a string in upper case.

Succ

Returns the successor of an ordinal value.

Standard routines and I/O

8-9

Other standard routines

Table 8.3

Other standard routines (continued)

Procedure or
function

Description

Sum

Returns the sum of the elements from an array.

Time

Returns the current time.

TimeToStr

Converts a variable of type TDateTime to a string.

Trunc

Truncates a real number to an integer.

UniqueString

Makes a string unique.

UpCase

Converts a character to uppercase.

UpperCase

Returns a string in uppercase.

VarArrayCreate

Creates a variant array.

VarArrayDimCount

Returns number of dimensions of a variant array.

VarARrayHighBound

Returns high bound for a dimension in a variant array.

VarArrayLock

Locks a variant array and returns a pointer to the data.

VarArrayLowBound

Returns the low bound of a dimension in a variant array.

VarArrayOf

Creates and fills a one-dimensional variant array.

VarArrayRedim

Resizes a variant array.

VarArrayRef

Returns a reference to the passed variant array.

VarArrayUnlock

Unlocks a variant array.

VarAsType

Converts a variant to specified type.

VarCast

Converts a variant to a specified type, storing the result in a variable.

VarClear

Clears a variant.

CarCopy

Copies a variant.

VarToStr

Converts variant to string.

VarType

Returns type code of specified variant.

For information on format strings, see Format strings in the online Help.

8-10

Object Pascal Language Guide

Part

II
Special topics

Part II

The chapters in Part II cover specialized language features and advanced topics.
These chapters include:
Chapter 9, Dynamic-link libraries and packages
Chapter 10, Object interfaces
Chapter 11, Memory management
Chapter 12, Program control
Chapter 13, Inline assembler code

Special topics

Chapter

Dynamic-link libraries and packages

Chapter9

A dynamic-link library (DLL) is a collection of routines that can be called by

applications and by other DLLs. Like units, DLLs contain sharable code or resources.
But a DLL is a separately compiled executable that is linked at runtime to the
programs that use it.
To distinguish them from standalone executables, files containing compiled DLLs are
named with the .DLL extension. Object Pascal programs can call DLLs written in
other languages, and Windows applications written in other languages can call DLLs
written in Object Pascal.

Calling DLLs
Before you can call routines defined in a DLL, you must import them. This can be
done in two ways: by declaring an external procedure or function, or by calling the
Windows API directly. Whichever method you use, the routines are not linked to
your application until runtime. This means that the DLL need not be present when
you compile your program. It also means that there is no compile-time validation of
attempts to import a routine.
Object Pascal does not support importing of variables from DLLs.

Static loading
The simplest way to import a procedure or function is to declare it using the external
directive. For example,
procedure DoSomething; external 'MYLIB.DLL';

If you include this declaration in a program, MYLIB.DLL is loaded once, when the
program starts. Throughout execution of the program, the identifier DoSomething
always refers to the same entry point in the same DLL.

Dynamic-link libraries and packages

9-1

Calling DLLs

Declarations of imported routines can be placed directly in the program or unit

where they are called. To simplify maintenance, however, you can collect external
declarations into a separate import unit that also contains any constants and types
required for interfacing with the DLL. (Delphis Windows unit is a good example.)
Other modules that use the import unit can call any routines declared in it.
For more information about external declarations, see Importing functions from
DLLs on page 6-7.

Dynamic loading
You can access routines in a DLL through direct calls to Windows library functions,
including LoadLibrary, FreeLibrary, and GetProcAddress (all declared in Delphis
Windows unit). In this case, use procedural-type variables to reference the imported
routines. For example,
uses Windows, ...;
type
TTimeRec = record
Second: Integer;
Minute: Integer;
Hour: Integer;
end;
TGetTime = procedure(var Time: TTimeRec);
THandle = Integer;
var
Time: TTimeRec;
Handle: THandle;
GetTime: TGetTime;

begin
Handle := LoadLibrary('DATETIME.DLL');
if Handle <> 0 then
begin
@GetTime := GetProcAddress(Handle, 'GetTime');
if @GetTime <> nil then
begin
GetTime(Time);
with Time do
WriteLn('The time is ', Hour, ':', Minute, ':', Second);
end;
FreeLibrary(Handle);
end;
end;

When you import routines this way, the DLL is not loaded until the code containing
the call to LoadLibrary executes. The DLL is later unloaded by the call to FreeLibrary.
This allows you to conserve memory, and to run your program even when some of
the DLLs it uses are not present.

9-2

Object Pascal Language Guide

Writing DLLs

Writing DLLs
The structure of a DLL is identical to that of a program, except that a DLL begins with
the reserved word library (instead of program).
The following example shows a DLL with two exported functions, Min and Max.
library MinMax;
function Min(X, Y: Integer): Integer; stdcall;
begin
if X < Y then Min := X else Min := Y;
end;
function Max(X, Y: Integer): Integer; stdcall;
begin
if X > Y then Max := X else Max := Y;
end;
exports
Min,
Max;
begin
end.

If you want your DLL to be available to applications written in other languages, its
safest to specify stdcall in the declarations of exported functions. Other languages
may not support Object Pascals default register calling convention.
DLLs can be built from multiple units. In this case, the library source file is frequently
reduced to a uses clause, an exports clause, and the DLLs initialization code. For
example,
library Editors;
uses EdInit, EdInOut, EdFormat, EdPrint;
exports
InitEditors,
DoneEditors index 17 name Done,
InsertText name Insert,
DeleteSelection name Delete,
FormatSelection,
PrintSelection name Print,

SetErrorHandler;
begin
InitLibrary;
end.

You can put exports clauses in the interface or implementation section of a unit. Any
library that includes such a unit in its uses clause automatically exports the routines
listed the units exports clauseswithout the need for an exports clause of its own.
Only routines that a library explicitly exports are available for importing by other
libraries or programs.

Dynamic-link libraries and packages

9-3

Writing DLLs

The exports clause

A routine is exported when it is listed in an exports clause, which has the form
exports entry1, ..., entryn;
where each entry consists of the name of a procedure or function (which must be
declared prior to the exports clause), followed by a parameter list (only if the routine
is overloaded), followed by an optional index specifier and an optional name
specifier. You can qualify the procedure or function name with the name of a unit.
(Entries can also include the directive resident, which is maintained for backward
compatibility and is ignored by the compiler.)
An index specifier consists of the directive index followed by a numeric constant
between 1 and 2,147,483,647. (For more efficient programs, use low index values.) If
an entry has no index specifier, the routine is automatically assigned a number in the
DLLs export table. Use of index specifiers, which are supported for backward
compatibility, is discouraged and may cause problems for other development tools.
A name specifier consists of the directive name followed by a string constant. If an
entry has no name specifier, the routine is exported under its original declared name,
with the same spelling and case. Use a name clause when you want to export a
routine under a different name. For example,
exports
DoSomethingABC name 'DoSomething';

When you export an overloaded function or procedure from a DLL, you must specify
its parameter list in the exports clause. For example,
exports
Divide(X, Y: Integer) name 'Divide_Ints',
Divide(X, Y: Real) name 'Divide_Reals';

Do not include index specifiers in entries for overloaded routines.

An exports clause can appear anywhere and any number of times in the declaration
part of a program or library, or in the interface or implementation section of a unit.
Programs seldom contain an exports clause.

Library initialization code

The statements in a librarys block constitute the librarys initialization code. These
statements are executed once every time the DLL is loaded. They typically perform
tasks like registering window classes and initializing variables. Library initialization
code can also install an exit procedure using the ExitProc variable, as described in
Exit procedures on page 12-4; the exit procedure executes when the DLL is
unloaded.
Library initialization code can signal an error by setting the ExitCode variable to a
nonzero value. ExitCode is declared in the System unit and defaults to zero, indicating
successful initialization. If a librarys initialization code sets ExitCode to another
value, the DLL is unloaded and the calling application is notified of the failure.

9-4

Object Pascal Language Guide

Writing DLLs

Similarly, if an unhandled exception occurs during execution of the initialization

code, the calling application is notified of a failure to load the DLL.
Here is an example of a library with initialization code and an exit procedure.
library Test;
var
SaveExit: Pointer;
procedure LibExit;
begin
// library exit code
ExitProc := SaveExit; // restore exit procedure chain
end;
begin
// library initialization code
SaveExit := ExitProc; // save exit procedure chain
ExitProc := @LibExit; // install LibExit exit procedure
end.

When a DLL is unloaded, the librarys exit procedures are executed by repeated calls
to the address stored in ExitProc, until ExitProc becomes nil. The initialization parts of
all units used by a library are executed before the librarys initialization code, and the
finalization parts of those units are executed after the librarys exit procedure.

Global variables in a DLL

Global variables declared in a DLL cannot be imported by an Object Pascal
application.
A DLL can be used by several applications at once, but each application has a copy of
the DLL in its own process space with its own set of global variables. For multiple
DLLsor multiple instances of a DLLto share memory, they must use memorymapped files. Refer to the Windows API documentation for further information.

DLLs and System variables

Several variables declared in the System unit are of special interest to programmers of
DLLs. Use IsLibrary to determine whether code is executing in an application or in a
DLL; IsLibrary is always False in an application and True in a DLL. During a DLLs
lifetime, HInstance contains its instance handle. CmdLine is always nil in a DLL.
The DLLProc variable allows a DLL to monitor calls that the operating system makes
to the DLLs entry point. This feature is normally used only by DLLs that support
multithreading. To monitor operating-system calls, create a callback procedure that
takes a single integer parameterfor example,
procedure DLLHandler(Reason: Integer);

Dynamic-link libraries and packages

9-5

Writing DLLs

and assign the address of the procedure to the DLLProc variable. When Windows
calls the procedure, it passes to it one of the following values (defined in the Windows
unit).
DLL_PROCESS_DETACH

DLL_THREAD_ATTACH
DLL_THREAD_DETACH

Indicates that the DLL is detaching from the address

space of the calling process as a result of a clean exit or
a call to FreeLibrary.
Indicates that the current process is creating a new
thread.
Indicates that a thread is exiting cleanly.

In the body of the procedure, you can specify actions to take depending on which
parameter is passed to the procedure.

Exceptions and runtime errors in DLLs

When an exception is raised but not handled in a DLL, it propagates out of the DLL
to the caller. If the calling application or DLL is itself written in Object Pascal, the
exception can be handled through a normal try...except statement. If the calling
application or DLL is written in another language, the exception can be handled as an
operating-system exception with the exception code $0EEDFACE. The first entry in
the ExceptionInformation array of the operating-system exception record contains the
exception address, and the second entry contains a reference to the Object Pascal
exception object.
If a DLL does not use the SysUtils unit, Delphis exception support is disabled. In this
case, when a runtime error occurs in the DLL, the calling application terminates.
Because the DLL has no way of knowing whether it was called from an Object Pascal
program, it cannot invoke the applications exit procedures; the application is simply
aborted and removed from memory.

The shared-memory manager

If a DLL exports routines that pass long strings or dynamic arrays as parameters or
function results (whether directly or nested in records or objects), then the DLL and
its client applications (or DLLs) must all use the ShareMem unit. The same is true if
one application or DLL allocates memory with New or GetMem which is deallocated
by a call to Dispose or FreeMem in another module. ShareMem should always be the
first unit listed in any program or library uses clause where it occurs.
ShareMem is the interface unit for the BORLANDMM.DLL memory manager, which
allows modules to share dynamically allocated memory. BORLANDMM.DLL must
be deployed with applications and DLLs that use ShareMem. When an application or
DLL uses ShareMem, its memory manager is replaced by the memory manager in
BORLANDMM.DLL.

9-6

Object Pascal Language Guide

Packages

Packages
A package is a specially compiled dynamic-link library used by Delphi applications,
the Delphi IDE, or both. Runtime packages provide functionality when a user runs an
application. Design-time packages are used to install components in Delphis IDE and
to create special property editors for custom components. A single package can
function at both design time and runtime, and design-time packages frequently work
by referencing runtime packages in their requires clauses.
To distinguish them from other DLLs, package libraries are stored in files that end
with the .BPL (Borland package library) extension.
Ordinarily, packages are loaded statically when an applications starts. But you can
use the LoadPackage and UnloadPackage routines (in the SysUtils unit) to load packages
dynamically.
Note

When an application utilizes packages, the name of each packaged unit still must
appear in the uses clause of any source file that references it. For more information
about packages, see the online Help.

Package declarations and source files

Each package is declared in a separate source file, which should be saved with the
.DPK (Delphi package) extension to avoid confusion with other files containing
Object Pascal code. A package source file does not contain type, data, procedure, or
function declarations. Instead, it contains
A name for the package.
A list of other packages required by the new package. These are packages to which
the new package is linked.
A list of unit files contained by, or bound into, the package when it is compiled. The
package is essentially a wrapper for these source-code units, which provide the
functionality of the compiled BPL.
A package declaration has the form
package packageName;
requiresClause;
containsClause;
end.
where packageName is any valid identifier. The requiresClause and containsClause are
both optional. For example, the following code declares the VCLDB50 package.
package VCLDB50;
requires VCL50;
contains Db, Dbcgrids, Dbctrls, Dbgrids, ... ;
end.

The requires clause lists other, external packages used by the package being
declared. It consists of the directive requires, followed by a comma-delimited list of
package names, followed by a semicolon. If a package does not reference other
packages, it does not need a requires clause.

Dynamic-link libraries and packages

9-7

Packages

The contains clause identifies the unit files to be compiled and bound into the
package. It consists of the directive contains, followed by a comma-delimited list of
unit names, followed by a semicolon. Any unit name may be followed by the
reserved word in and the name of a source file, with or without a directory path, in
single quotation marks; directory paths can be absolute or relative. For example,
contains MyUnit in 'C:\MyProject\MyUnit.pas';
Note

Thread-local variables (declared with threadvar) in a packaged unit cannot be

accessed from clients that use the package.

Naming packages
A compiled package involves several generated files. For example, the source file for
the package called VCL50 is VCL50.DPK, from which the compiler generates an
executable and a binary image called VCL50.BPL and VCL50.DCP, respectively. VCL50
is used to refer to the package in the requires clauses of other packages, or when using
the package in an application. Package names must be unique within a project.

The requires clause

The requires clause lists other, external packages that are used by the current
package. It functions like the uses clause in a unit file. An external package listed in
the requires clause is automatically linked at compile time into any application that
uses both the current package and one of the units contained in the external package.
If the unit files contained in a package make references to other packaged units, the
other packages should be included in the first packages requires clause. If the other
packages are omitted from the requires clause, the compiler loads the referenced
units from their DCU files.

Avoiding circular package references

Packages cannot contain circular references in their requires clauses. This means that
A package cannot reference itself in its own requires clause.
A chain of references must terminate without rereferencing any package in the
chain. If package A requires package B, then package B cannot require package A;
if package A requires package B and package B requires package C, then package
C cannot require package A.

Duplicate package references

The compiler ignores duplicate references in a packages requires clause. For
programming clarity and readability, however, duplicate references should be
removed.

The contains clause

The contains clause identifies the unit files to be bound into the package. Do not
include file-name extensions in the contains clause.

Avoiding redundant source code uses

A package cannot be listed in the contains clause of another package or the uses
clause of a unit.

9-8

Object Pascal Language Guide

Packages

All units included directly in a packages contains clause, or indirectly in the uses
clauses of those units, are bound into the package at compile time. The units
contained (directly or indirectly) in a package cannot be contained in any other
packages referenced in requires clause of that package.
A unit cannot be contained (directly or indirectly) in more than one package used by
the same application.

Compiling packages
Packages are ordinarily compiled from the Delphi IDE using .DPK files generated by
the Package editor. You can also compile .DPK files directly from the command line.
When you build a project that contains a package, the package is implicitly
recompiled if necessary.

Generated files
The following table lists the files produced by the successful compilation of a
package.
Table 9.1

Compiled package files

File extension

Contents

DCP

A binary image containing a package header and the concatenation of all DCU
files in the package. A single DCP file is created for each package. The base
name for the DCP is the base name of the DPK source file.

DCU

A binary image for a unit file contained in a package. One DCU is created,
when necessary, for each unit file.

BPL

The runtime package. This file is a Windows DLL with special Delphi-specific
features. The base name for the BPL is the base name of the DPK source file.

Several compiler directives and command-line switches are available to support

package compilation.

Package-specific compiler directives

The following table lists package-specific compiler directives that can be inserted into
source code. See the online Help for details.
Table 9.2

Package-specific compiler directives

Directive

Purpose

{$IMPLICITBUILD OFF}

Prevents a package from being implicitly recompiled later.

Use in .DPK files when compiling packages that provide
low-level functionality, that change infrequently between
builds, or whose source code will not be distributed.

{$G} or {$IMPORTEDDATA OFF}

Disables creation of imported data references. This

directive increases memory-access efficiency, but prevents
the unit where it occurs from referencing variables in
other packages.

{$WEAKPACKAGEUNIT ON}

Packages unit weakly, as explained in the online Help.

{$DENYPACKAGEUNIT ON}

Prevents unit from being placed in a package.

Dynamic-link libraries and packages

9-9

Packages

Table 9.2

Package-specific compiler directives (continued)

Directive

Purpose

{$DESIGNONLY ON}

Compiles the package for installation in the Delphi IDE.

(Put in .DPK file.)

{$RUNONLY ON}

Compiles the package as runtime only. (Put in .DPK file.)

Including {$DENYPACKAGEUNIT ON} in source code prevents the unit file from
being packaged. Including {$G} or {IMPORTEDDATA OFF} may prevent a
package from being used in the same application with other packages.
Other compiler directives may be included, if appropriate, in package source code.

Package-specific command-line compiler switches

The following package-specific switches are available for the command-line
compiler. See the online Help for details.
Table 9.3

Package-specific command-line compiler switches

Switch

Purpose

Disables creation of imported data references. Using this

switch increases memory-access efficiency, but prevents
packages compiled with it from referencing variables in
other packages.

LE path

Specifies the directory where the package BPL file will be

placed.

LN path

Specifies the directory where the package DCP file will be

placed.

LUpackageName[;packageName2;...]

Specifies additional runtime packages to use in an

application. Used when compiling a project.

Prevents a package from being implicitly recompiled later.

Use when compiling packages that provide low-level
functionality, that change infrequently between builds, or
whose source code will not be distributed.

Using the $G switch may prevent a package from being used in the same
application with other packages.
Other command-line options may be used, if appropriate, when compiling packages.

9-10

Object Pascal Language Guide

Chapter

10
Object interfaces

Chapter10

An object interfaceor simply interfacedefines methods that can be implemented by

a class. Interfaces are declared like classes, but cannot be directly instantiated and do
not have their own method definitions. Rather, it is the responsibility of any class that
supports an interface to provide implementations for the interfaces methods. A
variable of an interface type can reference an object whose class implements that
interface; however, only methods declared in the interface can be called using such a
variable.
Interfaces offer some of the advantages of multiple inheritance without the semantic
difficulties. They are also essential for using distributed object models, including
COM (the Component Object Model) and CORBA (Common Object Request Broker
Architecture). Objects built with Delphi that support interfaces can interact with
COM objects written in C++, Java, and other languages.

Interface types
Interfaces, like classes, can be declared only in the outermost scope of a program or
unit, not in a procedure or function declaration. An interface type declaration has the
form
type interfaceName = interface (ancestorInterface)
['{GUID}']
memberList
end;
where (ancestorInterface) and ['{GUID}'] are optional. In most respects, interface
declarations resemble class declarations, but the following restrictions apply.
The memberList can include only methods and properties. Fields are not allowed in
interfaces.
Since an interface has no fields, property read and write specifiers must be
methods.
Object interfaces

10-1

Interface types

All members of an interface are public. Visibility specifiers and storage specifiers
are not allowed. (But an array property can be declared as default.)
Interfaces have no constructors or destructors. They cannot be instantiated, except
through classes that implement their methods.
Methods cannot be declared as virtual, dynamic, abstract, or override. Since
interfaces do not implement their own methods, these designations have no
meaning.
Here is an example of an interface declaration:
type
IMalloc = interface(IUnknown)
['{00000002-0000-0000-C000-000000000046}']
function Alloc(Size: Integer): Pointer; stdcall;
function Realloc(P: Pointer; Size: Integer): Pointer; stdcall;
procedure Free(P: Pointer); stdcall;
function GetSize(P: Pointer): Integer; stdcall;
function DidAlloc(P: Pointer): Integer; stdcall;
procedure HeapMinimize; stdcall;
end;

IUnknown and inheritance

An interface, like a class, inherits all of its ancestors methods. But interfaces, unlike
classes, do not implement methods. What an interface inherits is the obligation to
implement methodsan obligation that devolves onto any class supporting the
interface.
The declaration of an interface can specify an ancestor interface. If no ancestor is
specified, the interface is a direct descendant of IUnknown, which is defined in the
System unit and is the ultimate ancestor of all other interfaces. IUnknown declares
three methods: QueryInterface, _AddRef, and _Release. QueryInterface provides the
means to move freely among the different interfaces that an object supports. _AddRef
and _Release provide lifetime management for interface references. The easiest way to
implement these methods is to derive the implementing class from the System units
TInterfacedObject.

Interface identification
An interface declaration can specify a globally unique identifier (GUID), represented
by a string literal enclosed in brackets immediately preceding the member list. The
GUID part of the declaration must have the form
['{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}']
where each x is a hexadecimal digit (0 through 9 or A through F).
A GUID is a 16-byte binary value that uniquely identifies an interface. If an interface
has a GUID, you can use interface querying to get references to its implementations.
(See Interface querying on page 10-9.)

10-2

Object Pascal Language Guide

Interface types

The TGUID and PGUID types, declared in the System unit, are used to manipulate
GUIDs.
type
PGUID
TGUID
D1:
D2:
D3:
D4:
end;

= ^TGUID;
= packed record
Longword;
Word;
Word;
array[0..7] of Byte;

When you declare a typed constant of type TGUID, you can use a string literal to
specify its value. For example,
const IID_IMalloc: TGUID = '{00000002-0000-0000-C000-000000000046}';

In procedure and function calls, either a GUID or an interface identifier can serve as a
value or constant parameter of type TGUID. For example, given the declaration
function Supports(Unknown: IUnknown; const IID: TGUID): Boolean;

Supports can be called in either of two ways:

if Supports(Allocator, IMalloc) then ...
if Supports(Allocator, IID_IMalloc) then ...

Calling conventions
The default calling convention is register, but interfaces shared among modules
(especially if they are written in different languages) should declare all methods with
stdcall. Use safecall to implement methods of dual interfaces (as described in Dual
interfaces on page 10-12) and CORBA interfaces.
For more information about calling conventions, see Calling conventions on
page 6-4.

Interface properties
Properties declared in an interface are accessible only through expressions of the
interface type; they cannot be accessed through class-type variables. Moreover,
interface properties are visible only within programs where the interface is compiled.
COM objects do not have properties.
In an interface, property read and write specifiers must be methods, since fields are
not available.

Forward declarations
An interface declaration that ends with the reserved word interface and a semicolon,
without specifying an ancestor, GUID, or member list, is a forward declaration. A
forward declaration must be resolved by a defining declaration of the same interface

Object interfaces

10-3

Implementing interfaces

within the same type declaration section. In other words, between a forward
declaration and its defining declaration, nothing can occur except other type
declarations.
Forward declarations allow mutually dependent interfaces. For example,
type
IControl = interface;
IWindow = interface
['{00000115-0000-0000-C000-000000000044}']
function GetControl(Index: Integer): IControl;

end;
IControl = interface
['{00000115-0000-0000-C000-000000000049}']
function GetWindow: IWindow;

end;

Mutually derived interfaces are not allowed. For example, it is not legal to derive
IWindow from IControl and also derive IControl from IWindow.

Implementing interfaces
Once an interface has been declared, it must be implemented in a class before it can
be used. The interfaces implemented by a class are specified in the classs declaration,
after the name of the classs ancestor. Such declarations have the form
type className = class (ancestorClass, interface1, ..., interfacen)
memberList
end;
For example,
type
TMemoryManager = class(TInterfacedObject, IMalloc, IErrorInfo)

end;

declares a class called TMemoryManager that implements the IMalloc and IErrorInfo
interfaces. When a class implements an interface, it must implement (or inherit an
implementation of) each method declared in the interface.
Here is the declaration of TInterfacedObject in the System unit.
type
TInterfacedObject = class(TObject, IUnknown)
protected
FRefCount: Integer;
function QueryInterface(const IID: TGUID; out Obj): Integer; stdcall;
function _AddRef: Integer; stdcall;
function _Release: Integer; stdcall;
public
property RefCount: Integer read FRefCount;
end;

10-4

Object Pascal Language Guide

Implementing interfaces

TInterfacedObject implements the IUnknown interface. Hence TInterfacedObject

declares and implements each of IUnknowns three methods.
Classes that implement interfaces can also be used as base classes. (The first example
above declares TMemoryManager as a direct descendent of TInterfacedObject.) Since
every interface inherits from IUnknown, a class that implements interfaces must
implement the QueryInterface, _AddRef, and _Release methods. The System units
TInterfacedObject implements these methods and is thus a convenient base from
which to derive other classes that implement interfaces.
When an interface is implemented, each of its methods is mapped onto a method in
the implementing class that has the same result type, the same calling convention, the
same number of parameters, and identically typed parameters in each position. By
default, each interface method is mapped to a method of the same name in the
implementing class.

Method resolution clauses

You can override the default name-based mappings by including method resolution
clauses in a class declaration. When a class implements two or more interfaces that
have identically named methods, use method resolution clauses to resolve the
naming conflicts.
A method resolution clause has the form
procedure interface.interfaceMethod = implementingMethod;
or
function interface.interfaceMethod = implementingMethod;
where implementingMethod is a method declared in the class or one of its ancestors.
The implementingMethod can be a method declared later in the class declaration, but
cannot be a private method of an ancestor class declared in another module.
For example, the class declaration
type
TMemoryManager = class(TInterfacedObject, IMalloc, IErrorInfo)
function IMalloc.Alloc = Allocate;
procedure IMalloc.Free = Deallocate;

end;

maps IMallocs Alloc and Free methods onto TMemoryManagers Allocate and Deallocate
methods.
A method resolution clause cannot alter a mapping introduced by an ancestor class.

Changing inherited implementations

Descendant classes can change the way a specific interface method is implemented
by overriding the implementing method. This requires that the implementing
method be virtual or dynamic.

Object interfaces

10-5

Implementing interfaces

A class can also reimplement an entire interface that it inherits from an ancestor class.
This involves relisting the interface in the descendant classs declaration. For
example,
type
IWindow = interface
['{00000115-0000-0000-C000-000000000146}']
procedure Draw;

end;
TWindow = class(TInterfacedObject, IWindow) // TWindow implements IWindow
procedure Draw;

end;
TFrameWindow = class(TWindow, IWindow) // TFrameWindow reimplements IWindow
procedure Draw;

end;

Reimplementing an interface hides the inherited implementation of the same

interface. Hence method resolution clauses in an ancestor class have no effect on the
reimplemented interface.

Implementing interfaces by delegation

The implements directive allows you to delegate implementation of an interface to a
property in the implementing class. For example,
property MyInterface: IMyInterface read FMyInterface implements IMyInterface;

declares a property called MyInterface that implements the interface IMyInterface.

The implements directive must be the last specifier in the property declaration and
can list more than one interface, separated by commas. The delegate property
must be of a class or interface type.
cannot be an array property or have an index specifier.
must have a read specifier. If the property uses a read method, that method must
use the default register calling convention and cannot be dynamic (though it can
be virtual) or specify the message directive.

Delegating to an interface-type property

If the delegate property is of an interface type, that interface, or an interface from
which it derives, must occur in the ancestor list of the class where the property is
declared. The delegate property must return an object whose class completely
implements the interface specified by the implements directive, and which does so
without method resolution clauses. For example,

10-6

Object Pascal Language Guide

Implementing interfaces

type
IMyInterface = interface
procedure P1;
procedure P2;
end;
TMyClass = class(TObject, IMyInterface)
FMyInterface: IMyInterface;
property MyInterface: IMyInterface read FMyInterface implements IMyInterface;
end;
var
MyClass: TMyClass;
MyInterface: IMyInterface;
begin
MyClass := TMyClass.Create;
MyClass.FMyInterface := ... // some object whose class implements IMyInterface
MyInterface := MyClass;
MyInterface.P1;
end;

Delegating to a class-type property

If the delegate property is of a class type, that class and its ancestors are searched for
methods implementing the specified interface before the enclosing class and its
ancestors are searched. Thus it is possible to implement some methods in the class
specified by the property, and others in the class where the property is declared.
Method resolution clauses can be used in the usual way to resolve ambiguities or
specify a particular method. An interface cannot be implemented by more than one
class-type property. For example,
type
IMyInterface = interface
procedure P1;
procedure P2;
end;
TMyImplClass = class
procedure P1;
procedure P2;
end;
TMyClass = class(TInterfacedObject, IMyInterface)
FMyImplClass: TMyImplClass;
property MyImplClass: TMyImplClass read FMyImplClass implements IMyInterface;
procedure IMyInterface.P1 = MyP1;
procedure MyP1;
end;
procedure TMyImplClass.P1;

procedure TMyImplClass.P2;

procedure TMyClass.MyP1;

var
MyClass: TMyClass;
MyInterface: IMyInterface;

Object interfaces

10-7

Interface references

begin
MyClass := TMyClass.Create;
MyClass.FMyImplClass := TMyImplClass.Create;
MyInterface := MyClass;
MyInterface.P1;
// calls TMyClass.MyP1;
MyInterface.P2;
// calls TImplClass.P2;
end;

Interface references
If you declare a variable of an interface type, the variable can reference instances of
any class that implements the interface. Such variables allow you to call interface
methods without knowing at compile time where the interface is implemented. But
they are subject to the following limitations.
An interface-type expression gives you access only to methods and properties
declared in the interface, not to other members of the implementing class.
An interface-type expression cannot reference an object whose class implements a
descendant interface, unless the class (or one that it inherits from) explicitly
implements the ancestor interface as well.
For example,
type
IAncestor = interface
end;
IDescendant = interface(IAncestor)
procedure P1;
end;
TSomething = class(TInterfacedObject, IDescendant)
procedure P1;
procedure P2;
end;

var
D: IDescendant;
A: IAncestor;
begin
D := TSomething.Create; // works!
A := TSomething.Create; // error
D.P1; // works!
D.P2; // error
end;

In this example,
A is declared as a variable of type IAncestor. Because TSomething does not list
IAncestor among the interfaces it implements, a TSomething instance cannot be
assigned to A. But if we changed TSomethings declaration to
TSomething = class(TInterfacedObject, IAncestor, IDescendant)

the first error would become a valid assignment.

10-8

Object Pascal Language Guide

Interface references

D is declared as a variable of type IDescendant. While D references an instance of

TSomething, we cannot use it to access TSomethings P2 method, since P2 is not a
method of IDescendant. But if we changed Ds declaration to
D: TSomething;

the second error would become a valid method call.

Interface references are managed through reference-counting, which depends on the
_AddRef and _Release methods inherited from IUnknown. When an object is
referenced only through interfaces, there is no need to destroy it manually; the object
is automatically destroyed when the last reference to it goes out of scope.
Global interface-type variables can be initialized only to nil.
To determine whether an interface-type expression references an object, pass it to the
standard function Assigned.

Interface assignment-compatibility
A class type is assignment-compatible with any interface type implemented by the
class. An interface type is assignment-compatible with any ancestor interface type.
The value nil can be assigned to any interface-type variable.
An interface-type expression can be assigned to a variant. If the interface is of type
IDispatch or a descendant, the variant receives the type code varDispatch. Otherwise,
the variant receives the type code varUnknown.
A variant whose type code is varEmpty, varUnknown, or varDispatch can be assigned
to an IUnknown variable. A variant whose type code is varEmpty or varDispatch can be
assigned to an IDispatch variable.

Interface typecasts
Interface types follow the same rules as class types in variable and value typecasts.
Class-type expressions can be cast to interface typesfor example,
IMyInterface(SomeObject)provided the class implements the interface.
An interface-type expression can be cast to Variant. If the interface is of type IDispatch
or a descendant, the resulting variant has the type code varDispatch. Otherwise, the
resulting variant has the type code varUnknown.
A variant whose type code is varEmpty, varUnknown, or varDispatch can be cast to
IUnknown. A variant whose type code is varEmpty or varDispatch can be cast to
IDispatch.

Interface querying
You can use the as operator to perform checked interface typecasts. This is known as
interface querying, and it yields an interface-type expression from an object reference

Object interfaces

10-9

Automation objects

or from another interface reference, based on the actual (runtime) type of the object.
An interface query has the form
object as interface
where object is an expression of an interface or variant type or denotes an instance of
a class that implements an interface, and interface is any interface declared with a
GUID.
An interface query returns nil if object is nil. Otherwise, it passes the GUID of interface
to the QueryInterface method in object, raising an exception unless QueryInterface
returns zero. If QueryInterface returns zero (indicating that objects class implements
interface), the interface query returns an interface reference to object.

Automation objects
An object whose class implements the IDispatch interface (declared in the System unit)
is an Automation object.

Dispatch interface types

Dispatch interface types define the methods and properties that an Automation
object implements through IDispatch. Calls to methods of a dispatch interface are
routed through IDispatchs Invoke method at runtime; a class cannot implement a
dispatch interface.
A dispatch interface type declaration has the form
type interfaceName = dispinterface
['{GUID}']
memberList
end;
where ['{GUID}'] is optional and memberList consists of property and method
declarations. Dispatch interface declarations are similar to regular interface
declarations, but they cannot specify an ancestor. For example,
type
IStringsDisp = dispinterface
['{EE05DFE2-5549-11D0-9EA9-0020AF3D82DA}']
property ControlDefault[Index: Integer]: OleVariant dispid 0; default;
function Count: Integer; dispid 1;
property Item[Index: Integer]: OleVariant dispid 2;
procedure Remove(Index: Integer); dispid 3;
procedure Clear; dispid 4;
function Add(Item: OleVariant): Integer; dispid 5;
function _NewEnum: IUnknown; dispid -4;
end;

10-10

Object Pascal Language Guide

Automation objects

Dispatch interface methods

Methods of a dispatch interface are prototypes for calls to the Invoke method of the
underlying IDispatch implementation. To specify an Automation dispatch ID for a
method, include the dispid directive in its declaration, followed by an integer
constant; specifying an already used ID causes an error.
A method declared in a dispatch interface cannot contain directives other than
dispid. Parameter and result types must be automatablethat is, they must be Byte,
Currency, Real, Double, Longint, Integer, Single, Smallint, AnsiString, WideString,
TDateTime, Variant, OleVariant, WordBool, or any interface type.

Dispatch interface properties

Properties of a dispatch interface do not include access specifiers. They can be
declared as readonly or writeonly. To specify a dispatch ID for a property, include
the dispid directive in its declaration, followed by an integer constant; specifying an
already used ID causes an error. Array properties can be declared as default. No
other directives are allowed in dispatch-interface property declarations.

Accessing Automation objects

Use variants to access Automation objects. When a variant references an Automation
object, you can call the objects methods and read or write to its properties through
the variant. To do this, you must include ComObj in the uses clause of one of your
units or your program or library.
Automation object method calls are bound at runtime and require no previous
method declarations. The validity of these calls is not checked at compile time.
The following example illustrates Automation method calls. The CreateOleObject
function (defined in ComObj) returns an IDispatch reference to an Automation object
and is assignment-compatible with the variant Word.
var
Word: Variant;
begin
Word := CreateOleObject('Word.Basic');
Word.FileNew('Normal');
Word.Insert('This is the first line'#13);
Word.Insert('This is the second line'#13);
Word.FileSaveAs('c:\temp\test.txt', 3);
end;

You can pass interface-type parameters to Automation methods.

Variant arrays with an element type of varByte are the preferred method of passing
binary data between Automation controllers and servers. Such arrays are subject to
no translation of their data, and can be efficiently accessed using the VarArrayLock
and VarArrayUnlock routines.

Object interfaces

10-11

Automation objects

Automation object method-call syntax

The syntax of an Automation object method call or property access is similar to that
of a normal method call or property access. Automation method calls, however, can
use both positional and named parameters. (But some Automation servers do not
support named parameters.)
A positional parameter is simply an expression. A named parameter consists of a
parameter identifier, followed by the := symbol, followed by an expression.
Positional parameters must precede any named parameters in a method call. Named
parameters can be specified in any order.
Some Automation servers allow you to omit parameters from a method call,
accepting their default values. For example,
Word.FileSaveAs('test.doc');
Word.FileSaveAs('test.doc', 6);
Word.FileSaveAs('test.doc',,,'secret');
Word.FileSaveAs('test.doc', Password := 'secret');
Word.FileSaveAs(Password := 'secret', Name := 'test.doc');

Automation method call parameters can be of integer, real, string, Boolean, and
variant types. A parameter is passed by reference if the parameter expression
consists only of a variable reference, and if the variable reference is of type Byte,
Smallint, Integer, Single, Double, Currency, TDateTime, AnsiString, WordBool, or Variant.
If the expression is not of one of these types, or if it is not just a variable, the
parameter is passed by value. Passing a parameter by reference to a method that
expects a value parameter causes COM to fetch the value from the reference
parameter. Passing a parameter by value to a method that expects a reference
parameter causes an error.

Dual interfaces
A dual interface is an interface that supports both compile-time binding and runtime
binding through Automation. Dual interfaces must descend from IDispatch.
All methods of a dual interface (except from those inherited from IUnknown and
IDispatch) must use the safecall convention, and all method parameter and result
types must be automatable. (The automatable types are Byte, Currency, Real, Double,
Real48, Integer, Single, Smallint, AnsiString, ShortString, TDateTime, Variant,
OleVariant, and WordBool.)

10-12

Object Pascal Language Guide

Chapter

11
Memory management

Chapter11

This chapter explains how programs use memory and describes the internal formats
of Object Pascal data types.

Delphis memory manager

The memory manager manages all dynamic memory allocations and deallocations in
a Delphi application. The New, Dispose, GetMem, ReallocMem, and FreeMem standard
procedures use the memory manager, and all objects and long strings are allocated
through the memory manager.
Delphis memory manager is optimized for applications that allocate large numbers
of small- to medium-sized blocks, as is typical for object-oriented applications and
applications that process string data. Other memory managers, such as the
implementations of GlobalAlloc, LocalAlloc, and private heap support in Windows,
typically do not perform well in such situations, and would slow down an
application if they were used directly.
To ensure the best performance, the memory manager interfaces directly with the
Win32 virtual memory API (the VirtualAlloc and VirtualFree functions). The memory
manager reserves memory from the operating system in 1-MB sections of address
space, and commits memory as required in 16-KB increments. It decommits and
releases unused memory in 16-KB and 1-MB sections. For smaller blocks, committed
memory is further suballocated.
Memory manager blocks are always rounded upward to a 4-byte boundary, and
always include a 4-byte header in which the size of the block and other status bits are
stored. This means that memory manager blocks are always double-word-aligned,
which guarantees optimal CPU performance when addressing the block.
The memory manager maintains two status variables, AllocMemCount and
AllocMemSize, which contain the number of currently allocated memory blocks and

Memory management

11-1

Internal data formats

the combined size of all currently allocated memory blocks. Applications can use
these variables to display status information for debugging.
The System unit provides two procedures, GetMemoryManager and
SetMemoryManager, that allow applications to intercept low-level memory manager
calls. The System unit also provides a function called GetHeapStatus that returns a
record containing detailed memory-manager status information. For further
information about these routines, see the online Help.

Variables
Global variables are allocated on the application data segment and persist for the
duration of the program. Local variables (declared within procedures and functions)
reside in an applications stack. Each time a procedure or function is called, it
allocates a set of local variables; on exit, the local variables are disposed of. Compiler
optimization may eliminate variables earlier.
An applications stack is defined by two values: the minimum stack size and the
maximum stack size. The values are controlled through the $MINSTACKSIZE and
$MAXSTACKSIZE compiler directives, and default to 16,384 (16K) and 1,048,576
(1M) respectively. An application is guaranteed to have the minimum stack size
available, and an applications stack is never allowed to grow larger than the
maximum stack size. If there is not enough memory available to satisfy an
applications minimum stack requirement, Windows will report an error upon
attempting to start the application.
If an application requires more stack space than specified by the minimum stack size,
additional memory is automatically allocated in 4K increments. If allocation of
additional stack space fails, either because more memory is not available or because
the total size of the stack would exceed the maximum stack size, an EStackOverflow
exception is raised. (Stack overflow checking is completely automatic. The $S
compiler directive, which originally controlled overflow checking, is maintained for
backward compatibility.)
Dynamic variables created with the GetMem or New procedure are heap-allocated
and persist until they are deallocated with FreeMem or Dispose.
Long strings, wide strings, dynamic arrays, variants, and interfaces are heapallocated, but their memory is managed automatically.

Internal data formats

The following sections describe the internal formats of Object Pascal data types.

Integer types
The format of an integer-type variable depends on its minimum and maximum
bounds.
If both bounds are within the range 128..127 (Shortint), the variable is stored as a
signed byte.

11-2

Object Pascal Language Guide

Internal data formats

If both bounds are within the range 0..255 (Byte), the variable is stored as an
unsigned byte.
If both bounds are within the range 32768..32767 (Smallint), the variable is stored
as a signed word.
If both bounds are within the range 0..65535 (Word), the variable is stored as an
unsigned word.
If both bounds are within the range 2147483648..2147483647 (Longint), the
variable is stored as a signed double word.
If both bounds are within the range 0..4294967295 (Longword), the variable is
stored as an unsigned double word.
Otherwise, the variable is stored as a signed quadruple word (Int64).

Character types
A Char, an AnsiChar, or a subrange of a Char type is stored as an unsigned byte. A
WideChar is stored as an unsigned word.

Boolean types
A Boolean type is stored as a Byte, a ByteBool is stored as a Byte, a WordBool type is
stored as a Word, and a LongBool is stored as a Longint.
A Boolean can assume the values 0 (False) and 1 (True). ByteBool, WordBool, and
LongBool types can assume the values 0 (False) or nonzero (True).

Enumerated types
An enumerated type is stored as an unsigned byte if the enumeration has no more
than 256 values and the type was declared in the {$Z1} state (the default). If an
enumerated type has more than 256 values, or if the type was declared in the {$Z2}
state, it is stored as an unsigned word. If an enumerated type is declared in the {$Z4}
state, it is stored as an unsigned double-word.

Real types
The real types store the binary representation of a sign (+ or ), an exponent, and a
significand. A real value has the form
+/ significand * 2exponent
where the significand has a single bit to the left of the binary decimal point. (That is,
0 <= significand < 2.)
In the figures that follow, the most significant bit is always on the left and the least
significant bit on the right. The numbers at the top indicate the width (in bits) of each

Memory management

11-3

Internal data formats

field, with the leftmost items stored at the highest addresses. For example, for a
Real48 value, e is stored in the first byte, f in the following five bytes, and s in the most
significant bit of the last byte.

The Real48 type

A 6-byte (48-bit) Real48 number is divided into three fields:
1

If 0 < e <= 255, the value v of the number is given by

v = (1)s * 2(e129) * (1.f)
If e = 0, then v = 0.
The Real48 type cant store denormals, NaNs, and infinities. Denormals become zero
when stored in a Real48, while NaNs and infinities produce an overflow error if an
attempt is made to store them in a Real48.

The Single type

A 4-byte (32-bit) Single number is divided into three fields:
1

The value v of the number is given by

if 0 < e < 255, then v = (1)s * 2(e127) * (1.f)
if e = 0 and f <> 0, then v = (1)s * 2(126) * (0.f)
if e = 0 and f = 0, then v = (1)s * 0
if e = 255 and f = 0, then v = (1)s * Inf
if e = 255 and f <> 0, then v is a NaN

The Double type

An 8-byte (64-bit) Double number is divided into three fields:
1

The value v of the number is given by

if 0 < e < 2047, then v = (1)s * 2(e1023) * (1.f)
if e = 0 and f <> 0, then v = (1)s * 2(1022) * (0.f)
if e = 0 and f = 0, then v = (1)s * 0
if e = 2047 and f = 0, then v = (1)s * Inf
if e = 2047 and f <> 0, then v is a NaN

11-4

Object Pascal Language Guide

Internal data formats

The Extended type

A 10-byte (80-bit) Extended number is divided into four fields:
1

The value v of the number is given by

if 0 <= e < 32767, then v = (1)s * 2(e16383) * (i.f)
if e = 32767 and f = 0, then v = (1)s * Inf
if e = 32767 and f <> 0, then v is a NaN

The Comp type

An 8-byte (64-bit) Comp number is stored as a signed 64-bit integer.

The Currency type

An 8-byte (64-bit) Currency number is stored as a scaled and signed 64-bit integer
with the four least-significant digits implicitly representing four decimal places.

Pointer types
A Pointer type is stored in 4 bytes as a 32-bit address. The pointer value nil is stored
as zero.

Short string types

A string occupies as many bytes as its maximum length plus one. The first byte
contains the current dynamic length of the string, and the following bytes contain the
characters of the string.
The length byte and the characters are considered unsigned values. Maximum string
length is 255 characters plus a length byte (string[255]).

Long string types

A long string variable occupies four bytes of memory which contain a pointer to a
dynamically allocated string. When a long string variable is empty (contains a zerolength string), the string pointer is nil and no dynamic memory is associated with the
string variable. For a nonempty string value, the string pointer points to a
dynamically allocated block of memory that contains the string value in addition to a
32-bit length indicator and a 32-bit reference count. The table below shows the layout
of a long-string memory block.
Table 11.1

Long string dynamic memory layout

Offset

Contents

32-bit reference-count

32-bit length indicator

Memory management

11-5

Internal data formats

Table 11.1

Long string dynamic memory layout (continued)

Offset

Contents

0..Length 1

character string

Length

NULL character

The NULL character at the end of a long string memory block is automatically
maintained by the compiler and the built-in string handling routines. This makes it
possible to typecast a long string directly to a null-terminated string.
For string constants and literals, the compiler generates a memory block with the same
layout as a dynamically allocated string, but with a reference count of 1. When a long
string variable is assigned a string constant, the string pointer is assigned the address of
the memory block generated for the string constant. The built-in string handling
routines know not to attempt to modify blocks that have a reference count of 1.

Wide string types

A wide string variable occupies four bytes of memory which contain a pointer to a
dynamically allocated string. When a wide string variable is empty (contains a zerolength string), the string pointer is nil and no dynamic memory is associated with the
string variable. For a nonempty string value, the string pointer points to a dynamically
allocated block of memory that contains the string value in addition to a 32-bit length
indicator. The table below shows the layout of a wide-string memory block.
Table 11.2

Wide string dynamic memory layout

Offset

Contents

32-bit length indicator (in bytes)

0..Length 1

character string

Length

NULL character

The string length is the number of bytes, so it is twice the number of wide characters
contained in the string.
The NULL character at the end of a wide string memory block is automatically
maintained by the compiler and the built-in string handling routines. This makes it
possible to typecast a wide string directly to a null-terminated string.

Set types
A set is a bit array where each bit indicates whether an element is in the set or not.
The maximum number of elements in a set is 256, so a set never occupies more than
32 bytes. The number of bytes occupied by a particular set is equal to
(Max div 8) (Min div 8) + 1
where Max and Min are the upper and lower bounds of the base type of the set. The
byte number of a specific element E is
(E div 8) (Min div 8)

11-6

Object Pascal Language Guide

Internal data formats

and the bit number within that byte is

E mod 8
where E denotes the ordinal value of the element.

Static array types

A static array is stored as a contiguous sequence of variables of the component type
of the array. The components with the lowest indexes are stored at the lowest
memory addresses. A multidimensional array is stored with the rightmost
dimension increasing first.

Dynamic array types

A dynamic-array variable occupies four bytes of memory which contain a pointer to
the dynamically allocated array. When the variable is empty (uninitialized) or holds
a zero-length array, the pointer is nil and no dynamic memory is associated with the
variable. For a nonempty array, the variable points to a dynamically allocated block
of memory that contains the array in addition to a 32-bit length indicator and a 32-bit
reference count. The table below shows the layout of a dynamic-array memory block.
Table 11.3

Dynamic array memory layout

Offset

Contents

32-bit reference-count

32-bit length indicator (number of elements)

0..Length * (size of element) 1

array elements

Record types
When a record type is declared in the {$A+} state (the default), and when the
declaration does not include a packed modifier, the type is an unpacked record type, and
the fields of the record are aligned for efficient access by the CPU. The alignment is
controlled by the type of each field. Every data type has an inherent alignment, which
is automatically computed by the compiler. The alignment can be 1, 2, 4, or 8, and
represents the byte boundary that a value of the type must be stored on to provide the
most efficient access. The table below lists the alignments for all data types.
Table 11.4

Type alignment masks

Type

Alignment

Ordinal types

size of the type (1, 2, 4, or 8)

Real types

2 for Real48 and Extended, 4 for all other real types

Short string types

Array types

same as the element type of the array.

Record types

the largest alignment of the fields in the record

Memory management

11-7

Internal data formats

Table 11.4

Type alignment masks (continued)

Type

Alignment

Set types

size of the type if 1, 2, or 4, otherwise 1

All other types

To ensure proper alignment of the fields in an unpacked record type, the compiler
inserts an unused byte before fields with an alignment of 2, and up to three unused
bytes before fields with an alignment of 4, if required. Finally, the compiler rounds
the total size of the record upward to the byte boundary specified by the largest
alignment of any of the fields.
When a record type is declared in the {$A} state, or when the declaration includes
the packed modifier, the fields of the record are not aligned, but are instead assigned
consecutive offsets. The total size of such a packed record is simply the size of all the
fields.

File types
File types are represented as records. Typed files and untyped files occupy 332 bytes,
which are laid out as follows:
type
TFileRec = record
Handle: Integer;
Mode: Integer;
RecSize: Cardinal;
Private: array[1..28] of Byte;
UserData: array[1..32] of Byte;
Name: array[0..259] of Char;
end;

Text files occupy 460 bytes, which are laid out as follows:
type
TTextBuf = array[0..127] of Char;
TTextRec = record
Handle: Integer;
Mode: Integer;
BufSize: Cardinal;
BufPos: Cardinal;
BufEnd: Cardinal;
BufPtr: PChar;
OpenFunc: Pointer;
InOutFunc: Pointer;
FlushFunc: Pointer;
CloseFunc: Pointer;
UserData: array[1..32] of Byte;
Name: array[0..259] of Char;
Buffer: TTextBuf;
end;

Handle contains the files handle (when the file is open).

11-8

Object Pascal Language Guide

Internal data formats

The Mode field can assume one of the values

const
fmClosed
fmInput
fmOutput
fmInOut

=
=
=
=

$D7B0;
$D7B1;
$D7B2;
$D7B3;

where fmClosed indicates that the file is closed, fmInput and fmOutput indicate that the
file is a text file that has been reset (fmInput) or rewritten (fmOutput), and fmInOut
indicates that the file variable is a typed or an untyped file that has been reset or
rewritten. Any other value indicates that the file variable is not assigned (and hence
not initialized).
The UserData field is available for user-written routines to store data in.
Name contains the file name, which is a sequence of characters terminated by a null
character (#0).
For typed files and untyped files, RecSize contains the record length in bytes, and the
Private field is unused but reserved.
For text files, BufPtr is a pointer to a buffer of BufSize bytes, BufPos is the index of the
next character in the buffer to read or write, and BufEnd is a count of valid characters
in the buffer. OpenFunc, InOutFunc, FlushFunc, and CloseFunc are pointers to the I/O
routines that control the file; see Device functions on page 8-5.

Procedural types
A procedure pointer is stored as a 32-bit pointer to the entry point of a procedure or
function. A method pointer is stored as a 32-bit pointer to the entry point of a
method, followed by a 32-bit pointer to an object.

Class types
A class-type value is stored as a 32-bit pointer to an instance of the class, which is
called an object. The internal data format of an object resembles that of a record. The
objects fields are stored in order of declaration as a sequence of contiguous variables.
Fields are always aligned, corresponding to an unpacked record type. Any fields
inherited from an ancestor class are stored before the new fields defined in the
descendant class.
The first 4-byte field of every object is a pointer to the virtual method table (VMT) of the
class. There is exactly one VMT per class (not one per object); distinct class types, no
matter how similar, never share a VMT. VMTs are built automatically by the
compiler, and are never directly manipulated by a program. Pointers to VMTs, which
are automatically stored by constructor methods in the objects they create, are also
never directly manipulated by a program.
The layout of a VMT is shown in the following table. At positive offsets, a VMT
consists of a list of 32-bit method pointersone per user-defined virtual method in
the class typein order of declaration. Each slot contains the address of the

Memory management

11-9

Internal data formats

corresponding virtual methods entry point. This layout is compatible with a C++ vtable and with COM. At negative offsets, a VMT contains a number of fields that are
internal to Object Pascals implementation. Applications should use the methods
defined in TObject to query this information, since the layout is likely to change in
future implementations of Object Pascal.
Table 11.5

Virtual method table layout

Offset

Type

Description

Pointer

pointer to virtual method table (or nil)

Pointer

pointer to interface table (or nil)

Pointer

pointer to Automation information table (or nil)

Pointer

pointer to instance initialization table (or nil)

Pointer

pointer to type information table (or nil)

Pointer

pointer to field definition table (or nil)

Pointer

pointer to method definition table (or nil)

Pointer

pointer to dynamic method table (or nil)

Pointer

pointer to short string containing class name

Cardinal

instance size in bytes

Pointer

pointer to a pointer to ancestor class (or nil)

Pointer

pointer to entry point of SafecallException method (or nil)

Pointer

entry point of AfterConstruction method

Pointer

entry point of BeforeDestruction method

Pointer

entry point of Dispatch method

Pointer

entry point of DefaultHandler method

Pointer

entry point of NewInstance method

Pointer

entry point of FreeInstance method

Pointer

entry point of Destroy destructor

Pointer

entry point of first user-defined virtual method

Pointer

entry point of second user-defined virtual method

Class reference types

A class-reference value is stored as a 32-bit pointer to the virtual method table (VMT)
of a class.

Variant types
A variant is stored as a 16-byte record that contains a type code and a value (or a
reference to a value) of the type given by the code. The System unit defines constants
and types for variants.

11-10

Object Pascal Language Guide

Internal data formats

The TVarData type represents the internal structure of a Variant variable, which is
identical to the Variant type used by COM and the Win32 API. The TVarData type can
be used in typecasts of Variant variables to access the internal structure of a variable.
The VType field of a TVarData record contains the type code of the variant in the
lower twelve bits (the bits defined by the varTypeMask constant). In addition, the
varArray bit may be set to indicate that the variant is an array, and the varByRef bit
may be set to indicate that the variant contains a reference as opposed to a value.
The Reserved1, Reserved2, and Reserved3 fields of a TVarData record are unused.
The contents of the remaining eight bytes of a TVarData record depend on the VType
field. If neither the varArray nor the varByRef bits are set, the variant contains a value
of the given type.
If the varArray bit is set, the variant contains a pointer to a TVarArray structure that
defines an array. The type of each array element is given by the varTypeMask bits in
the VType field.
If the varByRef bit is set, the variant contains a reference to a value of the type given
by the varTypeMask and varArray bits in the VType field.
The varString type code is private to Delphi. Variants containing a varString value
should never be passed to a non-Delphi function. Delphis Automation support
automatically converts varString variants to varOleStr variants before passing them as
parameters to external functions.

Memory management

11-11

11-12

Object Pascal Language Guide

Chapter

12
Program control

Chapter12

This chapter explains how parameters and function results are stored and
transferred. The final section discusses exit procedures.

Parameters and function results

Treatment of parameters and function results is determined by several factors,
including calling conventions, parameter semantics, and the type and size of the
value being passed.

Parameter passing
Parameters are transferred to procedures and functions via CPU registers or the
stack, depending on the routines calling convention. For information about calling
conventions, see Calling conventions on page 6-4.
Variable (var) parameters are always passed by reference, as 32-bit pointers that
point to the actual storage location.
Value and constant (const) parameters are passed by value or by reference,
depending on the type and size of the parameter:
An ordinal parameter is passed as an 8-bit, 16-bit, 32-bit, or 64-bit value, using the
same format as a variable of the corresponding type.
A real parameter is always passed on the stack. A Single parameter occupies 4
bytes, and a Double, Comp, or Currency parameter occupies 8 bytes. A Real48
occupies 8 bytes, with the Real48 value stored in the lower 6 bytes. An Extended
occupies 12 bytes, with the Extended value stored in the lower 10 bytes.
A short-string parameter is passed as a 32-bit pointer to a short string.

Program control

12-1

Parameters and function results

A long-string or dynamic-array parameter is passed as a 32-bit pointer to the

dynamic memory block allocated for the long string. The value nil is passed for an
empty long string.
A pointer, class, class-reference, or procedure-pointer parameter is passed as a 32bit pointer.
A method pointer is passed on the stack as two 32-bit pointers. The instance
pointer is pushed before the method pointer so that the method pointer occupies
the lowest address.
Under the register and pascal conventions, a Variant parameter is passed as a 32bit pointer to a Variant value.
Sets, records, and static arrays of 1, 2, or 4 bytes are passed as 8-bit, 16-bit, and 32bit values. Larger sets, records, and static arrays are passed as 32-bit pointers to
the value. An exception to this rule is that records are always passed directly on
the stack under the cdecl, stdcall, and safecall conventions; the size of a record
passed this way is rounded upward to the nearest double-word boundary.
An open-array parameter is passed as two 32-bit values. The first value is a pointer
to the array data, and the second value is one less than the number of elements in
the array.
When two parameters are passed on the stack, each parameter occupies a multiple of
4 bytes (a whole number of double words). For an 8-bit or 16-bit parameter, even
though the parameter occupies only a byte or a word, it is passed as a double word.
The contents of the unused parts of the double word are undefined.
Under the pascal, cdecl, stdcall and safecall conventions, all parameters are passed
on the stack. Under the pascal convention, parameters are pushed in the order of
their declaration (left-to-right), so that the first parameter ends up at the highest
address and the last parameter ends up at the lowest address. Under the cdecl,
stdcall, and safecall conventions, parameters are pushed in reverse order of
declaration (right-to-left), so that the first parameter ends up at the lowest address
and the last parameter ends up at the highest address.
Under the register convention, up to three parameters are passed in CPU registers,
and the rest (if any) are passed on the stack. The parameters are passed in order of
declaration (as with the pascal convention), and the first three parameters that
qualify are passed in the EAX, EDX, and ECX registers, in that order. Real and
method-pointer types do not qualify as register parameters, but all other parameters
do. If more than three parameters qualify as register parameters, the first three are
passed in EAX, EDX, and ECX, and the remaining parameters are pushed onto the
stack in order of declaration. For example, given the declaration
procedure Test(A: Integer; var B: Char; C: Double; const D: string; E: Pointer);

a call to Test passes A in EAX as a 32-bit integer, B in EDX as a pointer to a Char, and
D in ECX as a pointer to a long-string memory block; C and E are pushed onto the
stack as two double-words and a 32-bit pointer, in that order.

12-2

Object Pascal Language Guide

Parameters and function results

Register saving conventions

Procedures and functions must preserve the EBX, ESI, EDI, and EBP registers, but
can modify the EAX, EDX, and ECX registers. When implementing a constructor or
destructor in assembler, be sure to preserve the DL register. Procedures and
functions are invoked with the assumption that the CPUs direction flag is cleared
(corresponding to a CLD instruction) and must return with the direction flag cleared.

Function results
The following conventions are used for returning function result values.
Ordinal results are returned in a CPU register. Bytes are returned in AL, words are
returned in AX, and double-words are returned in EAX.
Real results are returned in the floating-point coprocessors top-of-stack register
(ST(0)). For function results of type Currency, the value in ST(0) is scaled by 10000.
For example, the Currency value 1.234 is returned in ST(0) as 12340.
For a string, dynamic array, method pointer, or Variant result, the effects are the
same as if the function result were declared as an additional var parameter
following the declared parameters. In other words, the caller passes an additional
32-bit pointer that points to a variable in which to return the function result.
Pointer, class, class-reference, and procedure-pointer results are returned in EAX.
For static-array, record, and set results, if the value occupies one byte it is returned
in AL; if the value occupies two bytes it is returned in AX; and if the value
occupies four bytes it is returned in EAX. Otherwise, the result is returned in an
additional var parameter that is passed to the function after the declared
parameters.

Method calls
Methods use the same calling conventions as ordinary procedures and functions,
except that every method has an additional implicit parameter Self, which is a
reference to the instance or class in which the method is called. The Self parameter is
passed as a 32-bit pointer.
Under the register convention, Self behaves as if it were declared before all other
parameters. It is therefore always passed in the EAX register.
Under the pascal convention, Self behaves as if it were declared after all other
parameters (including the additional var parameter sometimes passed for a
function result). It is therefore pushed last, ending up at a lower address than all
other parameters.
Under the cdecl, stdcall, and safecall conventions, Self behaves as if it were
declared before all other parameters, but after the additional var parameter (if any)
passed for a function result. It is therefore the last to be pushed, except for the
additional var parameter.

Program control

12-3

Exit procedures

Constructors and destructors

Constructors and destructors use the same calling conventions as other methods,
except that an additional Boolean flag parameter is passed to indicate the context of
the constructor or destructor call.
A value of False in the flag parameter of a constructor call indicates that the
constructor was invoked through an instance object or using the inherited keyword.
In this case, the constructor behaves like an ordinary method. A value of True in the
flag parameter of a constructor call indicates that the constructor was invoked
through a class reference. In this case, the constructor creates an instance of the class
given by Self, and returns a reference to the newly created object in EAX.
A value of False in the flag parameter of a destructor call indicates that the destructor
was invoked using the inherited keyword. In this case, the destructor behaves like an
ordinary method. A value of True in the flag parameter of a destructor call indicates
that the destructor was invoked through an instance object. In this case, the
destructor deallocates the instance given by Self just before returning.
The flag parameter behaves as if it were declared before all other parameters. Under
the register convention, it is passed in the DL register. Under the pascal convention,
it is pushed before all other parameters. Under the cdecl, stdcall, and safecall
conventions, it is pushed just before the Self parameter.
Since the DL register indicates whether the constructor or destructor is the outermost
in the call stack, you must restore the value of DL before exiting so that
BeforeDestruction or AfterConstruction can be called properly.

Exit procedures
Exit procedures ensure that specific actionssuch as updating and closing filesare
carried out before a program terminates. The ExitProc pointer variable allows you to
install an exit procedure, so that it is always called as part of the programs
terminationwhether the termination is normal, forced by a call to Halt, or the result
of a runtime error. An exit procedure takes no parameters.
Note

It is recommended that finalization sections, rather than exit procedures, be used for
all exit behavior. (See The finalization section on page 3-5.) Exit procedures are
available only for .EXE or .DLL targets; for packages, exit behavior must be
implemented in a finalization section. All exit procedures are called before execution
of finalization sections.
Units as well as programs can install exit procedures. A unit can install an exit
procedure as part of its initialization code, relying on the procedure to close files or
perform other clean-up tasks.
When implemented properly, an exit procedure is part of a chain of exit procedures.
The procedures are executed in reverse order of installation, ensuring that the exit
code of one unit isnt executed before the exit code of any units that depend on it. To
keep the chain intact, you must save the current contents of ExitProc before pointing
it to the address of your own exit procedure. Also, the first statement in your exit
procedure must reinstall the saved value of ExitProc.

12-4

Object Pascal Language Guide

Exit procedures

The following code shows a skeleton implementation of an exit procedure.

var
ExitSave: Pointer;
procedure MyExit;
begin
ExitProc := ExitSave; // always restore old vector first

end;
begin
ExitSave := ExitProc;
ExitProc := @MyExit;

end.

On entry, the code saves the contents of ExitProc in ExitSave, then installs the MyExit
procedure. When called as part of the termination process, the first thing MyExit does
is reinstall the previous exit procedure.
The termination routine in the runtime library keeps calling exit procedures until
ExitProc becomes nil. To avoid infinite loops, ExitProc is set to nil before every call, so
the next exit procedure is called only if the current exit procedure assigns an address
to ExitProc. If an error occurs in an exit procedure, it is not called again.
An exit procedure can learn the cause of termination by examining the ExitCode
integer variable and the ErrorAddr pointer variable. In case of normal termination,
ExitCode is zero and ErrorAddr is nil. In case of termination through a call to Halt,
ExitCode contains the value passed to Halt and ErrorAddr is nil. In case of termination
due to a runtime error, ExitCode contains the error code and ErrorAddr contains the
address of the invalid statement.
The last exit procedure (the one installed by the runtime library) closes the Input and
Output files. If ErrorAddr is not nil, it outputs a runtime error message. To output
your own runtime error message, install an exit procedure that examines ErrorAddr
and outputs a message if its not nil; before returning, set ErrorAddr to nil so that the
error is not reported again by other exit procedures.
Once the runtime library has called all exit procedures, it returns to Windows,
passing the value stored in ExitCode as a return code.

Program control

12-5

12-6

Object Pascal Language Guide

Chapter

13
Inline assembler code

Chapter13

The built-in assembler allows you to write Intel assembler code within Object Pascal
programs. It implements a large subset of the syntax supported by Turbo Assembler
and Microsofts Macro Assembler, including all 8086/8087 and 80386/80387 opcodes
and all but a few of Turbo Assemblers expression operators. Moreover, the built-in
assembler allows you to use Object Pascal identifiers in assembler statements.
Except for DB, DW, and DD (define byte, word, and double word), none of Turbo
Assemblers directives (such as EQU, PROC, STRUC, SEGMENT, and MACRO) are
supported by the built-in assembler. Operations implemented through Turbo
Assembler directives, however, are largely matched by corresponding Object Pascal
constructions. For example, most EQU directives correspond to constant, variable,
and type declarations; the PROC directive corresponds to procedure and function
declarations; and the STRUC directive corresponds to record types.
As an alternative to the built-in assembler, you can link to .OBJ files that contain
external procedures and functions. See Linking to .OBJ files on page 6-6 for more
information.

The asm statement

The built-in assembler is accessed through asm statements, which have the form
asm statementList end
where statementList is a sequence of assembler statements separated by semicolons,
end-of-line characters, or Object Pascal comments.
Comments in an asm statement must be in Object Pascal style. A semicolon does not
indicate that the rest of the line is a comment.
The reserved word inline and the directive assembler are maintained for backward
compatibility only. They have no effect on the compiler.

Inline assembler code

13-1

Assembler statement syntax

Register use
In general, the rules of register use in an asm statement are the same as those of an
external procedure or function. An asm statement must preserve the EDI, ESI, ESP,
EBP, and EBX registers, but can freely modify the EAX, ECX, and EDX registers. On
entry to an asm statement, BP points to the current stack frame, SP points to the top
of the stack, SS contains the segment address of the stack segment, and DS contains
the segment address of the data segment. Except for EDI, ESI, ESP, EBP, and EBX, an
asm statement can assume nothing about register contents on entry to the statement.

Assembler statement syntax

This syntax of an assembler statement is
Label: Prefix Opcode Operand1, Operand2
where Label is a label, Prefix is an assembler prefix opcode (operation code), Opcode is
an assembler instruction opcode or directive, and Operand is an assembler
expression. Label and Prefix are optional. Some opcodes take only one operand, and
some take none.
Comments are allowed between assembler statements, but not within them. For
example,
MOV AX,1 {Initial value}
MOV CX,100 {Count}

{ OK }
{ OK }

MOV {Initial value} AX,1;

MOV CX, {Count} 100

{ Error! }
{ Error! }

Labels
Labels are used in built-in assembler statements as they are in Object Pascalby
writing the label and a colon before a statement. There is no limit to a labels length,
but only the first 32 characters are significant. As in Object Pascal, labels must be
declared in a label declaration part in the block containing the asm statement. There
is one exception to this rule: local labels.
Local labels are labels that start with an at-sign (@). They consist of an at-sign
followed by one or more letters, digits, underscores, or at-signs. Use of local labels is
restricted to asm statements, and the scope of a local label extends from the asm
reserved word to the end of the asm statement that contains it. A local label doesnt
have to be declared.

13-2

Object Pascal Language Guide

Assembler statement syntax

Instruction opcodes
The built-in assembler supports the following opcodes.
LOCK

REP

REPE

REPZ

REPNE

REPNZ

SEGES

SEGCS

SEGSS

SEGDS

SEGFS

SEGGS

ADC,mLeft

ADD,mLeft

AND,mLeft

AAA,mAX

AAS,mAX

AAD,mAX

AAM,mAX

BOUND,
mNONE

BSF,mLeft

BSR,mLeft

BTC,mLeft

BTR,mLeft

BTS,mLeft

CALL,mNONE

CMP

CBW,mAX

CWDE,mAX

CWD,
<mAX,mDX>

CDQ,
<mAX,mDX>

CLC

CLD

CLI

CMC

CMPSB,
<mSIDI>

CMPSW,
<mSIDI>

CMPSD,
<mSIDI>

DAA,mAX

DAS,mAX

DEC,mLeft

DIV,mLeft

ENTER,
mNONE

HLT

IDIV,mLeft

IMUL,mLeft

IN,mLeft

INC,mLeft

INSB,mDI

INSW,mDI

INSD,mDI

INT

INTO

IRET

IRETD

JMP

JNO

JNAE

JNC

JAE

JNB

JNE

JNZ

JBE

JNA

JNBE

JNS

JPE

JNP

JPO

JNGE

JGE

JNL

JLE

JNG

JNLE

JCXZ

JECXZ

LAHF,mAX

LEA,mLeft

LEAVE,
mNONE

LDS,mSpecial

LES,mSpecial

LFS,mSpecial

LGS,mSpecial

LSS,mSpecial

LODSB,
<mAX,mDI>

LODSW,
<mAX,mDI>

LODSD,
<mAX,mDI>

LOOP,mCX

LOOPE,mCX

LOOPZ,mCX

LOOPNE,mCX

LOOPNZ,mCX

LOOPD,mCX

LOOPDE,mCX

LOOPDZ,mCX

LOOPDNE,
mCX

LOOPDNZ,
mCX

MOV,mLeft

MOVSX,mLeft

MOVZX,mLeft

MOVSB,
<mSIDI>

MOVSW,
<mSIDI>

MOVSD,
<mSIDI>

MUL,mLeft

NEG,mLeft

NOP

NOT,mLeft

OR,mLeft

OUT

OUTSB,mSI

OUTSW,mSI

OUTSD,mSI

POP,mLeft

POPF

POPA,mSpecial

POPAD,
mSpecial

POPFD,
mSpecial

PUSH

PUSHF

PUSHA

PUSHAD

PUSHFD

RET

RETN

RETF

SUB,mLeft

SBB,mLeft

RCL,mLeft

RCR,mLeft

ROL,mLeft

ROR,mLeft

SAL,mLeft

SHL,mLeft

SAR,mLeft

SHR,mLeft

SHLD,mLeft

SHRD,mLeft

SAHF

SCASB,mDI

SCASW,mDI

SCASD,mDI

STC

Inline assembler code

13-3

Assembler statement syntax

STD

STI

STOSB,mDI

STOSW,mDI

STOSD,mDI

TEST

WAIT

XCHG,<mLeft,
mRight>

XLAT,mAX

XOR,mLeft

SETA,mLeft

SETAE,mLeft

SETB,mLeft

SETBE,mLeft

SETC,mLeft

SETE,mLeft

SETG,mLeft

SETGE,mLeft

SETL,mLeft

SETLE,mLeft

SETNA,mLeft

SETNAE,mLeft

SETNB,mLeft

SETNBE,mLeft

SETNC,mLeft

SETNE,mLeft

SETNG,mLeft

SETNGE,mLeft

SETNL,mLeft

SETNLE,mLeft

SETNO,mLeft

SETNP,mLeft

SETNS,mLeft

SETNZ,mLeft

SETO,mLeft

SETP,mLeft

SETPE,mLeft

SETPO,mLeft

SETS,mLeft

SETZ,mLeft

ARPL

LAR,mLeft

CLTS

LGDT

SGDT

LIDT

SIDT

LLDT

SLDT

LMSW

SMSW

LSL,mLeft

LTR,mLeft

STR,mLeft

VERR

VERW

BSWAP,mLeft

XADD,mLeft

CMPXCHG,
<mLeft,mAX>

INVD

WBINVD

INVLPG

FLD,m87

FILD,m87

FST,m87

FSTP,m87

FIST,m87

FISTP,m87

FADD,m87

FADDP,m87

FIADD,m87

FSUB,m87

FSUBP,m87

FSUBR,m87

FSUBRP,m87

FISUB,m87

FISUBR,m87

FMUL,m87

FMULP,m87

FIMUL,m87

FDIV,m87

FDIVP,m87

FDIVR,m87

FDIVRP,m87

FIDIV,m87

FIDIVR,m87

FCOM,m87

FCOMP,m87

FCOMPP,m87

FICOM,m87

FICOMP,m87

F2XM1,m87

FABS,m87

FBLD,m87

FBSTP,m87

FCHS,m87

FDECSTP,m87

FFREE,m87

FINCSTP,m87

FLD1,m87

FLDCW,m87

FLDENV,m87

FLDL2E,m87

FLDL2T,m87

FLDLG2,m87

FLDLN2,m87

FLDPI,m87

FLDZ,m87

FNOP,m87

FPREM,m87

FPATAN,m87

FPTAN,m87

FRNDINT,m87

FRSTOR,m87

FSCALE,m87

FSETPM,m87

FSQRT,m87

FTST,m87

FWAIT,m87

FXAM,m87

FXCH,m87

FXTRACT,m87

FYL2X,m87

FYL2XP1,m87

FCLEX,m87

FNCLEX,m87

FDISI,m87

FNDISI,m87

FENI,m87

FNENI,m87

FINIT,m87

FNINIT,m87

FSAVE,m87

FNSAVE,m87

FSTCW,m87

FNSTCW,m87

FSTENV,m87

FNSTENV,m87

FSTSW,m87

FNSTSW,m87

FUCOM,m87

FUCOMP,m87

FUCOMPP,m87

FPREM1,m87

FCOS,m87

FSIN,m87

FSINCOS,m87

For a complete description of each instruction, refer to your microprocessor

documentation.

RET instruction sizing

The RET instruction opcode always generates a near return.

Automatic jump sizing

Unless otherwise directed, the built-in assembler optimizes jump instructions by
automatically selecting the shortest, and therefore most efficient, form of a jump
instruction. This automatic jump sizing applies to the unconditional jump instruction

13-4

Object Pascal Language Guide

Assembler statement syntax

(JMP), and to all conditional jump instructions when the target is a label (not a
procedure or function).
For an unconditional jump instruction (JMP), the built-in assembler generates a short
jump (one-byte opcode followed by a one-byte displacement) if the distance to the
target label is 128 to 127 bytes. Otherwise it generates a near jump (one-byte opcode
followed by a two-byte displacement).
For a conditional jump instruction, a short jump (one-byte opcode followed by a onebyte displacement) is generated if the distance to the target label is 128 to 127 bytes.
Otherwise, the built-in assembler generates a short jump with the inverse condition,
which jumps over a near jump to the target label (five bytes in total). For example, the
assembler statement
JC

Stop

where Stop isnt within reach of a short jump, is converted to a machine code
sequence that corresponds to this:
JNC
JMP
Skip:

Skip
Stop

Jumps to the entry points of procedures and functions are always near.

Assembler directives
The built-in assembler supports three assembler directives: DB (define byte), DW
(define word), and DD (define double word). Each generates data corresponding to
the comma-separated operands that follow the directive.
The DB directive generates a sequence of bytes. Each operand can be a constant
expression with a value between 128 and 255, or a character string of any length.
Constant expressions generate one byte of code, and strings generate a sequence of
bytes with values corresponding to the ASCII code of each character.
The DW directive generates a sequence of words. Each operand can be a constant
expression with a value between 32,768 and 65,535, or an address expression. For an
address expression, the built-in assembler generates a near pointerthat is, a word
that contains the offset part of the address.
The DD directive generates a sequence of double words. Each operand can be a
constant expression with a value between 2,147,483,648 and 4,294,967,295, or an
address expression. For an address expression, the built-in assembler generates a far
pointerthat is, a word that contains the offset part of the address, followed by a
word that contains the segment part of the address.
The data generated by the DB, DW, and DD directives is always stored in the code
segment, just like the code generated by other built-in assembler statements. To
generate uninitialized or initialized data in the data segment, you should use Object
Pascal var or const declarations.

Inline assembler code

13-5

Assembler statement syntax

Some examples of DB, DW, and DD directives follow.

asm
DB
DB
DB
DB
DB
DW
DW
DW
DW
DW
DW
DD
DD
DD
DD
DD
DD
end;

0FFH
0,99
'A'
'Hello world...',0DH,0AH
12,"Delphi"
0FFFFH
0,9999
'A'
'BA'
MyVar
MyProc
0FFFFFFFFH
0,999999999
'A'
'DCBA'
MyVar
MyProc

{
{
{
{
{
{
{
{
{
{
{
{
{
{
{
{
{

One byte }
Two bytes }
Ord('A') }
String followed by CR/LF }
Object Pascal style string }
One word }
Two words }
Same as DB 'A',0 }
Same as DB 'A','B' }
Offset of MyVar }
Offset of MyProc }
One double-word }
Two double-words }
Same as DB 'A',0,0,0 }
Same as DB 'A','B','C','D' }
Pointer to MyVar }
Pointer to MyProc }

In Turbo Assembler, when an identifier precedes a DB, DW, or DD directive, it

causes the declaration of a byte-, word-, or double-word-sized variable at the location
of the directive. For example, Turbo Assembler allows the following:
ByteVar
WordVar
IntVar

DB
DW
DD

?
?
?

MOV
MOV
MOV

AL,ByteVar
BX,WordVar
ECX,IntVar

The built-in assembler doesnt support such variable declarations. The only kind of
symbol that can be defined in an inline assembler statement is a label. All variables
must be declared using Object Pascal syntax; the preceding construction can be
replaced by
var
ByteVar: Byte;
WordVar: Word;
IntVar: Integer;

asm
MOV
AL,ByteVar
MOV
BX,WordVar
MOV
ECX,IntVar
end;

Operands
Built-in assembler operands are expressions that consist of constants, registers,
symbols, and operators.

13-6

Object Pascal Language Guide

Expressions

Within operands, the following reserved words have predefined meanings

Table 13.1

Built-in assembler reserved words

EBX

ESP

OFFSET

BYTE

ECX

AND

EDI

PTR

DWORD

EDX

HIGH

QWORD

TBYTE

EIP

LOW

SHL

TYPE

EAX

MOD

SHR

WORD

EBP

ESI

NOT

XOR

Reserved words always take precedence over user-defined identifiers. For example,
var
Ch: Char;

asm
MOV
CH, 1
end;

loads 1 into the CH register, not into the Ch variable. To access a user-defined symbol
with the same name as a reserved word, you must use the ampersand (&) override
operator:
MOV

&Ch, 1

It is best to avoid user-defined identifiers with the same names as built-in assembler
reserved words.

Expressions
The built-in assembler evaluates all expressions as 32-bit integer values. It doesnt
support floating-point and string values, except string constants.
Expressions are built from expression elements and operators, and each expression has
an associated expression class and expression type.

Differences between Object Pascal and assembler expressions

The most important difference between Object Pascal expressions and built-in
assembler expressions is that assembler expressions must resolve to a constant
valuea value that can be computed at compile time. For example, given the
declarations
const
X = 10;
Y = 20;
var
Z: Integer;

Inline assembler code

13-7

Expressions

the following is a valid statement.

asm
MOV
end;

Z,X+Y

Because both X and Y are constants, the expression X + Y is a convenient way of

writing the constant 30, and the resulting instruction simply moves of the value 30
into the variable Z. But if X and Y are variables
var
X, Y: Integer;

the built-in assembler cannot compute the value of X + Y at compile time. In this
case, to move the sum of X and Y into Z you would use
asm
MOV
ADD
MOV
end;

EAX,X
EAX,Y
Z,EAX

In an Object Pascal expression, a variable reference denotes the contents of the

variable. But in an assembler expression, a variable reference denotes the address of
the variable. In Object Pascal the expression X + 4 (where X is a variable) means the
contents of X plus 4, while to the built-in assembler it means the contents of the word
at the address four bytes higher than the address of X. So, even though youre
allowed to write
asm
MOV
end;

EAX,X+4

this code doesnt load the value of X plus 4 into AX; instead, it loads the value of a
word stored four bytes beyond X. The correct way to add 4 to the contents of X is
asm
MOV
ADD
end;

EAX,X
EAX,4

Expression elements
The elements of an expression are constants, registers, and symbols.

Constants
The built-in assembler supports two types of constant: numeric constants and string
constants.

Numeric constants
Numeric constants must be integers, and their values must be between 2,147,483,648
and 4,294,967,295.

13-8

Object Pascal Language Guide

Expressions

By default, numeric constants use decimal notation, but the built-in assembler also
supports binary, octal, and hexadecimal. Binary notation is selected by writing a B
after the number, octal notation by writing an O after the number, and hexadecimal
notation by writing an H after the number or a $ before the number.
Numeric constants must start with one of the digits 0 through 9 or the $ character.
When you write a hexadecimal constant using the H suffix, an extra zero is required
in front of the number if the first significant digit is one of the digits A through F. For
example, 0BAD4H and $BAD4 are hexadecimal constants, but BAD4H is an identifier
because it starts with a letter.

String constants
String constants must be enclosed in single or double quotation marks. Two
consecutive quotation marks of the same type as the enclosing quotation marks count
as only one character. Here are some examples of string constants:
'Z'
'Delphi'
"That's all folks"
'"That''s all folks," he said.'
'100'
'"'
"'"

String constants of any length are allowed in DB directives, and cause allocation of a
sequence of bytes containing the ASCII values of the characters in the string. In all
other cases, a string constant can be no longer than four characters and denotes a
numeric value which can participate in an expression. The numeric value of a string
constant is calculated as
Ord(Ch1) + Ord(Ch2) shl 8 + Ord(Ch3) shl 16 + Ord(Ch4) shl 24

where Ch1 is the rightmost (last) character and Ch4 is the leftmost (first) character. If
the string is shorter than four characters, the leftmost characters are assumed to be
zero. The following table shows string constants and their numeric values.
Table 13.2

String examples and their values

String

Value

'a'

00000061H

'ba'

00006261H

'cba'

00636261H

'dcba'

64636261H

'a '

00006120H

20202061H

'a' * 2

000000E2H

'a'-'A'

00000020H

not 'a'

FFFFFF9EH

Inline assembler code

13-9

Expressions

Registers
The following reserved symbols denote CPU registers:.
Table 13.3

CPU registers

32-bit general purpose

EAX EBX ECX EDX

32-bit pointer or index

16-bit general purpose

AX BX CX DX

16-bit pointer or index

ESP EBP ESI EDI

SP BP SI DI

8-bit low registers

AL BL CL DL

16-bit segment registers

CS DS SS ES

32-bit segment registers

FS GS

8-bit high registers

AH BH CH DH

Coprocessor register stack

When an operand consists solely of a register name, it is called a register operand. All
registers can be used as register operands, and some registers can be used in other
contexts.
The base registers (BX and BP) and the index registers (SI and DI) can be written
within square brackets to indicate indexing. Valid base/index register combinations
are [BX], [BP], [SI], [DI], [BX+SI], [BX+DI], [BP+SI], and [BP+DI]. You can also index
with all the 32-bit registersfor example, [EAX+ECX], [ESP], and [ESP+EAX+5].
The segment registers (ES, CS, SS, DS, FS, and GS) are supported, but segments are
normally not useful in 32-bit applications.
The symbol ST denotes the topmost register on the 8087 floating-point register stack.
Each of the eight floating-point registers can be referred to using ST(X), where X is a
constant between 0 and 7 indicating the distance from the top of the register stack.

Symbols
The built-in assembler allows you to access almost all Object Pascal identifiers in
assembler expressions, including constants, types, variables, procedures, and
functions. In addition, the built-in assembler implements the special symbol @Result,
which corresponds to the Result variable within the body of a function. For example,
the function
function Sum(X, Y: Integer): Integer;
begin
Result := X + Y;
end;

could be written in assembler as

function Sum(X, Y: Integer): Integer; stdcall;
begin
asm
MOV
EAX,X
ADD
EAX,Y
MOV
@Result,EAX
end;
end;

13-10

Object Pascal Language Guide

Expressions

The following symbols cannot be used in asm statements:

Standard procedures and functions (for example, WriteLn and Chr).

The Mem, MemW, MemL, Port, and PortW special arrays.
String, floating-point, and set constants.
Labels that arent declared in the current block.
The @Result symbol outside of functions.

The following table summarizes the kinds of symbol that can be used in asm statements.
Table 13.4

Symbols recognized by the built-in assembler

Symbol

Value

Class

Type

Label

Address of label

Memory reference

SHORT

Constant

Value of constant

Immediate value

Type

Memory reference

Size of type

Field

Offset of field

Memory

Size of type

Variable

Address of variable

Memory reference

Size of type

Procedure

Address of procedure

Memory reference

NEAR

Function

Address of function

Memory reference

NEAR

Unit

Immediate value

@Code

Code segment address

Memory reference

0FFF0H

@Data

Data segment address

Memory reference

0FFF0H

@Result

Result variable offset

Memory reference

Size of type

With optimizations disabled, local variables (variables declared in procedures and

functions) are always allocated on the stack and accessed relative to EBP, and the value
of a local variable symbol is its signed offset from EBP. The assembler automatically
adds [EBP] in references to local variables. For example, given the declaration
var Count: Integer;

within a function or procedure, the instruction

MOV

EAX,Count

assembles into MOV EAX,[EBP4].

The built-in assembler treats var parameters as a 32-bit pointers, and the size of a var
parameter is always 4. The syntax for accessing a var parameter is different from that
for accessing a value parameter. To access the contents of a var parameter, you must
first load the 32-bit pointer and then access the location it points to. For example,
function Sum(var X, Y: Integer): Integer; stdcall;
begin
asm
MOV
EAX,X
MOV
EAX,[EAX]
MOV
EDX,Y
ADD
EAX,[EDX]
MOV
@Result,AX
end;
end;

Inline assembler code

13-11

Expressions

Identifiers can be qualified within asm statements. For example, given the declarations
type
TPoint = record
X, Y: Integer;
end;
TRect = record
A, B: TPoint;
end;
var
P: TPoint;
R: TRect;

the following constructions can be used in an asm statement to access fields.

MOV
MOV
MOV
MOV

EAX,P.X
EDX,P.Y
ECX,R.A.X
EBX,R.B.Y

A type identifier can be used to construct variables on the fly. Each of the following
instructions generates the same machine code, which loads the contents of [EDX] into
EAX.
MOV
MOV
MOV
MOV

EAX,(TRect PTR [EDX]).B.X

EAX,TRect(EDX]).B.X
EAX,TRect[EDX].B.X
EAX,[EDX].TRect.B.X

Expression classes
The built-in assembler divides expressions into three classes: registers, memory
references, and immediate values.
An expression that consists solely of a register name is a register expression. Examples
of register expressions are AX, CL, DI, and ES. Used as operands, register expressions
direct the assembler to generate instructions that operate on the CPU registers.
Expressions that denote memory locations are memory references. Object Pascals
labels, variables, typed constants, procedures, and functions belong to this category.
Expressions that arent registers and arent associated with memory locations are
immediate values. This group includes Object Pascals untyped constants and type
identifiers.
Immediate values and memory references cause different code to be generated when
used as operands. For example,
const
Start = 10;
var
Count: Integer;

asm
MOV
EAX,Start
EBX,Count
MOV
ECX,[Start]
MOV
EDX,OFFSET Count
end;

13-12

Object Pascal Language Guide

{
{
{
{

MOV
MOV
MOV
MOV

EAX,xxxx }
EBX,[xxxx] }
ECX,[xxxx] }
EDX,xxxx }

Expressions

Because Start is an immediate value, the first MOV is assembled into a move
immediate instruction. The second MOV, however, is translated into a move memory
instruction, as Count is a memory reference. In the third MOV, the brackets convert
Start into a memory reference (in this case, the word at offset 10 in the data segment).
In the fourth MOV, the OFFSET operator converts Count into an immediate value
(the offset of Count in the data segment).
The brackets and OFFSET operator complement each other. The following asm statement
produces identical machine code to the first two lines of the previous asm statement.
asm
MOV
MOV
end;

EAX,OFFSET [Start]
EBX,[OFFSET Count]

Memory references and immediate values are further classified as either relocatable or
absolute. Relocation is the process by which the linker assigns absolute addresses to
symbols. A relocatable expression denotes a value that requires relocation at link
time, while an absolute expression denotes a value that requires no such relocation.
Typically, expressions that refer to labels, variables, procedures, or functions are
relocatable, since the final address of these symbols is unknown at compile time.
Expressions that operate solely on constants are absolute.
The built-in assembler allows you to carry out any operation on an absolute value, but
it restricts operations on relocatable values to addition and subtraction of constants.

Expression types
Every built-in assembler expression has a typeor, more correctly, a size, because the
assembler regards the type of an expression simply as the size of its memory location.
For example, the type of an Integer variable is four, because it occupies 4 bytes. The
built-in assembler performs type checking whenever possible, so in the instructions
var
QuitFlag: Boolean;
OutBufPtr: Word;

asm
MOV
AL,QuitFlag
MOV
BX,OutBufPtr
end;

the assembler checks that the size of QuitFlag is one (a byte), and that the size of
OutBufPtr is two (a word). The instruction
MOV

DL,OutBufPtr

produces an error because DL is a byte-sized register and OutBufPtr is a word. The

type of a memory reference can be changed through a typecast; these are correct
ways of writing the previous instruction:
MOV
MOV
MOV

DL,BYTE PTR OutBufPtr

DL,Byte(OutBufPtr)
DL,OutBufPtr.Byte

Inline assembler code

13-13

Expressions

These MOV instructions all refer to the first (least significant) byte of the OutBufPtr
variable.
In some cases, a memory reference is untyped. One example is an immediate value
enclosed in square brackets:
MOV
MOV

AL,[100H]
BX,[100H]

The built-in assembler permits both of these instructions, because the expression
[100H] has no typeit just means the contents of address 100H in the data
segment, and the type can be determined from the first operand (byte for AL, word
for BX). In cases where the type cant be determined from another operand, the builtin assembler requires an explicit typecast:
INC
IMUL

BYTE PTR [100H]

WORD PTR [100H]

The following table summarizes the predefined type symbols that the built-in
assembler provides in addition to any currently declared Object Pascal types.
Table 13.5

Predefined type symbols

Symbol

Type

BYTE

WORD

DWORD

QWORD

TBYTE

Expression operators
The built-in assembler provides a variety of operators. Precedence rules are different
from Object Pascal; for example, in an asm statement, AND has lower precedence
than the addition and subtraction operators. The following table lists the built-in
assemblers expression operators in decreasing order of precedence.
Table 13.6

Precedence of built-in assembler expression operators

Operators

Remarks

Precedence
highest

&
(), [], ., HIGH, LOW
+,

unary + and

:
OFFSET, SEG, TYPE, PTR, *, /, MOD,
SHL, SHR, +,
NOT, AND, OR, XOR

13-14

Object Pascal Language Guide

binary + and
lowest

Expressions

The following table defines the built-in assemblers expression operators.

Table 13.7

Definitions of built-in assembler expression operators

Operator

Description

Identifier override. The identifier immediately following the ampersand is treated as

a user-defined symbol, even if the spelling is the same as a built-in assembler
reserved symbol.

(...)

Subexpression. Expressions within parentheses are evaluated completely prior to

being treated as a single expression element. Another expression can precede the
expression within the parentheses; the result in this case is the sum of the values of
the two expressions, with the type of the first expression.

[...]

Memory reference. The expression within brackets is evaluated completely prior to

being treated as a single expression element. The expression within brackets can be
combined with the BX, BP, SI, or DI registers using the plus (+) operator, to indicate
CPU register indexing. Another expression can precede the expression within the
brackets; the result in this case is the sum of the values of the two expressions, with
the type of the first expression. The result is always a memory reference.

Structure member selector. The result is the sum of the expression before the period
and the expression after the period, with the type of the expression after the period.
Symbols belonging to the scope identified by the expression before the period can be
accessed in the expression after the period.

HIGH

Returns the high-order 8 bits of the word-sized expression following the operator.
The expression must be an absolute immediate value.

LOW

Returns the low-order 8 bits of the word-sized expression following the operator. The
expression must be an absolute immediate value.

Unary plus. Returns the expression following the plus with no changes. The
expression must be an absolute immediate value.

Unary minus. Returns the negated value of the expression following the minus. The
expression must be an absolute immediate value.

Addition. The expressions can be immediate values or memory references, but only
one of the expressions can be a relocatable value. If one of the expressions is a
relocatable value, the result is also a relocatable value. If either of the expressions is a
memory reference, the result is also a memory reference.

Subtraction. The first expression can have any class, but the second expression must
be an absolute immediate value. The result has the same class as the first expression.

Segment override. Instructs the assembler that the expression after the colon belongs
to the segment given by the segment register name (CS, DS, SS, FS, GS, or ES) before
the colon. The result is a memory reference with the value of the expression after the
colon. When a segment override is used in an instruction operand, the instruction is
prefixed with an appropriate segment-override prefix instruction to ensure that the
indicated segment is selected.

OFFSET

Returns the offset part (double word) of the expression following the operator. The
result is an immediate value.

TYPE

Returns the type (size in bytes) of the expression following the operator. The type of
an immediate value is 0.

PTR

Typecast operator. The result is a memory reference with the value of the expression
following the operator and the type of the expression in front of the operator.

Multiplication. Both expressions must be absolute immediate values, and the result
is an absolute immediate value.

Inline assembler code

13-15

Assembler procedures and functions

Table 13.7

Definitions of built-in assembler expression operators (continued)

Operator

Description

Integer division. Both expressions must be absolute immediate values, and the result
is an absolute immediate value.

MOD

Remainder after integer division. Both expressions must be absolute immediate

values, and the result is an absolute immediate value.

SHL

Logical shift left. Both expressions must be absolute immediate values, and the result
is an absolute immediate value.

SHR

Logical shift right. Both expressions must be absolute immediate values, and the
result is an absolute immediate value.

NOT

Bitwise negation. The expression must be an absolute immediate value, and the
result is an absolute immediate value.

AND

Bitwise AND. Both expressions must be absolute immediate values, and the result is
an absolute immediate value.

Bitwise OR. Both expressions must be absolute immediate values, and the result is an
absolute immediate value.

XOR

Bitwise exclusive OR. Both expressions must be absolute immediate values, and the
result is an absolute immediate value.

Assembler procedures and functions

You can write complete procedures and functions using inline assembler code,
without including a begin...end statement. For example,
function LongMul(X, Y: Integer): Longint;
asm
MOV
EAX,X
IMUL
Y
end;

The compiler performs several optimizations on these routines:

No code is generated to copy value parameters into local variables. This affects all
string-type value parameters and other value parameters whose size isnt 1, 2, or 4
bytes. Within the routine, such parameters must be treated as if they were var
parameters.
Unless a function returns a string, variant, or interface reference, the compiler
doesnt allocate a function result variable; a reference to the @Result symbol is an
error. For strings, variants, and interfaces, the caller always allocates an @Result
pointer.
The compiler generates no stack frame for routines that arent nested and have no
parameters or local variables.

13-16

Object Pascal Language Guide

Assembler procedures and functions

The automatically generated entry and exit code for the routine looks like this:
PUSH
MOV
SUB

MOV
POP
RET

EBP
EBP,ESP
ESP,Locals

;Present if Locals <> 0 or Params <> 0

;Present if Locals <> 0 or Params <> 0
;Present if Locals <> 0

ESP,EBP
EBP
Params

;Present if Locals <> 0

;Present if Locals <> 0 or Params <> 0
;Always present

If locals include variants, long strings, or interfaces, they are initialized to zero but
not finalized.
Locals is the size of the local variables and Params is the size of the parameters. If
both Locals and Params are zero, there is no entry code, and the exit code consists
simply of a RET instruction.
Assembler functions return their results as follows.
Ordinal values are returned in AL (8-bit values), AX (16-bit values), or EAX (32-bit
values).
Real values are returned in ST(0) on the coprocessors register stack. (Currency
values are scaled by 10000.)
Pointers, including long strings, are returned in EAX.
Short strings and variants are returned in the temporary location pointed to by
@Result.

Inline assembler code

13-17

13-18

Object Pascal Language Guide

Appendix

A
Object Pascal grammar

Appendix A

Goal -> (Program | Package | Library | Unit)

Program -> [PROGRAM Ident ['(' IdentList ')'] ';']
ProgramBlock '.'
Unit -> UNIT Ident ';'
InterfaceSection
ImplementationSection
InitSection '.'
Package -> PACKAGE Ident ';'
[RequiresClause]
[ContainsClause]
END '.'
Library -> LIBRARY Ident ';'
ProgramBlock '.'
ProgramBlock -> [UsesClause]
Block
UsesClause -> USES IdentList ';'
InterfaceSection -> INTERFACE
[UsesClause]
[InterfaceDecl]...
InterfaceDecl ->
->
->
->

ConstSection
TypeSection
VarSection
ExportedHeading

ExportedHeading -> ProcedureHeading ';' [Directive]

-> FunctionHeading ';' [Directive]
ImplementationSection -> IMPLEMENTATION
[UsesClause]
[DeclSection]...

Object Pascal grammar

A-1

Block -> [DeclSection]

CompoundStmt
DeclSection ->
->
->
->
->

LabelDeclSection
ConstSection
TypeSection
VarSection
ProcedureDeclSection

LabelDeclSection -> LABEL LabelId

ConstSection -> CONST (ConstantDecl ';')...
ConstantDecl -> Ident '=' ConstExpr
-> Ident ':' TypeId '=' TypedConstant
TypeSection -> TYPE (TypeDecl ';')...
TypeDecl -> Ident '=' Type
-> Ident '=' RestrictedType
TypedConstant -> (ConstExpr | ArrayConstant | RecordConstant)
ArrayConstant -> '(' TypedConstant/','... ')'
RecordConstant -> '(' RecordFieldConstant/';'... ')'
RecordFieldConstant -> Ident ':' TypedConstant
Type ->
->
->
->
->
->
->
->

TypeId
SimpleType
StrucType
PointerType
StringType
ProcedureType
VariantType
ClassRefType

RestrictedType -> ObjectType

-> ClassType
-> InterfaceType
ClassRefType -> CLASS OF TypeId
SimpleType -> (OrdinalType | RealType)
RealType ->
->
->
->
->
->
->

REAL48
REAL
SINGLE
DOUBLE
EXTENDED
CURRENCY
COMP

OrdinalType -> (SubrangeType | EnumeratedType | OrdIdent)

OrdIdent ->
->
->
->
->
->
->

A-2

SHORTINT
SMALLINT
INTEGER
BYTE
LONGINT
INT64
WORD

Object Pascal Language Guide

->
->
->
->
->

BOOLEAN
CHAR
WIDECHAR
LONGWORD
PCHAR

VariantType -> VARIANT

-> OLEVARIANT
SubrangeType -> ConstExpr '..' ConstExpr
EnumeratedType -> '(' IdentList ')'
StringType ->
->
->
->

STRING
ANSISTRING
WIDESTRING
STRING '[' ConstExpr ']'

StrucType -> [PACKED] (ArrayType | SetType | FileType | RecType)

ArrayType -> ARRAY ['[' OrdinalType/','... ']'] OF Type
RecType -> RECORD [FieldList] END
FieldList -> FieldDecl/';'... [VariantSection] [';']
FieldDecl -> IdentList ':' Type
VariantSection -> CASE [Ident ':'] TypeId OF RecVariant/';'...
RecVariant -> ConstExpr/','... ':' '(' [FieldList] ')'
SetType -> SET OF OrdinalType
FileType -> FILE OF TypeId
PointerType -> '^' TypeId
ProcedureType -> (ProcedureHeading | FunctionHeading) [OF OBJECT]
VarSection -> VAR (VarDecl ';')...
VarDecl -> IdentList ':' Type [(ABSOLUTE (Ident | ConstExpr)) | '=' ConstExpr]
Expression -> SimpleExpression [RelOp SimpleExpression]...
SimpleExpression -> ['+' | '-'] Term [AddOp Term]...
Term -> Factor [MulOp Factor]...
Factor ->
->
->
->
->
->
->
->
->
RelOp ->
->
->
->
->

Designator ['(' ExprList ')']

'' Designator
Number
String
NIL
'(' Expression ')'
NOT Factor
SetConstructor
TypeId '(' Expression ')'
'>'
'<'
'<='
'>='
'<>'

Object Pascal grammar

A-3

-> IN
-> IS
-> AS
AddOp ->
->
->
->

'+'
'-'
OR
XOR

MulOp ->
->
->
->
->
->
->

'*'
'/'
DIV
MOD
AND
SHL
SHR

Designator -> QualId ['.' Ident | '[' ExprList ']' | '^']...

SetConstructor -> '[' [SetElement/','...] ']'
SetElement -> Expression ['..' Expression]
ExprList -> Expression/','...
Statement -> [LabelId ':'] [SimpleStatement | StructStmt]
StmtList -> Statement/';'...
SimpleStatement ->
->
->
->
StructStmt ->
->
->
->

Designator ['(' ExprList ')']

Designator ':=' Expression
INHERITED
GOTO LabelId

CompoundStmt
ConditionalStmt
LoopStmt
WithStmt

CompoundStmt -> BEGIN StmtList END

ConditionalStmt -> IfStmt
-> CaseStmt
IfStmt -> IF Expression THEN Statement [ELSE Statement]
CaseStmt -> CASE Expression OF CaseSelector/';'... [ELSE Statement] [';'] END
CaseSelector -> CaseLabel/','... ':' Statement
CaseLabel -> ConstExpr ['..' ConstExpr]
LoopStmt -> RepeatStmt
-> WhileStmt
-> ForStmt
RepeatStmt -> REPEAT Statement UNTIL Expression
WhileStmt -> WHILE Expression DO Statement
ForStmt -> FOR QualId ':=' Expression (TO | DOWNTO) Expression DO Statement
WithStmt -> WITH IdentList DO Statement

A-4

Object Pascal Language Guide

ProcedureDeclSection -> ProcedureDecl

-> FunctionDecl
ProcedureDecl -> ProcedureHeading ';' [Directive]
Block ';'
FunctionDecl -> FunctionHeading ';' [Directive]
Block ';'
FunctionHeading -> FUNCTION Ident [FormalParameters] ':' (SimpleType | STRING)
ProcedureHeading -> PROCEDURE Ident [FormalParameters]
FormalParameters -> '(' FormalParm/';'... ')'
FormalParm -> [VAR | CONST | OUT] Parameter
Parameter -> IdentList [':' ([ARRAY OF] SimpleType | STRING | FILE)]
-> Ident ':' SimpleType '=' ConstExpr
Directive ->
->
->
->
->
->
->
->
->
->
->
->
->
->
->

CDECL
REGISTER
DYNAMIC
VIRTUAL
EXPORT
EXTERNAL
FAR
FORWARD
MESSAGE
OVERRIDE
OVERLOAD
PASCAL
REINTRODUCE
SAFECALL
STDCALL

ObjectType -> OBJECT [ObjHeritage] [ObjFieldList] [MethodList] END

ObjHeritage -> '(' QualId ')'
MethodList -> (MethodHeading [';' VIRTUAL])/';'...
MethodHeading ->
->
->
->

ProcedureHeading
FunctionHeading
ConstructorHeading
DestructorHeading

ConstructorHeading -> CONSTRUCTOR Ident [FormalParameters]

DestructorHeading -> DESTRUCTOR Ident [FormalParameters]
ObjFieldList -> (IdentList ':' Type)/';'...
InitSection -> INITIALIZATION StmtList [FINALIZATION StmtList] END
-> BEGIN StmtList END
-> END
ClassType -> CLASS [ClassHeritage]
[ClassFieldList]
[ClassMethodList]
[ClassPropertyList]
END

Object Pascal grammar

A-5

ClassHeritage -> '(' IdentList ')'

ClassVisibility -> [PUBLIC | PROTECTED | PRIVATE | PUBLISHED]
ClassFieldList -> (ClassVisibility ObjFieldList)/';'...
ClassMethodList -> (ClassVisibility MethodList)/';'...
ClassPropertyList -> (ClassVisibility PropertyList ';')...
PropertyList -> PROPERTY Ident [PropertyInterface] PropertySpecifiers
PropertyInterface -> [PropertyParameterList] ':' Ident
PropertyParameterList -> '[' (IdentList ':' TypeId)/';'... ']'
PropertySpecifiers -> [INDEX ConstExpr]
[READ Ident]
[WRITE Ident]
[STORED (Ident | Constant)]
[(DEFAULT ConstExpr) | NODEFAULT]
[IMPLEMENTS TypeId]
InterfaceType -> INTERFACE [InterfaceHeritage]
[ClassMethodList]
[ClassPropertyList]
END
InterfaceHeritage -> '(' IdentList ')'
RequiresClause -> REQUIRES IdentList... ';'
ContainsClause -> CONTAINS IdentList... ';'
IdentList -> Ident/','...
QualId -> [UnitId '.'] Ident
TypeId -> [UnitId '.'] <type-identifier>
Ident -> <identifier>
ConstExpr -> <constant-expression>
UnitId -> <unit-identifier>
LabelId -> <label-identifier>
Number -> <number>
String -> <string>

A-6

Object Pascal Language Guide

Index
Symbols
- 4-4, 4-6, 4-9, 4-10
" 13-9
# 4-4
$ 4-4, 4-5
(*, *) 4-5
(, ) 4-2, 4-12, 4-14, 5-6, 5-41, 6-2,
6-3, 6-9, 7-2, 10-1
* 4-2, 4-6, 4-10
+ 4-4, 4-6, 4-9, 4-10
, 3-5, 4-23, 5-6, 5-20, 5-22, 6-9,
7-16, 9-4, 9-7, 9-8, 10-6, 13-2
. 3-2, 4-2, 4-13, 5-25, 9-7, 10-5
/ 4-2, 4-6
// 4-5
: 4-2, 4-17, 4-23, 5-20, 5-21, 5-36,
5-41, 6-3, 6-9, 7-16, 7-18, 7-27,
13-2
:= 4-17, 4-25
named parameters 10-12
; 3-2, 3-5, 4-16, 4-19, 4-24, 5-20,
5-21, 5-36, 6-2, 6-3, 6-9, 7-2, 7-6,
9-4, 9-7, 10-1, 10-3, 10-10
before else 4-22
< 4-2, 4-9, 4-10
<= 4-9, 4-10
<> 4-9, 4-10
= 4-2, 4-9, 4-10, 4-17, 5-35, 5-36,
5-38, 5-41, 6-9, 6-16, 10-5
> 4-2, 4-9, 4-10
>= 4-9, 4-10
@ 4-6, 4-11, 5-25, 5-29, 5-42, 7-16
@@ 5-29
@Result 13-10, 13-16
[, ] 4-13, 5-10, 5-11, 5-16, 5-30,
6-13, 6-18, 7-16, 7-18, 7-19, 10-1,
10-10
^ 4-6, 4-9, 5-18, 5-26
and variants 5-32
pointer overview 5-25
_ 4-2
{, } 4-5, 10-1, 10-10
3-6, 4-4, 6-7, 9-8, 10-1, 10-10

A
$A directive 11-7, 11-8
absolute (directive) 5-37
absolute addresses 5-37

absolute expressions
(assembler) 13-13
abstract methods 7-11
access specifiers 7-1, 7-16
array properties 7-18
Automation 7-6
calling convention 6-5, 7-17
index specifiers and 7-19
overloading 7-12, 7-17
overriding 7-21
actual parameters 6-17
Add method (TCollection) 7-9
addition 4-6
pointers 4-9
Addr function 5-25
_AddRef method 10-2, 10-5,
10-9
address operator 4-11, 5-25,
5-29, 5-42
properties and 7-16
alignment (data) 5-15, 11-7
See also internal data formats
AllocMemCount variable 11-1
AllocMemSize variable 11-1
alphanumeric characters 4-1,
4-2
ampersand See Symbols
ancestors 7-2, 7-3
and 4-7, 4-8
ANSI characters 5-4, 5-11, 5-12
AnsiChar type 5-4, 5-10, 5-12,
5-26, 11-3
AnsiString type 5-9, 5-11, 5-12,
5-14, 5-26
See also long strings
memory management 11-5
variant arrays and 5-32
Append procedure 8-2, 8-4, 8-5,
8-6
Application variable 2-5, 3-3
arithmetic operators 4-6, 5-4
array properties 7-5, 7-18
default 7-19
in dispatch interfaces 10-11
storage specifiers and 7-20
arrays 5-3, 5-16 to 5-20
array of const 6-15
accessing with
PByteArray 5-26
accessing with
PWordArray 5-26

assignments and 5-20

character 4-5, 5-12, 5-13,
5-15, 5-17
character arrays and string
constants 5-41
constant 5-41
dynamic 5-17, 6-14, 11-7
indexes 4-13
multidimensional 5-17, 5-19
open array
constructors 6-15, 6-18
parameters 6-10, 6-13
static 5-17, 11-7
variants and 5-29, 5-32
as 4-11, 7-23, 7-24, 10-9
ASCII 4-1, 4-4, 5-12
asm statements 13-1, 13-16
assembler (directive) 6-6, 13-1
assembly language
assembler routines 13-16
built-in assembler 13-1 to
13-17
external routines 6-6
Object Pascal and 13-1, 13-6,
13-7, 13-8, 13-10, 13-12,
13-14
Assign procedure
custom 8-4
Assigned function 5-29, 10-9
AssignFile procedure 8-2, 8-4,
8-6
assignment statements 4-17
typecasts 4-14
assignment-compatibility 5-34,
7-3, 10-9
asterisk See Symbols
at (reserved word) 7-26
at-sign See @, address operator
automatable types 7-6, 10-11
automated class members 7-4,
7-5
Automation 7-5, 10-10 to 10-12
See also COM
dual interfaces 10-12
method calls 10-12
variants and 11-11

B
$B directive 4-8
base types 5-7, 5-16, 5-17

Index

I-1

begin (reserved word) 3-2, 4-19,

6-2, 6-3
binary operators 4-6
binding
fields 7-7
methods 7-9
bitwise operators,not 4-8
blanks 4-1
BlockRead procedure 8-4
blocks 4-27
function 3-4, 6-1, 6-3
library 9-4
outer and inner 4-28
procedure 3-4, 6-1, 6-2
program 3-1, 3-2
scope 4-27 to 4-28
try...except 7-26, 7-28
try...finally 7-30
BlockWrite procedure 8-4
body (routine) 6-1
boldface 1-2
Boolean operators 4-7
complete vs. partial
evaluation 4-7
Boolean type 5-5, 11-3
Boolean types 5-5, 11-3
BORLANDMM.DLL 9-6
.BPL files 2-3, 9-7, 9-9
braces See Symbols
brackets See Symbols
Break procedure 4-24
exception handlers 7-27
in try...finally block 7-30
BSTR type (COM) 5-12
built-in assembler 13-1 to 13-17
built-in types 5-1
by reference (parameters) 6-10,
6-11, 10-12, 12-1
by value (parameters) 6-10,
10-12, 12-1
Byte type 5-4, 11-3
assembler 13-14
ByteArray type 5-26
ByteBool type 5-5, 11-3

C
C++ 10-1, 11-10
calling conventions 5-28, 6-4,
12-1
access specifiers 6-5, 7-17
DLLs 9-3
interfaces 10-3, 10-6
methods 12-3
Cardinal type 5-3
caret See Symbols
I-2

carriage-return 4-1, 4-5

case (reserved word) 4-23, 5-21
case statements 4-23
case-sensitivity 4-1, 4-2, 6-7
-cc compiler switch 8-3
cdecl (calling convention) 6-4,
12-2
constructors and
destructors 12-4
Self 12-3
Char type 5-4, 5-12, 5-26, 11-3
character operators 4-9
character sets
ANSI 5-4, 5-11, 5-12
extended 5-12
multibyte (MBCS) 5-12
Pascal 4-1, 4-2, 4-4
single-byte (SBCS) 5-12
character strings 4-1, 4-4, 5-42
characters
pointers 5-26
string literals as 4-5, 5-5
types 5-4, 11-3
wide 5-12, 11-3
checked typecasts
interfaces 10-9
objects 7-24
Chr function 5-5
circular references
packages 9-8
units 3-7 to 3-8
circumflex See Symbols
classes 7-1 to 7-30
class methods 7-1, 7-24
class references 7-22
class types 7-1
comparison 4-11
compatibility 7-3, 10-9
declaring class types 7-1, 7-4,
7-6, 7-7, 7-8, 7-16, 10-5
files and 5-23
memory 11-9
metaclasses 7-22
operators 4-11, 7-23
scope 4-28
variants and 5-29
Classes unit 7-9, 7-22
ClassParent method 7-23
class-reference types 7-22
comparison 4-11
constructors and 7-22
memory 11-10
variants and 5-29
ClassType method 7-23
clients 3-4

Object Pascal Language Guide

Close function 8-4, 8-6

CloseFile function 8-5
CloseFile procedure 8-6
CmdLine variable 9-5
colon See Symbols
COM 5-12, 10-1, 10-3
See also Automation
error handling 6-5
interfaces 10-1
OleVariant 5-33
out parameters 6-12
safecall 6-5
variants and 5-29, 5-32, 11-11
comma See Symbols
comments 4-1, 4-5
ComObj unit 7-5, 10-11
Comp type 5-8, 5-9, 11-5
comparison
classes 4-11
class-reference types 4-11
dynamic arrays 5-18
integer types 4-11
objects 4-11
packed strings 4-11
PChar type 4-11
real types 4-11
relational operators 4-10
strings 4-11, 5-10
compiler 2-2, 2-3, 2-5, 3-1
command-line 2-3 to 2-5
directives 3-2, 4-5
packages 9-9
compile-time binding See static
methods
complete evaluation 4-7
components, of classes See
members
compound statements 4-19
concatenation (strings) 4-9
conditional statements 4-19
conjunction 4-7
console applications 2-3, 8-3
const (reserved word) 5-38,
5-41, 6-9, 6-10, 6-11, 6-15, 12-1
constant expression
array constants 5-41
case statements 4-23
constant declarations 5-38,
5-41
default paramters 6-16
defined 5-39
initializing variables 5-36
subrange types 5-7, 5-8
type 5-39, 6-8

constant parameters 6-10, 6-11,

6-17, 12-1
open array constructors 6-18
constants 4-6, 5-38
array 5-41
assembler 13-8
declared 5-38 to 5-42
numeric See numerals
pointer 5-42
procedural 5-42
record 5-41
true 5-38
type compatibility 5-39
typed 5-40
constructors 7-1, 7-9, 7-12
calling conventions 12-4
class references and 7-22
exceptions 7-26, 7-30
contains clause 9-7, 9-8
context-sensitive Help (errorhandling) 7-30
Continue procedure 4-24
exception handlers 7-27
in try...finally block 7-30
control (program) 6-17, 12-1 to
12-5
control characters 4-1, 4-4
control loops 4-19, 4-24
control strings 4-4
conversion
See also typecasts
variants 5-30, 5-30 to 5-32
Copy function 5-18
copy-on-write semantics 5-11
CORBA 10-1
interfaces 10-1, 10-3
out parameters 6-12
variants and 5-29
CPU See registers
Create method 7-13
Currency type 5-8, 5-9, 5-26,
11-5

D
data alignment 5-15, 11-7
data formats, internal 11-2 to
11-11
data types See types
DCC32.CFG 2-4
DCC32.EXE 2-4
.DCP files 2-3, 9-9
.DCU files 2-3, 3-1, 3-7, 9-8, 9-9
Dec procedure 5-3, 5-4
declarations 4-1, 4-16, 4-27
class 7-1, 7-7, 7-8, 7-16, 10-5

constant 5-38, 5-41

defining 6-5, 7-6, 7-8, 10-3
field 7-7
forward 3-4, 6-5, 7-6, 10-3
function 6-1, 6-3
implementation 7-8
interface 3-4
local 6-8
method 7-8
package 9-7
procedure 6-1, 6-2
property 7-16, 7-18
type 5-35
variable 5-36
declared types 5-1
decrementing ordinals 5-3, 5-4,
5-5
default (directive) 7-19, 10-11
default parameters 6-9, 6-16 to
6-17
Automation objects 10-12
forward and interface
declarations 6-17
overloading and 6-8, 6-17
procedural types 6-16
default properties 7-19
interfaces 10-2
default property (COM
object) 5-32
default specifier 7-6, 7-16, 7-20
DefaultHandler method 7-15,
7-16
defining declarations 6-5, 7-6,
7-8, 10-3
DefWindowProc function 7-15
delegation (interface
implementation) 10-6
Delphi 1-1, 2-1, 2-2, 3-5, 5-1,
7-20
example application 2-5
forms 2-2
Library search path 3-6
packages 9-7
project files 3-1, 3-2
project manager 2-1
variants and 11-11
$DENYPACKAGEUNIT
directive 9-9
dependency
units 3-7 to 3-8
dereference operator 4-9, 5-18
pointer overview 5-25
variants and 5-32
descendants 7-2, 7-4
$DESIGNONLY directive 9-10

design-time packages 9-7

desktop settings files 2-2
Destroy method 7-13, 7-14, 7-27
destructors 7-1, 7-13, 7-14
calling conventions 12-4
device drivers, text-file 8-4
device functions 8-4, 8-5
.DFM files 2-2, 2-7, 7-5, 7-20
.DFN files 2-2
difference (sets) 4-10
directives 4-1, 4-3
See also reserved words
assembler 13-5
compiler 3-2, 4-5
list 4-3
directory paths
in uses clause 3-6
disjunction 4-7
bitwise 4-8
dispatch interface types 10-10
Dispatch method 7-15
dispatching messages 7-15
dispatching method calls 7-11
dispid (directive) 7-6, 10-11
dispinterface 10-10
Dispose procedure 5-18, 5-37,
7-4, 9-6, 11-1, 11-2
div 4-6
division 4-6
.DLL files 2-3, 6-7, 9-1
DLL_PROCESS_DETACH 9-6
DLL_THREAD_ATTACH 9-6
DLL_THREAD_DETACH 9-6
DLLProc variable 9-5
DLLs 9-1 to 9-6
calling routines in 6-7, 9-1
dynamic arrays in 9-6
dynamic variables in 9-6
exceptions 9-6
global variables 9-5
loading dynamically 9-2
loading statically 9-1
long strings in 9-6
multithreading 9-5
packages (BPLs) 9-7, 9-9
variables 9-1
writing 9-3
do (reserved word) 4-20, 4-25,
7-27
.DOF files 2-2
dollar See Symbols
Double type 5-8, 11-4
downto (reserved word) 4-25
.DPK files 2-1, 9-7, 9-9
.DPR files 2-1, 3-1, 3-6

Index

I-3

.DRC files 2-3

.DSK files 2-2
.DTI files 2-2
dual interfaces 10-3, 10-12
methods 6-5
DWORD type (assembler) 13-14
dynamic arrays 5-17, 11-7
assigning to 5-18
comparison 5-18
files and 5-23
in DLLs 9-6
memory management 11-2
multidimensional 5-19
open array parameters
and 6-14
records and 5-22
truncating 5-18
variants and 5-29
dynamic methods 7-9, 7-10
dynamic variables 5-37
and pointer constants 5-42
in DLLs 9-6
dynamically loaded DLLs 9-2
dynamic-link libraries See DLLs

E
E (in numerals) 4-4
else (reserved word) 4-21, 4-23,
7-27
empty set 5-16
end (reserved word) 3-2, 4-19,
4-23, 5-20, 5-21, 6-2, 6-3, 7-2,
7-27, 7-30, 9-7, 10-1, 10-10, 13-1
end-of-line character 4-1, 8-3
enumerated types 5-6, 11-3
Eof function 8-5
Eoln function 8-5
equality operator 4-10
error handling See exceptions
ErrorAddr variable 12-5
EStackOverflow exception 11-2
EVariantError exception 5-31
event handlers 2-7, 7-5
events 2-7, 7-5
example programs 2-3 to 2-7
except (reserved word) 7-27
ExceptAddr function 7-30
Exception class 7-25, 7-30
exception handlers 7-25, 7-27
identifiers in 7-28
ExceptionInformation
variable 9-6
exceptions 4-19, 7-13, 7-14, 7-25
to 7-30
constructors 7-26, 7-30
I-4

declaring 7-25
destroying 7-26, 7-27
DLLs 9-5, 9-6
file I/O 8-3
handling 7-26, 7-28, 7-30
in initialization section 7-26
nested 7-29
propagation 7-27, 7-29, 7-30
raising 7-25
re-raising 7-28
standard exceptions 7-30
standard routines 7-30
ExceptObject function 7-30
.EXE files 2-3
Exit procedure 6-1
exception handlers 7-27
in try...finally block 7-30
exit procedures 9-4, 12-4 to 12-5
packages and 12-4
ExitCode variable 9-4, 12-5
ExitProc variable 9-4, 9-5, 12-4
export (directive) 6-5
exports clause 4-27, 9-4
overloaded routines 9-4
expressions 4-1, 4-5
assembler 13-7 to 13-16
extended syntax 4-5
Extended type 4-7, 5-8, 5-9,
5-26, 11-5
external (directive) 6-6, 9-1, 9-2

F
False 5-5, 11-3
far (directive) 6-5
fields 5-20 to 5-23, 7-1, 7-7
See also records, classes
publishing 7-5
file (reserved word) 5-23
file I/O 8-1 to 8-6
exceptions 8-3
file variables 8-2
FilePos function 8-2
files
as parameters 6-10
file types 5-23, 8-2
generated 2-2, 2-3, 9-8, 9-9
initializing 5-37
memory 11-8
source code 2-1
text 8-2, 8-3
typed 5-23, 8-2
untyped 5-24, 8-2, 8-4
variants and 5-29
FileSize function 8-2
finalization section 3-3, 3-5, 12-4

Object Pascal Language Guide

Finalize procedure 5-18

finally (reserved word) 7-30
floating-point types See real
types
Flush function 8-4, 8-6
for statements 4-19, 4-24, 4-25
form files 2-2, 2-5 to 2-7, 7-5,
7-20
formal parameters 6-17
forward declarations
classes 7-6
default parameters 6-17
interfaces 10-3
overloading and 6-8
routines 3-4, 6-5
Free method 7-14
FreeLibrary function 9-2
FreeMem procedure 5-37, 9-6,
11-1, 11-2
functions 3-4, 6-1 to 6-18
assembler 13-16
calling externally 6-6
declaring 6-3, 6-5
function calls 4-13, 4-17, 6-1,
6-17 to 6-18
nested 5-28, 6-9
overloading 6-6, 6-7
pointers 4-11, 5-27
return type 6-3, 6-4
return value 6-3, 6-4
return values in
registers 12-3, 13-17
fundamental types 5-1

G
-$G- compiler switch 9-10
$G directive 9-9
generic types 5-1
GetHeapStatus function 11-2
GetMem procedure 5-25, 5-37,
9-6, 11-1, 11-2
GetMemoryManager
procedure 11-2
GetProcAddress function 9-2
getter See read specifier
global identifiers 4-27
global variables 5-36
DLLs 9-5
interfaces 10-9
memory management 11-2
GlobalAlloc 11-1
globally unique identifiers See
GUIDs
goto statements 4-18
grammar (formal) A-1 to A-6

greater-than See Symbols

GUIDs 10-1, 10-2, 10-10

H
$H directive 5-10, 6-13
Halt procedure 12-4, 12-5
heading
program 2-1, 3-1, 3-2
routine 6-1
unit 3-3
heap memory 5-37, 11-2
Hello world! 2-3
HelpContext property 7-30
hexadecimal numerals 4-4
hiding class members 7-7, 7-11,
7-21
See also overloaded methods
reintroduce 7-11
hiding interface
implementations 10-6
High function 5-3, 5-4, 5-11,
5-17, 5-19, 6-14
HInstance variable 9-5

I
$I directive 8-3
IDE 1-1
See also Delphi
identifiers 4-1, 4-2, 4-3
global and local 4-27
in exception handlers 7-28
qualified 3-6
scope 4-27 to 4-28
IDispatch 10-9, 10-10
dual interfaces 10-12
if...then statements 4-21
nested 4-22
immediate values
(assembler) 13-12
implementation section 3-3, 3-4,
3-7
and forward declarations 6-6
methods 7-8
scope 4-28
uses clause 3-7
implements (directive) 7-21,
10-6
$IMPLICITBUILD directive 9-9
$IMPORTEDDATA
directive 9-9
importing routines from
DLLs 9-1
in (reserved word) 3-6, 4-10,
5-16, 5-32, 9-8

Inc procedure 5-3, 5-4

incrementing ordinals 5-3, 5-4,
5-5
index (directive) 6-7
index specifier 7-6, 7-16, 7-19,
9-4
indexes 4-13
array 5-17, 5-18, 5-19
array properties 7-18
in var parameters 5-32, 6-11
string 5-10
string variants 5-30
variant arrays 5-32
indirect unit references 3-6 to
3-7
inequality operator 4-10
inheritance 7-2, 7-3, 7-4
interfaces 10-2
inherited (reserved word) 7-8,
7-13
calling conventions 12-4
message handlers 7-15
InheritsFrom method 7-23
initialization
DLLs 9-4
files 5-37
objects 7-13
units 3-4
variables 5-36, 5-37
variants 5-30, 5-37
initialization section 3-3, 3-4
exceptions 7-26
Initialize procedure 5-37
inline (reserved word) 13-1
inline assembler code 13-1 to
13-17
inner block 4-28
InOut function 8-4, 8-5
input (program parameter) 3-2
input See file I/O
Input variable 8-3
Int64 type 4-7, 5-3, 5-4, 5-9, 11-3
standard functions and
procedures 5-4
variants and 5-29
integer operators 4-6
Integer type 4-7, 5-3, 5-4
integer types 5-3
comparison 4-11
constants 5-39
conversion 4-14
data formats 11-2
integrated development
environment See IDE

Integrated Translation
Environment 2-2
interface declarations 3-4
default paramters 6-17
interface section 3-3, 3-4, 3-7
forward declarations and 6-6
methods 7-8
scope 4-28
uses clause 3-7
interfaces 7-2, 10-1 to 10-12
accessing 10-8 to 10-10
Automation 10-10
calling conventions 10-3
compatibility 10-9
delegation 10-6
dispatch interface
types 10-10
dual interfaces 10-12
GUIDs 10-1, 10-2, 10-10
implementing 10-4 to 10-7
interface references 10-8 to
10-10
interface types 10-1 to 10-4
memory management 11-2
method resolution
clauses 10-5, 10-6
properties 10-1, 10-3, 10-6
querying 10-9
records and 5-22
typecasts 10-9
internal data formats 11-2 to
11-11
intersection (sets) 4-10
IntToHex function 5-4
IntToStr function 5-4
Invoke method 10-10
IOResult function 8-3, 8-4
is 4-11, 5-32, 7-23
IsLibrary variable 9-5
italics 1-2
IUnknown 10-2, 10-5, 10-9,
10-12

J
$J directive 5-40
Java 10-1
jump instructions
(assembler) 13-4

L
labels 4-1, 4-4, 4-18
assembler 13-2
-$LE- compiler switch 9-10
Length function 5-10, 5-17, 5-19
Index

I-5

less-than See Symbols

libraries See DLLs
library (reserved word) 9-3
Library search path 3-6
line-feed 4-5
-$LN- compiler switch 9-10
LoadLibrary function 9-2
local identifiers 4-27
local variables 5-36, 6-8
memory management 11-2
LocalAlloc 11-1
logical operators 4-8
long strings 4-9, 5-9, 5-11
files and 5-23
in DLLs 9-6
memory management 11-2,
11-5
records and 5-22
LongBool type 5-5, 11-3
Longint type 5-3, 5-4, 11-3
Longword type 5-4, 11-3
loop statements 4-19, 4-24
Low function 5-3, 5-4, 5-11,
5-17, 5-19, 6-14
-$LU- compiler switch 9-10

M
$M directive 7-4, 7-5
main form 2-5 to 2-7
$MAXSTACKSIZE
directive 11-2
members See sets
members, of classes 7-1
interfaces 10-2
visibility 7-4
memory 4-1, 5-2, 5-24, 5-25,
5-30, 5-37, 7-14
DLLs 9-5
heap 5-37
management 11-1 to 11-11
overlays (in records) 5-22
shared memory manager 9-6
memory references
(assembler) 13-12
message (directive) 7-15
interfaces 10-6
message dispatching 7-15
message handlers 7-15
inherited 7-15
overriding 7-15
Message property 7-30
Messages unit 7-15, 7-16
metaclasses 7-22
method pointers 4-11, 5-27

I-6

method resolution clauses 10-5,

10-6
methods 7-1, 7-2, 7-8 to 7-16
abstract 7-11
Automation 7-6, 10-12
binding 7-9
calling conventions 12-3
class methods 7-1, 7-24
constructors 7-12, 12-4
destructors 7-14, 12-4
dispatch interface 10-11
dispatching calls 7-11
dual-interface 6-5
dynamic 7-9, 7-10
implementation 7-8
overloading 7-12
overriding 7-10, 7-11, 10-5
pointers 4-11, 5-27
publishing 7-5
static 7-9
virtual 7-6, 7-9, 7-10
$MINSTACKSIZE
directive 11-2
minus See Symbols
mod 4-6
modules See units
multibyte character sets 5-12
string-handling routines 8-7
multidimensional arrays 5-17,
5-19, 5-41
multiple unit references 3-6 to
3-7
multiplication 4-6
multithreaded applications 5-38
DLLs 9-5
mutually dependent classes 7-6
mutually dependent units 3-7

N
name (directive) 6-7, 9-4
named parameters 10-12
names
See also identifiers
exported routines (DLLs) 9-4
functions 6-3, 6-4
identifiers 4-16
packages 9-8
programs 3-1, 3-2
units 3-3, 3-6
naming conflicts 3-6, 4-28
near (directive) 6-5
negation 4-7
bitwse 4-8
nested conditionals 4-22
nested exceptions 7-29

Object Pascal Language Guide

nested routines 5-28, 6-9

New procedure 5-18, 5-25, 5-37,
7-4, 9-6, 11-1, 11-2
nil 5-26, 5-29, 11-5
nodefault specifier 7-6, 7-16,
7-20
not 4-6, 4-7
Null (variants) 5-30, 5-31, 5-32
null character 5-12, 11-6, 11-9
null string 4-4
null-terminated strings 5-12 to
5-15, 5-26, 11-6
mixing with Pascal
strings 5-14
standard routines 8-6, 8-7
numerals 4-1, 4-4
as labels 4-4, 4-18
assembler 13-8
type 5-39, 6-8

O
.OBJ files
calling routines in 6-6
Object Inspector (Delphi) 7-5
object interfaces See interfaces,
COM, CORBA
object types 7-3
objects 4-20, 7-1
See also classes
of object 5-27
comparison 4-11
files and 5-23
memory 11-9
of (reserved word) 4-23, 5-16,
5-17, 5-23, 5-27, 6-13, 6-15, 7-22
of object (method pointers) 5-27
OleAuto unit 7-5
OleVariant type 5-26, 5-33
on (reserved word) 7-27
opcodes (assembler) 13-2, 13-3
open array constructors 6-15,
6-18
open array parameters 6-13,
6-18
and dynamic arrays 6-14
Open function 8-4, 8-5
OpenString 6-13
operands 4-6
operators 4-6 to 4-12
assembler 13-14
class 7-23
precedence 4-12, 7-24
or 4-7, 4-8
Ord function 5-3, 5-4
ordinal types 5-2 to 5-8

ordinality 5-2
out (output) parameters 6-10,
6-11, 6-17
out (reserved word) 6-9, 6-10,
6-11
outer block 4-28
OutlineError 7-30
output (program
parameter) 3-2
output See file I/O
Output variable 8-3
overloaded methods 7-12
access specifiers 7-12, 7-17
publishing 7-5
overloaded procedures and
functions 6-6, 6-7
default parameters 6-8, 6-17
DLLs 9-4
forward declarations 6-8
overriding interface
implementations 10-5
overriding methods 7-10, 10-5
hiding and 7-11
overriding properties 7-20
access specifiers and 7-21
Automation 7-6
hiding and 7-21

P
$P directive 6-13
package files 2-1
packages 9-7 to 9-10
compiler directives 9-9
compiler switches 9-10
compiling 9-9
declaring 9-7
loading dynamically 9-7
loading statically 9-7
thread variables 9-8
uses clause and 9-7
packed (reserved word) 5-15,
11-7
packed arrays 4-5, 4-9, 5-17
packed records 11-8
packed strings 5-17
comparison 4-11
pairs of symbols 4-2
PAnsiChar type 5-12, 5-26
PAnsiString type 5-26
parameters 5-28, 6-2, 6-3, 6-9 to
6-17
See also overloaded
procedures and functions
actual 6-17
array 6-10, 6-13

array property indexes 7-18

Automation method
calls 10-12
calling conventions 6-4
constant 6-11, 12-1
default 6-16 to 6-17, 10-12
file 6-10
formal 6-17
names 10-12
open array 6-13
output (out) 6-11
overloading and 6-6, 6-7, 6-8
parameter list 6-9
passing 12-1
positional 10-12
program control 12-1
properties as 7-16
registers 6-4, 6-5, 12-2
short strings 6-13
typed 6-10
untyped 6-12, 6-17
value 6-10, 12-1
variable (var) 6-10, 12-1
variant open arrray 6-15
parentheses See Symbols
partial evaluation 4-7
.PAS files 2-1, 2-3, 3-1, 3-3, 3-7
pascal (calling convention) 6-4,
12-2
constructors and
destructors 12-4
Self 12-3
PByteArray type 5-26
PChar type 4-5, 4-9, 5-12, 5-13,
5-14, 5-26, 5-42
comparison 4-11
PCurrency type 5-26
period See Symbols
PExtended type 5-26
PGUID 10-3
plus See Symbols
Pointer type 5-24, 5-25, 5-26,
11-5
pointers 5-24 to 5-26
arithmetic 4-9
character 5-26
constants 5-42
files and 5-23
functions 4-11, 5-27
in var parameters 6-11
in variant open array
parameters 6-15
long strings 5-15
memory 11-5
method pointers 5-27

nil 5-26, 11-5

null-terminated strings 5-13,
5-15
operators 4-9
overview 5-24
Pointer type 4-11, 11-5
pointer types 4-11, 5-25, 5-26,
11-5
procedural types 4-11, 5-27
to 5-29
records and 5-22
standard types 5-26
variants and 5-29
POleVariant type 5-26
polymorphism 7-8, 7-11, 7-14
positional parameters 10-12
pound See Symbols
precedence of operators 4-12,
7-24
Pred function 5-3, 5-4
predecessor 5-2
predefined types 5-1
private class members 7-4, 7-5
procedural constants 5-42
procedural types 4-15, 5-27 to
5-29
calling DLLs with 9-2
calling routines with 5-28,
5-29
compatibility 5-28
default parameters 6-16
in assignments 5-28, 5-29
memory 11-9
procedure pointers 4-11, 5-27
procedures 3-4, 6-1 to 6-18
assembler 13-16
calling externally 6-6
declaring 6-2, 6-5
nested 5-28, 6-9
overloading 6-6, 6-7
pointers 4-11, 5-27
procedure calls 4-17, 6-1, 6-2,
6-17 to 6-18
program (reserved word) 3-2
program control 6-17, 12-1 to
12-5
programs 2-1 to 2-7, 3-1 to 3-8
examples 2-3 to 2-7
syntax 3-1 to 3-3
project files 2-1, 3-1, 3-2, 3-6
project options files 2-2
projects 2-5 to 2-7, 3-6
properties 7-1, 7-16 to 7-21
access specifiers 7-16
array 7-5, 7-18

Index

I-7

as parameters 7-16
declaring 7-16, 7-18
default 7-19, 10-2
interfaces 10-3
overriding 7-6, 7-20
read-only 7-18
write-only 7-18
protected class members 7-4,
7-5
prototypes 6-1
PShortString type 5-26
PString type 5-26
PTextBuf type 5-26
Ptr function 5-25
public class members 7-4, 7-5
public identifiers (interface
section) 3-4
published class members 7-4,
7-5
$M directive 7-5
restrictions 7-5
PVariant type 5-26
PVarRec type 5-26
PWideChar type 5-12, 5-13, 5-26
PWideString type 5-26
PWordArray type 5-26

Q
qualified identifiers 3-6, 4-2,
4-28, 5-21
in typecasts 4-14, 4-15
pointers 5-25
with Self 7-9
querying (interfaces) 10-9
QueryInterface method 10-2,
10-5, 10-10
quotation marks See Symbols
quoted strings 4-4, 5-42
assembler 13-9
QWORD type (assembler) 13-14

R
raise (reserved word) 4-19, 7-25,
7-27, 7-28
range-checking 5-4, 5-5, 5-8
Read procedure 8-2, 8-3, 8-4,
8-5, 8-6
read specifier 7-6, 7-16
array properties 7-18
index specifier and 7-19
object interfaces 10-1, 10-3,
10-6
overloading 7-12, 7-17
Readln procedure 8-5, 8-6
I-8

readonly (directive) 10-11

read-only properties 7-18
real (floating-point)
operators 4-6
Real type 5-9
real types 5-8, 11-3
comparison 4-11
conversion 4-14
publishing 7-5
Real48 type 5-8, 5-9, 7-5, 11-4
$REALCOMPATIBILITY
directive 5-9
ReallocMem procedure 5-37,
11-1
records 4-20, 5-20 to 5-23
constants 5-41
memory 11-7
record types 5-20
scope 4-28, 5-21
variant parts 5-21 to 5-23
variants and 5-29
recursive procedure and
function calls 6-1, 6-4
reference-counting 5-11, 10-9,
11-6, 11-7
register (calling
convention) 6-4, 7-6, 7-13,
7-14, 12-2
constructors and
destructors 12-4
DLLs 9-3
interfaces 10-3, 10-6
Self 12-3
registers 6-4, 6-5, 12-2, 12-3
assembler 13-2, 13-10, 13-12,
13-17
reintroduce (directive) 7-11,
7-12
relational operators 4-10
_Release method 10-2, 10-5,
10-9
relocatable expressions
(assembler) 13-13
Rename procedure 8-6
repeat statements 4-19, 4-24
requires clause 9-7, 9-8
.RES files 2-2, 3-2
reserved words 4-1, 4-2, 4-3
See also directives
assembler 13-7
list 4-3
Reset procedure 8-2, 8-4, 8-5,
8-6
resident (directive) 9-4
resource files 2-2, 2-3, 3-2

Object Pascal Language Guide

resource strings 5-40

resourcestring (reserved
word) 5-40
Result variable 6-3, 6-4
RET instruction 13-4
return type (functions) 6-3, 6-4
return value (functions) 6-3, 6-4
constructors 7-13
Rewrite procedure 8-2, 8-4, 8-5,
8-6
Round function 5-4
routines 6-1 to 6-18
See also functions, procedures
exporting 9-4
standard 8-1 to 8-10
.RPS files 2-2
RTTI 7-5, 7-12, 7-20
$RUNONLY directive 9-10
runtime binding See dynamic
methods, virtual methods
runtime packages 9-7
runtime type information See
RTTI

S
$S directive 11-2
safecall (calling convention) 6-4,
12-2
constructors and
destructors 12-4
dual interfaces 10-12
interfaces 10-3
Self 12-3
scope 4-27 to 4-28
classes 7-2
records 5-21
type identifiers 5-35
Seek procedure 8-2
SeekEof function 8-5
SeekEoln function 8-5
Self 7-9
calling conventions 12-3
class methods 7-24
semicolon See Symbols
separators 4-1, 4-5
SetLength procedure 5-10, 5-15,
5-17, 5-19, 6-14
SetMemoryManager
procedure 11-2
sets
empty 5-16
memory 11-6
operators 4-10
publishing 7-5
set constructors 4-13

set types 5-16

variants and 5-29
SetString procedure 5-15
setter See write specifier
ShareMem unit 9-6
shift-left (bitwise operator) 4-8
shift-right (bitwise operator) 4-8
shl 4-8
short strings 5-3, 5-9, 5-11
short-circuit evaluation 4-7
Shortint type 5-3, 11-2
ShortString type 5-9, 5-11, 5-26,
11-5
parameters 6-13
variant arrays and 5-32
ShowException procedure 7-30
shr 4-8
sign
in typecasts 4-14
numerals 4-4
simple statements 4-16
simple types 5-2
Single type 5-8, 11-4
16-bit applications (backward
compatibility) 6-5
SizeOf function 5-2, 5-4, 6-14
slash See Symbols
Smallint type 5-3, 11-3
source-code files 2-1
spaces 4-1
special symbols 4-1, 4-2
stack size 11-2
standard routines 8-1 to 8-10
null-terminated strings 8-6,
8-7
wide-character strings 8-7
statements 4-1, 4-16 to 4-26,
4-27, 6-1
static arrays 5-17, 11-7
variants and 5-29
static methods 7-9
statically loaded DLLs 9-1
stdcall (calling convention) 6-4,
12-2
constructors and
destructors 12-4
DLLs 9-3
interfaces 10-3
Self 12-3
storage specifiers 7-20
array properties and 7-20
stored specifier 7-6, 7-16, 7-20
Str procedure 8-6
StrAlloc function 5-37
StrDispose procedure 5-37

streaming (data) 5-2

string
See also character sets
comparison 4-11, 5-10
constants 4-4, 5-42, 13-9
handling See also standard
routines, null-terminated
strings
in variant open array
parameters 6-15
indexes 4-13
literals 4-4, 5-42
memory management 11-5,
11-6
null-terminated 5-12 to 5-15,
5-26
operators 4-9, 5-14
parameters 6-13
types 5-9 to 5-15
variant arrays 5-32
variants 5-30
wide 5-12, 8-7, 11-2
string (reserved word) 5-10
StringToWideChar function 8-7
strong typing 5-1
StrToInt64 function 5-4
StrToInt64Def function 5-4
structured statements 4-19
structured types 5-15
files and 5-23
records and 5-22
variants and 5-29
structures 5-20
StrUpper function 5-14
subrange types 4-7, 4-23, 5-7
subset operator 4-10
subtraction 4-6
pointers 4-9
Succ function 5-3, 5-4
successor 5-2
superset operator 4-10
symbol pairs 4-2
symbols 4-1, 4-2
See also special symbols and
Symbols on page I-1
assembler 13-10
syntax
descriptions 1-2
formal A-1 to A-6
System unit 3-1, 3-5, 5-26, 5-30,
5-31, 6-15, 7-3, 7-26, 8-1, 8-7,
10-2, 10-3, 10-4, 10-5, 10-10,
11-10
DLLs 9-4, 9-5
memory management 11-2

modifying 8-1
scope 4-28
uses clause and 8-1
SysUtils unit 3-5, 5-26, 6-9, 6-15,
7-25, 7-26, 7-30
DLLs 9-6
uses clause and 8-1

T
$T directive 4-11
tag (records) 5-22
TAutoObject 7-5
TBYTE type (assembler) 13-14
TClass 7-3, 7-22, 7-23
TCollection 7-22
Add method 7-9
TCollectionItem 7-22
TDateTime 5-31
text files 8-2, 8-3
Text type 5-23, 8-3
TextBuf type 5-26
text-file device drivers 8-4
TextFile type 5-23
TGUID 10-3
then (reserved word) 4-21
thread variables 5-38
in packages 9-8
threadvar 5-38
TInterfacedObject 10-2, 10-4,
10-5
to (reserved word) 4-25
TObject 7-3, 7-15, 7-23
tokens 4-1
TPersistent 7-5
True 5-5, 11-3
true constants 5-38
Trunc function 5-4
try...except statements 4-19,
7-26
try...finally statements 4-19,
7-30
TTextRec type 5-26
Turbo Assembler 13-1, 13-6
TVarData 5-30, 11-11
TVarRec 5-26
TVarRec type 6-15
TWordArray 5-26
type identifiers 5-2
typecasts 4-14 to 4-15, 7-7
checked 7-24, 10-9
in constant declarations 5-39
interface 10-9
untyped parameters 6-12
variants 5-30
type-checking (objects) 7-23
Index

I-9

types 5-1 to 5-36

array 5-16 to 5-20, 11-7
assembler 13-13
assignmentcompatibility 5-34
automatable 7-6, 10-11
Boolean 5-5, 11-3
built-in 5-1
character 5-4, 11-3
class 7-1, 7-4, 7-6, 7-7, 7-8,
7-16, 11-9
classification 5-1
class-reference 7-22, 11-10
compatibility 5-15, 5-28, 5-34
constants 5-39
declared 5-1
declaring 5-35
dispatch interface 10-10
enumerated 5-6, 11-3
exception 7-25
file 5-23, 11-8
fundamental 5-1
generic 5-1
identity 5-33
integer 5-3, 11-2
interface 10-1 to 10-4
internal data formats 11-2 to
11-11
object 7-3
ordinal 5-2 to 5-8
pointer 5-26
predefined 5-1
procedural 5-27 to 5-29, 11-9
real 5-8, 11-3
record 5-20 to 5-23, 11-7
scope 5-35
set 5-16, 11-6
simple 5-2
string 5-9 to 5-15, 11-5, 11-6
structured 5-15
subrange 5-7
type identity 5-33
user-defined 5-1
variant 5-29 to 5-33
typographical conventions 1-2

U
unary operators 4-6
Unassigned (variants) 5-30,
5-31, 5-32
underscores 4-2
Unicode 5-4, 5-12
union (sets) 4-10
UniqueString procedure 5-15
unit files 2-1, 3-1, 3-3
I-10

units 2-1, 3-1 to 3-8

scope 4-28
syntax 3-3 to 3-8
until (reserved word) 4-24
untyped files 5-24, 8-2, 8-4
untyped parameters 6-12
UpCase function 5-10
uses clause 2-1, 3-1, 3-2, 3-4, 3-5
to 3-8
interface section 3-7
ShareMem 9-6
syntax 3-5
System unit and 8-1
SysUtils unit and 8-1

V
Val procedure 8-6
value parameters 6-10, 6-17,
12-1
open array constructors 6-18
value typecasts 4-14
var (reserved word) 5-36, 6-9,
6-10, 12-1
VarArrayCreate function 5-32
VarArrayDimCount
function 5-32
VarArrayHighBound
function 5-32
VarArrayLock function 5-32,
10-11
VarArrayLowBound
function 5-32
VarArrayOf function 5-32
VarArrayRedim function 5-32
VarArrayRef function 5-32
VarArrayUnlock
procedure 5-32, 10-11
VarAsType function 5-30
VarCast procedure 5-30
variable (var) parameters 6-10,
6-17, 12-1
variable parameters 6-17
variable typecasts 4-14
variables 4-6, 5-36 to 5-38
absolute addresses 5-37
declaring 5-36
dynamic 5-37
file 8-2
from DLLs 9-1
global 5-36, 10-9
heap-allocated 5-37
initializing 5-36, 5-37
local 5-36, 6-8
memory management 11-2
thread 5-38

Object Pascal Language Guide

variant arrays 5-30

variant open array
parameters 6-15, 6-18
variant parts (records) 5-21 to
5-23
variants 5-29 to 5-33
and Automation 11-11
conversions 5-30, 5-30 to
5-32
files and 5-23
initializing 5-30, 5-37
interfaces and 10-9
memory management 11-2,
11-10
non-Delphi functions 11-11
OleVariant 5-33
operators 4-6, 5-32
records and 5-22
typecasts 5-30
variant arrays 5-32
variant arrays and
strings 5-32
Variant type 5-26, 5-29
variant types 5-29 to 5-33
varOleString constant 5-32
varString constant 5-32
VarType function 5-30
varTypeMask constant 5-30
VCL 1-1, 2-5
virgule See Symbols
virtual method table 11-9
virtual methods 7-9, 7-10
Automation 7-6
constructors 7-14
overloading 7-12
VirtualAlloc function 11-1
VirtualFree function 11-1
visibility (class members) 7-4
interfaces 10-2
Visual Component Library See
VCL
VMT 11-9

W
$WEAKPACKAGEUNIT
directive 9-9
while statements 4-19, 4-24,
4-25
wide characters and
strings 5-12
memory management 11-2
standard routines 8-7
WideChar type 4-9, 5-4, 5-10,
5-12, 5-26, 11-3

WideCharLenToString
function 8-7
WideCharToString function 8-7
WideString type 5-9, 5-12,
5-26
memory management 11-6
Windows 2-2, 5-12, 5-31, 6-5,
7-15, 8-4
DLLs 9-1, 9-5
example application 2-5
memory management 11-1,
11-2
messages 7-15
variants and 11-11
Windows unit 9-2
with statements 4-19, 4-20, 5-21

Word type 5-4, 11-3

assembler 13-14
WordBool type 5-5, 11-3
wrap-around (ordinal
types) 5-4, 5-5
Write procedure 8-2, 8-3, 8-4,
8-5, 8-6
write procedures 5-3
write specifier 7-6, 7-16
array properties 7-18
index specifier and 7-19
object interfaces 10-1, 10-3
overloading 7-12, 7-17
Writeln procedure 2-4, 8-5, 8-6
writeonly (directive) 10-11
write-only properties 7-18

X
$X directive 4-5
xor 4-7, 4-8

Y
Y2K issues 1-2
year 2000 issues 1-2

Z
-$Z- compiler switch 9-10
$Z directive 11-3

Index

I-11

I-12