Subsections

- 1 Types
- 2 Functions and Procedures
  - 1 AssignFile
  - 2 CloseFile
  - 3 Freemem
  - 4 Getmem
  - 5 GetResourceStringCurrentValue
  - 6 GetResourceStringDefaultValue
  - 7 GetResourceStringHash
  - 8 GetResourceStringName
  - 9 Hash
  - 10 Paramstr
  - 11 ResetResourceTables
  - 12 ResourceStringCount
  - 13 ResourceStringTableCount
  - 14 SetResourceStrings
  - 15 SetResourceStringValue

# 14 The OBJPAS unit

The objpas unit is meant for compatibility with Object Pascal as implemented by Delphi. The unit is loaded automatically by the Free Pascal compiler whenever the `Delphi` or `objfpc` more is entered, either through the command line switches `-Sd` or `-Sh` or with the `{$MODE DELPHI}` or `{$MODE OBJFPC}` directives.

It redefines some basic pascal types, introduces some functions for compatibility with Delphi's system unit, and introduces some methods for the management of the resource string tables.

# 1 Types

The objpas unit redefines two integer types, for compatibity with Delphi:

    type
      smallint = system.integer;
      integer  = system.longint;

The resource string tables can be managed with a callback function which the user must provide: `TResourceIterator`.

    Type
       TResourceIterator =
          Function (Name,Value : AnsiString;Hash : Longint):AnsiString;

# 2 Functions and Procedures

##
1 AssignFile

Declaration
  `Procedure AssignFile(Var f: FileType;Name: Character type);`
Description
  AssignFile is completely equivalent to the system unit's Assign function: It assigns `Name` to a function of any type (`FileType` can be `Text` or a typed or untyped `File` variable). `Name` can be a string, a single character or a `PChar`.

  It is most likely introduced to avoid confusion between the regular Assign function and the `Assign` method of `TPersistent` in the Delphi VCL.

Errors
  None.
See also
  CloseFile, Assign, Reset, Rewrite, Append

Example

      Program Example88;

      { Program to demonstrate the AssignFile and CloseFile functions. }

      {$MODE Delphi}

      Var F : text;

      begin
        AssignFile(F,'textfile.txt');
        Rewrite(F);
        Writeln (F,'This is a silly example of AssignFile and CloseFile.');
        CloseFile(F);
      end.

##
2 CloseFile

Declaration
  `Procedure CloseFile(Var F: FileType);`
Description
  CloseFile flushes and closes a file `F` of any file type. `F` can be `Text` or a typed or untyped `File` variable. After a call to `CloseFile`, any attempt to write to the file `F` will result in an error.

  It is most likely introduced to avoid confusion between the regular Close function and the `Close` method of `TForm` in the Delphi VCL.

Errors
  None.
See also
  Close, AssignFile, Reset, Rewrite, Append

for an example, see AssignFile.

##
3 Freemem

Declaration
  `Procedure FreeMem(Var p:pointer[;Size:Longint]);`
Description
  FreeMem releases the memory reserved by a call to GetMem. The (optional) `Size` parameter is ignored, since the object pascal version of `GetMem` stores the amount of memory that was requested.

  Be sure not to release memory that was not obtained with the `Getmem` call in Objpas. Normally, this should not happen, since objpas changes the default memory manager to it's own memory manager.

Errors
  None.
See also
  Freemem, GetMem, Getmem

Example

      Program Example89;

      { Program to demonstrate the FreeMem function. }
      {$Mode Delphi}

      Var P : Pointer;

      begin
        Writeln ('Memory before : ',Memavail);
        GetMem(P,10000);
        FreeMem(P);
        Writeln ('Memory after  : ',Memavail);
      end.

##
4 Getmem

Declaration
  `Procedure Getmem(Var P:pointer;Size:Longint);`
Description
  GetMem reserves `Size` bytes of memory on the heap and returns a pointer to it in `P`. `Size` is stored at offset -4 of the result, and is used to release the memory again. `P` can be a typed or untyped pointer.

  Be sure to release this memory with the FreeMem call defined in the objpas unit.

Errors
  In case no more memory is available, and no more memory could be obtained from the system a run-time error is triggered.
See also
  FreeMem, Getmem.

For an example, see FreeMem.

##
5 GetResourceStringCurrentValue

Declaration
  `Function GetResourceStringCurrentValue(TableIndex,StringIndex : Longint) : AnsiString;`
Description
  GetResourceStringCurrentValue returns the current value of the resourcestring in table `TableIndex` with index `StringIndex`.

  The current value depends on the system of internationalization that was used, and which language is selected when the program is executed.

