]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/file.h
added template wxScopedArray<> too
[wxWidgets.git] / interface / wx / file.h
index 2522be80e1d5b39b0794065d57fd8e538b8badcd..30269c2e531caddc592b0a40eb1421df4212747a 100644 (file)
@@ -8,8 +8,8 @@
 
 
 /**
-    We redefine these constants here because S_IREAD &c are _not_ standard
-    however, we do assume that the values correspond to the Unix umask bits.
+    We redefine these constants here because S_IREAD &c are _not_ standard.
+    However, we do assume that the values correspond to the Unix umask bits.
 */
 enum wxPosixPermissions
 {
@@ -44,7 +44,7 @@ enum wxPosixPermissions
     //@}
 
     /// Default mode for the new files: allow reading/writing them to everybody but
-    /// the effective file mode will be set after anding this value with umask and
+    /// the effective file mode will be set after ANDing this value with umask and
     /// so won't include wxS_IW{GRP,OTH} for the default 022 umask value
     wxS_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | \
                    wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | \
@@ -52,7 +52,7 @@ enum wxPosixPermissions
 
     /// Default mode for the new directories (see wxFileName::Mkdir): allow
     /// reading/writing/executing them to everybody, but just like wxS_DEFAULT
-    /// the effective directory mode will be set after anding this value with umask
+    /// the effective directory mode will be set after ANDing this value with umask
     wxS_DIR_DEFAULT = (wxPOSIX_USER_READ | wxPOSIX_USER_WRITE | wxPOSIX_USER_EXECUTE | \
                        wxPOSIX_GROUP_READ | wxPOSIX_GROUP_WRITE | wxPOSIX_GROUP_EXECUTE | \
                        wxPOSIX_OTHERS_READ | wxPOSIX_OTHERS_WRITE | wxPOSIX_OTHERS_EXECUTE)
@@ -84,12 +84,12 @@ enum wxPosixPermissions
     file by default, you should explicitly call wxTempFile::Commit() to do it.
     Calling wxTempFile::Discard() explicitly discards any modifications: it
     closes and deletes the temporary file and leaves the original file unchanged.
-    If you don't call neither of Commit() and Discard(), the destructor will
+    If you call neither Commit() nor Discard(), the destructor will
     call Discard() automatically.
 
     To summarize: if you want to replace another file, create an instance of
-    wxTempFile passing the name of the file to be replaced to the constructor
-    (you may also use default constructor and pass the file name to wxTempFile::Open).
+    wxTempFile passing the name of the file to be replaced to the constructor.
+    (You may also use default constructor and pass the file name to wxTempFile::Open.)
     Then you can write to wxTempFile using wxFile-like functions and later call
     wxTempFile::Commit() to replace the old file (and close this one) or call
     wxTempFile::Discard() to cancel the modifications.
@@ -102,12 +102,14 @@ class wxTempFile
 public:
     /**
         Associates wxTempFile with the file to be replaced and opens it.
-        You should use IsOpened() to verify if the constructor succeeded.
+
+        @warning
+        You should use IsOpened() to verify that the constructor succeeded.
     */
     wxTempFile(const wxString& strName);
 
     /**
-        Destructor calls Discard() if temporary file is still opened.
+        Destructor calls Discard() if temporary file is still open.
     */
     ~wxTempFile();
 
@@ -116,14 +118,14 @@ public:
         file to the old name. Returns @true if both actions succeeded.
 
         If @false is returned it may unfortunately mean two quite different things:
-        either that either the old file couldn't be deleted or that the new file
+        either that the old file couldn't be deleted or that the new file
         couldn't be renamed to the old name.
     */
     bool Commit();
 
     /**
-        Discard changes: the old file contents is not changed, temporary file is
-        deleted.
+        Discard changes: the old file contents are not changed, the temporary
+        file is deleted.
     */
     void Discard();
 
@@ -135,9 +137,8 @@ public:
     /**
         Returns the length of the file.
 
-        This method may return wxInvalidOffset if the length couldn't be
-        determined or also 0 even for non-empty files if the file is not
-        seekable.
+        This method may return ::wxInvalidOffset if the length couldn't be
+        determined or 0 even for non-empty files if the file is not seekable.
 
         In general, the only way to determine if the file for which this function
         returns 0 is really empty or not is to try reading from it.
@@ -161,7 +162,7 @@ public:
                       wxSeekMode mode = wxFromStart);
 
     /**
-        Returns the current position or wxInvalidOffset if file is not opened or
+        Returns the current position or ::wxInvalidOffset if file is not opened or
         if another error occurred.
     */
     wxFileOffset Tell() const;
@@ -180,20 +181,11 @@ public:
 /**
     @class wxFile
 
-    A wxFile performs raw file I/O.
-
-    This is a very small class designed to minimize the overhead of using it - in fact,
-    there is hardly any overhead at all, but using it brings you automatic error
-    checking and hides differences between platforms and compilers.
-
-    wxFile also automatically closes the file in its destructor making it unnecessary
-    to worry about forgetting to do it.
-
     A wxFile performs raw file I/O. This is a very small class designed to
     minimize the overhead of using it - in fact, there is hardly any overhead at
     all, but using it brings you automatic error checking and hides differences
     between platforms and compilers. wxFile also automatically closes the file in
-    its destructor making it unnecessary to worry about forgetting to do it.
+    its destructor so you won't forget to do so.
     wxFile is a wrapper around @c file descriptor. - see also wxFFile for a
     wrapper around @c FILE structure.
 
@@ -226,7 +218,7 @@ public:
         read_write,
 
         /** Open file for appending: the file is opened for writing, but the old contents
-            of the file is not erased and the file pointer is initially placed at the end
+            of the file are not erased and the file pointer is initially placed at the end
             of the file; can not be used with Access().
 
             This is the same as OpenMode::write if the file doesn't exist.
@@ -258,6 +250,9 @@ public:
             The filename.
         @param mode
             The mode in which to open the file.
+
+        @warning
+        You should use IsOpened() to verify that the constructor succeeded.
     */
     wxFile(const wxString& filename,
            wxFile::OpenMode mode = wxFile::read);
@@ -273,7 +268,7 @@ public:
 
     /**
         Destructor will close the file.
-        @note it is not virtual so you should not use wxFile polymorphically.
+        @note This destructor is not virtual so you should not use wxFile polymorphically.
     */
     ~wxFile();
 
@@ -285,7 +280,7 @@ public:
 
     /**
         Attaches an existing file descriptor to the wxFile object.
-        Example of predefined file descriptors are 0, 1 and 2 which correspond to
+        Examples of predefined file descriptors are 0, 1 and 2 which correspond to
         stdin, stdout and stderr (and have symbolic names of @c wxFile::fd_stdin,
         @c wxFile::fd_stdout and @c wxFile::fd_stderr).
 
@@ -297,7 +292,7 @@ public:
     /**
         Closes the file.
     */
-    void Close();
+    bool Close();
 
     /**
         Creates a file for writing.
@@ -321,7 +316,7 @@ public:
 
     /**
         Returns @true if the end of the file has been reached.
-        Note that the behaviour of the file pointer based class wxFFile is
+        Note that the behaviour of the file pointer-based class wxFFile is
         different as wxFFile::Eof() will return @true here only if an
         attempt has been made to read @b past the last byte of the file, while
         wxFile::Eof() will return @true even before such attempt is made if the
@@ -329,7 +324,7 @@ public:
 
         Note also that this function doesn't work on unseekable file descriptors
         (examples include pipes, terminals and sockets under Unix) and an attempt to
-        use it will result in an error message in such case.
+        use it will result in an error message.
 
         So, to read the entire file into memory, you should write a loop which uses
         Read() repeatedly and tests its return condition instead of using Eof()
@@ -339,7 +334,7 @@ public:
 
     /**
         Returns @true if the given name specifies an existing regular file
-        (not a directory or a link)
+        (not a directory or a link).
     */
     static bool Exists(const wxString& filename);
 
@@ -375,10 +370,9 @@ public:
         @param mode
             The mode in which to open the file.
         @param access
-            An OR-combination of wxPosixPermissions enumeration values.
+            An OR-combination of ::wxPosixPermissions enumeration values.
     */
-    bool Open(const wxString& filename,
-              wxFile::OpenMode mode = wxFile::read,
+    bool Open(const wxString& filename, wxFile::OpenMode mode = wxFile::read,
               int access = wxS_DEFAULT);
 
     /**
@@ -389,9 +383,9 @@ public:
         @param count
            Bytes to read
 
-        @return The number of bytes read, or the symbol wxInvalidOffset.
+        @return The number of bytes read, or the symbol ::wxInvalidOffset.
     */
-    size_t Read(void* buffer, size_t count);
+    ssize_t Read(void* buffer, size_t count);
 
     /**
         Seeks to the specified position.
@@ -401,7 +395,7 @@ public:
         @param mode
             One of wxFromStart, wxFromEnd, wxFromCurrent.
 
-        @return The actual offset position achieved, or wxInvalidOffset on
+        @return The actual offset position achieved, or ::wxInvalidOffset on
                 failure.
     */
     wxFileOffset Seek(wxFileOffset ofs,
@@ -415,13 +409,13 @@ public:
         @param ofs
             Number of bytes before the end of the file.
 
-        @return The actual offset position achieved, or wxInvalidOffset on
+        @return The actual offset position achieved, or ::wxInvalidOffset on
                 failure.
     */
     wxFileOffset SeekEnd(wxFileOffset ofs = 0);
 
     /**
-        Returns the current position or wxInvalidOffset if file is not opened or
+        Returns the current position or ::wxInvalidOffset if file is not opened or
         if another error occurred.
     */
     wxFileOffset Tell() const;