X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/adaaa68635b4c8a4d8c5284add40366ea3eefb07..9e9574fe45b176ee74bba8fad7574cf9906145d1:/interface/wx/textfile.h?ds=inline diff --git a/interface/wx/textfile.h b/interface/wx/textfile.h index 4d0158d7fb..a2a9b1cdef 100644 --- a/interface/wx/textfile.h +++ b/interface/wx/textfile.h @@ -2,10 +2,23 @@ // Name: textfile.h // Purpose: interface of wxTextFile // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +// TODO: document wxTextBuffer + +/** + The line termination type. +*/ +enum wxTextFileType +{ + wxTextFileType_None, //!< incomplete (the last line of the file only) + wxTextFileType_Unix, //!< line is terminated with 'LF' = 0xA = 10 = '\\n' + wxTextFileType_Dos, //!< line is terminated with 'CR' 'LF' + wxTextFileType_Mac, //!< line is terminated with 'CR' = 0xD = 13 = '\\r' + wxTextFileType_Os2 //!< line is terminated with 'CR' 'LF' +}; + /** @class wxTextFile @@ -18,39 +31,31 @@ One word of warning: the class is not at all optimized for big files and thus it will load the file entirely into memory when opened. Of course, you should - not - work in this way with large files (as an estimation, anything over 1 Megabyte is - surely too big for this class). On the other hand, it is not a serious + not work in this way with large files (as an estimation, anything over 1 Megabyte + is surely too big for this class). On the other hand, it is not a serious limitation for small files like configuration files or program sources which are well handled by wxTextFile. The typical things you may do with wxTextFile in order are: - Create and open it: this is done with either - wxTextFile::Create or wxTextFile::Open - function which opens the file (name may be specified either as the argument to - these functions or in the constructor), reads its contents in memory (in the - case of @c Open()) and closes it. - Work with the lines in the file: this may be done either with "direct - access" functions like wxTextFile::GetLineCount and - wxTextFile::GetLine (@e operator[] does exactly the same - but looks more like array addressing) or with "sequential access" functions - which include wxTextFile::GetFirstLine/ - wxTextFile::GetNextLine and also - wxTextFile::GetLastLine/wxTextFile::GetPrevLine. - For the sequential access functions the current line number is maintained: it is - returned by wxTextFile::GetCurrentLine and may be - changed with wxTextFile::GoToLine. - Add/remove lines to the file: wxTextFile::AddLine and - wxTextFile::InsertLine add new lines while - wxTextFile::RemoveLine deletes the existing ones. - wxTextFile::Clear resets the file to empty. - Save your changes: notice that the changes you make to the file will @b not be - saved automatically; calling wxTextFile::Close or doing - nothing discards them! To save the changes you must explicitly call - wxTextFile::Write - here, you may also change the line - termination type if you wish. - + - Create and open it: this is done with either wxTextFile::Create or wxTextFile::Open + function which opens the file (name may be specified either as the argument to + these functions or in the constructor), reads its contents in memory (in the + case of wxTextFile::Open()) and closes it. + - Work with the lines in the file: this may be done either with "direct + access" functions like wxTextFile::GetLineCount and wxTextFile::GetLine + (@e operator[] does exactly the same but looks more like array addressing) + or with "sequential access" functions which include wxTextFile::GetFirstLine, + wxTextFile::GetNextLine and also wxTextFile::GetLastLine, wxTextFile::GetPrevLine. + For the sequential access functions the current line number is maintained: it is + returned by wxTextFile::GetCurrentLine and may be changed with wxTextFile::GoToLine. + - Add/remove lines to the file: wxTextFile::AddLine and wxTextFile::InsertLine + add new lines while wxTextFile::RemoveLine deletes the existing ones. + wxTextFile::Clear resets the file to empty. + - Save your changes: notice that the changes you make to the file will @b not be + saved automatically; calling wxTextFile::Close or doing nothing discards them! + To save the changes you must explicitly call wxTextFile::Write - here, you may + also change the line termination type if you wish. @library{wxbase} @category{file} @@ -60,6 +65,17 @@ class wxTextFile { public: + /** + Default type for current platform determined at compile time. + */ + static const wxTextFileType typeDefault; + + /** + Default constructor, use Create() or Open() with a file name parameter to + initialize the object. + */ + wxTextFile(); + /** Constructor does not load the file into memory, use Open() to do it. */ @@ -73,31 +89,35 @@ public: /** Adds a line to the end of file. */ - void AddLine(const wxString& str, - wxTextFileType type = typeDefault) const; + void AddLine(const wxString& str, wxTextFileType type = typeDefault); /** Delete all lines from the file, set current line number to 0. */ - void Clear() const; + void Clear(); /** - Closes the file and frees memory, @b losing all changes. Use Write() - if you want to save them. + Closes the file and frees memory, @b "losing all changes". + Use Write() if you want to save them. */ - bool Close() const; + bool Close(); - //@{ /** - Creates the file with the given name or the name which was given in the - @ref ctor() constructor. The array of file lines is initially - empty. - It will fail if the file already exists, Open() should - be used in this case. + Creates the file with the name which was given in the + wxTextFile(const wxString&) constructor. + The array of file lines is initially empty. + + It will fail if the file already exists, Open() should be used in this case. */ - bool Create() const; - const bool Create(const wxString& strFile) const; - //@} + bool Create(); + + /** + Creates the file with the given name. + The array of file lines is initially empty. + + It will fail if the file already exists, Open() should be used in this case. + */ + bool Create(const wxString& strFile); /** Returns @true if the current line is the last one. @@ -113,43 +133,70 @@ public: /** Returns the current line: it has meaning only when you're using GetFirstLine()/GetNextLine() functions, it doesn't get updated when - you're using "direct access" functions like GetLine(). GetFirstLine() and - GetLastLine() also change the value of the current line, as well as - GoToLine(). + you're using "direct access" functions like GetLine(). + GetFirstLine() and GetLastLine() also change the value of the current line, + as well as GoToLine(). */ size_t GetCurrentLine() const; /** - Get the line termination string corresponding to given constant. @e typeDefault - is - the value defined during the compilation and corresponds to the native format - of the platform, i.e. it will be wxTextFileType_Dos under Windows, - wxTextFileType_Unix under Unix (including Mac OS X when compiling with the - Apple Developer Tools) and wxTextFileType_Mac under Mac OS (including - Mac OS X when compiling with CodeWarrior). + Get the line termination string corresponding to given constant. + + @e typeDefault is the value defined during the compilation and corresponds + to the native format of the platform, i.e. it will be @c wxTextFileType_Dos + under Windows and @c wxTextFileType_Unix under Unix (including Mac OS + X, the value @c wxTextFileType_Mac was only used for classic Mac OS + versions). */ - static const char* GetEOL(wxTextFileType type = typeDefault) const; + static const wxChar* GetEOL(wxTextFileType type = typeDefault); /** - This method together with GetNextLine() - allows more "iterator-like" traversal of the list of lines, i.e. you may - write something like: + This method together with GetNextLine() allows more "iterator-like" + traversal of the list of lines, i.e. you may write something like: + + @code + wxTextFile file; + ... + for ( str = file.GetFirstLine(); !file.Eof(); str = file.GetNextLine() ) + { + // do something with the current line in str + } + // do something with the last line in str + @endcode */ - wxString GetFirstLine() const; + wxString& GetFirstLine(); /** - Gets the last line of the file. Together with - GetPrevLine() it allows to enumerate the lines + Gets the last line of the file. + + Together with GetPrevLine() it allows to enumerate the lines in the file from the end to the beginning like this: + + @code + wxTextFile file; + ... + for ( str = file.GetLastLine(); + file.GetCurrentLine() > 0; + str = file.GetPrevLine() ) + { + // do something with the current line in str + } + // do something with the first line in str + @endcode */ - wxString GetLastLine(); + wxString& GetLastLine(); /** - Retrieves the line number @a n from the file. The returned line may be - modified but you shouldn't add line terminator at the end - this will be done - by wxTextFile. + Retrieves the line number @a n from the file. + + The returned line may be modified when non-const method is used but you + shouldn't add line terminator at the end -- this will be done by + wxTextFile itself. */ - wxString GetLine(size_t n) const; + //@{ + wxString& GetLine(size_t n); + const wxString& GetLine(size_t n) const; + //@} /** Get the number of lines in the file. @@ -157,84 +204,97 @@ public: size_t GetLineCount() const; /** - Get the type of the line (see also wxTextFile::GetEOL) + Get the type of the line (see also wxTextFile::GetEOL). */ wxTextFileType GetLineType(size_t n) const; /** Get the name of the file. */ - const char* GetName() const; + const wxString& GetName() const; /** - Gets the next line (see GetFirstLine() for - the example). + Gets the next line (see GetFirstLine() for the example). */ - wxString GetNextLine(); + wxString& GetNextLine(); /** Gets the previous line in the file. */ - wxString GetPrevLine(); + wxString& GetPrevLine(); /** - Changes the value returned by GetCurrentLine() - and used by wxTextFile::GetFirstLine/GetNextLine(). + Changes the value returned by GetCurrentLine() and used by GetFirstLine() + and GetNextLine(). */ - void GoToLine(size_t n) const; + void GoToLine(size_t n); /** - Guess the type of file (which is supposed to be opened). If sufficiently - many lines of the file are in DOS/Unix/Mac format, the corresponding value will - be returned. If the detection mechanism fails wxTextFileType_None is returned. + Guess the type of file (which is supposed to be opened). + + If sufficiently many lines of the file are in DOS/Unix/Mac format, + the corresponding value will be returned. + If the detection mechanism fails @c wxTextFileType_None is returned. */ wxTextFileType GuessType() const; /** - Insert a line before the line number @e n. + Insert a line before the line number @a n. */ void InsertLine(const wxString& str, size_t n, - wxTextFileType type = typeDefault) const; + wxTextFileType type = typeDefault); /** Returns @true if the file is currently opened. */ bool IsOpened() const; - //@{ /** - ) - Open() opens the file with the given name or the name which was given in the - @ref ctor() constructor and also loads file in memory on - success. It will fail if the file does not exist, - Create() should be used in this case. - The @e conv argument is only meaningful in Unicode build of wxWidgets when + Opens the file with the name which was given in the wxTextFile(const wxString&) + constructor and also loads file in memory on success. + + It will fail if the file does not exist, Create() should be used in this case. + + The @a conv argument is only meaningful in Unicode build of wxWidgets when it is used to convert the file to wide character representation. */ - bool Open() const; - const bool Open(const wxString& strFile) const; - //@} + bool Open(const wxMBConv& conv = wxConvAuto()); + + /** + Opens the file with the given name and also loads file in memory on success. + + It will fail if the file does not exist, Create() should be used in this case. + + The @a conv argument is only meaningful in Unicode build of wxWidgets when + it is used to convert the file to wide character representation. + */ + bool Open(const wxString& strFile, const wxMBConv& conv = wxConvAuto()); /** Delete line number @a n from the file. */ - void RemoveLine(size_t n) const; + void RemoveLine(size_t n); /** - ) - Change the file on disk. The @a typeNew parameter allows you to change the - file format (default argument means "don't change type") and may be used to - convert, for example, DOS files to Unix. - The @e conv argument is only meaningful in Unicode build of wxWidgets when - it is used to convert all lines to multibyte representation before writing them + Change the file on disk. + + The @a typeNew parameter allows you to change the file format + (default argument means "don't change type") and may be used to convert, + for example, DOS files to Unix. + + The @a conv argument is only meaningful in Unicode build of wxWidgets when + it is used to convert all lines to multibyte representation before writing them to physical file. - Returns @true if operation succeeded, @false if it failed. + + @return + @true if operation succeeded, @false if it failed. */ - bool Write(wxTextFileType typeNew = wxTextFileType_None) const; + bool Write(wxTextFileType typeNew = wxTextFileType_None, + const wxMBConv& conv = wxConvAuto()); /** The same as GetLine(). */ - wxString operator[](size_t n) const; + wxString& operator[](size_t n) const; };