Difference between revisions of "Documentation/DevGuide/ProUNO/Basic/Mapping of Simple Types"

From Apache OpenOffice Wiki
Jump to: navigation, search
m (FINAL VERSION FOR L10N)
m
 
Line 10: Line 10:
 
{{DISPLAYTITLE:Mapping of Simple Types}}
 
{{DISPLAYTITLE:Mapping of Simple Types}}
 
In general, the {{PRODUCTNAME}} Basic type system is not rigid. Unlike C++ and Java, {{PRODUCTNAME}} Basic does not require the declaration of variables, unless the <code>Option Explicit</code> command is used that forces the declaration. To declare variables, the <code>Dim</code> command is used. Also, a {{PRODUCTNAME}} Basic type can be optionally specified through the <code>Dim</code> command. The general syntax is:
 
In general, the {{PRODUCTNAME}} Basic type system is not rigid. Unlike C++ and Java, {{PRODUCTNAME}} Basic does not require the declaration of variables, unless the <code>Option Explicit</code> command is used that forces the declaration. To declare variables, the <code>Dim</code> command is used. Also, a {{PRODUCTNAME}} Basic type can be optionally specified through the <code>Dim</code> command. The general syntax is:
 
+
<source lang="oobas">
 
   Dim VarName [As Type][, VarName [As Type]]...
 
   Dim VarName [As Type][, VarName [As Type]]...
 
+
</source>
 
All variables declared without a specific type have the type <code>Variant</code>. Variables of type <code>Variant</code> can be assigned values of arbitrary Basic types. Undeclared variables are <code>Variant</code> unless type postfixes are used with their names. Postfixes can be used in <code>Dim</code> commands as well. The following table contains a complete list of types supported by Basic and their corresponding postfixes:
 
All variables declared without a specific type have the type <code>Variant</code>. Variables of type <code>Variant</code> can be assigned values of arbitrary Basic types. Undeclared variables are <code>Variant</code> unless type postfixes are used with their names. Postfixes can be used in <code>Dim</code> commands as well. The following table contains a complete list of types supported by Basic and their corresponding postfixes:
  
Line 73: Line 73:
  
 
Consider the following Dim examples.
 
Consider the following Dim examples.
 
+
<source lang="oobas">
 
   Dim a, b ' Type of a and b is Variant
 
   Dim a, b ' Type of a and b is Variant
 
   Dim c as Variant ' Type of c is Variant
 
   Dim c as Variant ' Type of c is Variant
Line 96: Line 96:
 
   Dim s$ ' is the same as
 
   Dim s$ ' is the same as
 
   Dim s as String
 
   Dim s as String
 
+
</source>
 
The correlation below is used to map types from UNO to Basic and vice versa.  
 
The correlation below is used to map types from UNO to Basic and vice versa.  
  
Line 153: Line 153:
  
 
When UNO methods or properties are accessed, and the target UNO type is known, Basic automatically chooses the appropriate types:
 
When UNO methods or properties are accessed, and the target UNO type is known, Basic automatically chooses the appropriate types:
 
+
<source lang="oobas">
 
   ' The UNO object oExample1 has a property "Count" of type short
 
   ' The UNO object oExample1 has a property "Count" of type short
 
   a% = 42
 
   a% = 42
Line 163: Line 163:
 
   s$ = "111"
 
   s$ = "111"
 
   oExample1.Count = s$ ' s$ will be converted to short, so Count will become 111
 
   oExample1.Count = s$ ' s$ will be converted to short, so Count will become 111
 
+
</source>
 
Occasionally, {{PRODUCTNAME}} Basic does not know the required target type, especially if a parameter of an interface method or a property has the type <code>any</code>. In this situation, {{PRODUCTNAME}} Basic mechanically converts the {{PRODUCTNAME}} Basic type into the UNO type shown in the table above, although a different type may be expected. The only mechanism provided by {{PRODUCTNAME}} Basic is an automatic downcast of numeric values:
 
Occasionally, {{PRODUCTNAME}} Basic does not know the required target type, especially if a parameter of an interface method or a property has the type <code>any</code>. In this situation, {{PRODUCTNAME}} Basic mechanically converts the {{PRODUCTNAME}} Basic type into the UNO type shown in the table above, although a different type may be expected. The only mechanism provided by {{PRODUCTNAME}} Basic is an automatic downcast of numeric values:
  
