- Add functionality to morph a string into an external string

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 1466 matching lines @@
  *   the array of UTF-16 encoded characters.
  * \param length Used to pass in the length of the provided array.
  *   Used to return the length of the array which was actually used.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_StringToUTF16(Dart_Handle str,
                                            uint16_t* utf16_array,
                                            intptr_t* length);
 
+/**
+ * Gets the storage size in bytes of a String.
+ *
+ * \param str A String.
+ * \param length Returns the storage size in bytes of the String.
+ *  This is the size in bytes needed to store the String.
+ *
+ * \return A valid handle if no error occurs during the operation.
+ */
+DART_EXPORT Dart_Handle Dart_StringStorageSize(Dart_Handle str, intptr_t* size);
+
+
+/**
+ * Converts a String into an ExternalString.
+ * The original object is morphed into an external string object.
+ *
+ * \param array External space into which the string data will be
+ *   copied into. This must not move.
+ * \param length The size in bytes of the provided external space (array).
+ * \param peer An external pointer to associate with this string.
+ * \param cback A callback to be called when this string is finalized.
+ *
+ * \return the converted ExternalString object if no error occurs.
+ *   Otherwise returns an error handle.
+ *
+ * For example:
+ *  intptr_t size;
+ *  Dart_Handle result;
+ *  result = DartStringStorageSize(str, &size);
+ *  void* data = malloc(size);
+ *  result = Dart_MakeExternalString(str, data, size, NULL, NULL);
+ *
+ */
+DART_EXPORT Dart_Handle Dart_MakeExternalString(Dart_Handle str,
+                                                void* array,
+                                                intptr_t length,
+                                                void* peer,
+                                                Dart_PeerFinalizer cback);
+
 
 // --- Lists ---
 
 /**
  * Is this object a List?
  */
 DART_EXPORT bool Dart_IsList(Dart_Handle object);
 
 /**
  * Returns a List of the desired length.
@@ skipping 1235 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_