[dart:io] Adds functions to set file access and modification time

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;
 
 /**
  * The modes in which a File can be opened.
  */
 class FileMode {
@@ skipping 201 matching lines @@
   factory File(String path) => new _File(path);
 
   /**
    * Create a File object from a URI.
    *
    * If [uri] cannot reference a file this throws [UnsupportedError].
    */
   factory File.fromUri(Uri uri) => new File(uri.toFilePath());
 
   /**
-   * Create the file. Returns a [:Future<File>:] that completes with
+   * Create the file. Returns a `Future<File>` that completes with
    * the file when it has been created.
    *
    * If [recursive] is false, the default, the file is created only if
    * all directories in the path exist. If [recursive] is true, all
    * non-existing path components are created.
    *
    * Existing files are left untouched by [create]. Calling [create] on an
    * existing file might fail if there are restrictive permissions on
    * the file.
    *
@@ skipping 48 matching lines @@
    * Synchronously copy this file. Returns a [File]
    * instance for the copied file.
    *
    * If [newPath] identifies an existing file, that file is
    * replaced. If [newPath] identifies an existing directory the
    * operation fails and an exception is thrown.
    */
   File copySync(String newPath);
 
   /**
-   * Get the length of the file. Returns a [:Future<int>:] that
+   * Get the length of the file. Returns a `Future<int>` that
    * completes with the length in bytes.
    */
   Future<int> length();
 
   /**
    * Synchronously get the length of the file.
    *
    * Throws a [FileSystemException] if the operation fails.
    */
   int lengthSync();
 
   /**
    * Returns a [File] instance whose path is the absolute path to [this].
    *
    * The absolute path is computed by prefixing
    * a relative path with the current working directory, and returning
    * an absolute path unchanged.
    */
   File get absolute;
 
+/**
+ * Get the last-accessed time of the file.
+ *
+ * Returns the date and time when the file was last accessed, if the
+ * information is available.
+ *
+ * Throws a [FileSystemException] if the operation fails.
+ */
+  Future<DateTime> lastAccessed();
+
+/**
+ * Get the last-accessed time of the file.
+ *
+ * Returns the date and time when the file was last accessed,
+ * if the information is available. Blocks until the information can be returned
+ * or it is determined that the information is not available.
+ *
+ * Throws a [FileSystemException] if the operation fails.
+ */
+  DateTime lastAccessedSync();
+
   /**
-   * Get the last-modified time of the file. Returns a
-   * [:Future<DateTime>:] that completes with a [DateTime] object for the
-   * modification date.
+   * Modifies the time the file was last accessed.
+   *
+   * Throws a [FilsSystemException] if the time cannot be set.
    */
+  Future setLastAccessed(DateTime time);
+
+  /**
+   * Synchronously modifies the time the file was last accessed.
+   *
+   * Throws a [FilsSystemException] if the time cannot be set.
+   */
+  void setLastAccessedSync(DateTime time);
+
+/**
+ * Get the last-modified time of the file.
+ *
+ * Returns the date and time when the file was last modified, if the
+ * information is available.
+ *
+ * Throws a [FileSystemException] if the operation fails.
+ */
   Future<DateTime> lastModified();
 
-  /**
-   * Get the last-modified time of the file. Throws an exception
-   * if the file does not exist.
-   *
-   * Throws a [FileSystemException] if the operation fails.
-   */
+/**
+ * Get the last-modified time of the file.
+ *
+ * Returns the date and time when the file was last modified,
+ * if the information is available. Blocks until the information can be returned
+ * or it is determined that the information is not available.
+ *
+ * Throws a [FileSystemException] if the operation fails.
+ */
   DateTime lastModifiedSync();
 
   /**
+   * Modifies the time the file was last modified.
+   *
+   * Throws a [FilsSystemException] if the time cannot be set.
+   */
+  Future setLastModified(DateTime time);
+
+  /**
+   * Synchronously modifies the time the file was last modified.
+   *
+   * If the attributes cannot be set, throws a [FileSystemException].
+   */
+  void setLastModifiedSync(DateTime time);
+
+  /**
    * Open the file for random access operations. Returns a
-   * [:Future<RandomAccessFile>:] that completes with the opened
+   * `Future<RandomAccessFile>` that completes with the opened
    * random access file. [RandomAccessFile]s must be closed using the
    * [RandomAccessFile.close] method.
    *
    * Files can be opened in three modes:
    *
    * [FileMode.READ]: open the file for reading.
    *
    * [FileMode.WRITE]: open the file for both reading and writing and
    * truncate the file to length zero. If the file does not exist the
    * file is created.
@@ skipping 36 matching lines @@
    * system resources.
    *
    * An [IOSink] for a file can be opened in two modes:
    *
    * * [FileMode.WRITE]: truncates the file to length zero.
    * * [FileMode.APPEND]: sets the initial write position to the end
    *   of the file.
    *
    *  When writing strings through the returned [IOSink] the encoding
    *  specified using [encoding] will be used. The returned [IOSink]
-   *  has an [:encoding:] property which can be changed after the
+   *  has an `encoding` property which can be changed after the
    *  [IOSink] has been created.
    */
   IOSink openWrite({FileMode mode: FileMode.WRITE,
                     Encoding encoding: UTF8});
 
   /**
    * Read the entire file contents as a list of bytes. Returns a
-   * [:Future<List<int>>:] that completes with the list of bytes that
+   * `Future<List<int>>` that completes with the list of bytes that
    * is the contents of the file.
    */
   Future<List<int>> readAsBytes();
 
   /**
    * Synchronously read the entire file contents as a list of bytes.
    *
    * Throws a [FileSystemException] if the operation fails.
    */
   List<int> readAsBytesSync();
 
   /**
    * Read the entire file contents as a string using the given
    * [Encoding].
    *
-   * Returns a [:Future<String>:] that completes with the string once
+   * Returns a `Future<String>` that completes with the string once
    * the file contents has been read.
    */
   Future<String> readAsString({Encoding encoding: UTF8});
 
   /**
    * Synchronously read the entire file contents as a string using the
    * given [Encoding].
    *
    * Throws a [FileSystemException] if the operation fails.
    */
   String readAsStringSync({Encoding encoding: UTF8});
 
   /**
    * Read the entire file contents as lines of text using the given
    * [Encoding].
    *
-   * Returns a [:Future<List<String>>:] that completes with the lines
+   * Returns a `Future<List<String>>` that completes with the lines
    * once the file contents has been read.
    */
   Future<List<String>> readAsLines({Encoding encoding: UTF8});
 
   /**
    * Synchronously read the entire file contents as lines of text
    * using the given [Encoding].
    *
    * Throws a [FileSystemException] if the operation fails.
    */
   List<String> readAsLinesSync({Encoding encoding: UTF8});
 
   /**
    * Write a list of bytes to a file.
    *
    * Opens the file, writes the list of bytes to it, and closes the file.
-   * Returns a [:Future<File>:] that completes with this [File] object once
+   * Returns a `Future<File>` that completes with this [File] object once
    * the entire operation has completed.
    *
    * By default [writeAsBytes] creates the file for writing and truncates the
    * file if it already exists. In order to append the bytes to an existing
    * file, pass [FileMode.APPEND] as the optional mode parameter.
    *
    * If the argument [flush] is set to `true`, the data written will be
    * flushed to the file system before the returned future completes.
    */
   Future<File> writeAsBytes(List<int> bytes,
@@ skipping 15 matching lines @@
    * Throws a [FileSystemException] if the operation fails.
    */
   void writeAsBytesSync(List<int> bytes,
                         {FileMode mode: FileMode.WRITE,
                          bool flush: false});
 
   /**
    * Write a string to a file.
    *
    * Opens the file, writes the string in the given encoding, and closes the
-   * file. Returns a [:Future<File>:] that completes with this [File] object
+   * file. Returns a `Future<File>` that completes with this [File] object
    * once the entire operation has completed.
    *
    * By default [writeAsString] creates the file for writing and truncates the
    * file if it already exists. In order to append the bytes to an existing
    * file, pass [FileMode.APPEND] as the optional mode parameter.
    *
    * If the argument [flush] is set to `true`, the data written will be
    * flushed to the file system before the returned future completes.
    *
    */
@@ skipping 28 matching lines @@
    */
   String get path;
 }
 
 
 /**
  * `RandomAccessFile` provides random access to the data in a
  * file.
  *
  * `RandomAccessFile` objects are obtained by calling the
- * [:open:] method on a [File] object.
+ * `open` method on a [File] object.
  *
  * A `RandomAccessFile` have both asynchronous and synchronous
  * methods. The asynchronous methods all return a `Future`
  * whereas the synchronous methods will return the result directly,
  * and block the current isolate until the result is ready.
  *
  * At most one asynchronous method can be pending on a given `RandomAccessFile`
  * instance at the time. If an asynchronous method is called when one is
  * already in progress a [FileSystemException] is thrown.
  *
  * If an asynchronous method is pending it is also not possible to call any
  * synchronous methods. This will also throw a [FileSystemException].
  */
 abstract class RandomAccessFile {
   /**
-   * Closes the file. Returns a [:Future<RandomAccessFile>:] that
+   * Closes the file. Returns a `Future<RandomAccessFile>` that
    * completes with this RandomAccessFile when it has been closed.
    */
   Future<RandomAccessFile> close();
 
   /**
    * Synchronously closes the file.
    *
    * Throws a [FileSystemException] if the operation fails.
    */
   void closeSync();
 
   /**
-   * Reads a byte from the file. Returns a [:Future<int>:] that
+   * Reads a byte from the file. Returns a `Future<int>` that
    * completes with the byte, or with -1 if end-of-file has been reached.
    */
   Future<int> readByte();
 
   /**
    * Synchronously reads a single byte from the file. If end-of-file
    * has been reached -1 is returned.
    *
    * Throws a [FileSystemException] if the operation fails.
    */
@@ skipping 12 matching lines @@
    */
   List<int> readSync(int bytes);
 
   /**
    * 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 [end] - [start] bytes will be read into
    * [buffer], otherwise up to [buffer.length]. If [end] == [start] nothing
    * happens.
    *
-   * Returns a [:Future<int>:] that completes with the number of bytes read.
+   * Returns a `Future<int>` that completes with the number of bytes read.
    */
   Future<int> readInto(List<int> buffer, [int start = 0, int end]);
 
   /**
    * 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 [end] - [start] bytes will be
    * read into [buffer], otherwise up to [buffer.length]. If [end] == [start]
    * nothing happens.
    *
    * Throws a [FileSystemException] if the operation fails.
    */
   int readIntoSync(List<int> buffer, [int start = 0, int end]);
 
   /**
    * Writes a single byte to the file. Returns a
-   * [:Future<RandomAccessFile>:] that completes with this
+   * `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 [FileSystemException] if the operation fails.
    */
   int writeByteSync(int value);
 
   /**
    * Writes from a [List<int>] to the file. It will read the buffer from index
    * [start] to index [end]. If [start] is omitted, it'll start from index 0.
    * If [end] is omitted, it will write to end of [buffer].
    *
-   * Returns a [:Future<RandomAccessFile>:] that completes with this
+   * Returns a `Future<RandomAccessFile>` that completes with this
    * [RandomAccessFile] when the write completes.
    */
   Future<RandomAccessFile> writeFrom(
       List<int> buffer, [int start = 0, int end]);
 
   /**
    * Synchronously writes from a [List<int>] to the file. It will read the
    * buffer from index [start] to index [end]. If [start] is omitted, it'll
    * start from index 0. If [end] is omitted, it will write to the end of
    * [buffer].
    *
    * Throws a [FileSystemException] if the operation fails.
    */
   void writeFromSync(List<int> buffer, [int start = 0, int end]);
 
   /**
    * Writes a string to the file using the given [Encoding]. Returns a
-   * [:Future<RandomAccessFile>:] that completes with this
+   * `Future<RandomAccessFile>` that completes with this
    * RandomAccessFile when the write completes.
    */
   Future<RandomAccessFile> writeString(String string,
                                        {Encoding encoding: UTF8});
 
   /**
    * Synchronously writes a single string to the file using the given
    * [Encoding].
    *
    * Throws a [FileSystemException] if the operation fails.
    */
   void writeStringSync(String string,
                        {Encoding encoding: UTF8});
 
   /**
    * Gets the current byte position in the file. Returns a
-   * [:Future<int>:] that completes with the position.
+   * `Future<int>` that completes with the position.
    */
   Future<int> position();
 
   /**
    * Synchronously gets the current byte position in the file.
    *
    * Throws a [FileSystemException] if the operation fails.
    */
   int positionSync();
 
   /**
    * Sets the byte position in the file. Returns a
-   * [:Future<RandomAccessFile>:] that completes with this
+   * `Future<RandomAccessFile>` that completes with this
    * RandomAccessFile when the position has been set.
    */
   Future<RandomAccessFile> setPosition(int position);
 
   /**
    * Synchronously sets the byte position in the file.
    *
    * Throws a [FileSystemException] if the operation fails.
    */
   void setPositionSync(int position);
 
   /**
    * Truncates (or extends) the file to [length] bytes. Returns a
-   * [:Future<RandomAccessFile>:] that completes with this
+   * `Future<RandomAccessFile>` that completes with this
    * RandomAccessFile when the truncation has been performed.
    */
   Future<RandomAccessFile> truncate(int length);
 
   /**
    * Synchronously truncates (or extends) the file to [length] bytes.
    *
    * Throws a [FileSystemException] if the operation fails.
    */
   void truncateSync(int length);
 
   /**
-   * Gets the length of the file. Returns a [:Future<int>:] that
+   * Gets the length of the file. Returns a `Future<int>` that
    * completes with the length in bytes.
    */
   Future<int> length();
 
   /**
    * Synchronously gets the length of the file.
    *
    * Throws a [FileSystemException] if the operation fails.
    */
   int lengthSync();
 
   /**
    * Flushes the contents of the file to disk. Returns a
-   * [:Future<RandomAccessFile>:] that completes with this
+   * `Future<RandomAccessFile>` that completes with this
    * RandomAccessFile when the flush operation completes.
    */
   Future<RandomAccessFile> flush();
 
   /**
    * Synchronously flushes the contents of the file to disk.
    *
    * Throws a [FileSystemException] if the operation fails.
    */
   void flushSync();
@@ skipping 164 matching lines @@
       sb.write(": $osError");
       if (path != null) {
         sb.write(", path = '$path'");
       }
     } else if (path != null) {
       sb.write(": $path");
     }
     return sb.toString();
   }
 }