From b77281799348a1df79ed3805237b63c43b7d6065 Mon Sep 17 00:00:00 2001 From: Nimpruda <7427905+Nimpruda@users.noreply.github.com> Date: Wed, 20 Oct 2021 12:38:16 +0200 Subject: [PATCH] Added documentation to DataView --- boa/src/builtins/dataview/mod.rs | 295 +++++++++++++++++++++++++++++-- 1 file changed, 284 insertions(+), 11 deletions(-) diff --git a/boa/src/builtins/dataview/mod.rs b/boa/src/builtins/dataview/mod.rs index 6208489aacb..c9832012d55 100644 --- a/boa/src/builtins/dataview/mod.rs +++ b/boa/src/builtins/dataview/mod.rs @@ -85,6 +85,17 @@ impl BuiltIn for DataView { impl DataView { pub(crate) const LENGTH: usize = 1; + /// `25.3.2.1 DataView ( buffer [ , byteOffset [ , byteLength ] ] )` + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// The DataView view provides a low-level interface for reading and writing multiple number types in a + /// binary ArrayBuffer, without having to care about the platform's endianness. + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview-buffer-byteoffset-bytelength + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/DataView pub(crate) fn constructor( new_target: &JsValue, args: &[JsValue], @@ -107,7 +118,7 @@ impl DataView { let buffer = buffer_borrow .as_array_buffer() .ok_or_else(|| context.construct_type_error("buffer must be an ArrayBuffer"))?; - + // 3. Let offset be ? ToIndex(byteOffset). let offset = args.get_or_undefined(1).to_index(context)?; // 4. If IsDetachedBuffer(buffer) is true, throw a TypeError exception. @@ -144,10 +155,11 @@ impl DataView { // 10. If IsDetachedBuffer(buffer) is true, throw a TypeError exception. if buffer_obj - .borrow() - .as_array_buffer() - .ok_or_else(|| context.construct_type_error("buffer must be an ArrayBuffer"))? - .is_detached_buffer() { + .borrow() + .as_array_buffer() + .ok_or_else(|| context.construct_type_error("buffer must be an ArrayBuffer"))? + .is_detached_buffer() + { return context.throw_type_error("ArrayBuffer can't be detached"); } @@ -167,6 +179,16 @@ impl DataView { Ok(obj.into()) } + /// `25.3.4.1 get DataView.prototype.buffer` + /// + /// The buffer accessor property represents the ArrayBuffer or SharedArrayBuffer referenced by the DataView at construction time. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-get-dataview.prototype.buffer + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/buffer pub(crate) fn get_buffer( this: &JsValue, _args: &[JsValue], @@ -174,11 +196,11 @@ impl DataView { ) -> JsResult { // 1. Let O be the this value. // 2. Perform ? RequireInternalSlot(O, [[DataView]]). - let dataview = this.as_object().map(|obj| obj.borrow()); + let dataview = this.as_object().map(|obj| obj.borrow()); let dataview = dataview - .as_ref() - .and_then(|obj| obj.as_data_view()) - .ok_or_else(|| context.construct_type_error("`this` is not a DataView"))?; + .as_ref() + .and_then(|obj| obj.as_data_view()) + .ok_or_else(|| context.construct_type_error("`this` is not a DataView"))?; // 3. Assert: O has a [[ViewedArrayBuffer]] internal slot. // 4. Let buffer be O.[[ViewedArrayBuffer]]. let buffer = dataview.viewed_array_buffer.clone(); @@ -186,6 +208,16 @@ impl DataView { Ok(buffer.into()) } + /// `25.3.4.1 get DataView.prototype.byteLength` + /// + /// The byteLength accessor property represents the length (in bytes) of the dataview. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-get-dataview.prototype.bytelength + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/byteLength pub(crate) fn get_byte_length( this: &JsValue, _args: &[JsValue], @@ -220,6 +252,16 @@ impl DataView { Ok(size.into()) } + /// `25.3.4.1 get DataView.prototype.byteOffset` + /// + /// The byteOffset accessor property represents the offset (in bytes) of this view from the start of its ArrayBuffer or SharedArrayBuffer. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-get-dataview.prototype.byteoffset + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/byteOffset pub(crate) fn get_byte_offset( this: &JsValue, _args: &[JsValue], @@ -254,6 +296,15 @@ impl DataView { Ok(offset.into()) } + /// `25.3.1.1 GetViewValue ( view, requestIndex, isLittleEndian, type )` + /// + /// The abstract operation GetViewValue takes arguments view, requestIndex, isLittleEndian, and type. + /// It is used by functions on DataView instances to retrieve values from the view's buffer. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// + /// [spec]: https://tc39.es/ecma262/#sec-getviewvalue fn get_view_value( view: &JsValue, request_index: &JsValue, @@ -274,30 +325,41 @@ impl DataView { } else { return context.throw_type_error("`this` is not a DataView"); }; + // 3. Let getIndex be ? ToIndex(requestIndex). let get_index = request_index.to_index(context)?; + // 4. Set isLittleEndian to ! ToBoolean(isLittleEndian). let is_little_endian = is_little_endian.to_boolean(); + // 5. Let buffer be view.[[ViewedArrayBuffer]]. let buffer = &view.viewed_array_buffer; let buffer_borrow = buffer.borrow(); - let buffer = buffer_borrow.as_array_buffer().expect("ca marche"); + let buffer = buffer_borrow + .as_array_buffer() + .expect("Should be unreachable"); + // 6. If IsDetachedBuffer(buffer) is true, throw a TypeError exception. if buffer.is_detached_buffer() { return context.throw_type_error("ArrayBuffer is detached"); } // 7. Let viewOffset be view.[[ByteOffset]]. let view_offset = view.byte_offset; + // 8. Let viewSize be view.[[ByteLength]]. let view_size = view.byte_length; + // 9. Let elementSize be the Element Size value specified in Table 72 for Element Type type. let element_size = t.element_size(); + // 10. If getIndex + elementSize > viewSize, throw a RangeError exception. if get_index + element_size > view_size { return context.throw_range_error("Offset is outside the bounds of the DataView"); } + // 11. Let bufferIndex be getIndex + viewOffset. let buffer_index = get_index + view_offset; + // 12. Return GetValueFromBuffer(buffer, bufferIndex, type, false, Unordered, isLittleEndian). Ok(buffer.get_value_from_buffer( buffer_index, @@ -308,6 +370,16 @@ impl DataView { )) } + /// `25.3.4.5 DataView.prototype.getBigInt64 ( byteOffset [ , littleEndian ] )` + /// + /// The getBigInt64() method gets a signed 64-bit integer (long long) at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.getbigint64 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getBigInt64 pub(crate) fn get_big_int64( this: &JsValue, args: &[JsValue], @@ -326,6 +398,16 @@ impl DataView { ) } + /// `25.3.4.6 DataView.prototype.getBigUint64 ( byteOffset [ , littleEndian ] )` + /// + /// The getBigUint64() method gets an unsigned 64-bit integer (unsigned long long) at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.getbiguint64 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getBigUint64 pub(crate) fn get_big_uint64( this: &JsValue, args: &[JsValue], @@ -344,6 +426,16 @@ impl DataView { ) } + /// `25.3.4.7 DataView.prototype.getBigUint64 ( byteOffset [ , littleEndian ] )` + /// + /// The getFloat32() method gets a signed 32-bit float (float) at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.getfloat32 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getFloat32 pub(crate) fn get_float32( this: &JsValue, args: &[JsValue], @@ -362,6 +454,16 @@ impl DataView { ) } + /// `25.3.4.8 DataView.prototype.getFloat64 ( byteOffset [ , littleEndian ] )` + /// + /// The getFloat64() method gets a signed 64-bit float (double) at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.getfloat64 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getFloat64 pub(crate) fn get_float64( this: &JsValue, args: &[JsValue], @@ -380,6 +482,16 @@ impl DataView { ) } + /// `25.3.4.9 DataView.prototype.getInt8 ( byteOffset [ , littleEndian ] )` + /// + /// The getInt8() method gets a signed 8-bit integer (byte) at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.getint8 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getInt8 pub(crate) fn get_int8( this: &JsValue, args: &[JsValue], @@ -398,6 +510,16 @@ impl DataView { ) } + /// `25.3.4.10 DataView.prototype.getInt16 ( byteOffset [ , littleEndian ] )` + /// + /// The getInt16() method gets a signed 16-bit integer (short) at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.getint16 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getInt16 pub(crate) fn get_int16( this: &JsValue, args: &[JsValue], @@ -416,6 +538,16 @@ impl DataView { ) } + /// `25.3.4.11 DataView.prototype.getInt32 ( byteOffset [ , littleEndian ] )` + /// + /// The getInt32() method gets a signed 32-bit integer (long) at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.getint32 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getInt32 pub(crate) fn get_int32( this: &JsValue, args: &[JsValue], @@ -434,6 +566,16 @@ impl DataView { ) } + /// `25.3.4.12 DataView.prototype.getUint8 ( byteOffset [ , littleEndian ] )` + /// + /// The getUint8() method gets an unsigned 8-bit integer (unsigned byte) at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.getuint8 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getUint8 pub(crate) fn get_uint8( this: &JsValue, args: &[JsValue], @@ -452,6 +594,16 @@ impl DataView { ) } + /// `25.3.4.13 DataView.prototype.getUint16 ( byteOffset [ , littleEndian ] )` + /// + /// The getUint16() method gets an unsigned 16-bit integer (unsigned short) at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.getuint16 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getUint16 pub(crate) fn get_uint16( this: &JsValue, args: &[JsValue], @@ -470,6 +622,16 @@ impl DataView { ) } + /// `25.3.4.14 DataView.prototype.getUint32 ( byteOffset [ , littleEndian ] )` + /// + /// The getUint32() method gets an unsigned 32-bit integer (unsigned long) at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.getuint32 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getUint32 pub(crate) fn get_uint32( this: &JsValue, args: &[JsValue], @@ -488,6 +650,15 @@ impl DataView { ) } + /// `25.3.1.1 SetViewValue ( view, requestIndex, isLittleEndian, type )` + /// + /// The abstract operation SetViewValue takes arguments view, requestIndex, isLittleEndian, type, and value. + /// It is used by functions on DataView instances to store values into the view's buffer. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// + /// [spec]: https://tc39.es/ecma262/#sec-setviewvalue fn set_view_value( view: &JsValue, request_index: &JsValue, @@ -526,7 +697,9 @@ impl DataView { // 7. Let buffer be view.[[ViewedArrayBuffer]]. let buffer = &view.viewed_array_buffer; let mut buffer_borrow = buffer.borrow_mut(); - let buffer = buffer_borrow.as_array_buffer_mut().expect("ca marche"); + let buffer = buffer_borrow + .as_array_buffer_mut() + .expect("Should be unreachable"); // 8. If IsDetachedBuffer(buffer) is true, throw a TypeError exception. if buffer.is_detached_buffer() { @@ -561,6 +734,16 @@ impl DataView { ) } + /// `25.3.4.15 DataView.prototype.setBigInt64 ( byteOffset, value [ , littleEndian ] )` + /// + /// The setBigInt64() method stores a signed 64-bit integer (long long) value at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.setbigint64 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setBigInt64 pub(crate) fn set_big_int64( this: &JsValue, args: &[JsValue], @@ -581,6 +764,16 @@ impl DataView { ) } + /// `25.3.4.16 DataView.prototype.setBigUint64 ( byteOffset, value [ , littleEndian ] )` + /// + /// The setBigUint64() method stores an unsigned 64-bit integer (unsigned long long) value at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.setbiguint64 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setBigUint64 pub(crate) fn set_big_uint64( this: &JsValue, args: &[JsValue], @@ -601,6 +794,16 @@ impl DataView { ) } + /// `25.3.4.17 DataView.prototype.setFloat32 ( byteOffset, value [ , littleEndian ] )` + /// + /// The setFloat32() method stores a signed 32-bit float (float) value at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.setfloat32 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setFloat32 pub(crate) fn set_float32( this: &JsValue, args: &[JsValue], @@ -621,6 +824,16 @@ impl DataView { ) } + /// `25.3.4.18 DataView.prototype.setFloat64 ( byteOffset, value [ , littleEndian ] )` + /// + /// The setFloat64() method stores a signed 64-bit float (double) value at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.setfloat64 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setFloat64 pub(crate) fn set_float64( this: &JsValue, args: &[JsValue], @@ -641,6 +854,16 @@ impl DataView { ) } + /// `25.3.4.19 DataView.prototype.setInt8 ( byteOffset, value [ , littleEndian ] )` + /// + /// The setInt8() method stores a signed 8-bit integer (byte) value at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.setint8 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setInt8 pub(crate) fn set_int8( this: &JsValue, args: &[JsValue], @@ -661,6 +884,16 @@ impl DataView { ) } + /// `25.3.4.20 DataView.prototype.setInt16 ( byteOffset, value [ , littleEndian ] )` + /// + /// The setInt16() method stores a signed 16-bit integer (short) value at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.setint16 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setInt16 pub(crate) fn set_int16( this: &JsValue, args: &[JsValue], @@ -681,6 +914,16 @@ impl DataView { ) } + /// `25.3.4.21 DataView.prototype.setInt32 ( byteOffset, value [ , littleEndian ] )` + /// + /// The setInt32() method stores a signed 32-bit integer (long) value at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.setint32 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setInt32 pub(crate) fn set_int32( this: &JsValue, args: &[JsValue], @@ -701,6 +944,16 @@ impl DataView { ) } + /// `25.3.4.22 DataView.prototype.setUint8 ( byteOffset, value [ , littleEndian ] )` + /// + /// The setUint8() method stores an unsigned 8-bit integer (byte) value at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.setuint8 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setUint8 pub(crate) fn set_uint8( this: &JsValue, args: &[JsValue], @@ -721,6 +974,16 @@ impl DataView { ) } + /// `25.3.4.23 DataView.prototype.setUint16 ( byteOffset, value [ , littleEndian ] )` + /// + /// The setUint16() method stores an unsigned 16-bit integer (unsigned short) value at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.setuint16 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setUint16 pub(crate) fn set_uint16( this: &JsValue, args: &[JsValue], @@ -741,6 +1004,16 @@ impl DataView { ) } + /// `25.3.4.24 DataView.prototype.setUint32 ( byteOffset, value [ , littleEndian ] )` + /// + /// The setUint32() method stores an unsigned 32-bit integer (unsigned long) value at the specified byte offset from the start of the DataView. + /// + /// More information: + /// - [ECMAScript reference][spec] + /// - [MDN][mdn] + /// + /// [spec]: https://tc39.es/ecma262/#sec-dataview.prototype.setuint32 + /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setUint32 pub(crate) fn set_uint32( this: &JsValue, args: &[JsValue],