Compiler Functions


Syntax

Size = SizeOf(Type)
Description
SizeOf can be used to find the size of any complex Structure, built-in type (word, float, etc.), Interface or even ReferenceLink "variables" "variables" (Structures with same name as variable take precedence). This can be useful in many areas such as calculating memory requirements for operations, using API commands, etc.
As a compiler function, SizeOf(x) is assigned to a constant and does not require assignment to another variable if inside a loop or often called procedure.
As a compile time function SizeOf doesn't work with runtime Array, List or Map. ArraySize(), ListSize() or MapSize() can be used instead.

Note: A Character (.c) variable is unicode and uses 2 bytes. An Ascii variable (.a) is Ascii and uses 1 byte.

Parameters

Type The type of the object.

Return value

The size of the object in memory, in bytes.

Example: 1

  char.c='!'
  Debug SizeOf(char); display 2

  ascii.a='!'
  Debug SizeOf(ascii); display 1

Example: 2

  Structure Person
    Name.s
    ForName.s 
    Age.w 
  EndStructure
  
  Debug "The size of my friend is "+Str(Sizeof(Person))+" bytes" ; will be 10 on 32-bit compiler as a string pointer is 4 bytes in memory
                                                                 ; will be 18 on 64-bit compiler as a string pointer is 8 bytes in memory
  
  John.Person\Name = "John"
  
  Debug SizeOf(John) ; will be the same

Syntax
Index = OffsetOf(Structure\Field)
Index = OffsetOf(Interface\Function())
Description
OffsetOf can be used to find out the address offset of a Structure field or the address offset of an Interface function. When used with an Interface, the function index is the memory offset, so it will be IndexOfTheFunction*SizeOf(Integer).

Parameters

Structure\Field or Interface\Function() The field of the structure or function of the interface.

Return value

Returns the index of the field or function, zero otherwise.

Example

  Structure Person
    Name.s
    ForName.s 
    Age.w 
  EndStructure
  
  Debug OffsetOf(Person\Age) ; will be  8 on 32-bit compiler as a string pointer is 4 bytes in memory
                             ; will be 16 on 64-bit compiler as a string pointer is 8 bytes in memory
  
  Interface ITest
    Create()
    Destroy(Flags) 
  EndInterface
  
  Debug OffsetOf(ITest\Destroy()) ; will be 4 on 32-bit compiler as a pointer is 4 bytes in memory
                                  ; will be 8 on 64-bit compiler as a pointer is 8 bytes in memory

Syntax
Type = TypeOf(Object)
Description
TypeOf can be used to find out the type of a variable, or a structure field.

Parameters

Object The object to use.

Return value

The type of the object.

The type can be one of the following values: 
  #PB_Byte      
  #PB_Word      
  #PB_Long      
  #PB_String    
  #PB_Structure
  #PB_Float
  #PB_Character
  #PB_Double
  #PB_Quad
  #PB_List
  #PB_Array
  #PB_Integer
  #PB_Map
  #PB_Ascii
  #PB_Unicode
  #PB_Interface

Example

  Structure Person
    Name.s
    ForName.s 
    Age.w 
  EndStructure
  
  If TypeOf(Person\Age) = #PB_Word
    Debug "Age is a 'Word'"
  EndIf
            
  Surface.f                 
  If TypeOf(Surface) = #PB_Float
    Debug "Surface is a 'Float'"
  EndIf

Syntax
Result = Subsystem(<constant string expression>)
Description
Subsystem can be used to find out if a subsystem is in use for the program being compiled. The specified subsystem name is not case-sensitive.

Parameters

constant string expression The subsystem name.
Windows: DirectX9, DirectX11
Linux : Gtk2, Qt
MacOS X: None

Return value

Returns nonzero if the subsystem is used, zero otherwise.

Example

  CompilerIf Subsystem("OpenGL")
    Debug "Compiling with the OpenGL subsystem"
  CompilerEndIf

Syntax
Result = Defined(Name, Type)
Description
Defined checks if a particular object of a code source like structure, interface, variables etc. is already defined or not.

Parameters

Name The name of the object. The 'Name' parameter has to be specified without any extra decoration (ie: without the '#' for a constant, without '()' for an array, a list or a map).
Type The 'Type' parameter can be one of the following values: 
  #PB_Constant
  #PB_Variable
  #PB_Array
  #PB_List
  #PB_Map
  #PB_Structure
  #PB_Interface
  #PB_Procedure
  #PB_Function
  #PB_OSFunction
  #PB_Label
  #PB_Prototype
  #PB_Module
  #PB_Enumeration

Return value

Returns nonzero if the object is defined, zero otherwise.

