1. wxFile docs updated, wxTextFile and wxTempFile docs written (thanks HelpGen :-)
Added file classes section to the "classes by category" and tfile.tex - file classes/functions overview, feel free to add stuff there. 2. wxArray docs finally written. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1368 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Vadim Zeitlin
parent
7978fe62dd
commit
247aba1065
@ -1,3 +1,484 @@
|
||||
\section{\class{wxArray}}\label{wxarray}
|
||||
|
||||
TODO
|
||||
This section describes the so called {\it dynamic arrays}. This is a C
|
||||
array-like data structure i.e. the member access time is constant (and not
|
||||
linear in number of container elements as for linked lists). However, these
|
||||
arrays are dynamic in the sense that they will automatically allocate more
|
||||
memory if there is not enough of it for adding a new element. They also perform
|
||||
range checking on the index values but in debug mode only, so please be sure to
|
||||
compile your application in debug mode to use it (see \helpref{debugging
|
||||
overview}{debuggingoverview} for details). So, unlike the arrays in some other
|
||||
languages, attempt to access an element beyond the arrays bound doesn't
|
||||
automatically expand the array but provokes an assertion failure instead in
|
||||
debug build and does nothing (except possibly crashing your program) in the
|
||||
release build.
|
||||
|
||||
The array classes were designed to be reasonably efficient, both in terms of
|
||||
run-time speed and memory consumption and the executable size. The speed of
|
||||
array item access if, of course, constant (independent of number of elements)
|
||||
making them much more efficient than linked lists (\helpref{wxList}{wxlist}).
|
||||
Adding items to the arrays is also implemented in more or less constant time -
|
||||
but the price is preallocating the memory in advance. In the
|
||||
\helpref{memory management}{wxarraymemorymanagement} section you may find some
|
||||
useful hints about optimizing wxArray memory usage. As for executable size, all
|
||||
wxArray functions are inline, so they do not take {\it any space at all}.
|
||||
|
||||
wxWindows has three different kinds of array. All of them derive from
|
||||
wxBaseArray class which works with untyped data and can not be used directly.
|
||||
The standard macros WX\_DEFINE\_ARRAY(), WX\_DEFINE\_SORTED\_ARRAY() and
|
||||
WX\_DEFINE\_OBJARRAY() are used to define a new class deriving from it. The
|
||||
classes declared will be called in this documentation wxArray, wxSortedArray and
|
||||
wxObjArray but you should keep in mind that no classes with such names actually
|
||||
exist, each time you use one of WX\_DEFINE\_XXXARRAY macro you define a class
|
||||
with a new name. In fact, these names are "template" names and each usage of one
|
||||
of the macros mentioned above creates a template specialization for the given
|
||||
element type.
|
||||
|
||||
wxArray is suitable for storing integer types and pointers which it does not
|
||||
treat as objects in any way, i.e. the element pointed to by the pointer is not
|
||||
deleted when the element is removed from the array \&c. It should be noted that
|
||||
all of wxArray functions are inline, so it costs strictly nothing to define as
|
||||
many array types as you want (either in terms of the executable size or the
|
||||
speed) as long as at least one of them is defined and this is always the case
|
||||
because wxArrays are used by wxWindows internally.
|
||||
|
||||
wxSortedArray is a wxArray variant which should be used when searching in the
|
||||
array is a frequently used operation. It requires you to define an additional
|
||||
function for comparing two elements of the array element type and always stores
|
||||
its items in the sorted order (according to this function). Thus, it's
|
||||
\helpref{Index()}{wxarrayindex} function execution time is $O(log(N))$ instead of
|
||||
$O(N)$ for the usual arrays but the \helpref{Add()}{wxarrayadd} method is
|
||||
slower: it is $O(log(N))$ instead of constant time (neglecting time spent in
|
||||
memory allocation routine). However, in a usual situation elements are added to
|
||||
an array much less often than searched inside it, so wxSortedArray may lead to
|
||||
huge performance improvements compared to wxArray. As wxArray this array can not
|
||||
be used
|
||||
|
||||
wxObjArray class treats its elements like "objects". It may delete them when
|
||||
they are removed from the array (invoking the correct destructor) and copies
|
||||
them using the objects copy constructor. In order to implement this behaviour
|
||||
the definition of the wxObjArray arrays is split in two parts: first, you should
|
||||
declare the new wxObjArray class using WX\_DECLARE\_OBJARRAY() macro and then
|
||||
you must include the file defining the implementation of template type:
|
||||
<wx/arrimpl.cpp> and define the array class with WX\_DEFINE\_OBJARRAY() macro
|
||||
from a point where the full (as opposed to `forward') declaration of the array
|
||||
elements class is in scope. As it probably sounds very complicated here is an
|
||||
example:
|
||||
|
||||
\begin{verbatim}
|
||||
#include <wx/dynarray.h>
|
||||
|
||||
// we must forward declare the array because it's used inside the class
|
||||
// declaration
|
||||
class MyDirectory;
|
||||
class MyFile;
|
||||
|
||||
// this defines two new types: ArrayOfDirectories and ArrayOfFiles which can be
|
||||
// now used as shown below
|
||||
WX_DECLARE_OBJARRAY(MyDirectory, ArrayOfDirectories);
|
||||
WX_DECLARE_OBJARRAY(MyFile, ArrayOfFiles);
|
||||
|
||||
class MyDirectory
|
||||
{
|
||||
...
|
||||
ArrayOfDirectories m_subdirectories; // all subdirectories
|
||||
ArrayOfFiles m_files; // all files in this directory
|
||||
};
|
||||
|
||||
...
|
||||
|
||||
// now that we have MyDirectory declaration in scope we may finish the
|
||||
// definition of ArrayOfDirectories
|
||||
#include <wx/arrimpl.cpp> // this is a magic incantation which must be done!
|
||||
WX_DEFINE_OBJARRAY(ArrayOfDirectories);
|
||||
|
||||
// that's all!
|
||||
|
||||
\end{verbatim}
|
||||
|
||||
It is not as elegant as writing
|
||||
|
||||
\begin{verbatim}
|
||||
typedef std::vector<MyDirectory> ArrayOfDirectories;
|
||||
\end{verbatim}
|
||||
but is not that complicated and allows the code to be compiled with any, however
|
||||
dumb, C++ compiler in the world.
|
||||
|
||||
The things are much simpler for wxArray and wxSortedArray however: it is enough
|
||||
just to write
|
||||
|
||||
\begin{verbatim}
|
||||
WX_DEFINE_ARRAY(MyDirectory *, ArrayOfDirectories);
|
||||
WX_DEFINE_SORTED_ARRAY(MyFile *, ArrayOfFiles);
|
||||
\end{verbatim}
|
||||
|
||||
\wxheading{See also:}
|
||||
|
||||
\helpref{Container classes overview}{wxcontaineroverview}, \helpref{wxList}{wxlist}
|
||||
|
||||
\wxheading{Required headers:}
|
||||
|
||||
<wx/dynarray.h> for wxArray and wxSortedArray and additionally <wx/arrimpl.cpp>
|
||||
for wxObjArray.
|
||||
|
||||
\latexignore{\rtfignore{\wxheading{Function groups}}}
|
||||
|
||||
\membersection{Macros for template array definition}
|
||||
|
||||
To use an array you must first define the array class. This is done with the
|
||||
help of the macros in this section. The class of array elements must be (at
|
||||
least) forward declared for WX\_DEFINE\_ARRAY, WX\_DEFINE\_SORTED\_ARRAY and
|
||||
WX\_DECLARE\_OBJARRAY macros and must be fully declared before you use
|
||||
WX\_DEFINE\_OBJARRAY macro.
|
||||
|
||||
\helpref{WX\_DEFINE\_ARRAY}{wxdefinearray}\\
|
||||
\helpref{WX\_DEFINE\_SORTED\_ARRAY}{wxdefinesortedarray}\\
|
||||
\helpref{WX\_DECLARE\_OBJARRAY}{wxdeclareobjarray}\\
|
||||
\helpref{WX\_DEFINE\_OBJARRAY}{wxdefineobjarray}
|
||||
|
||||
\membersection{Constructors and destructors}
|
||||
|
||||
Array classes are 100\% C++ objects and as such they have the appropriate copy
|
||||
constructors and assignment operators. Copying wxArray just copies the elements
|
||||
but copying wxObjArray copies the arrays items. However, for memory-efficiency
|
||||
sake, neither of these classes has virtual destructor. It is not very important
|
||||
for wxArray which has trivial destructor anyhow, but it does mean that you
|
||||
should avoid deleting wxObjArray through a wxBaseArray pointer (as you would
|
||||
never use wxBaseArray anyhow it shouldn't be a problem) and that you should not
|
||||
derive your own classes from the array classes.
|
||||
|
||||
\helpref{wxArray default constructor}{wxarrayctordef}
|
||||
\helpref{wxArray copy constructors and assignment operators}{wxarrayctorcopy}
|
||||
\helpref{\destruct{wxArray}}{wxarraydtor}
|
||||
|
||||
\membersection{Memory management}\label{wxarraymemorymanagement}
|
||||
|
||||
Automatic array memory management is quite trivial: the array starts by
|
||||
preallocating some minimal amount of memory (defined by
|
||||
WX\_ARRAY\_DEFAULT\_INITIAL\_SIZE) and when further new items exhaust already
|
||||
allocated memory it reallocates it adding 50\% of the currently allocated
|
||||
amount, but no more than some maximal number which is defined by
|
||||
ARRAY\_MAXSIZE\_INCREMENT constant. Of course, this may lead to some memory
|
||||
being wasted (ARRAY\_MAXSIZE\_INCREMENT in the worst case, i.e. 4Kb in the
|
||||
current implementation), so the \helpref{Shrink()}{wxarrayshrink} function is
|
||||
provided to unallocate the extra memory. The \helpref{Alloc()}{wxarrayalloc}
|
||||
function can also be quite useful if you know in advance how many items you are
|
||||
going to put in the array and will prevent the array code from reallocating the
|
||||
memory more times than needed.
|
||||
|
||||
\helpref{Alloc}{wxarrayalloc}\\
|
||||
\helpref{Shrink}{wxarrayshrink}
|
||||
|
||||
\membersection{Number of elements and simple item access}
|
||||
|
||||
Functions in this section return the total number of array elements and allow to
|
||||
retrieve them - possibly using just the C array indexing $[]$ operator which
|
||||
does exactly the same as \helpref{Item()}{wxarrayitem} method.
|
||||
|
||||
\helpref{Count}{wxarraycount}\\
|
||||
\helpref{GetCount}{wxarraygetcount}\\
|
||||
\helpref{IsEmpty}{wxarrayisempty}\\
|
||||
\helpref{Item}{wxarrayitem}\\
|
||||
\helpref{Last}{wxarraylast}
|
||||
|
||||
\membersection{Adding items}
|
||||
\helpref{Add}{wxarrayadd}\\
|
||||
\helpref{Insert}{wxarrayinsert}
|
||||
|
||||
\membersection{Removing items}
|
||||
\helpref{WX\_CLEAR\_ARRAY}{wxcleararray}\\
|
||||
\helpref{Empty}{wxarrayempty}\\
|
||||
\helpref{Clear}{wxarrayclear}\\
|
||||
\helpref{Remove}{wxarrayremove}
|
||||
|
||||
\membersection{Searching and sorting}
|
||||
\helpref{Index}{wxarrayindex}\\
|
||||
\helpref{Sort}{wxarraysort}
|
||||
|
||||
%%%%% MEMBERS HERE %%%%%
|
||||
\helponly{\insertatlevel{2}{
|
||||
|
||||
\wxheading{Members}
|
||||
|
||||
}}
|
||||
|
||||
\membersection{WX\_DEFINE\_ARRAY}\label{wxdefinearray}
|
||||
\func{}{WX\_DEFINE\_ARRAY}{\param{}{T}, \param{name}}
|
||||
|
||||
This macro defines a new array class named {\it name} and containing the
|
||||
elements of type {\it T}. Example:
|
||||
\begin{verbatim}
|
||||
WX_DEFINE_ARRAY(int, wxArrayInt);
|
||||
|
||||
class MyClass;
|
||||
WX_DEFINE_ARRAY(MyClass *, wxArrayOfMyClass);
|
||||
\end{verbatim}
|
||||
|
||||
Note that wxWindows predefines the following standard array classes: wxArrayInt,
|
||||
wxArrayLong and wxArrayPtrVoid.
|
||||
|
||||
\membersection{WX\_DEFINE\_SORTED\_ARRAY}\label{wxdefinesortedarray}
|
||||
\func{}{WX\_DEFINE\_SORTED\_ARRAY}{\param{}{T}, \param{name}}
|
||||
|
||||
This macro defines a new sorted array class named {\it name} and containing
|
||||
the elements of type {\it T}. Example:
|
||||
\begin{verbatim}
|
||||
WX_DEFINE_SORTED_ARRAY(int, wxArrayInt);
|
||||
|
||||
class MyClass;
|
||||
WX_DEFINE_SORTED_ARRAY(MyClass *, wxArrayOfMyClass);
|
||||
\end{verbatim}
|
||||
|
||||
You will have to initialize the objects of this class by passing a comparaison
|
||||
function to the array object constructor like this:
|
||||
\begin{verbatim}
|
||||
int CompareInts(int n1, int n2)
|
||||
{
|
||||
return n1 - n2;
|
||||
}
|
||||
|
||||
wxArrayInt sorted(CompareInts);
|
||||
|
||||
int CompareMyClassObjects(MyClass *item1, MyClass *item2)
|
||||
{
|
||||
// sort the items by their address...
|
||||
return Stricmp(item1->GetAddress(), item2->GetAddress());
|
||||
}
|
||||
|
||||
wxArrayOfMyClass another(CompareMyClassObjects);
|
||||
\end{verbatim}
|
||||
|
||||
\membersection{WX\_DECLARE\_OBJARRAY}\label{wxdeclareobjarray}
|
||||
\func{}{WX\_DECLARE\_OBJARRAY}{\param{}{T}, \param{name}}
|
||||
|
||||
This macro declares a new object array class named {\it name} and containing
|
||||
the elements of type {\it T}. Example:
|
||||
\begin{verbatim}
|
||||
class MyClass;
|
||||
WX_DEFINE_OBJARRAY(MyClass, wxArrayOfMyClass); // note: not "MyClass *"!
|
||||
\end{verbatim}
|
||||
You must use \helpref{WX\_DEFINE\_OBJARRAY()}{wxdefineobjarray} macro to define
|
||||
the array class - otherwise you would get link errors.
|
||||
|
||||
\membersection{WX\_DEFINE\_OBJARRAY}\label{wxdefineobjarray}
|
||||
\func{}{WX\_DEFINE\_OBJARRAY}{\param{name}}
|
||||
|
||||
This macro defines the methods of the array class {\it name} not defined by the
|
||||
\helpref{WX\_DECLARE\_OBJARRAY()}{wxdeclareobjarray} macro. You must include the
|
||||
file <wx/arrimpl.cpp> before using this macro and you must have the full
|
||||
declaration of the class of array elements in scope! If you forget to do the
|
||||
first, the error will be caught by the compiler, but, unfortunately, many
|
||||
compilers will not give any warnings if you forget to do the second - but the
|
||||
objects of the class will not be copied correctly and their real destructor will
|
||||
not be called.
|
||||
|
||||
Example of usage:
|
||||
\begin{verbatim}
|
||||
// first declare the class!
|
||||
class MyClass
|
||||
{
|
||||
public:
|
||||
MyClass(const MyClass&);
|
||||
|
||||
...
|
||||
|
||||
virtual ~MyClass();
|
||||
};
|
||||
|
||||
#include <wx/arrimpl.cpp>
|
||||
WX_DEFINE_OBJARRAY(wxArrayOfMyClass);
|
||||
\end{verbatim}
|
||||
|
||||
\membersection{WX\_CLEAR\_ARRAY}\label{wxcleararray}
|
||||
\func{\void}{WX\_CLEAR\_ARRAY}{\param{wxArray\& }{array}}
|
||||
|
||||
This macro may be used to delete all elements of the array before emptying it.
|
||||
It can not be used with wxObjArrays - but they will delete their elements anyhow
|
||||
when you call Empty().
|
||||
|
||||
\membersection{Default constructors}\label{wxarrayctor}
|
||||
\func{}{wxArray}{}
|
||||
\func{}{wxObjArray}{}
|
||||
|
||||
Default constructor initializes an empty array object.
|
||||
|
||||
\func{}{wxSortedArray}{\param{int (*)(T first, T second)}{compareFunction}}
|
||||
|
||||
There is no default constructor for wxSortedArray classes - you must initialize it
|
||||
with a function to use for item comparaison. It is a function which is passed
|
||||
two arguments of type {\it T} where {\it T} is the array element type and which
|
||||
should return a negative, zero or positive value according to whether the first
|
||||
element passed to it is less than, equal to or greater than the second one.
|
||||
|
||||
\membersection{wxArray copy constructor and assignemnt operator}\label{wxarrayctorcopy}
|
||||
\func{}{wxArray}{\param{const wxArray\& }{array}}
|
||||
\func{}{wxSortedArray}{\param{const wxSortedArray\& }{array}}
|
||||
\func{}{wxObjArray}{\param{const wxObjArray\& }{array}}
|
||||
|
||||
\func{wxArray\&}{operator=}{\param{const wxArray\& }{array}}
|
||||
\func{wxSortedArray\&}{operator=}{\param{const wxSortedArray\& }{array}}
|
||||
\func{wxObjArray\&}{operator=}{\param{const wxObjArray\& }{array}}
|
||||
|
||||
The copy constructors and assignment operators perform a shallow array copy
|
||||
(i.e. they don't copy the objects pointed to even if the source array contains
|
||||
the items of pointer type) for wxArray and wxSortedArray and a deep copy (i.e.
|
||||
the array element are copied too) for wxObjArray.
|
||||
|
||||
\membersection{wxArray::\destruct{wxArray}}\label{wxarraydtor}
|
||||
\func{}{\destruct{wxArray}}{}
|
||||
\func{}{\destruct{wxSortedArray}}{}
|
||||
\func{}{\destruct{wxObjArray}}{}
|
||||
|
||||
The wxObjArray destructor deletes all the items owned by the array. This is not
|
||||
done by wxArray and wxSortedArray versions - you may use
|
||||
\helpref{WX\_CLEAR\_ARRAY}{wxcleararray} macro for this.
|
||||
|
||||
\membersection{wxArray::Add}\label{wxarrayadd}
|
||||
\func{\void}{Add}{\param{T }{item}}
|
||||
\func{\void}{Add}{\param{T *}{item}}
|
||||
\func{\void}{Add}{\param{T \&}{item}}
|
||||
|
||||
Appends a new element to the array (where {\it T} is the type of the array
|
||||
elements.)
|
||||
|
||||
The first version is used with wxArray and wxSortedArray. The second and the
|
||||
third are used with wxObjArray. There is an {\bf important difference} between
|
||||
them: if you give a pointer to the array, it will take ownership of it, i.e.
|
||||
will delete it when the item is deleted from the array. If you give a reference
|
||||
to the array, however, the array will make a copy of the item and will not take
|
||||
ownership of the original item. Once again, it only makes sense for wxObjArrays
|
||||
because the other array types never take ownership of their elements.
|
||||
|
||||
\membersection{wxArray::Alloc}\label{wxarrayalloc}
|
||||
\func{\void}{Alloc}{\param{size\_t }{count}}
|
||||
|
||||
Preallocates memory for a given number of array elements. It is worth calling
|
||||
when the number of items which are going to be added to the array is known in
|
||||
advance because it will save unneeded memory reallocation. If the array already
|
||||
has enough memory for the given number of items, nothing happens.
|
||||
|
||||
\membersection{wxArray::Clear}\label{wxarrayclear}
|
||||
\func{\void}{Clear}{\void}
|
||||
|
||||
This function does the same as \helpref{Empty()}{wxarrayempty} and additionally
|
||||
frees the memory allocated to the array.
|
||||
|
||||
\membersection{wxArray::Count}\label{wxarraycount}
|
||||
\constfunc{size\_t}{Count}{\void}
|
||||
|
||||
Same as \helpref{GetCount()}{wxarraygetcount}. This function is deprecated -
|
||||
it exists only for compatibility.
|
||||
|
||||
\membersection{wxObjArray::Detach}\label{wxobjarraydetach}
|
||||
\func{T *}{Detach}{\param{size\_t }{index}}
|
||||
|
||||
Removes the element from the array, but, unlike,
|
||||
\helpref{Remove()}{wxarrayremove} doesn't delete it. The function returns the
|
||||
pointer to the removed element.
|
||||
|
||||
\membersection{wxArray::Empty}\label{wxarrayempty}
|
||||
\func{\void}{Empty}{\void}
|
||||
|
||||
Empties the array. For wxObjArray classes, this destroys all of the array
|
||||
elements. For wxArray and wxSortedArray this does nothing except marking the
|
||||
array of being empty - this function does not free the allocated memory, use
|
||||
\helpref{Clear()}{wxarrayclear} for this.
|
||||
|
||||
\membersection{wxArray::GetCount}\label{wxarraygetcount}
|
||||
\constfunc{size\_t}{GetCount}{\void}
|
||||
|
||||
Return the number of items in the array.
|
||||
|
||||
\membersection{wxArray::Index}\label{wxarrayindex}
|
||||
\func{int}{Index}{\param{T\& }{item}, \param{bool }{searchFromEnd = FALSE}}
|
||||
\func{int}{Index}{\param{T\& }{item}}
|
||||
|
||||
The first version of the function is for wxArray and wxObjArray, the second is
|
||||
for wxSortedArray only.
|
||||
|
||||
Searches the element in the array, starting from either beginning or the end
|
||||
depending on the value of {\it searchFromEnd} parameter. wxNOT\_FOUND is
|
||||
returned if the element is not found, otherwise the index of the element is
|
||||
returned.
|
||||
|
||||
Linear search is used for the wxArray and wxObjArray classes but binary search
|
||||
in the sorted array is used for wxSortedArray (this is why searchFromEnd
|
||||
parameter doesn't make sense for it).
|
||||
|
||||
\membersection{wxArray::Insert}\label{wxarrayinsert}
|
||||
\func{\void}{Insert}{\param{T }{item}, \param{size\_t }{n}}
|
||||
\func{\void}{Insert}{\param{T *}{item}, \param{size\_t }{n}}
|
||||
\func{\void}{Insert}{\param{T \&}{item}, \param{size\_t }{n}}
|
||||
|
||||
Insert a new item into the array before the item {\it n} - thus, {\it
|
||||
Insert(something, 0u}} will insert an item in such way that it will become the
|
||||
first array element.
|
||||
|
||||
Please see \helpref{Add()}{wxarrayadd} for explanation of the differences
|
||||
between the overloaded versions of this function.
|
||||
|
||||
\membersection{wxArray::IsEmpty}\label{wxarrayisempty}
|
||||
\constfunc{bool}{IsEmpty}{}
|
||||
|
||||
Returns TRUE if the array is empty, FALSE otherwise.
|
||||
|
||||
\membersection{wxArray::Item}\label{wxarrayitem}
|
||||
\constfunc{T\&}{Item}{\param{size\_t }{index}}
|
||||
|
||||
Returns the item at the given position in the array. If {\it index} is out of
|
||||
bounds, an assert failure is raised in the debug builds but nothing special is
|
||||
done in the release build.
|
||||
|
||||
The returned value is of type "reference to the array element type" for all of
|
||||
the array classes.
|
||||
|
||||
\membersection{wxArray::Last}\label{wxarraylast}
|
||||
\constfunc{T\&}{Last}{\void}
|
||||
|
||||
Returns the last element in the array, i.e. is the same as Item(GetCount() - 1).
|
||||
An assert failure is raised in the debug mode if the array is empty.
|
||||
|
||||
The returned value is of type "reference to the array element type" for all of
|
||||
the array classes.
|
||||
|
||||
\membersection{wxArray::Remove}\label{wxarrayremove}
|
||||
\func{\void}{Remove}{\param{size\_t }{index}}
|
||||
\func{\void}{Remove}{\param{T }{item}}
|
||||
|
||||
Removes the element from the array either by index or by value. When an element
|
||||
is removed from wxObjArray it is deleted by the array - use
|
||||
\helpref{Detach()}{wxobjarraydetach} if you don't want this to happen. On the
|
||||
other hand, when an object is removed from a wxArray nothing happens - you
|
||||
should delete the it manually if required:
|
||||
\begin{verbatim}
|
||||
T *item = array[n];
|
||||
delete item;
|
||||
array.Remove(n)
|
||||
\end{verbatim}
|
||||
|
||||
See also \helpref{WX\_CLEAR\_ARRAY}{wxcleararray} macro which deletes all
|
||||
elements of a wxArray (supposed to contain pointers).
|
||||
|
||||
\membersection{wxArray::Shrink}\label{wxarrayshrink}
|
||||
\func{\void}{Shrink}{\void}
|
||||
|
||||
Frees all memory unused by the array. If the program knows that no new items
|
||||
will be added to the array it may call Shrink() to reduce its memory usage.
|
||||
However, if a new item is added to the array, some extra memory will be
|
||||
allocated again.
|
||||
|
||||
\membersection{wxArray::Sort}\label{wxarraysort}
|
||||
\func{\void}{Sort}{\param{CMPFUNC<T> }{compareFunction}}
|
||||
|
||||
The notation CMPFUNC<T> should be read as if we had the following declaration:
|
||||
\begin{verbatim}
|
||||
template int CMPFUNC(T *first, T *second);
|
||||
\end{verbatim}
|
||||
where {\it T} is the type of the array elements. I.e. it is a function returning
|
||||
{\it int} which is passed two arguments of type {\it T *}.
|
||||
|
||||
Sorts the array using the specified compare function: this function should
|
||||
return a negative, zero or positive value according to whether the first element
|
||||
passed to it is less than, equal to or greater than the second one.
|
||||
|
||||
wxSortedArray doesn't have this function because it is always sorted.
|
||||
|
||||
@ -326,6 +326,17 @@ product.
|
||||
\twocolitem{\helpref{wxRecordSet}{wxrecordset}}{Class representing one or more record}
|
||||
\end{twocollist}
|
||||
|
||||
{\large {\bf File related classes}}
|
||||
|
||||
wxWindows has several small classes to work with disk files, see \helpref{file classes
|
||||
overview}{wxfileoverview} for more details.
|
||||
|
||||
\begin{twocollist}\itemsep=0pt
|
||||
\twocolitem{\helpref{wxFile}{wxfile}}{Low-level file input/output}
|
||||
\twocolitem{\helpref{wxTempFile}{wxtempfile}}{Class to safely replace an existing file}
|
||||
\twocolitem{\helpref{wxTextFile}{wxtextfile}}{Class for working with text files as with arrays of lines}
|
||||
\end{twocollist}
|
||||
|
||||
{\large {\bf Miscellaneous}}
|
||||
|
||||
\begin{twocollist}\itemsep=0pt
|
||||
@ -339,5 +350,3 @@ product.
|
||||
\twocolitem{\helpref{wxTimer}{wxtimer}}{Timer class}
|
||||
\twocolitem{\helpref{wxSystemSettings}{wxsystemsettings}}{System settings class}
|
||||
\end{twocollist}
|
||||
|
||||
|
||||
|
||||
@ -182,6 +182,8 @@ $$\image{14cm;0cm}{wxclass.ps}$$
|
||||
\input text.tex
|
||||
\input textdlg.tex
|
||||
\input valtext.tex
|
||||
\input tempfile.tex
|
||||
\input textfile.tex
|
||||
\input thread.tex
|
||||
\input time.tex
|
||||
\input timer.tex
|
||||
|
||||
@ -1,12 +1,66 @@
|
||||
\section{\class{wxFile}}\label{wxfile}
|
||||
|
||||
A wxFile performs raw file I/O. Note that wxFile::Flush is not implemented on some Windows compilers
|
||||
due to a missing fsync function, which reduces the usefulness of this class.
|
||||
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.
|
||||
|
||||
\wxheading{Derived from}
|
||||
|
||||
None.
|
||||
|
||||
\wxheading{Constants}
|
||||
|
||||
wx/file.h defines the following constants:
|
||||
{\small
|
||||
\begin{verbatim}
|
||||
#define wxS_IRUSR 00400
|
||||
#define wxS_IWUSR 00200
|
||||
#define wxS_IXUSR 00100
|
||||
|
||||
#define wxS_IRGRP 00040
|
||||
#define wxS_IWGRP 00020
|
||||
#define wxS_IXGRP 00010
|
||||
|
||||
#define wxS_IROTH 00004
|
||||
#define wxS_IWOTH 00002
|
||||
#define wxS_IXOTH 00001
|
||||
|
||||
// default mode for the new files: corresponds to umask 022
|
||||
#define wxS_DEFAULT (wxS_IRUSR | wxS_IWUSR | wxS_IRGRP | wxS_IWGRP | wxS_IROTH | wxS_IWOTH)
|
||||
\end{verbatim}
|
||||
}
|
||||
|
||||
These constants define the file access rights and are used with
|
||||
\helpref{wxFile::Create}{wxfilecreate} and \helpref{wxFile::Open}{wxfileopen}.
|
||||
|
||||
The {\it OpenMode} enumeration defines the different modes for opening a file,
|
||||
it's defined inside wxFile class so its members should be specified with {\it
|
||||
wxFile::} scope resolution prefix. It is also used with
|
||||
\helpref{wxFile::Access}{wxfileaccess} function.
|
||||
|
||||
\twocolwidtha{7cm}%
|
||||
\begin{twocollist}\itemsep=0pt
|
||||
\twocolitem{{\bf wxFile::read}}{Open file for reading or test if it can be opened for reading with Access()}
|
||||
\twocolitem{{\bf wxFile::write}}{Open file for writing deleting the contents of the file if it already exists
|
||||
or test if it can be opened for writing with Access()}
|
||||
\twocolitem{{\bf wxFile::read\_write}}{Open file for reading and writing; can not be used with Access()}
|
||||
\twocolitem{{\bf wxFile::write\_append}}{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;
|
||||
can not be used with Access()}
|
||||
\end{twocollist}
|
||||
|
||||
Other constants defined elsewhere but used by wxFile functions are wxInvalidOffset which represents an
|
||||
invalid value of type {\it off\_t} and is returned by functions returning {\it off\_t} on error and the seek
|
||||
mode constants used with \helpref{Seek()}{wxfileseek}:
|
||||
|
||||
\twocolwidtha{7cm}
|
||||
\begin{twocollist}\itemsep=0pt
|
||||
\twocolitem{{\bf wxFromStart}}{Count offset from the start of the file}
|
||||
\twocolitem{{\bf wxFromCurrent}}{Count offset from the current position of the file pointer}
|
||||
\twocolitem{{\bf wxFromEnd}}{Count offset from the end of the file (backwards)}
|
||||
\end{twocollist}
|
||||
|
||||
\latexignore{\rtfignore{\wxheading{Members}}}
|
||||
|
||||
\membersection{wxFile::wxFile}\label{wxfileconstr}
|
||||
@ -17,7 +71,10 @@ Default constructor.
|
||||
|
||||
\func{}{wxFile}{\param{const char*}{ filename}, \param{wxFile::OpenMode}{ mode = wxFile::read}}
|
||||
|
||||
Opens a file with the given mode.
|
||||
Opens a file with the given mode. As there is no way to return whether the
|
||||
operation was successful or not from the constructor you should test the
|
||||
return value of \helpref{IsOpened}{wxfileisopened} to check that it didn't
|
||||
fail.
|
||||
|
||||
\func{}{wxFile}{\param{int}{ fd}}
|
||||
|
||||
@ -29,19 +86,31 @@ Opens a file with the given file descriptor, which has already been opened.
|
||||
|
||||
\docparam{mode}{The mode in which to open the file. May be one of {\bf wxFile::read}, {\bf wxFile::write} and {\bf wxFile::read\_write}.}
|
||||
|
||||
\docparam{fd}{An existing file descriptor.}
|
||||
\docparam{fd}{An existing file descriptor (see \helpref{Attach()}{wxfileattach} for the list of predefined descriptors)}
|
||||
|
||||
\membersection{wxFile::\destruct{wxFile}}
|
||||
|
||||
\func{}{\destruct{wxFile}}{\void}
|
||||
|
||||
Destructor. This is not virtual, for efficiency.
|
||||
Destructor will close the file.
|
||||
|
||||
NB: it is not virtual so you should {\it not} derive from wxFile!
|
||||
|
||||
\membersection{wxFile::Access}\label{wxfileaccess}
|
||||
\func{static bool}{Access}{\param{const char *}{ name}, \param{OpenMode}{ mode}
|
||||
|
||||
This function verifies if we may access the given file in specified mode. Only
|
||||
values of wxFile::read or wxFile::write really make sense here.
|
||||
|
||||
\membersection{wxFile::Attach}\label{wxfileattach}
|
||||
|
||||
\func{void}{Attach}{\param{int}{ fd}}
|
||||
|
||||
Attaches an existing file descriptor to the wxFile object.
|
||||
Attaches an existing file descriptor to the wxFile object. Example of predefined
|
||||
file descriptors are 0, 1 and 2 which correspond to stdin, stdout and stderr (and
|
||||
have symbolic names of wxFile::fd\_stdin, wxFile::fd\_stdout and wxFile::fd\_stderr).
|
||||
|
||||
The descriptor should be already opened and it will be closed by wxFile
|
||||
object.
|
||||
|
||||
\membersection{wxFile::Close}\label{wxfileclose}
|
||||
|
||||
@ -51,11 +120,22 @@ Closes the file.
|
||||
|
||||
\membersection{wxFile::Create}\label{wxfilecreate}
|
||||
|
||||
\func{bool}{Create}{\param{const char*}{ filename}, \param{bool}{ overwrite = FALSE}}
|
||||
\func{bool}{Create}{\param{const char*}{ filename}, \param{bool}{ overwrite = FALSE}, \param{int }{access = wxS\_DEFAULT}}
|
||||
|
||||
Creates a file for writing. If the file already exists, setting {\bf overwrite} to TRUE
|
||||
will ensure it is overwritten.
|
||||
|
||||
\membersection{wxFile::Detach}\label{wxfiledetach}
|
||||
\func{void}{Detach}{\void}
|
||||
|
||||
Get back a file descriptor from wxFile object - the caller is responsible for closing the file if this
|
||||
descriptor is opened. \helpref{IsOpened()}{wxfileisopened} will return FALSE after call to Detach().
|
||||
|
||||
\membersection{wxFile::fd}\label{wxfilefd}
|
||||
\constfunc{int}{fd}{\void}
|
||||
|
||||
Returns the file descriptor associated with the file.
|
||||
|
||||
\membersection{wxFile::Eof}\label{wxfileeof}
|
||||
|
||||
\constfunc{bool}{Eof}{\void}
|
||||
@ -66,13 +146,17 @@ Returns TRUE if the end of the file has been reached.
|
||||
|
||||
\func{static bool}{Exists}{\param{const char*}{ filename}}
|
||||
|
||||
Returns TRUE if the file exists.
|
||||
Returns TRUE if the given name specifies an existing regular file.
|
||||
|
||||
\membersection{wxFile::Flush}\label{wxfileflush}
|
||||
|
||||
\func{bool}{Flush}{\void}
|
||||
|
||||
Flushes the file descriptor. Not implemented for some Windows compilers.
|
||||
Flushes the file descriptor.
|
||||
|
||||
Note that wxFile::Flush is not implemented on some Windows compilers
|
||||
due to a missing fsync function, which reduces the usefulness of this function
|
||||
(it can still be called but it will do nothing on unsupported compilers).
|
||||
|
||||
\membersection{wxFile::IsOpened}\label{wxfileisopened}
|
||||
|
||||
@ -112,7 +196,7 @@ Reads the specified number of bytes into a buffer, returning the actual number r
|
||||
|
||||
\wxheading{Return value}
|
||||
|
||||
The number of bytes read, or the symbol {\bf ofsInvalid} (-1) if there was an error.
|
||||
The number of bytes read, or the symbol {\bf wxInvalidOffset} (-1) if there was an error.
|
||||
|
||||
\membersection{wxFile::Seek}\label{wxfileseek}
|
||||
|
||||
@ -128,7 +212,7 @@ Seeks to the specified position.
|
||||
|
||||
\wxheading{Return value}
|
||||
|
||||
The actual offset position achieved, or ofsInvalid on failure.
|
||||
The actual offset position achieved, or wxInvalidOffset on failure.
|
||||
|
||||
\membersection{wxFile::SeekEnd}\label{wxfileseekend}
|
||||
|
||||
@ -142,13 +226,14 @@ Moves the file pointer to the specified number of bytes before the end of the fi
|
||||
|
||||
\wxheading{Return value}
|
||||
|
||||
The actual offset position achieved, or ofsInvalid on failure.
|
||||
The actual offset position achieved, or wxInvalidOffset on failure.
|
||||
|
||||
\membersection{wxFile::Tell}\label{wxfiletell}
|
||||
|
||||
\constfunc{off\_t}{Tell}{\void}
|
||||
|
||||
Returns the current position.
|
||||
Returns the current position or wxInvalidOffset if file is not opened or if another
|
||||
error occured.
|
||||
|
||||
\membersection{wxFile::Write}\label{wxfilewrite}
|
||||
|
||||
@ -166,4 +251,7 @@ Writes the specified number of bytes from a buffer.
|
||||
|
||||
TRUE if the operation was successful.
|
||||
|
||||
\membersection{wxFile::Write}\label{wxfilewrites}
|
||||
\func{bool}{Write}{\param{const wxString& }{s}}
|
||||
|
||||
Writes the contents of the string to the file, returns TRUE on success
|
||||
|
||||
@ -21,7 +21,7 @@ your programs as well if you wish.
|
||||
The list classes in wxWindows are double-linked lists which may either own the
|
||||
objects they contain (meaning that the list deletes the object when it is
|
||||
removed from the list or the list itself is destroyed) or just store the
|
||||
pointers depending on whether you called or not
|
||||
pointers depending on whether you called or not
|
||||
\helpref{wxList::DeleteContents}{wxlistdeletecontents} method.
|
||||
|
||||
Dynamic arrays resemble to C arrays but with two important differences: they
|
||||
|
||||
@ -38,4 +38,5 @@ This chapter contains a selection of topic overviews.
|
||||
\input tstring.tex
|
||||
\input tdnd.tex
|
||||
\input tthreads.tex
|
||||
\input tfile.tex
|
||||
\input tusage.tex
|
||||
|
||||
Loading…
Reference in New Issue
Block a user