Add Dart class for _ExternalUint8ClampedArray and API to allocate it.

runtime/include/dart_api.h

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 #ifndef INCLUDE_DART_API_H_
 #define INCLUDE_DART_API_H_
 
 /** \mainpage Dart Embedding API Reference
  *
  * Dart is a class-based programming language for creating structured
@@ skipping 1654 matching lines @@
  *
  * \return The ByteArray object if no error occurs. Otherwise returns
  *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewExternalByteArray(uint8_t* data,
                                                   intptr_t length,
                                                   void* peer,
                                                   Dart_PeerFinalizer callback);
 
 /**
+ * Returns a clamped ByteArray which references an external array of
+ * 8-bit bytes.
+ * A clamped ByteArray differs from ByteArray above in the indexed store
+ * operation where negative values are clamped to 0 and values above 255 are
+ * clamped to 255.
+ *
+ * \param value An array of 8-bit bytes. This array must not move.
+ * \param length The length of the array.
+ * \param peer An external pointer to associate with this byte array.
+ *
+ * \return The clamped ByteArray object if no error occurs. Otherwise returns
+ *   an error handle.
+ */
+DART_EXPORT Dart_Handle Dart_NewExternalClampedByteArray(

[Anton Muhin, 2013/01/15 10:11:43]

It may be only me, but when I first time met the name Dart_NewExternalByteArray
I was 100% that it allocates an instance of ByteArray, not Uint8List.  May we
rename those methods?

Another issue: are you going to add eventually methods for all the array kinds? 
or maybe an ueber method taking kind as an argument.

Right now we've got in somewhat strange situation when some types can be
allocated directly while others cannot.

Surprisingly, to some extent it was better before as the only option one had was
to allocate Uint8List and then reuse its storage in some other view.

+    uint8_t* data,
+    intptr_t length,
+    void* peer,
+    Dart_PeerFinalizer callback);
+
+/**
  * Retrieves the data pointer associated with an external ByteArray.
  */
 DART_EXPORT Dart_Handle Dart_ExternalByteArrayGetData(Dart_Handle object,
                                                       void** data);
 
 /**
  * Retrieves the peer pointer associated with an external ByteArray.
  */
 DART_EXPORT Dart_Handle Dart_ExternalByteArrayGetPeer(Dart_Handle object,
                                                       void** peer);
@@ skipping 1122 matching lines @@
  *
  * \param object An object.
  * \param peer A value to store in the peer field.
  *
  * \return Returns an error if 'object' is a subtype of Null, num, or
  *   bool.
  */
 DART_EXPORT Dart_Handle Dart_SetPeer(Dart_Handle object, void* peer);
 
 #endif  // INCLUDE_DART_API_H_