Rename RandomAccessFile.readList and RandomAccessFile.writeList to RandomAccessFile.readInto and Ra…

sdk/lib/io/file.dart

 // Copyright (c) 2013, 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.
 
 part of dart.io;
 
 /**
  * FileMode describes the modes in which a file can be opened.
  */
 class FileMode {
@@ skipping 350 matching lines @@
 
   /**
    * Synchronously reads a maximum of [bytes] bytes from a file and
    * returns the result in a list of bytes.
    *
    * Throws a [FileIOException] if the operation fails.
    */
   List<int> readSync(int bytes);
 
   /**
-   * Reads into an existing List<int> from the file. A maximum of [bytes] bytes
-   * is read into [buffer], starting at position [offset] in the buffer.
+   * Reads into an existing List<int> from the file. If [start] is present, the
+   * bytes will be filled into [buffer] from at index [start], otherwise index
+   * 0. If [end] is present, the [buffer] will be filled up to index [end],

[Søren Gjesse, 2013/04/15 13:48:44]

Emphasize that buffer[end] is exclusive. That is end - start bytes are read, and
if start == end nothing happens.

[Anders Johnsen, 2013/04/15 15:37:05]

Done.

+   * otherwise index [buffer.length] - 1.
+   *
    * Returns a [:Future<int>:] that completes with the number of bytes read.
    */
-  Future<int> readList(List<int> buffer, int offset, int bytes);
+  Future<int> readInto(List<int> buffer, [int start, int end]);
 
   /**
-   * Synchronously reads from a file into [buffer].  A maximum of [bytes] bytes
-   * is read into [buffer], starting at position [offset] in the buffer.
-   * Returns the number of bytes read.
+   * Synchronously reads into an existing List<int> from the file. If [start] is
+   * present, the bytes will be filled into [buffer] from at index [start],
+   * otherwise index 0. If [end] is present, the [buffer] will be filled up to
+   * index [end], otherwise index [buffer.length] - 1.
    *
    * Throws a [FileIOException] if the operation fails.
    */
-  int readListSync(List<int> buffer, int offset, int bytes);
+  int readIntoSync(List<int> buffer, [int start, int end]);
 
   /**
    * Writes a single byte to the file. Returns a
    * [:Future<RandomAccessFile>:] that completes with this
    * RandomAccessFile when the write completes.
    */
   Future<RandomAccessFile> writeByte(int value);
 
   /**
    * Synchronously writes a single byte to the file. Returns the
    * number of bytes successfully written.
    *
    * Throws a [FileIOException] if the operation fails.
    */
   int writeByteSync(int value);
 
   /**
-   * Writes from a List<int> to the file. [bytes] bytes are written from
-   * [buffer], starting at position [offset] in the buffer. Returns a
-   * [:Future<RandomAccessFile>:] that completes with this
-   * RandomAccessFile when the write completes.
+   * Writes from a [List<int>] to the file. It'll read the buffer from index
+   * [start] to index [end]. If [start] is omitted, it'll start from index 0.

[Søren Gjesse, 2013/04/15 13:48:44]

it'll -> it will

[Anders Johnsen, 2013/04/15 15:37:05]

Done.

+   * If [end] is omitted, it'll write to index [buffer.length] - 1.

[Søren Gjesse, 2013/04/15 13:48:44]

Ditto

[Anders Johnsen, 2013/04/15 15:37:05]

Done.

+   *
+   * Returns a [:Future<RandomAccessFile>:] that completes with this
+   * [RandomAccessFile] when the write completes.
    */
-  Future<RandomAccessFile> writeList(List<int> buffer, int offset, int bytes);
+  Future<RandomAccessFile> writeFrom(List<int> buffer, [int start, int end]);
 
   /**
    * Synchronously writes a List<int> to the file.  [bytes] bytes are

[Søren Gjesse, 2013/04/15 13:48:44]

Please update this dartdoc as well.

[Anders Johnsen, 2013/04/15 15:37:05]

Done.

    * written from [buffer], starting at position [offset] in the
    * buffer. Returns the number of bytes successfully written.
    *
    * Throws a [FileIOException] if the operation fails.
    */
-  int writeListSync(List<int> buffer, int offset, int bytes);
+  void writeFromSync(List<int> buffer, [int start, int end]);
 
   /**
    * Writes a string to the file using the given [Encoding]. Returns a
    * [:Future<RandomAccessFile>:] that completes with this
    * RandomAccessFile when the write completes.
    */
   Future<RandomAccessFile> writeString(String string,
                                        {Encoding encoding: Encoding.UTF_8});
 
   /**
    * Synchronously writes a single string to the file using the given
-   * [Encoding]. Returns the number of characters successfully
-   * written.
+   * [Encoding].
    *
    * Throws a [FileIOException] if the operation fails.
    */
-  int writeStringSync(String string,
-                      {Encoding encoding: Encoding.UTF_8});
+  void writeStringSync(String string,
+                       {Encoding encoding: Encoding.UTF_8});
 
   /**
    * Gets the current byte position in the file. Returns a
    * [:Future<int>:] that completes with the position.
    */
   Future<int> position();
 
   /**
    * Synchronously gets the current byte position in the file.
    *
@@ skipping 80 matching lines @@
         sb.write(" ($osError)");
       }
     } else if (osError != null) {
       sb.write(": osError");
     }
     return sb.toString();
   }
   final String message;
   final OSError osError;
 }