php-doc-en/reference/com/functions/class.variant.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/com.xml, last change in rev 1.7 -->
 <refentry xml:id="class.variant" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>VARIANT</refname>
   <refpurpose>VARIANT class</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
  <synopsis>$vVar = new <classname>VARIANT</classname>($var)</synopsis>
  </refsynopsisdiv>
  <refsect1 xml:id="class.variant.class">
   <title>Description</title>
   <simpara>
    The VARIANT is COM's equivalent of the PHP zval; it is a structure that
    can contain a value with a range of different possible types.  The VARIANT
    class provided by the COM extension allows you to have more control over
    the way that PHP passes values to and from COM.
   </simpara>
  </refsect1>
  <refsect1 xml:id="class.variant.constructor">
   <title>Methods</title>
    <methodsynopsis>
     <type>object</type><methodname>VARIANT::VARIANT</methodname>
     <methodparam choice="opt"><type>mixed</type><parameter>value</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>type</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>codepage</parameter></methodparam>
    </methodsynopsis>
   <para>
    VARIANT class constructor. Parameters:
    <variablelist>
    <varlistentry><term>value</term>
    <listitem>
     <simpara>
      initial value. if omitted, or set to &null; an VT_EMPTY object is created.
     </simpara>
    </listitem>
    </varlistentry>
    <varlistentry><term>type</term>
    <listitem>
     <simpara>
      specifies the content type of the VARIANT object. Possible values are
      one of the <constant>VT_XXX</constant> <xref
      linkend="com.constants"/>.
     </simpara>
     <simpara>
      In PHP versions prior to PHP 5, you could force PHP to pass a variant
      object by reference by OR'ing <constant>VT_BYREF</constant>
      with the <parameter>type</parameter>.  In PHP 5, this hack is not
      supported; instead, PHP 5 can detect parameters passed by reference
      automatically; they do not even need to be passed as VARIANT objects.
     </simpara>
     <simpara>
      Consult the <acronym>MSDN</acronym> library for additional information
      on the VARIANT type.
     </simpara>
    </listitem>
    </varlistentry>
    <varlistentry><term>codepage</term>
    <listitem>
     <simpara>
      specifies the codepage that is used to convert strings to
      unicode.  See the parameter of the same name in the 
      <xref linkend="class.com"/> class for more information.
     </simpara>
    </listitem>
    </varlistentry>
    </variablelist>
   </para>

   <para>
    PHP versions prior to PHP 5 define a number of (undocumented) virtual properties
    for instances of the VARIANT class; these properties have all been removed in
    PHP 5 in favour of its more natural syntax; these differences are best
    highlighted by example:
   </para>

   <para>
    <example xml:id="com.variant.example.php4">
     <title>Variant example, PHP 4.x style</title>
     <programlisting role="php">
<![CDATA[
<?php
$v = new VARIANT(42);
print "The type is " . $v->type . "<br/>";
print "The value is " . $v->value . "<br/>";
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example xml:id="com.variant.example.php5">
     <title>Variant example, PHP 5 style</title>
     <programlisting role="php">
<![CDATA[
<?php
$v = new VARIANT(42);
print "The type is " . variant_get_type($v) . "<br/>";
print "The value is " . $v . "<br/>";
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    The reason for the change is that, internally, the COM extension sees
    VARIANT, COM and DOTNET classes as the same thing, and the design
    philosophy for these classes is that all property and member accesses are
    passed through to COM with no interference.  The new syntax is more
    natural and less effort, and most of the removed virtual properties didn't
    make any sense in a PHP context in any case.
   </para>

   <note>
    <para>
     PHP 5 takes a much simpler approach to handling VARIANTs; when returning
     a value or fetching a variant property, the variant is converted to a PHP
     value only when there is a direct mapping between the types that would
     not result in a loss of information.  In all other cases, the result is
     returned as an instance of the VARIANT class.  You can force PHP to
     convert or evaluate the variant as a PHP native type by using a casting
     operator explicitly, or implicitly casting to a string by
     <function>print</function>ing it.  You may use the wide range of variant
     functions to perform arithmetic operations on variants without forcing a
     conversion or risking a loss of data.
    </para>
   </note>

   <para>
    See also <function>variant_get_type</function>.
   </para>
     
  </refsect1>
 </refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->