Add Dart_IsExternalString and Dart_ExternalStringGetPeer to the dart

runtime/include/dart_api.h

 // Copyright (c) 2011, 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 709 matching lines @@
 DART_EXPORT bool Dart_IsString(Dart_Handle object);
 
 /**
  * Is this object a String whose codepoints all fit into 8 bits?
  */
 DART_EXPORT bool Dart_IsString8(Dart_Handle object);
 
 /**
  * Is this object a String whose codepoints all fit into 16 bits?
  */
 DART_EXPORT bool Dart_IsString16(Dart_Handle object);

[siva, 2011/12/02 01:53:01]

to make the API uniform maybe we need a Dart_IsString32 also?

[turnidge, 2011/12/05 17:54:28]

I wondered the same thing.  When I looked at the code, I found that each of
these tests is inclusive of the size below.  For example, Dart_IsString16
returns true for an 8 and 16 bit string and false for a 32 bit string.  Because
it is inclusive of all smaller sizes, Dart_IsString32 would have the same
semantics as Dart_IsString, which is why I think that it must have been left
out.

If you and I both found this to be confusing, then probably others will too.  Do
you want to chat about this offline?

 
 /**
  * Gets the length of a String.
  *
  * \param str A String.
  * \param length Returns the length of the String.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_StringLength(Dart_Handle str, intptr_t* length);
@@ skipping 40 matching lines @@
  *
  * \return The String object if no error occurs. Otherwise returns
  *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewString32(const uint32_t* codepoints,
                                          intptr_t length);
 
 
 typedef void (*Dart_PeerFinalizer)(void* peer);
 
+/**
+ * Is this object an external String?
+ *
+ * An external String is a String which references a fixed array of
+ * codepoints which is external to the Dart heap.
+ */
+DART_EXPORT bool Dart_IsExternalString(Dart_Handle object);
+
+/**
+ * Retrieves the peer pointer associated with an external String.
+ */
+DART_EXPORT Dart_Handle Dart_ExternalStringGetPeer(Dart_Handle object,
+                                                   void** peer);
+
+
+/**
+ * Returns a String which references an external array of 8-bit codepoints.
+ *
+ * \param value An array of 8-bit codepoints.  This array must not move.
+ * \param length The length of the codepoints array.
+ * \param peer An external pointer to associate with this string.
+ * \param callback A callback to be called when this string is finalized.
+ *
+ * \return The String object if no error occurs. Otherwise returns
+ *   an error handle.
+ */
 DART_EXPORT Dart_Handle Dart_NewExternalString8(const uint8_t* codepoints,
                                                 intptr_t length,
                                                 void* peer,
                                                 Dart_PeerFinalizer callback);
 
+/**
+ * Returns a String which references an external array of 16-bit codepoints.
+ *
+ * \param value An array of 16-bit codepoints.  This array must not move.
+ * \param length The length of the codepoints array.
+ * \param peer An external pointer to associate with this string.
+ * \param callback A callback to be called when this string is finalized.
+ *
+ * \return The String object if no error occurs. Otherwise returns
+ *   an error handle.
+ */
 DART_EXPORT Dart_Handle Dart_NewExternalString16(const uint16_t* codepoints,
                                                  intptr_t length,
                                                  void* peer,
                                                  Dart_PeerFinalizer callback);
 
+/**
+ * Returns a String which references an external array of 32-bit codepoints.
+ *
+ * \param value An array of 32-bit codepoints.  This array must not move.
+ * \param length The length of the codepoints array.
+ * \param peer An external pointer to associate with this string.
+ * \param callback A callback to be called when this string is finalized.
+ *
+ * \return The String object if no error occurs. Otherwise returns
+ *   an error handle.
+ */
 DART_EXPORT Dart_Handle Dart_NewExternalString32(const uint32_t* codepoints,
                                                  intptr_t length,
                                                  void* peer,
                                                  Dart_PeerFinalizer callback);
 
 /**
  * Gets the codepoints from a String.
  *
  * This function is only valid on strings for which Dart_IsString8 is
  * true. Otherwise an error occurs.
@@ skipping 416 matching lines @@
 
 // --- Profiling support ----
 
 // External pprof support for gathering and dumping symbolic
 // information that can be used for better profile reports for
 // dynamically generated code.
 DART_EXPORT void Dart_InitPprofSupport();
 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size);
 
 #endif  // INCLUDE_DART_API_H_