Compiler Functions

Size = SizeOf(Type)

SizeOf can be used to find out the size of any Structure (it does not work on the simple built-in types such as word, float etc.), Interface or even variables. This can be useful in many areas such as calculating memory requirements for operations, using API commands. As SizeOf is a compile time function, it doesn't work with runtime Array, List or Map. ArraySize(), ListSize() or MapSize() can be used instead.

Note: In unicode mode one character uses 2 bytes. In Ascii mode one character uses 1 byte. Sizeof(Character) allows to return the size (in bytes), which is taken by one character according to the active mode.

Example

  Structure Person
    Name.s
    ForName.s 
    Age.w 
  EndStructure
  
  Debug "The size of my friend is "+Str(Sizeof(Person))+" bytes" ; will be 10 (4+4+2)
  
  John.Person\Name = "John"
  
  Debug SizeOf(John) ; will be also 10 

Note: if a variable and a structure have the same name, the structure will have the priority over the variable.

Index = OffsetOf(Structure\Field)
Index = OffsetOf(Interface\Function())

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

Example

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

Type = TypeOf(Object)

TypeOf can be used to find out the type of a variable, or a structure field. 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  

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

Result = Subsystem(<constant string expression>)

Subsystem can be used to find out if a subsystem is in use for the program being compiled. The name of the subsystem is case sensitive.

Example

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

Result = Defined(Name, Type)

Defined checks if a particular object of a code source like structure, interface, variables etc. is already defined or not. 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).

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

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

InitializeStructure(*Pointer, Structure)

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). '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()().

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

CopyStructure(*Source, *Destination, Structure)

CopyStructure copy the memory of a structured memory area to another. This is useful when dealing with dynamic allocations, trough 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.

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")

ClearStructure(*Pointer, Structure)

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. 'Structure' is 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. This function is for advanced users and should be used with care.

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

ResetStructure(*Pointer, Structure)

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. 'Structure' is the name of the structure which should be used to perform the clearing. This function is for advanced users and should be used with care.

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 reseted. The map is still usable but empty.
  ;
  Debug Henry\Friends("1")

Bool(<boolean expression>)

Bool can be used to evaluate a boolean expression outside of regular conditional operator like If, While, Until etc. If the boolean expression is true, it will return #True, otherwise it will return #False.

Example

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

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