libcore/as_value.h

   1 //
   2 //   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010 Free Software
   3 //   Foundation, Inc
   4 //
   5 // This program is free software; you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation; either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // This program is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with this program; if not, write to the Free Software
  17 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  18
  19 #ifndef GNASH_AS_VALUE_H
  20 #define GNASH_AS_VALUE_H
  21
  22 #include "dsodefs.h"
  23 #include "CharacterProxy.h"
  24
  25 #include <limits>
  26 #include <string>
  27 #include <boost/variant.hpp>
  28 #include <ostream> // for inlined output operator
  29 #include <boost/type_traits/is_floating_point.hpp>
  30 #include <boost/utility/enable_if.hpp>
  31 #include <boost/cstdint.hpp>
  32
  33 #include "utility.h" // UNUSED
  34
  35 // Forward declarations
  36 namespace gnash {
  37     class VM;
  38         class as_object;
  39         class Global_as;
  40         class fn_call;
  41         class as_function;
  42         class MovieClip;
  43         class DisplayObject;
  44     namespace amf {
  45         class Writer;
  46     }
  47 }
  48
  49 namespace gnash {
  50
  51
  52 // NaN constant for use in as_value implementation
  53 static const double NaN = std::numeric_limits<double>::quiet_NaN();
  54
  55 // The following template works just like its C counterpart, with added
  56 // type safety (i.e., they will only compile for floating point arguments).
  57 template <typename T>
  58 inline bool
  59 isNaN(const T& num, typename boost::enable_if<boost::is_floating_point<T> >::
  60         type* dummy = 0)
  61 {
  62         UNUSED(dummy);
  63         return num != num;
  64 }
  65
  66 template <typename T>
  67 inline bool
  68 isInf(const T& num)
  69 {
  70         return isNaN(num - num);
  71 }
  72
  73
  74 /// These are the primitive types, see the ECMAScript reference.
  75 enum primitive_types
  76 {
  77         PTYPE_STRING,
  78         PTYPE_NUMBER,
  79         PTYPE_BOOLEAN
  80 };
  81
  82 /// ActionScript value type.
  83 //
  84 /// The as_value class can store basic ActionScript types.
  85 //
  86 /// These are the primitive types (Number, Boolean, String, null, and
  87 /// undefined), as well as complex types (Object and DisplayObject).
  88 //
  89 /// Most type handling is hidden within the class. There are two different
  90 /// types of access to the as_value: converting and non-converting.
  91 //
  92 /// Non-converting access
  93 /// Non-converting access is available for the complex types, for instance
  94 /// to_function() and toMovieClip(). In these cases, an object pointer is
  95 /// return only if the as_value is currently of the requested type. There
  96 /// are no ActionScript side-effects in such cases.
  97 //
  98 /// Converting access
  99 /// The primitive types and Objects have converting access. This means that
 100 /// as_values of a different type are converted to the requested type. These
 101 /// functions may have ActionScript side-effects, for instance the calling of
 102 /// toString or valueOf, or construction of an object.
 103 //
 104 /// It is possible to check the current type of an as_value using is_string(),
 105 /// is_number() etc. These functions have no ActionScript side effects.
 106 class as_value
 107 {
 108
 109 public:
 110
 111     // The exception type should always be one greater than the normal type.
 112     enum AsType
 113     {
 114         UNDEFINED,
 115         UNDEFINED_EXCEPT,
 116         NULLTYPE,
 117         NULLTYPE_EXCEPT,
 118         BOOLEAN,
 119         BOOLEAN_EXCEPT,
 120         STRING,
 121         STRING_EXCEPT,
 122         NUMBER,
 123         NUMBER_EXCEPT,
 124         OBJECT,
 125         OBJECT_EXCEPT,
 126         DISPLAYOBJECT,
 127         DISPLAYOBJECT_EXCEPT
 128     };
 129
 130     /// Construct an undefined value
 131     DSOEXPORT as_value()
 132         :
 133         _type(UNDEFINED),
 134         _value(boost::blank())
 135     {
 136     }
 137
 138     /// Copy constructor.
 139     DSOEXPORT as_value(const as_value& v)
 140         :
 141         _type(v._type),
 142         _value(v._value)
 143     {
 144     }
 145
 146     ~as_value() {}
 147
 148     /// Construct a primitive String value
 149     DSOEXPORT as_value(const char* str)
 150         :
 151         _type(STRING),
 152         _value(std::string(str))
 153     {}
 154
 155     /// Construct a primitive String value
 156     DSOEXPORT as_value(const std::string& str)
 157         :
 158         _type(STRING),
 159         _value(std::string(str))
 160     {}
 161
 162     /// Construct a primitive Boolean value
 163     template <typename T>
 164     as_value(T val, typename boost::enable_if<boost::is_same<bool, T> >::type*
 165              dummy = 0)
 166         :
 167         _type(BOOLEAN),
 168         _value(val)
 169         {
 170         UNUSED(dummy);
 171         }
 172
 173     /// Construct a primitive Number value
 174     as_value(double num)
 175         :
 176         _type(NUMBER),
 177         _value(num)
 178     {}
 179
 180     /// Construct a null, Object, or DisplayObject value
 181     as_value(as_object* obj)
 182         :
 183         _type(UNDEFINED)
 184     {
 185         set_as_object(obj);
 186     }
 187
 188     /// Assign to an as_value.
 189     DSOEXPORT as_value& operator=(const as_value& v)
 190     {
 191         _type = v._type;
 192         _value = v._value;
 193         return *this;
 194     }
 195
 196     friend std::ostream& operator<<(std::ostream& o, const as_value&);
 197
 198     /// Return the primitive type of this value as a string.
 199     const char* typeOf() const;
 200
 201     /// Return true if this value is a function
 202     bool is_function() const;
 203
 204     /// Return true if this value is a string
 205     bool is_string() const {
 206         return _type == STRING;
 207     }
 208
 209     /// Return true if this value is strictly a number
 210     bool is_number() const {
 211         return _type == NUMBER;
 212     }
 213
 214     /// Return true if this value is an object
 215     //
 216     /// Both DisplayObjects and Objects count as Objects
 217     bool is_object() const {
 218         return _type == OBJECT || _type == DISPLAYOBJECT;
 219     }
 220
 221     /// Return true if this value is a DISPLAYOBJECT
 222     bool is_sprite() const {
 223         return _type == DISPLAYOBJECT;
 224     }
 225
 226     /// Get a std::string representation for this value.
 227     //
 228     /// @param version      The SWF version to use to transform the string.
 229     ///                     This only affects undefined values, which trace
 230     ///                     "undefined" for version 7 and above, nothing
 231     ///                     for lower versions.
 232     //
 233     /// TODO: drop the default argument.
 234     std::string to_string(int version = 7) const;
 235
 236     /// Get a number representation for this value
 237     //
 238     /// This function performs conversion if necessary.
 239     double to_number(int version) const;
 240
 241     /// Conversion to boolean.
 242     //
 243     /// This function performs conversion if necessary.
 244     bool to_bool(int version) const;
 245
 246     /// Return value as an object, converting primitive values as needed.
 247     //
 248     /// This function performs conversion where necessary.
 249     //
 250     /// string values are converted to String objects
 251     /// numeric values are converted to Number objects
 252     /// boolean values are converted to Boolean objects
 253     ///
 254     /// If you want to avoid the conversion, check with is_object() before
 255     /// calling this function.
 256     //
 257     /// @param global   The global object object for the conversion. This
 258     ///                 contains the prototypes or constructors necessary for
 259     ///                 conversion.
 260     as_object* to_object(VM& vm) const;
 261
 262     /// Return the value as an as_object only if it is an as_object.
 263     //
 264     /// Note that this performs no conversion, so returns 0 if the as_value
 265     /// is not an object.
 266     as_object* get_object() const;
 267
 268     /// Returns value as a MovieClip if it is a MovieClip.
 269     //
 270     /// This function performs no conversion, so returns 0 if the as_value is
 271     /// not a MovieClip.
 272     //
 273     /// This is just a wrapper around toDisplayObject() performing
 274     /// an additional final cast.
 275     MovieClip* toMovieClip(bool skipRebinding = false) const;
 276
 277     /// Return value as a DisplayObject or NULL if this is not possible.
 278     //
 279     /// Note that this function performs no conversion, so returns 0 if the
 280     /// as_value is not a DisplayObject.
 281     //
 282     /// If the value is a DisplayObject value, the stored DisplayObject target
 283     /// is evaluated using the root movie's environment.
 284     /// If the target points to something that doesn't cast to a DisplayObject,
 285     /// 0 is returned.
 286     ///
 287     /// @param skipRebinding    If true a reference to a destroyed
 288     ///                         DisplayObject is still returned, rather than
 289     ///                         attempting to resolve it as a soft-reference.
 290     ///                         Main use for this is during paths resolution,
 291     ///                         to avoid infinite loops. See bug #21647.
 292     DisplayObject* toDisplayObject(bool skipRebinding = false) const;
 293
 294     /// Return the value as a function only if it is a function.
 295     //
 296     /// Note that this performs no conversion, so returns 0 if the as_value
 297     /// is not a function.
 298     as_function* to_function() const;
 299
 300     AsType defaultPrimitive(int version) const;
 301
 302     /// Return value as a primitive type, with a preference
 303     //
 304     /// This function performs no conversion.
 305     //
 306     /// Primitive types are: undefined, null, boolean, string, number.
 307     /// See ECMA-2.6.2 (sections 4.3.2 and 8.6.2.6).
 308     ///
 309     /// @param hint
 310     ///         NUMBER or STRING, the preferred representation we're asking for.
 311     ///
 312     /// @throw ActionTypeError if an object can't be converted to a primitive
 313     ///
 314     as_value to_primitive(AsType hint) const;
 315
 316     /// Set to a primitive string.
 317     void set_string(const std::string& str);
 318
 319     /// Set to a primitive number.
 320     void set_double(double val);
 321
 322     /// Set to a primitive boolean.
 323     void set_bool(bool val);
 324
 325     /// Make this value a NULL, OBJECT, DISPLAYOBJECT value
 326     void set_as_object(as_object* obj);
 327
 328     /// Set to undefined.
 329     void set_undefined();
 330
 331     /// Set this value to the NULL value
 332     void set_null();
 333
 334     bool is_undefined() const {
 335         return (_type == UNDEFINED);
 336     }
 337
 338     bool is_null() const {
 339         return (_type == NULLTYPE);
 340     }
 341
 342     bool is_bool() const {
 343         return (_type == BOOLEAN);
 344     }
 345
 346     bool is_exception() const {
 347         return (_type == UNDEFINED_EXCEPT || _type == NULLTYPE_EXCEPT
 348                 || _type == BOOLEAN_EXCEPT || _type == NUMBER_EXCEPT
 349                 || _type == OBJECT_EXCEPT || _type == DISPLAYOBJECT_EXCEPT
 350                 || _type == STRING_EXCEPT);
 351     }
 352
 353     // Flag or unflag an as_value as an exception -- this gets flagged
 354     // when an as_value is 'thrown'.
 355     void flag_exception() {
 356         if (!is_exception()) {
 357             _type = static_cast<AsType>(static_cast<int>(_type) + 1);
 358         }
 359     }
 360
 361     void unflag_exception() {
 362         if (is_exception()) {
 363             _type = static_cast<AsType>(static_cast<int>(_type) - 1);
 364         }
 365     }
 366
 367     /// Return true if this value is strictly equal to the given one
 368     //
 369     /// Strict equality is defined as the two values being of the
 370     /// same type and the same value.
 371     bool strictly_equals(const as_value& v) const;
 372
 373     /// Return true if this value is abstractly equal to the given one
 374     //
 375     /// See ECMA-262 abstract equality comparison (sect 11.9.3)
 376     ///
 377     /// NOTE: these invariants should hold
 378     ///
 379     /// - A != B is equivalent to ! ( A == B )
 380     /// - A == B is equivalent to B == A, except for order of
 381     ///   evaluation of A and B.
 382     ///
 383     /// @param v     The as_value to compare to
 384     bool equals(const as_value& v, int version) const;
 385
 386     /// Set any object value as reachable (for the GC)
 387     //
 388     /// Object values are values stored by pointer (objects and functions)
 389     void setReachable() const;
 390
 391     /// Serialize value in AMF0 format.
 392     //
 393     /// @param buf
 394     ///     The buffer to append serialized version of this value to.
 395     ///
 396     /// @param offsetTable
 397     ///     A map of already-parsed objects, pass an empty map on first call as
 398     ///     it will be used internally.
 399     ///
 400     /// @param vm
 401     ///     Virtual machine to use for serialization of property names
 402     ///     (string_table)
 403     ///
 404     /// @param allowStrictArray
 405     ///     If true strict arrays will be encoded a STRICT_ARRAY types.
 406     ///
 407     bool writeAMF0(amf::Writer& w) const;
 408
 409 private:
 410
 411     /// AsValueType handles the following AS types:
 412     //
 413     /// 1. undefined / null
 414     /// 2. Number
 415     /// 3. Boolean
 416     /// 4. Object
 417     /// 5. MovieClip
 418     /// 6. String
 419     typedef boost::variant<boost::blank,
 420                            double,
 421                            bool,
 422                            as_object*,
 423                            CharacterProxy,
 424                            std::string>
 425     AsValueType;
 426
 427     /// Use the relevant equality function, not operator==
 428     bool operator==(const as_value& v) const;
 429
 430     /// Use the relevant inequality function, not operator!=
 431     bool operator!=(const as_value& v) const;
 432
 433     /// Compare values of the same type
 434     //
 435     /// NOTE: will abort if values are not of the same type!
 436     ///
 437     bool equalsSameType(const as_value& v) const;
 438
 439     AsType _type;
 440
 441     AsValueType _value;
 442
 443     /// Get the object pointer variant member.
 444     //
 445     /// Callers must check that this is an Object (including DisplayObjects).
 446     as_object* getObj() const;
 447
 448     /// Get the DisplayObject variant member.
 449     //
 450     /// The caller must check that this is a DisplayObject.
 451     DisplayObject* getCharacter(bool skipRebinding = false) const;
 452
 453     /// Get the DisplayObject proxy variant member.
 454     //
 455     /// The caller must check that this value is a DisplayObject
 456     CharacterProxy getCharacterProxy() const;
 457
 458     /// Get the number variant member.
 459     //
 460     /// The caller must check that this value is a Number.
 461     double getNum() const {
 462         assert(_type == NUMBER);
 463         return boost::get<double>(_value);
 464     }
 465
 466     /// Get the boolean variant member.
 467     //
 468     /// The caller must check that this value is a Boolean.
 469     bool getBool() const {
 470         assert(_type == BOOLEAN);
 471         return boost::get<bool>(_value);
 472     }
 473
 474     /// Get the boolean variant member.
 475     //
 476     /// The caller must check that this value is a String.
 477     const std::string& getStr() const {
 478         assert(_type == STRING);
 479         return boost::get<std::string>(_value);
 480     }
 481
 482 };
 483
 484 /// Stream operator.
 485 std::ostream& operator<<(std::ostream& os, const as_value& v);
 486
 487 /// Convert numeric value to string value, following ECMA-262 specification
 488 //
 489 // Printing formats:
 490 //
 491 // If _val > 1, Print up to 15 significant digits, then switch
 492 // to scientific notation, rounding at the last place and
 493 // omitting trailing zeroes.
 494 // For values < 1, print up to 4 leading zeroes after the
 495 // decimal point, then switch to scientific notation with up
 496 // to 15 significant digits, rounding with no trailing zeroes
 497 // If the value is negative, just add a '-' to the start; this
 498 // does not affect the precision of the printed value.
 499 //
 500 // This almost corresponds to iomanip's std::setprecision(15)
 501 // format, except that iomanip switches to scientific notation
 502 // at e-05 not e-06, and always prints at least two digits for the exponent.
 503 std::string doubleToString(double val, int radix = 10);
 504
 505 /// Try to parse a string into a 32-bit signed int using base 8 or 16.  //
 506 /// This function will throw a boost::bad_lexical_cast (or a derived
 507 /// exception) if the passed string cannot be converted.
 508 //
 509 /// @param s      The string to parse
 510 /// @param d      The 32-bit int represented as a double. This is only a
 511 ///               valid number if the return value is true.
 512 /// @param whole  If true, expect the whole string to be valid, i.e.
 513 ///               throw if there are any invalid DisplayObjects. If false,
 514 ///               returns any valid number up to the first invalid
 515 ///               DisplayObject.
 516 /// @return       True if the string was non-decimal and successfully
 517 ///               parsed.
 518 bool parseNonDecimalInt(const std::string& s, double& d, bool whole = true);
 519
 520 /// Set a value to NaN
 521 inline void
 522 setNaN(as_value& v) {
 523     v.set_double(NaN);
 524 }
 525
 526 } // namespace gnash
 527
 528 #endif // GNASH_AS_VALUE_H
 529
 530 // Local Variables:
 531 // mode: C++
 532 // indent-tabs-mode: nil
 533 // End:
 534