Errors
  If either `TableIndex` or `StringIndex` are out of range, then a empty string is returned.
See also
  SetResourceStrings, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount, ResourceStringCount

Example

      Program Example90;

      { Program to demonstrate the GetResourceStringCurrentValue function. }
      {$Mode Delphi}

      ResourceString

        First  = 'First string';
        Second = 'Second String';

      Var I,J : Longint;

      begin
        { Print current values of all resourcestrings }
        For I:=0 to ResourceStringTableCount-1 do
          For J:=0 to ResourceStringCount(i)-1 do
            Writeln (I,',',J,' : ',GetResourceStringCurrentValue(I,J));
      end.

##
6 GetResourceStringDefaultValue

Declaration
  `Function GetResourceStringDefaultValue(TableIndex,StringIndex : Longint) : AnsiString`
Description
  GetResourceStringDefaultValue returns the default value of the resourcestring in table `TableIndex` with index `StringIndex`.

  The default value is the value of the string that appears in the source code of the programmer, and is compiled into the program.

Errors
  If either `TableIndex` or `StringIndex` are out of range, then a empty string is returned.
Errors
See also
  SetResourceStrings, GetResourceStringCurrentValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount, ResourceStringCount

Example

      Program Example91;

      { Program to demonstrate the GetResourceStringDefaultValue function. }
      {$Mode Delphi}

      ResourceString

        First  = 'First string';
        Second = 'Second String';

      Var I,J : Longint;

      begin
        { Print default values of all resourcestrings }
        For I:=0 to ResourceStringTableCount-1 do
          For J:=0 to ResourceStringCount(i)-1 do
            Writeln (I,',',J,' : ',GetResourceStringDefaultValue(I,J));
      end.

##
7 GetResourceStringHash

Declaration
  `Function GetResourceStringHash(TableIndex,StringIndex : Longint) : Longint;`
Description
  GetResourceStringHash returns the hash value associated with the resource string in table `TableIndex`, with index `StringIndex`.

  The hash value is calculated from the default value of the resource string in a manner that gives the same result as the GNU gettext mechanism. It is stored in the resourcestring tables, so retrieval is faster than actually calculating the hash for each string.

Errors
  If either `TableIndex` or `StringIndex` is zero, 0 is returned.
See also
  Hash SetResourceStrings, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount, ResourceStringCount

For an example, see Hash.

##
8 GetResourceStringName

Declaration
  `Function GetResourceStringName(TableIndex,StringIndex : Longint) : Ansistring;`
Description
  GetResourceStringName returns the name of the resourcestring in table `TableIndex` with index `StringIndex`. The name of the string is always the unit name in which the string was declared, followed by a period and the name of the constant, all in lowercase.

  If a unit MyUnit declares a resourcestring `MyTitle` then the name returned will be `myunit.mytitle`. A resourcestring in the program file will have the name of the program prepended.

  The name returned by this function is also the name that is stored in the resourcestring file generated by the compiler.

  Strictly speaking, this information isn't necessary for the functioning of the program, it is provided only as a means to easier translation of strings.

Errors
  If either `TableIndex` or `StringIndex` is zero, an empty string is returned.
See also
  SetResourceStrings, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount, ResourceStringCount

Example

      Program Example92;

      { Program to demonstrate the GetResourceStringName function. }
      {$Mode Delphi}

      ResourceString

        First  = 'First string';
        Second = 'Second String';

      Var I,J : Longint;

      begin
        { Print names of all resourcestrings }
        For I:=0 to ResourceStringTableCount-1 do
          For J:=0 to ResourceStringCount(i)-1 do
            Writeln (I,',',J,' : ',GetResourceStringName(I,J));
      end.

##
9 Hash

Declaration
  `Function Hash(S : AnsiString) : longint;`
Description
  Hash calculates the hash value of the string `S` in a manner that is compatible with the GNU gettext hash value for the string. It is the same value that is stored in the Resource string tables, and which can be retrieved with the GetResourceStringHash function call.
Errors
  None. In case the calculated hash value should be 0, the returned result will be -1.
See also
  GetResourceStringHash,

Example

      Program Example93;

      { Program to demonstrate the Hash function. }
      {$Mode Delphi}

      ResourceString

        First  = 'First string';
        Second = 'Second String';

      Var I,J : Longint;

      begin
        For I:=0 to ResourceStringTableCount-1 do
          For J:=0 to ResourceStringCount(i)-1 do
            If Hash(GetResourceStringDefaultValue(I,J))
              <>GetResourceStringHash(I,J) then
              Writeln ('Hash mismatch at ',I,',',J)
            else
              Writeln ('Hash (',I,',',J,') matches.');
      end.

