cc81d32f2b
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@18805 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
296 lines
10 KiB
TeX
296 lines
10 KiB
TeX
\section{\class{wxTextFile}}\label{wxtextfile}
|
|
|
|
The wxTextFile is a simple class which allows to work with text files on line by
|
|
line basis. It also understands the differences in line termination characters
|
|
under different platforms and will not do anything bad to files with "non
|
|
native" line termination sequences - in fact, it can be also used to modify the
|
|
text files and change the line termination characters from one type (say DOS) to
|
|
another (say Unix).
|
|
|
|
One word of warning: the class is not at all optimized for big files and so 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
|
|
limitation for the small files like configuration files or programs sources
|
|
which are well handled by wxTextFile.
|
|
|
|
The typical things you may do with wxTextFile in order are:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item Create and open it: this is done with either
|
|
\helpref{Create}{wxtextfilecreate} or \helpref{Open}{wxtextfileopen}
|
|
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 {\tt Open()}) and closes it.
|
|
\item Work with the lines in the file: this may be done either with "direct
|
|
access" functions like \helpref{GetLineCount}{wxtextfilegetlinecount} and
|
|
\helpref{GetLine}{wxtextfilegetline} ({\it operator[]} does exactly the same
|
|
but looks more like array addressing) or with "sequential access" functions
|
|
which include \helpref{GetFirstLine}{wxtextfilegetfirstline}/
|
|
\helpref{GetNextLine}{wxtextfilegetnextline} and also
|
|
\helpref{GetLastLine}{wxtextfilegetlastline}/\helpref{GetPrevLine}{wxtextfilegetprevline}.
|
|
For the sequential access functions the current line number is maintained: it is
|
|
returned by \helpref{GetCurrentLine}{wxtextfilegetcurrentline} and may be
|
|
changed with \helpref{GoToLine}{wxtextfilegotoline}.
|
|
\item Add/remove lines to the file: \helpref{AddLine}{wxtextfileaddline} and
|
|
\helpref{InsertLine}{wxtextfileinsertline} add new lines while
|
|
\helpref{RemoveLine}{wxtextfileremoveline} deletes the existing ones.
|
|
\item Save your changes: notice that the changes you make to the file will {\bf
|
|
not} be saved automatically; calling \helpref{Close}{wxtextfileclose} or doing
|
|
nothing discards them! To save the changes you must explicitly call
|
|
\helpref{Write}{wxtextfilewrite} - here, you may also change the line
|
|
termination type if you wish.
|
|
\end{itemize}
|
|
|
|
\wxheading{Derived from}
|
|
|
|
No base class
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/textfile.h>
|
|
|
|
\wxheading{Data structures}
|
|
|
|
The following constants identify the line termination type:
|
|
|
|
\begin{verbatim}
|
|
enum wxTextFileType
|
|
{
|
|
wxTextFileType_None, // incomplete (the last line of the file only)
|
|
wxTextFileType_Unix, // line is terminated with 'LF' = 0xA = 10 = '\n'
|
|
wxTextFileType_Dos, // 'CR' 'LF'
|
|
wxTextFileType_Mac // 'CR' = 0xD = 13 = '\r'
|
|
};
|
|
\end{verbatim}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxFile}{wxfile}
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxTextFile::wxTextFile}\label{wxtextfilectordef}
|
|
|
|
\constfunc{}{wxTextFile}{\void}
|
|
|
|
Default constructor, use \helpref{Create}{wxtextfilecreate} or
|
|
\helpref{Open}{wxtextfileopen} with a file name parameter to initialize the object.
|
|
|
|
\membersection{wxTextFile::wxTextFile}\label{wxtextfilector}
|
|
|
|
\constfunc{}{wxTextFile}{\param{const wxString\& }{strFile}}
|
|
|
|
Constructor does not load the file into memory, use Open() to do it.
|
|
|
|
\membersection{wxTextFile::\destruct{wxTextFile}}\label{wxtextfiledtor}
|
|
|
|
\constfunc{}{\destruct{wxTextFile}}{\void}
|
|
|
|
Destructor does nothing.
|
|
|
|
\membersection{wxTextFile::AddLine}\label{wxtextfileaddline}
|
|
|
|
\constfunc{void}{AddLine}{\param{const wxString\& }{str}, \param{wxTextFileType }{type = typeDefault}}
|
|
|
|
Adds a line to the end of file.
|
|
|
|
\membersection{wxTextFile::Close}\label{wxtextfileclose}
|
|
|
|
\constfunc{bool}{Close}{\void}
|
|
|
|
Closes the file and frees memory, {\bf losing all changes}. Use \helpref{Write()}{wxtextfilewrite}
|
|
if you want to save them.
|
|
|
|
\membersection{wxTextFile::Create}\label{wxtextfilecreate}
|
|
|
|
\constfunc{bool}{Create}{\void}
|
|
|
|
\constfunc{bool}{Create}{\param{const wxString\& }{strFile}}
|
|
|
|
Creates the file with the given name or the name which was given in the
|
|
\helpref{constructor}{wxtextfilector}. The array of file lines is initially
|
|
empty.
|
|
|
|
It will fail if the file already exists, \helpref{Open}{wxtextfileopen} should
|
|
be used in this case.
|
|
|
|
\membersection{wxTextFile::Exists}\label{wxtextfileexists}
|
|
|
|
\constfunc{bool}{Exists}{\void}
|
|
|
|
Return true if file exists - the name of the file should have been specified
|
|
in the constructor before calling Exists().
|
|
|
|
\membersection{wxTextFile::IsOpened}\label{wxtextfileisopened}
|
|
|
|
\constfunc{bool}{IsOpened}{\void}
|
|
|
|
Returns true if the file is currently opened.
|
|
|
|
\membersection{wxTextFile::GetLineCount}\label{wxtextfilegetlinecount}
|
|
|
|
\constfunc{size\_t}{GetLineCount}{\void}
|
|
|
|
Get the number of lines in the file.
|
|
|
|
\membersection{wxTextFile::GetLine}\label{wxtextfilegetline}
|
|
|
|
\constfunc{wxString\&}{GetLine}{\param{size\_t }{n}}
|
|
|
|
Retrieves the line number {\it 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.
|
|
|
|
\membersection{wxTextFile::operator[]}\label{wxtextfileoperatorarray}
|
|
|
|
\constfunc{wxString\&}{operator[]}{\param{size\_t }{n}}
|
|
|
|
The same as \helpref{GetLine}{wxtextfilegetline}.
|
|
|
|
\membersection{wxTextFile::GetCurrentLine}\label{wxtextfilegetcurrentline}
|
|
|
|
\constfunc{size\_t}{GetCurrentLine}{\void}
|
|
|
|
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().
|
|
|
|
\membersection{wxTextFile::GoToLine}\label{wxtextfilegotoline}
|
|
|
|
\constfunc{void}{GoToLine}{\param{size\_t }{n}}
|
|
|
|
Changes the value returned by \helpref{GetCurrentLine}{wxtextfilegetcurrentline}
|
|
and used by \helpref{GetFirstLine()}{wxtextfilegetfirstline}/\helpref{GetNextLine()}{wxtextfilegetnextline}.
|
|
|
|
\membersection{wxTextFile::Eof}\label{wxtextfileeof}
|
|
|
|
\constfunc{bool}{Eof}{\void}
|
|
|
|
Returns true if the current line is the last one.
|
|
|
|
\membersection{wxTextFile::GetEOL}\label{wxtextfilegeteol}
|
|
|
|
\constfunc{static const char*}{GetEOL}{\param{wxTextFileType }{type = typeDefault}}
|
|
|
|
Get the line termination string corresponding to given constant. {\it 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).
|
|
|
|
\membersection{wxTextFile::GetFirstLine}\label{wxtextfilegetfirstline}
|
|
|
|
\constfunc{wxString\&}{GetFirstLine}{\void}
|
|
|
|
This method together with \helpref{GetNextLine()}{wxtextfilegetnextline}
|
|
allows more "iterator-like" traversal of the list of lines, i.e. you may
|
|
write something like:
|
|
|
|
\begin{verbatim}
|
|
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
|
|
\end{verbatim}
|
|
|
|
\membersection{wxTextFile::GetNextLine}\label{wxtextfilegetnextline}
|
|
|
|
\func{wxString\&}{GetNextLine}{\void}
|
|
|
|
Gets the next line (see \helpref{GetFirstLine}{wxtextfilegetfirstline} for
|
|
the example).
|
|
|
|
\membersection{wxTextFile::GetPrevLine}\label{wxtextfilegetprevline}
|
|
|
|
\func{wxString\&}{GetPrevLine}{\void}
|
|
|
|
Gets the previous line in the file.
|
|
|
|
\membersection{wxTextFile::GetLastLine}\label{wxtextfilegetlastline}
|
|
|
|
\func{wxString\&}{GetLastLine}{\void}
|
|
|
|
Gets the last line of the file. Together with
|
|
\helpref{GetPrevLine}{wxtextfilegetprevline} it allows to enumerate the lines
|
|
in the file from the end to the beginning like this:
|
|
|
|
\begin{verbatim}
|
|
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
|
|
\end{verbatim}
|
|
|
|
\membersection{wxTextFile::GetLineType}\label{wxtextfilegetlinetype}
|
|
|
|
\constfunc{wxTextFileType}{GetLineType}{\param{size\_t }{n}}
|
|
|
|
Get the type of the line (see also \helpref{GetEOL}{wxtextfilegeteol})
|
|
|
|
\membersection{wxTextFile::GuessType}\label{wxtextfileguesstype}
|
|
|
|
\constfunc{wxTextFileType}{GuessType}{\void}
|
|
|
|
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.
|
|
|
|
\membersection{wxTextFile::GetName}\label{wxtextfilegetname}
|
|
|
|
\constfunc{const char*}{GetName}{\void}
|
|
|
|
Get the name of the file.
|
|
|
|
\membersection{wxTextFile::InsertLine}\label{wxtextfileinsertline}
|
|
|
|
\constfunc{void}{InsertLine}{\param{const wxString\& }{str}, \param{size\_t }{n}, \param{wxTextFileType }{type = typeDefault}}
|
|
|
|
Insert a line before the line number {\it n}.
|
|
|
|
\membersection{wxTextFile::Open}\label{wxtextfileopen}
|
|
|
|
\constfunc{bool}{Open}{\param{wxMBConv\&}{ conv = wxConvLibc}}
|
|
|
|
\constfunc{bool}{Open}{\param{const wxString\& }{strFile}, \param{wxMBConv\&}{ conv = wxConvLibc}}
|
|
|
|
Open() opens the file with the given name or the name which was given in the
|
|
\helpref{constructor}{wxtextfilector} and also loads file in memory on
|
|
success. It will fail if the file does not exist,
|
|
\helpref{Create}{wxtextfilecreate} should be used in this case.
|
|
|
|
The {\it conv} argument is only meaningful in Unicode build of wxWindows when
|
|
it is used to convert the file to wide character representation.
|
|
|
|
\membersection{wxTextFile::RemoveLine}\label{wxtextfileremoveline}
|
|
|
|
\constfunc{void}{RemoveLine}{\param{size\_t }{n}}
|
|
|
|
Delete line number {\it n} from the file.
|
|
|
|
\membersection{wxTextFile::Write}\label{wxtextfilewrite}
|
|
|
|
\constfunc{bool}{Write}{\param{wxTextFileType }{typeNew = wxTextFileType\_None}, \param{wxMBConv\&}{ conv = wxConvLibc}}
|
|
|
|
Change the file on disk. The {\it 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 {\it conv} argument is only meaningful in Unicode build of wxWindows when
|
|
it is used to convert all lines to multibyte representation before writing them
|
|
them to physical file.
|
|
|
|
Returns true if operation succeeded, false if it failed.
|
|
|