Line 176: Line 176:
  
 
In the following example, <code>oNameCont</code> is an object that supports <idl>com.sun.star.container.XNameContainer</idl> and contains elements of type <code>short</code>. Assume <code>FirstValue</code> is a valid entry.
 
In the following example, <code>oNameCont</code> is an object that supports <idl>com.sun.star.container.XNameContainer</idl> and contains elements of type <code>short</code>. Assume <code>FirstValue</code> is a valid entry.
 
+
<source lang="oobas">
 
   a% = 42
 
   a% = 42
 
   oNameCount.replaceByName( "FirstValue", a% ) ' Ok, a% is downcasted to type byte
 
   oNameCount.replaceByName( "FirstValue", a% ) ' Ok, a% is downcasted to type byte
Line 182: Line 182:
 
   b% = 123456
 
   b% = 123456
 
   oNameCount.replaceByName( "FirstValue", b% ) ' Fails, b% is outside the short range
 
   oNameCount.replaceByName( "FirstValue", b% ) ' Fails, b% is outside the short range
 
+
</source>
 
The method call fails, therefore the implementation should throw the appropriate exception that is converted to a {{PRODUCTNAME}} Basic error by the {{PRODUCTNAME}} Basic RTL. It may happen that an implementation also accepts unsuitable types and does not throw an exception. Ensure that the values used are suitable for their UNO target by using numeric values that do not exceed the target range or converting them to the correct Basic type before applying them to UNO.  
 
The method call fails, therefore the implementation should throw the appropriate exception that is converted to a {{PRODUCTNAME}} Basic error by the {{PRODUCTNAME}} Basic RTL. It may happen that an implementation also accepts unsuitable types and does not throw an exception. Ensure that the values used are suitable for their UNO target by using numeric values that do not exceed the target range or converting them to the correct Basic type before applying them to UNO.  
  
 
Always use the type <code>Variant</code> to declare variables for UNO Basic objects, ''not'' the type <code>Object</code>. The {{PRODUCTNAME}} Basic type <code>Object</code> is tailored for pure {{PRODUCTNAME}} Basic objects and not for UNO {{PRODUCTNAME}} Basic objects. The <code>Variant</code> variables are best for UNO Basic objects to avoid problems that can result from the {{PRODUCTNAME}} Basic specific behavior of the type <code>Object</code>:
 
Always use the type <code>Variant</code> to declare variables for UNO Basic objects, ''not'' the type <code>Object</code>. The {{PRODUCTNAME}} Basic type <code>Object</code> is tailored for pure {{PRODUCTNAME}} Basic objects and not for UNO {{PRODUCTNAME}} Basic objects. The <code>Variant</code> variables are best for UNO Basic objects to avoid problems that can result from the {{PRODUCTNAME}} Basic specific behavior of the type <code>Object</code>:
 
+
<source lang="oobas">
 
   Dim oService1 ' Ok
 
   Dim oService1 ' Ok
 
   oService1 = CreateUnoService( "com.sun.star.anywhere.Something" )
 
   oService1 = CreateUnoService( "com.sun.star.anywhere.Something" )
Line 192: Line 192:
 
   Dim oService2 as Object ' NOT recommended
 
   Dim oService2 as Object ' NOT recommended
 
   oService2 = CreateUnoService( "com.sun.star.anywhere.SomethingElse" )
 
   oService2 = CreateUnoService( "com.sun.star.anywhere.SomethingElse" )
 
+
</source>
  
 
{{PDL1}}
 
