Commit bdb828c9 authored by Anna Henningsen's avatar Anna Henningsen Committed by Commit Bot

[api] Various improvements to documentation

This improves documentation about some things that came up
in conversation and things that I noticed while working on
those other things. :)

Change-Id: I4f47cec6594f7b331259bea8ed506f5de908d438
Reviewed-on: https://chromium-review.googlesource.com/c/v8/v8/+/1954386
Commit-Queue: Ulan Degenbaev <ulan@chromium.org>
Reviewed-by: 's avatarToon Verwaest <verwaest@chromium.org>
Reviewed-by: 's avatarUlan Degenbaev <ulan@chromium.org>
Cr-Commit-Position: refs/heads/master@{#65449}
parent 2f205f5a
......@@ -216,9 +216,13 @@ class Local {
/**
* Checks whether two handles are the same.
* Returns true if both are empty, or if the objects
* to which they refer are identical.
* The handles' references are not checked.
* Returns true if both are empty, or if the objects to which they refer
* are identical.
*
* If both handles refer to JS objects, this is the same as strict equality.
* For primitives, such as numbers or strings, a `false` return value does not
* indicate that the values aren't equal in the JavaScript sense.
* Use `Value::StrictEquals()` to check primitives for equality.
*/
template <class S>
V8_INLINE bool operator==(const Local<S>& that) const {
......@@ -242,7 +246,11 @@ class Local {
* Checks whether two handles are different.
* Returns true if only one of the handles is empty, or if
* the objects to which they refer are different.
* The handles' references are not checked.
*
* If both handles refer to JS objects, this is the same as strict
* non-equality. For primitives, such as numbers or strings, a `true` return
* value does not indicate that the values aren't equal in the JavaScript
* sense. Use `Value::StrictEquals()` to check primitives for equality.
*/
template <class S>
V8_INLINE bool operator!=(const Local<S>& that) const {
......@@ -2487,12 +2495,16 @@ class V8_EXPORT Value : public Data {
/**
* Returns true if this value is the undefined value. See ECMA-262
* 4.3.10.
*
* This is equivalent to `value === undefined` in JS.
*/
V8_INLINE bool IsUndefined() const;
/**
* Returns true if this value is the null value. See ECMA-262
* 4.3.11.
*
* This is equivalent to `value === null` in JS.
*/
V8_INLINE bool IsNull() const;
......@@ -2500,37 +2512,56 @@ class V8_EXPORT Value : public Data {
* Returns true if this value is either the null or the undefined value.
* See ECMA-262
* 4.3.11. and 4.3.12
*
* This is equivalent to `value == null` in JS.
*/
V8_INLINE bool IsNullOrUndefined() const;
/**
* Returns true if this value is true.
*/
* Returns true if this value is true.
*
* This is not the same as `BooleanValue()`. The latter performs a
* conversion to boolean, i.e. the result of `Boolean(value)` in JS, whereas
* this checks `value === true`.
*/
bool IsTrue() const;
/**
* Returns true if this value is false.
*
* This is not the same as `!BooleanValue()`. The latter performs a
* conversion to boolean, i.e. the result of `!Boolean(value)` in JS, whereas
* this checks `value === false`.
*/
bool IsFalse() const;
/**
* Returns true if this value is a symbol or a string.
*
* This is equivalent to
* `typeof value === 'string' || typeof value === 'symbol'` in JS.
*/
bool IsName() const;
/**
* Returns true if this value is an instance of the String type.
* See ECMA-262 8.4.
*
* This is equivalent to `typeof value === 'string'` in JS.
*/
V8_INLINE bool IsString() const;
/**
* Returns true if this value is a symbol.
*
* This is equivalent to `typeof value === 'symbol'` in JS.
*/
bool IsSymbol() const;
/**
* Returns true if this value is a function.
*
* This is equivalent to `typeof value === 'function'` in JS.
*/
bool IsFunction() const;
......@@ -2547,21 +2578,27 @@ class V8_EXPORT Value : public Data {
/**
* Returns true if this value is a bigint.
*
* This is equivalent to `typeof value === 'bigint'` in JS.
*/
bool IsBigInt() const;
/**
* Returns true if this value is boolean.
*
* This is equivalent to `typeof value === 'boolean'` in JS.
*/
bool IsBoolean() const;
/**
* Returns true if this value is a number.
*
* This is equivalent to `typeof value === 'number'` in JS.
*/
bool IsNumber() const;
/**
* Returns true if this value is external.
* Returns true if this value is an `External` object.
*/
bool IsExternal() const;
......@@ -2763,22 +2800,57 @@ class V8_EXPORT Value : public Data {
*/
bool IsModuleNamespaceObject() const;
/**
* Perform the equivalent of `BigInt(value)` in JS.
*/
V8_WARN_UNUSED_RESULT MaybeLocal<BigInt> ToBigInt(
Local<Context> context) const;
/**
* Perform the equivalent of `Number(value)` in JS.
*/
V8_WARN_UNUSED_RESULT MaybeLocal<Number> ToNumber(
Local<Context> context) const;
/**
* Perform the equivalent of `String(value)` in JS.
*/
V8_WARN_UNUSED_RESULT MaybeLocal<String> ToString(
Local<Context> context) const;
/**
* Provide a string representation of this value usable for debugging.
* This operation has no observable side effects and will succeed
* unless e.g. execution is being terminated.
*/
V8_WARN_UNUSED_RESULT MaybeLocal<String> ToDetailString(
Local<Context> context) const;
/**
* Perform the equivalent of `Object(value)` in JS.
*/
V8_WARN_UNUSED_RESULT MaybeLocal<Object> ToObject(
Local<Context> context) const;
/**
* Perform the equivalent of `Number(value)` in JS and convert the result
* to an integer. Negative values are rounded up, positive values are rounded
* down. NaN is converted to 0. Infinite values yield undefined results.
*/
V8_WARN_UNUSED_RESULT MaybeLocal<Integer> ToInteger(
Local<Context> context) const;
/**
* Perform the equivalent of `Number(value)` in JS and convert the result
* to an unsigned 32-bit integer by performing the steps in
* https://tc39.es/ecma262/#sec-touint32.
*/
V8_WARN_UNUSED_RESULT MaybeLocal<Uint32> ToUint32(
Local<Context> context) const;
/**
* Perform the equivalent of `Number(value)` in JS and convert the result
* to a signed 32-bit integer by performing the steps in
* https://tc39.es/ecma262/#sec-toint32.
*/
V8_WARN_UNUSED_RESULT MaybeLocal<Int32> ToInt32(Local<Context> context) const;
/**
* Perform the equivalent of `Boolean(value)` in JS. This can never fail.
*/
Local<Boolean> ToBoolean(Isolate* isolate) const;
/**
......@@ -2788,13 +2860,18 @@ class V8_EXPORT Value : public Data {
V8_WARN_UNUSED_RESULT MaybeLocal<Uint32> ToArrayIndex(
Local<Context> context) const;
/** Returns the equivalent of `ToBoolean()->Value()`. */
bool BooleanValue(Isolate* isolate) const;
/** Returns the equivalent of `ToNumber()->Value()`. */
V8_WARN_UNUSED_RESULT Maybe<double> NumberValue(Local<Context> context) const;
/** Returns the equivalent of `ToInteger()->Value()`. */
V8_WARN_UNUSED_RESULT Maybe<int64_t> IntegerValue(
Local<Context> context) const;
/** Returns the equivalent of `ToUint32()->Value()`. */
V8_WARN_UNUSED_RESULT Maybe<uint32_t> Uint32Value(
Local<Context> context) const;
/** Returns the equivalent of `ToInt32()->Value()`. */
V8_WARN_UNUSED_RESULT Maybe<int32_t> Int32Value(Local<Context> context) const;
/** JS == */
......@@ -4162,7 +4239,10 @@ class FunctionCallbackInfo {
public:
/** The number of available arguments. */
V8_INLINE int Length() const;
/** Accessor for the available arguments. */
/**
* Accessor for the available arguments. Returns `undefined` if the index
* is out of bounds.
*/
V8_INLINE Local<Value> operator[](int i) const;
/** Returns the receiver. This corresponds to the "this" value. */
V8_INLINE Local<Object> This() const;
......
......@@ -4357,6 +4357,15 @@ THREADED_TEST(HandleEquality) {
global2.Reset();
}
THREADED_TEST(HandleEqualityPrimitives) {
v8::HandleScope scope(CcTest::isolate());
// Local::operator== works like strict equality except for primitives.
CHECK_NE(v8_str("str"), v8_str("str"));
CHECK_NE(v8::Number::New(CcTest::isolate(), 0.5),
v8::Number::New(CcTest::isolate(), 0.5));
CHECK_EQ(v8::Number::New(CcTest::isolate(), 1),
v8::Number::New(CcTest::isolate(), 1));
}
THREADED_TEST(LocalHandle) {
v8::HandleScope scope(CcTest::isolate());
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment