Rename WebKitTools to Tools
[WebKit-https.git] / Tools / DumpRenderTree / chromium / CppVariant.h
1 /*
2  * Copyright (C) 2010 Google Inc. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are
6  * met:
7  *
8  *     * Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  *     * Redistributions in binary form must reproduce the above
11  * copyright notice, this list of conditions and the following disclaimer
12  * in the documentation and/or other materials provided with the
13  * distribution.
14  *     * Neither the name of Google Inc. nor the names of its
15  * contributors may be used to endorse or promote products derived from
16  * this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30
31 /*
32   This file contains the declaration for CppVariant, a type used by C++ classes
33   that are to be bound to JavaScript objects.
34
35   CppVariant exists primarily as an interface between C++ callers and the
36   corresponding NPVariant type.  CppVariant also provides a number of
37   convenience constructors and accessors, so that the NPVariantType values
38   don't need to be exposed, and a destructor to free any memory allocated for
39   string values.
40 */
41
42 #ifndef CppVariant_h
43 #define CppVariant_h
44
45 #include "WebBindings.h"
46 #include "webkit/support/webkit_support.h"
47 #include <string>
48 #include <wtf/Vector.h>
49
50 class CppVariant : public NPVariant {
51 public:
52     CppVariant();
53     ~CppVariant();
54     void setNull();
55     void set(bool);
56     void set(int32_t);
57     void set(double);
58
59     // Note that setting a CppVariant to a string value involves copying the
60     // string data, which must be freed with a call to freeData() when the
61     // CppVariant is set to a different value or is no longer needed.  Normally
62     // this is handled by the other set() methods and by the destructor.
63     void set(const char*); // Must be a null-terminated string.
64     void set(const std::string&);
65     void set(const NPString&);
66     void set(const NPVariant&);
67
68     // Note that setting a CppVariant to an NPObject involves ref-counting
69     // the actual object. freeData() should only be called if the CppVariant
70     // is no longer needed. The other set() methods handle this internally.
71     // Also, the object's NPClass is expected to be a static object: neither
72     // the NP runtime nor CppVariant will ever free it.
73     void set(NPObject*_value);
74
75     // These three methods all perform deep copies of any string data.  This
76     // allows local CppVariants to be released by the destructor without
77     // corrupting their sources. In performance-critical code, or when strings
78     // are very long, avoid creating new CppVariants.
79     // In case of NPObject as the data, the copying involves ref-counting
80     // as opposed to deep-copying. The ref-counting ensures that sources don't
81     // get corrupted when the copies get destroyed.
82     void copyToNPVariant(NPVariant* result) const;
83     CppVariant& operator=(const CppVariant& original);
84     CppVariant(const CppVariant& original);
85
86     // Calls NPN_ReleaseVariantValue, which frees any string data
87     // held by the object and sets its type to null.
88     // In case of NPObject, the NPN_ReleaseVariantValue decrements
89     // the ref-count (releases when ref-count becomes 0)
90     void freeData();
91
92     // Compares this CppVariant's type and value to another's.  They must be
93     // identical in both type and value to be considered equal.  For string and
94     // object types, a deep comparison is performed; that is, the contents of the
95     // strings, or the classes and refcounts of the objects, must be the same,
96     // but they need not be the same pointers.
97     bool isEqual(const CppVariant&) const;
98
99     // The value of a CppVariant may be read directly from its NPVariant (but
100     // should only be set using one of the set() methods above). Although the
101     // type of a CppVariant is likewise public, it can be accessed through these
102     // functions rather than directly if a caller wishes to avoid dependence on
103     // the NPVariantType values.
104     bool isBool() const { return (type == NPVariantType_Bool); }
105     bool isInt32() const { return (type == NPVariantType_Int32); }
106     bool isDouble() const { return (type == NPVariantType_Double); }
107     bool isNumber() const { return (isInt32() || isDouble()); }
108     bool isString() const { return (type == NPVariantType_String); }
109     bool isVoid() const { return (type == NPVariantType_Void); }
110     bool isNull() const { return (type == NPVariantType_Null); }
111     bool isEmpty() const { return (isVoid() || isNull()); }
112     bool isObject() const { return (type == NPVariantType_Object); }
113
114     // Converters.  The CppVariant must be of a type convertible to these values.
115     // For example, toInt32() works only if isNumber() is true.
116     std::string toString() const;
117     int32_t toInt32() const;
118     double toDouble() const;
119     bool toBoolean() const;
120     // Returns a vector of strings for the specified argument. This is useful
121     // for converting a JavaScript array of strings into a vector of strings.
122     Vector<std::string> toStringVector() const;
123
124     // Invoke method of the given name on an object with the supplied arguments.
125     // The first argument should be the object on which the method is to be
126     // invoked.  Returns whether the method was successfully invoked.  If the
127     // method was invoked successfully, any return value is stored in the
128     // CppVariant specified by result.
129     bool invoke(const std::string&, const CppVariant* arguments,
130                 uint32_t argumentCount, CppVariant& result) const;
131 };
132
133 #endif // CppVariant_h