Changes per discussion with Anton

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 1445 matching lines @@
  * \param cstr Returns the String represented as a C string.
  *   This C string is scope allocated and is only valid until
  *   the next call to Dart_ExitScope.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_StringToCString(Dart_Handle str,
                                              const char** cstr);
 
 /**
+ * Gets the Latin-1 (ISO-8859-1) encoded representation of a string.

[cshapiro, 2012/12/14 00:00:36]

This seems misleading, I would really like to see something change.

This API gets the contents of a OneByteString a.k.a. a Latin-1 string.  The
naming philosophy was to have To be reserved for conversions and this is not a
conversion, it will generate an error if the input cannot be encoded as Latin-1.

(Consider Dart_StringToUTF8 below.)

[siva, 2012/12/14 03:30:09]

I have changed the description here to word it to say it is not a conversion but
just a straight extraction of data and strings that are not latin1 strings will
get an error.

On 2012/12/14 00:00:36, cshapiro wrote:

+ *
+ * \param str A string.
+ * \param latin1_array Returns the String represented as Latin-1 characters
+ *   This array is scope allocated and is only valid
+ *   until the next call to Dart_ExitScope.

[antonm, 2012/12/14 01:31:59]

there are two flavours of string data fetching: Dart_StringToUTF16 which allows
caller to pass the buffer caller is managing and Dart_String~ToUTF8 where VM
allocates the buffer.

From my experience, _StringToUTF16 is by far more convenient as it least in my
case I need to copy those data away immediately anyway and hence I save on one
copy.

[siva, 2012/12/14 03:30:09]

I have changed Dart_StringToLatin1 to use the API similar to Dart_StringToUTF16
which should be more convenient for you.

Will try and change Dart_StringToUTF8 to also follow the same pattern in another
CL.

On 2012/12/14 01:31:59, antonm wrote:

[antonm, 2012/12/14 03:31:30]

Thanks!

On 2012/12/14 03:30:09, siva wrote:

+ * \param length 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_StringToLatin1(Dart_Handle str,
+                                            uint8_t** latin1_array,
+                                            intptr_t* length);
+
+/**
  * Gets a UTF-8 encoded representation of a String.
  *
  * \param str A string.
  * \param utf8_array Returns the String represented as UTF-8 code
  *   units.  This UTF-8 array is scope allocated and is only valid
  *   until the next call to Dart_ExitScope.
  * \param length Used to return the length of the array which was
  *   actually used.
  *
  * \return A valid handle if no error occurs during the operation.
@@ skipping 34 matching lines @@
  * 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.
+ *   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.
  *
  * 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,
@@ skipping 1239 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_