Setup a peer for read only strings that are not externalized in

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
@@ skipping 1392 matching lines @@
  * \param utf32_array An array of UTF-32 encoded characters.
  * \param length The length of the codepoints array.
  *
  * \return The String object if no error occurs. Otherwise returns
  *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewStringFromUTF32(const int32_t* utf32_array,
                                                 intptr_t length);
 
 /**
- * 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
  * Latin-1 (ISO-8859-1) encoded characters.
  *
  * \param latin1_array Array of Latin-1 encoded characters. This must not move.
  * \param length The length of the characters 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 String object if no error occurs. Otherwise returns
  *   an error handle.
@@ skipping 100 matching lines @@
  *
  * \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.
  *   If the object is a valid string but if it cannot be externalized
- *   then Dart_Null() is returned and the string data is copied into
- *   the external space specified.
+ *   the string data is copied into the external space specified
+ *   and the passed in peer is setup as a peer for this string object.
+ *   In this case the function returns the original String object as is.
  *
  * 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);
 
 /**
  * Retrieves some properties associated with a String.
  * Properties retrieved are:
  * - character size of the string (one or two byte)
  * - length of the string
  * - peer pointer of string if it is an external string.
  * \param str A String.
  * \param char_size Returns the character size of the String.
  * \param str_len Returns the length of the String.
  * \param peer Returns the peer pointer if the String is an external String.

[Ivan Posva, 2013/08/22 15:44:51]

Please update this comment.

[siva, 2013/08/22 16:57:08]

Done.

  * \return Success if no error occurs. Otherwise returns
  *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_StringGetProperties(Dart_Handle str,
                                                  intptr_t* char_size,
                                                  intptr_t* str_len,
                                                  void** peer);
 
 /*
  * =====
@@ skipping 418 matching lines @@
 /**
  * Gets the native field of the receiver.
  */
 DART_EXPORT Dart_Handle Dart_GetNativeReceiver(Dart_NativeArguments args,
                                                intptr_t* value);
 
 /**
  * Gets a string native argument at some index.
  * \param args Native arguments structure.
  * \param arg_index Index of the desired argument in the structure above.
  * \param peer Returns the peer pointer if the String is an external String.

[Ivan Posva, 2013/08/22 15:44:51]

Please update this comment.

[siva, 2013/08/22 16:57:08]

Done.

  * \return the String object if no error occurs. Otherwise returns
  *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_GetNativeStringArgument(Dart_NativeArguments args,
                                                      int arg_index,
                                                      void** peer);
 
 /**
  * Sets the return value for a native function.
  */
@@ skipping 238 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_ */  /* NOLINT */