##
10 Paramstr

Declaration
  `Function ParamStr(Param : Integer) : Ansistring;`
Description
  ParamStr returns the `Param`-th command-line parameter as an AnsiString. The system unit Paramstr function limits the result to 255 characters.

  The zeroeth command-line parameter contains the path of the executable, except on LINUX, where it is the command as typed on the command-line.

Errors
  In case `Param` is an invalid value, an empty string is returned.
See also
  Paramstr

For an example, see Paramstr.

##
11 ResetResourceTables

Declaration
  `Procedure ResetResourceTables;`
Description
  ResetResourceTables resets all resource strings to their default (i.e. as in the source code) values.

  Normally, this should never be called from a user's program. It is called in the initialization code of the objpas unit. However, if the resourcetables get messed up for some reason, this procedure will fix them again.

Errors
  None.
See also
  SetResourceStrings, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount, ResourceStringCount

##
12 ResourceStringCount

Declaration
  `Function ResourceStringCount(TableIndex : longint) : longint;`
Description
  ResourceStringCount returns the number of resourcestrings in the table with index `TableIndex`. The strings in a particular table are numbered from `0` to `ResourceStringCount-1`, i.e. they're zero based.
Errors
  If an invalid `TableIndex` is given, `-1` is returned.
See also
  SetResourceStrings, GetResourceStringCurrentValue, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount,

For an example, see GetResourceStringDefaultValue

##
13 ResourceStringTableCount

Declaration
  `Function ResourceStringTableCount : Longint;`
Description
  ResourceStringTableCount returns the number of resource string tables; this may be zero if no resource strings are used in a program.

  The tables are numbered from 0 to `ResourceStringTableCount-1`, i.e. they're zero based.

Errors
See also
  SetResourceStrings, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringCount

For an example, see GetResourceStringDefaultValue

##
14 SetResourceStrings

Declaration
  `TResourceIterator = Function (Name,Value : AnsiString;Hash : Longint):AnsiString;`

  `Procedure SetResourceStrings (SetFunction : TResourceIterator);`

Description
  SetResourceStrings calls `SetFunction` for all resourcestrings in the resourcestring tables and sets the resourcestring's current value to the value returned by `SetFunction`.

  The `Name`,`Value` and `Hash` parameters passed to the iterator function are the values stored in the tables.

Errors
  None.
See also
  GetResourceStringCurrentValue, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount, ResourceStringCount

Example

      Program Example95;

      { Program to demonstrate the SetResourceStrings function. }
      {$Mode objfpc}

      ResourceString

        First  = 'First string';
        Second = 'Second String';

      Var I,J : Longint;
          S : AnsiString;

      Function Translate (Name,Value : AnsiString; Hash : longint): AnsiString;

      begin
        Writeln ('Translate (',Name,') => ',Value);
        Write   ('->');
        Readln  (Result);
      end;

      begin
        SetResourceStrings(@Translate);
        Writeln ('Translated strings : ');
        For I:=0 to ResourceStringTableCount-1 do
          For J:=0 to ResourceStringCount(i)-1 do
            begin
            Writeln (GetResourceStringDefaultValue(I,J));
            Writeln ('Translates to : ');
            Writeln (GetResourceStringCurrentValue(I,J));
            end;
      end.

##
15 SetResourceStringValue

Declaration
  `Function SetResourceStringValue(TableIndex,StringIndex : longint; Value : Ansistring) : Boolean;`
Description
  SetResourceStringValue assigns `Value` to the resource string in table `TableIndex` with index `StringIndex`.
Errors
See also
  SetResourceStrings, GetResourceStringCurrentValue, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount, ResourceStringCount

Example

      Program Example94;

      { Program to demonstrate the SetResourceStringValue function. }
      {$Mode Delphi}

      ResourceString

        First  = 'First string';
        Second = 'Second String';

      Var I,J : Longint;
          S : AnsiString;

      begin
        { Print current values of all resourcestrings }
        For I:=0 to ResourceStringTableCount-1 do
          For J:=0 to ResourceStringCount(i)-1 do
            begin
            Writeln ('Translate => ',GetResourceStringDefaultValue(I,J));
            Write   ('->');
            Readln(S);
            SetResourceStringValue(I,J,S);
            end;
        Writeln ('Translated strings : ');
        For I:=0 to ResourceStringTableCount-1 do
          For J:=0 to ResourceStringCount(i)-1 do
            begin
            Writeln (GetResourceStringDefaultValue(I,J));
            Writeln ('Translates to : ');
            Writeln (GetResourceStringCurrentValue(I,J));
            end;
      end.