]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/arrstrng.tex
added sizers support; allow resizeable wizards (Robert Vazan)
[wxWidgets.git] / docs / latex / wx / arrstrng.tex
CommitLineData
9e2be6f0
VZ
1\section{\class{wxArrayString}}\label{wxarraystring}
2
3wxArrayString is an efficient container for storing
4\helpref{wxString}{wxstring} objects. It has the same features as all
5\helpref{wxArray}{wxarray} classes, i.e. it dynamically expands when new items
2a47d3c1
JS
6are added to it (so it is as easy to use as a linked list), but the access
7time to the elements is constant, instead of being linear in number of
8elements as in the case of linked lists. It is also very size efficient and
e87271f3
VZ
9doesn't take more space than a C array {\it wxString[]} type (wxArrayString
10uses its knowledge of internals of wxString class to achieve this).
9e2be6f0
VZ
11
12This class is used in the same way as other dynamic \helpref{arrays}{wxarray},
13except that no {\it WX\_DEFINE\_ARRAY} declaration is needed for it. When a
14string is added or inserted in the array, a copy of the string is created, so
15the original string may be safely deleted (e.g. if it was a {\it char *}
16pointer the memory it was using can be freed immediately after this). In
17general, there is no need to worry about string memory deallocation when using
18this class - it will always free the memory it uses itself.
19
20The references returned by \helpref{Item}{wxarraystringitem},
21\helpref{Last}{wxarraystringlast} or
22\helpref{operator[]}{wxarraystringoperatorindex} are not constant, so the
23array elements may be modified in place like this
24
25\begin{verbatim}
26 array.Last().MakeUpper();
27\end{verbatim}
28
2edb0bde 29There is also a variant of wxArrayString called wxSortedArrayString which has
e87271f3
VZ
30exactly the same methods as wxArrayString, but which always keeps the string
31in it in (alphabetical) order. wxSortedArrayString uses binary search in its
2edb0bde 32\helpref{Index}{wxarraystringindex} function (instead of linear search for
e87271f3
VZ
33wxArrayString::Index) which makes it much more efficient if you add strings to
34the array rarely (because, of course, you have to pay for Index() efficiency
35by having Add() be slower) but search for them often. Several methods should
2edb0bde 36not be used with sorted array (basically, all which break the order of items)
e87271f3
VZ
37which is mentioned in their description.
38
39Final word: none of the methods of wxArrayString is virtual including its
40destructor, so this class should not be used as a base class.
9e2be6f0 41
2a47d3c1 42\wxheading{Derived from}
9e2be6f0
VZ
43
44Although this is not true strictly speaking, this class may be considered as a
45specialization of \helpref{wxArray}{wxarray} class for the wxString member
46data: it is not implemented like this, but it does have all of the wxArray
47functions.
48
49\wxheading{Include files}
50
df5168c4 51<wx/arrstr.h>
9e2be6f0
VZ
52
53\wxheading{See also}
54
2a47d3c1 55\helpref{wxArray}{wxarray}, \helpref{wxString}{wxstring}, \helpref{wxString overview}{wxstringoverview}
9e2be6f0
VZ
56
57\latexignore{\rtfignore{\wxheading{Members}}}
58
59\membersection{wxArrayString::wxArrayString}\label{wxarraystringctor}
60
61\func{}{wxArrayString}{\void}
62
63\func{}{wxArrayString}{\param{const wxArrayString\&}{ array}}
64
65Default and copy constructors.
66
e87271f3
VZ
67Note that when an array is assigned to a sorted array, its contents is
68automatically sorted during construction.
69
9e2be6f0
VZ
70\membersection{wxArrayString::\destruct{wxArrayString}}\label{wxarraystringdtor}
71
72\func{}{\destruct{wxArrayString}}{}
73
74Destructor frees memory occupied by the array strings. For the performance
75reasons it is not virtual, so this class should not be derived from.
76
77\membersection{wxArrayString::operator=}\label{wxarraystringoperatorassign}
78
79\func{wxArrayString \&}{operator $=$}{\param{const wxArrayString\&}{ array}}
80
81Assignment operator.
82
f6bcfd97
BP
83\membersection{wxArrayString::operator==}\label{wxarraystringoperatorequal}
84
85\constfunc{bool}{operator $==$}{\param{const wxArrayString\&}{ array}}
86
cc81d32f 87Compares 2 arrays respecting the case. Returns true only if the arrays have
f6bcfd97
BP
88the same number of elements and the same strings in the same order.
89
90\membersection{wxArrayString::operator!=}\label{wxarraystringoperatornotequal}
91
92\constfunc{bool}{operator $!=$}{\param{const wxArrayString\&}{ array}}
93
cc81d32f 94Compares 2 arrays respecting the case. Returns true if the arrays have
f6bcfd97
BP
95different number of elements or if the elements don't match pairwise.
96
9e2be6f0
VZ
97\membersection{wxArrayString::operator[]}\label{wxarraystringoperatorindex}
98
e87271f3 99\func{wxString\&}{operator[]}{\param{size\_t }{nIndex}}
9e2be6f0
VZ
100
101Return the array element at position {\it nIndex}. An assert failure will
102result from an attempt to access an element beyond the end of array in debug
103mode, but no check is done in release mode.
104
105This is the operator version of \helpref{Item}{wxarraystringitem} method.
106
107\membersection{wxArrayString::Add}\label{wxarraystringadd}
108
8a2a6bbf 109\func{size\_t}{Add}{\param{const wxString\& }{str}, \param{size\_t}{ copies = $1$}}
9e2be6f0 110
8a2a6bbf
SN
111Appends the given number of {\it copies} of the new item {\it str} to the
112array and returns the index of the first new item in the array.
9e2be6f0 113
e87271f3
VZ
114{\bf Warning:} For sorted arrays, the index of the inserted item will not be,
115in general, equal to \helpref{GetCount()}{wxarraystringgetcount} - 1 because
116the item is inserted at the correct position to keep the array sorted and not
117appended.
118
9e2be6f0
VZ
119See also: \helpref{Insert}{wxarraystringinsert}
120
121\membersection{wxArrayString::Alloc}\label{wxarraystringalloc}
122
123\func{void}{Alloc}{\param{size\_t }{nCount}}
124
125Preallocates enough memory to store {\it nCount} items. This function may be
126used to improve array class performance before adding a known number of items
127consecutively.
128
129See also: \helpref{Dynamic array memory management}{wxarraymemorymanagement}
130
131\membersection{wxArrayString::Clear}\label{wxarraystringclear}
132
133\func{void}{Clear}{\void}
134
135Clears the array contents and frees memory.
136
137See also: \helpref{Empty}{wxarraystringempty}
138
139\membersection{wxArrayString::Count}\label{wxarraystringcount}
140
141\constfunc{size\_t}{Count}{\void}
142
143Returns the number of items in the array. This function is deprecated and is
144for backwards compatibility only, please use
145\helpref{GetCount}{wxarraystringgetcount} instead.
146
147\membersection{wxArrayString::Empty}\label{wxarraystringempty}
148
149\func{void}{Empty}{\void}
150
151Empties the array: after a call to this function
152\helpref{GetCount}{wxarraystringgetcount} will return $0$. However, this
153function does not free the memory used by the array and so should be used when
154the array is going to be reused for storing other strings. Otherwise, you
155should use \helpref{Clear}{wxarraystringclear} to empty the array and free
156memory.
157
158\membersection{wxArrayString::GetCount}\label{wxarraystringgetcount}
159
160\constfunc{size\_t}{GetCount}{\void}
161
162Returns the number of items in the array.
163
164\membersection{wxArrayString::Index}\label{wxarraystringindex}
165
cc81d32f 166\func{int}{Index}{\param{const char *}{ sz}, \param{bool}{ bCase = true}, \param{bool}{ bFromEnd = false}}
9e2be6f0
VZ
167
168Search the element in the array, starting from the beginning if
cc81d32f 169{\it bFromEnd} is false or from end otherwise. If {\it bCase}, comparison is
9e2be6f0
VZ
170case sensitive (default), otherwise the case is ignored.
171
e87271f3
VZ
172This function uses linear search for wxArrayString and binary search for
173wxSortedArrayString, but it ignores the {\it bCase} and {\it bFromEnd}
174parameters in the latter case.
175
9e2be6f0
VZ
176Returns index of the first item matched or wxNOT\_FOUND if there is no match.
177
178\membersection{wxArrayString::Insert}\label{wxarraystringinsert}
179
8a2a6bbf 180\func{void}{Insert}{\param{const wxString\& }{str}, \param{size\_t}{ nIndex}, \param{size\_t }{copies = $1$}}
9e2be6f0 181
8a2a6bbf 182Insert the given number of {\it copies} of the new element in the array before the position {\it nIndex}. Thus, for
9e2be6f0
VZ
183example, to insert the string in the beginning of the array you would write
184
185\begin{verbatim}
186Insert("foo", 0);
187\end{verbatim}
188
d3f7a53b 189If {\it nIndex} is equal to {\it GetCount()} this function behaves as
9e2be6f0
VZ
190\helpref{Add}{wxarraystringadd}.
191
fa482912 192{\bf Warning:} this function should not be used with sorted arrays because it
e87271f3 193could break the order of items and, for example, subsequent calls to
fa482912 194\helpref{Index()}{wxarraystringindex} would then not work!
e87271f3 195
9e2be6f0
VZ
196\membersection{wxArrayString::IsEmpty}\label{wxarraystringisempty}
197
198\func{}{IsEmpty}{}
199
cc81d32f 200Returns true if the array is empty, false otherwise. This function returns the
9e2be6f0
VZ
201same result as {\it GetCount() == 0} but is probably easier to read.
202
203\membersection{wxArrayString::Item}\label{wxarraystringitem}
204
205\constfunc{wxString\&}{Item}{\param{size\_t }{nIndex}}
206
207Return the array element at position {\it nIndex}. An assert failure will
208result from an attempt to access an element beyond the end of array in debug
209mode, but no check is done in release mode.
210
211See also \helpref{operator[]}{wxarraystringoperatorindex} for the operator
212version.
213
214\membersection{wxArrayString::Last}\label{wxarraystringlast}
215
216\func{}{Last}{}
217
218Returns the last element of the array. Attempt to access the last element of
219an empty array will result in assert failure in debug build, however no checks
220are done in release mode.
221
f6bcfd97 222\membersection{wxArrayString::Remove}\label{wxarraystringremove}
9e2be6f0
VZ
223
224\func{void}{Remove}{\param{const char *}{ sz}}
225
226Removes the first item matching this value. An assert failure is provoked by
227an attempt to remove an element which does not exist in debug build.
228
f6bcfd97 229See also: \helpref{Index}{wxarraystringindex}
9e2be6f0 230
d4c92f55
MB
231\membersection{wxArrayString::RemoveAt}\label{wxarraystringremoveat}
232
233\func{void}{RemoveAt}{\param{size\_t }{nIndex}, \param{size\_t }{count = $1$}}
9e2be6f0 234
8a2a6bbf 235Removes {\it count} items starting at position {\it nIndex} from the array.
9e2be6f0 236
9e2be6f0
VZ
237\membersection{wxArrayString::Shrink}\label{wxarraystringshrink}
238
239\func{void}{Shrink}{\void}
240
241Releases the extra memory allocated by the array. This function is useful to
242minimize the array memory consumption.
243
244See also: \helpref{Alloc}{wxarraystringalloc}, \helpref{Dynamic array memory management}{wxarraymemorymanagement}
245
f6bcfd97 246\membersection{wxArrayString::Sort}\label{wxarraystringsort}
9e2be6f0 247
cc81d32f 248\func{void}{Sort}{\param{bool}{ reverseOrder = false}}
9e2be6f0 249
fa482912 250Sorts the array in alphabetical order or in reverse alphabetical order if
2f930c85 251{\it reverseOrder} is true. The sort is case-sensitive.
9e2be6f0 252
e87271f3
VZ
253{\bf Warning:} this function should not be used with sorted array because it
254could break the order of items and, for example, subsequent calls to
fa482912 255\helpref{Index()}{wxarraystringindex} would then not work!
e87271f3 256
9e2be6f0
VZ
257\func{void}{Sort}{\param{CompareFunction }{compareFunction}}
258
259Sorts the array using the specified {\it compareFunction} for item comparison.
260{\it CompareFunction} is defined as a function taking two {\it const
fa482912 261wxString\&} parameters and returning an {\it int} value less than, equal to or
9e2be6f0
VZ
262greater than 0 if the first string is less than, equal to or greater than the
263second one.
264
2a47d3c1 265\wxheading{Example}
9e2be6f0 266
2a47d3c1 267The following example sorts strings by their length.
9e2be6f0 268
2a47d3c1 269\begin{verbatim}
9e2be6f0
VZ
270static int CompareStringLen(const wxString& first, const wxString& second)
271{
272 return first.length() - second.length();
273}
274
275...
276
277wxArrayString array;
278
279array.Add("one");
280array.Add("two");
281array.Add("three");
282array.Add("four");
283
284array.Sort(CompareStringLen);
9e2be6f0
VZ
285\end{verbatim}
286
e87271f3
VZ
287{\bf Warning:} this function should not be used with sorted array because it
288could break the order of items and, for example, subsequent calls to
fa482912 289\helpref{Index()}{wxarraystringindex} would then not work!
e87271f3 290