{{PDL1}}
  
 
[[Category:Documentation/Developer's Guide/Professional UNO]]
 
[[Category:Documentation/Developer's Guide/Professional UNO]]

Latest revision as of 11:07, 22 October 2009



In general, the OpenOffice.org Basic type system is not rigid. Unlike C++ and Java, OpenOffice.org Basic does not require the declaration of variables, unless the Option Explicit command is used that forces the declaration. To declare variables, the Dim command is used. Also, a OpenOffice.org Basic type can be optionally specified through the Dim command. The general syntax is:

  Dim VarName [As Type][, VarName [As Type]]...

All variables declared without a specific type have the type Variant. Variables of type Variant can be assigned values of arbitrary Basic types. Undeclared variables are Variant unless type postfixes are used with their names. Postfixes can be used in Dim commands as well. The following table contains a complete list of types supported by Basic and their corresponding postfixes:

Type Postfix Range
Boolean True or False
Integer  % -32768 to 32767
Long & -2147483648 to 2147483647
Single  ! Floating point number

negative: -3.402823E38 to -1.401298E-45

positive: 1.401298E-45 to 3.402823E38

Double # Double precision floating point number

negative: -1.79769313486232E308 to -4.94065645841247E-324

positive: 4.94065645841247E-324 to 1.79769313486232E308

Currency @ Fixed point number with four decimal places

-922,337,203,685,477.5808 to 922,337,203,685,477.5807

Date 01/01/100 to 12/31/9999
Object Basic Object
String $ Character string
Variant arbitrary Basic type

Consider the following Dim examples.

  Dim a, b ' Type of a and b is Variant
  Dim c as Variant ' Type of c is Variant
 
  Dim d as Integer ' Type of d is Integer (16 bit!)
 
  ' The type only refers to the preceding variable
  Dim e, f as Double ' ATTENTION! Type of e is Variant!
  ' Only the type of f is Double
 
  Dim g as String ' Type of g is String
 
  Dim h as Date ' Type of h is Date
 
  ' Usage of Postfixes
  Dim i% ' is the same as
  Dim i as Integer
 
  Dim d# ' is the same as
  Dim d as Double
 
  Dim s$ ' is the same as
  Dim s as String

The correlation below is used to map types from UNO to Basic and vice versa.

UNO Basic
void internal type
boolean Boolean
byte Integer
short Integer
unsigned short internal type
long Long
unsigned long internal type
hyper internal type
unsigned hyper internal type
float Single
double Double
char internal type
string String
type com.sun.star.reflection.XIdlClass
any Variant

The simple UNO type type is mapped to the com.sun.star.reflection.XIdlClass interface to retrieve type specific information. For further details, refer to UNO Reflection API.

When UNO methods or properties are accessed, and the target UNO type is known, Basic automatically chooses the appropriate types:

  ' The UNO object oExample1 has a property "Count" of type short
  a% = 42
  oExample1.Count = a% ' a% has the right type (Integer)
 
  pi = 3,141593
  oExample1.Count = pi ' pi will be converted to short, so Count will become 3
 
  s$ = "111"
  oExample1.Count = s$ ' s$ will be converted to short, so Count will become 111

Occasionally, OpenOffice.org Basic does not know the required target type, especially if a parameter of an interface method or a property has the type any. In this situation, OpenOffice.org Basic mechanically converts the OpenOffice.org Basic type into the UNO type shown in the table above, although a different type may be expected. The only mechanism provided by OpenOffice.org Basic is an automatic downcast of numeric values:

Long and Integer values are always converted to the shortest possible integer type:

  • to byte if -128 <= Value <= 127
  • to short if -32768 <= Value <= 32767

The Single/Double values are converted to integers in the same manner if they have no decimal places.

This mechanism is used, because some internal C++ tools used to implement UNO functionality in OpenOffice.org provide an automatic upcast but no downcast. Therefore, it can be successful to pass a byte value to an interface expecting a long value, but not vice versa.

In the following example, oNameCont is an object that supports com.sun.star.container.XNameContainer and contains elements of type short. Assume FirstValue is a valid entry.

  a% = 42
  oNameCount.replaceByName( "FirstValue", a% ) ' Ok, a% is downcasted to type byte
 
  b% = 123456
  oNameCount.replaceByName( "FirstValue", b% ) ' Fails, b% is outside the short range

The method call fails, therefore the implementation should throw the appropriate exception that is converted to a OpenOffice.org Basic error by the OpenOffice.org Basic RTL. It may happen that an implementation also accepts unsuitable types and does not throw an exception. Ensure that the values used are suitable for their UNO target by using numeric values that do not exceed the target range or converting them to the correct Basic type before applying them to UNO.

Always use the type Variant to declare variables for UNO Basic objects, not the type Object. The OpenOffice.org Basic type Object is tailored for pure OpenOffice.org Basic objects and not for UNO OpenOffice.org Basic objects. The Variant variables are best for UNO Basic objects to avoid problems that can result from the OpenOffice.org Basic specific behavior of the type Object:

  Dim oService1 ' Ok
  oService1 = CreateUnoService( "com.sun.star.anywhere.Something" )
 
  Dim oService2 as Object ' NOT recommended
  oService2 = CreateUnoService( "com.sun.star.anywhere.SomethingElse" )
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages