- 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.
+ *
+ * \return A valid handle if no error occurs during the operation.
+ */
+DART_EXPORT Dart_Handle Dart_StringStorageSize(Dart_Handle str, intptr_t* size);

[Ivan Posva, 2012/11/15 06:17:15]

I read the description and it is not clear to me whether this is the per indexed
value storage size or the size needed to store this String. Maybe you can add an
example how this is supposed to be used in conjunction with
Dart_MakeExternalString?

Basically should I do:

intptr_t size;
Dart_StringStorageSize(str, &size);
void* data = malloc(size);

or

intptr_t len;
Dart_StringLength(str, &len);
intptr_t size;
Dart_StringStorageSize(str, &size);
void* data = malloc(size * len);

[siva, 2012/11/15 21:34:13]

Added comments to both Dart_StringStorageSize and
Dart_MakeExternalString.

On 2012/11/15 06:17:15, Ivan Posva wrote:

+
+
+/**
+ * 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.
+ */
+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_