Example

  #PureConstant = 10
  
  CompilerIf Defined(PureConstant, #PB_Constant)
    Debug "Constant 'PureConstant' is declared"
  CompilerEndIf
  
  Test = 25
  
  CompilerIf Defined(Test, #PB_Variable)
    Debug "Variable 'Test' is declared"
  CompilerEndIf

Syntax
InitializeStructure(*Pointer, Structure)
Description
InitializeStructure initialize the specified structured memory area. It initializes structure members of type Array, List and Map, other members are not affected (.s, .l, .i etc).

Parameters

*Pointer The memory address to use.
Structure 'Structure' is the name of the structure which should be used to perform the initialization. There is no internal check to ensures the structure match the memory area. Warning: multiple calls to InitializeStructure create a memory leak because the old members are not freed (ClearStructure has to be called before calling InitializeStructure once more). This function is for advanced users and should be used with care. To allocate dynamic structure, use AllocateStructure()().

Return value

None.

Example

  Structure People
    Name$
    Age.l
    List Friends.s()
  EndStructure

  *Student.People = AllocateMemory(SizeOf(People))
  InitializeStructure(*Student, People)

  ; Now the list is ready to use
  ;
  AddElement(*Student\Friends())
  *Student\Friends() = "John"
  
  AddElement(*Student\Friends())
  *Student\Friends() = "Yann"

  ; Print out the list content
  ;
  ForEach *Student\Friends()
    Debug *Student\Friends()
  Next

Syntax
Result = CompareStructure(*Pointer1, *Pointer2, Structure [, Flags])
Description
CompareStructure compares the memory of two structures for equality. The comparison is recursively applied also to child elements such as arrays, lists, and maps.

Parameters

*Pointer1 The memory address of the first structured variable to be tested.
*Pointer2 The memory address of the second structured variable to be tested.
Structure The structure used.
Flags (optional) It can have one of the following values: 
  #PB_String_CaseSensitive : String comparison is case sensitive (a=a). (default)
  #PB_String_NoCase        : String comparison is case insensitive(a=A).
  #PB_Memory_FollowPointers: If a structure element is a pointer that is not 0, recursively compare the pointer target. 
                              The default is to compare only the pointer value itself.

Remarks

Caution: The #PB_Memory_FollowPointers option is for advanced users and requires special care to avoid crashes. If this option is used then all pointer values must point to valid and initialized memory or have the value 0. It is also not allowed to have loops in the pointed elements (a chain of pointers that refers back to itself).

Return value

Returns nonzero if the structures are the same or zero if they differ.

Example

  Structure People
    Name$
    LastName$
    Map Friends$()
    Age.l
  EndStructure

  StudentA.People\Name$ = "Paul"
  StudentA\LastName$ = "Morito"
  StudentA\Friends$("Tom") = "Jones"
  StudentA\Friends$("Jim") = "Doe"

  StudentB.People\Name$ = "Paul"
  StudentB\LastName$ = "Morito"
  StudentB\Friends$("Tom") = "Jones"
  StudentB\Friends$("Jim") = "Doe"

  StudentC.People\Name$ = "Paul"
  StudentC\LastName$ = "Morito"
  StudentC\Friends$("Tom") = "Hanks" ; Not the same as in StudentA
  StudentC\Friends$("Jim") = "Doe"

  Debug CompareStructure(@StudentA, @StudentB, People) ; Equal
  Debug CompareStructure(@StudentA, @StudentC, People) ; Not equal

Syntax
CopyStructure(*Source, *Destination, Structure)
Description
CopyStructure copy the memory of a structured memory area to another. This is useful when dealing with dynamic allocations, through pointers. Every fields will be duplicated, even array, list, and map. The destination structure will be automatically cleared before doing the copy, it's not needed to call ClearStructure before CopyStructure. Warning: the destination should be a valid structure memory area, or a cleared memory area. If the memory area is not cleared, it could crash, as random values will be used by the clear routine. There is no internal check to ensures that the structure match the two memory area. This function is for advanced users and should be used with care.

Parameters

*Source The memory address containing the structure to copy.
*Destination The memory address of the copy.
Structure The name of the structure that should be used to perform the copy.

Return value

None.

Example

  Structure People
    Name$
    LastName$
    Map Friends$()
    Age.l
  EndStructure

  Student.People\Name$ = "Paul"
  Student\LastName$ = "Morito"
  Student\Friends$("Tom") = "Jones"
  Student\Friends$("Jim") = "Doe"
  
  CopyStructure(@Student, @StudentCopy.People, People)
  
  Debug StudentCopy\Name$
  Debug StudentCopy\LastName$
  Debug StudentCopy\Friends$("Tom")
  Debug StudentCopy\Friends$("Jim")

Syntax
ClearStructure(*Pointer, Structure)
Description
ClearStructure clears a structured memory area. This is useful when the structure contains strings, array, list or map which have been allocated internally by PureBasic. This function is for advanced users and should be used with care.

Parameters

*Pointer The memory address containing the structure to be erased.
Structure The name of the structure which should be used to perform the clearing. All the fields will be set to zero, even native type like long, integer etc. There is no internal check to ensures the structure match the memory area.

Return value

None.

Example

  Structure People
    Name$
    LastName$
    Age.l
  EndStructure

  Student.People\Name$ = "Paul"
  Student\LastName$ = "Morito"
  Student\Age = 10
  
  ClearStructure(@Student, People)
  
  ; Will print empty strings as the whole structure has been cleared. All other fields have been reset to zero.
  ;
  Debug Student\Name$
  Debug Student\LastName$
  Debug Student\Age

Syntax
ResetStructure(*Pointer, Structure)
Description
ResetStructure clears a structured memory area and initialize it to be ready to use. This is useful when the structure contains strings, array, list or map which have been allocated internally by PureBasic. This function is for advanced users and should be used with care.

Parameters

*Pointer The memory address containing the structure to be reinitialized.
Structure The name of the structure which should be used to perform the clearing.

Return value

None.

Example

  Structure Person
    Map Friends.s()
  EndStructure

  Henry.Person\Friends("1") = "Paul"
  
  ResetStructure(@Henry, Person)
  
  ; Will print an empty string as the whole structure has been reset. The map is still usable but empty.
  ;
  Debug Henry\Friends("1")

Syntax
Result = Bool(<boolean expression>)
Description
Bool can be used to evaluate a boolean expression outside of regular conditional operator like If, While, Until etc.

Parameters

boolean expression The Boolean expression to test.

Return value

Returns #True if the boolean expression is true, #False otherwise.

Example

  Hello$ = "Hello"
  World$ = "World"

  Debug Bool(Hello$ = "Hello")  ; will print 1
  Debug Bool(Hello$ <> "Hello" Or World$ = "World") ; will print 1