]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/arrstrng.tex
1. added code to dyntbar to allow bitmap loading from windows resources
[wxWidgets.git] / docs / latex / wx / arrstrng.tex
1 \section{\class{wxArrayString}}\label{wxarraystring}
2
3 wxArrayString 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
6 are added to it (so it is as easy to use as a linked list), but the access
7 time to the elements is constant, instead of being linear in number of
8 elements as in the case of linked lists. It is also very size efficient and
9 doesn't take more space than a C array {\it wxString[]} type. wxArrayString
10 uses its knowledge of internals of wxString class to achieve this.
11
12 This class is used in the same way as other dynamic \helpref{arrays}{wxarray},
13 except that no {\it WX\_DEFINE\_ARRAY} declaration is needed for it. When a
14 string is added or inserted in the array, a copy of the string is created, so
15 the original string may be safely deleted (e.g. if it was a {\it char *}
16 pointer the memory it was using can be freed immediately after this). In
17 general, there is no need to worry about string memory deallocation when using
18 this class - it will always free the memory it uses itself.
19
20 The references returned by \helpref{Item}{wxarraystringitem},
21 \helpref{Last}{wxarraystringlast} or
22 \helpref{operator[]}{wxarraystringoperatorindex} are not constant, so the
23 array elements may be modified in place like this
24
25 \begin{verbatim}
26 array.Last().MakeUpper();
27 \end{verbatim}
28
29 Finally, none of the methods of this class is virtual including its
30 destructor, so this class should not be derived from.
31
32 \wxheading{Derived from}
33
34 Although this is not true strictly speaking, this class may be considered as a
35 specialization of \helpref{wxArray}{wxarray} class for the wxString member
36 data: it is not implemented like this, but it does have all of the wxArray
37 functions.
38
39 \wxheading{Include files}
40
41 <wx/string.h>
42
43 \wxheading{See also}
44
45 \helpref{wxArray}{wxarray}, \helpref{wxString}{wxstring}, \helpref{wxString overview}{wxstringoverview}
46
47 \latexignore{\rtfignore{\wxheading{Members}}}
48
49 \membersection{wxArrayString::wxArrayString}\label{wxarraystringctor}
50
51 \func{}{wxArrayString}{\void}
52
53 \func{}{wxArrayString}{\param{const wxArrayString\&}{ array}}
54
55 Default and copy constructors.
56
57 \membersection{wxArrayString::\destruct{wxArrayString}}\label{wxarraystringdtor}
58
59 \func{}{\destruct{wxArrayString}}{}
60
61 Destructor frees memory occupied by the array strings. For the performance
62 reasons it is not virtual, so this class should not be derived from.
63
64 \membersection{wxArrayString::operator=}\label{wxarraystringoperatorassign}
65
66 \func{wxArrayString \&}{operator $=$}{\param{const wxArrayString\&}{ array}}
67
68 Assignment operator.
69
70 \membersection{wxArrayString::operator[]}\label{wxarraystringoperatorindex}
71
72 \func{wxString\&}{operatorp[]}{\param{size\_t }{nIndex}}
73
74 Return the array element at position {\it nIndex}. An assert failure will
75 result from an attempt to access an element beyond the end of array in debug
76 mode, but no check is done in release mode.
77
78 This is the operator version of \helpref{Item}{wxarraystringitem} method.
79
80 \membersection{wxArrayString::Add}\label{wxarraystringadd}
81
82 \func{void}{Add}{\param{const wxString\& }{str}}
83
84 Appends a new item to the array.
85
86 See also: \helpref{Insert}{wxarraystringinsert}
87
88 \membersection{wxArrayString::Alloc}\label{wxarraystringalloc}
89
90 \func{void}{Alloc}{\param{size\_t }{nCount}}
91
92 Preallocates enough memory to store {\it nCount} items. This function may be
93 used to improve array class performance before adding a known number of items
94 consecutively.
95
96 See also: \helpref{Dynamic array memory management}{wxarraymemorymanagement}
97
98 \membersection{wxArrayString::Clear}\label{wxarraystringclear}
99
100 \func{void}{Clear}{\void}
101
102 Clears the array contents and frees memory.
103
104 See also: \helpref{Empty}{wxarraystringempty}
105
106 \membersection{wxArrayString::Count}\label{wxarraystringcount}
107
108 \constfunc{size\_t}{Count}{\void}
109
110 Returns the number of items in the array. This function is deprecated and is
111 for backwards compatibility only, please use
112 \helpref{GetCount}{wxarraystringgetcount} instead.
113
114 \membersection{wxArrayString::Empty}\label{wxarraystringempty}
115
116 \func{void}{Empty}{\void}
117
118 Empties the array: after a call to this function
119 \helpref{GetCount}{wxarraystringgetcount} will return $0$. However, this
120 function does not free the memory used by the array and so should be used when
121 the array is going to be reused for storing other strings. Otherwise, you
122 should use \helpref{Clear}{wxarraystringclear} to empty the array and free
123 memory.
124
125 \membersection{wxArrayString::GetCount}\label{wxarraystringgetcount}
126
127 \constfunc{size\_t}{GetCount}{\void}
128
129 Returns the number of items in the array.
130
131 \membersection{wxArrayString::Index}\label{wxarraystringindex}
132
133 \func{int}{Index}{\param{const char *}{ sz}, \param{bool}{ bCase = TRUE}, \param{bool}{ bFromEnd = FALSE}}
134
135 Search the element in the array, starting from the beginning if
136 {\it bFromEnd} is FALSE or from end otherwise. If {\it bCase}, comparison is
137 case sensitive (default), otherwise the case is ignored.
138
139 Returns index of the first item matched or wxNOT\_FOUND if there is no match.
140
141 \membersection{wxArrayString::Insert}\label{wxarraystringinsert}
142
143 \func{void}{Insert}{\param{const wxString\& }{str}, \param{size\_t}{ nIndex}}
144
145 Insert a new element in the array before the position {\it nIndex}. Thus, for
146 example, to insert the string in the beginning of the array you would write
147
148 \begin{verbatim}
149 Insert("foo", 0);
150 \end{verbatim}
151
152 If {\it nIndex} is equal to {\it GetCount() + 1} this function behaves as
153 \helpref{Add}{wxarraystringadd}.
154
155 \membersection{wxArrayString::IsEmpty}\label{wxarraystringisempty}
156
157 \func{}{IsEmpty}{}
158
159 Returns TRUE if the array is empty, FALSE otherwise. This function returns the
160 same result as {\it GetCount() == 0} but is probably easier to read.
161
162 \membersection{wxArrayString::Item}\label{wxarraystringitem}
163
164 \constfunc{wxString\&}{Item}{\param{size\_t }{nIndex}}
165
166 Return the array element at position {\it nIndex}. An assert failure will
167 result from an attempt to access an element beyond the end of array in debug
168 mode, but no check is done in release mode.
169
170 See also \helpref{operator[]}{wxarraystringoperatorindex} for the operator
171 version.
172
173 \membersection{wxArrayString::Last}\label{wxarraystringlast}
174
175 \func{}{Last}{}
176
177 Returns the last element of the array. Attempt to access the last element of
178 an empty array will result in assert failure in debug build, however no checks
179 are done in release mode.
180
181 \membersection{wxArrayString::Remove (by value)}\label{wxarraystringremoveval}
182
183 \func{void}{Remove}{\param{const char *}{ sz}}
184
185 Removes the first item matching this value. An assert failure is provoked by
186 an attempt to remove an element which does not exist in debug build.
187
188 See also: \helpref{Index}{wxarraystringindex}, \helpref{Remove}{wxarraystringremove}
189
190 \membersection{wxArrayString::Remove (by index)}\label{wxarraystringremove}
191
192 \func{void}{Remove}{\param{size\_t }{nIndex}}
193
194 Removes the item at given position.
195
196 See also: \helpref{Remove}{wxarraystringremoveval}
197
198 \membersection{wxArrayString::Shrink}\label{wxarraystringshrink}
199
200 \func{void}{Shrink}{\void}
201
202 Releases the extra memory allocated by the array. This function is useful to
203 minimize the array memory consumption.
204
205 See also: \helpref{Alloc}{wxarraystringalloc}, \helpref{Dynamic array memory management}{wxarraymemorymanagement}
206
207 \membersection{wxArrayString::Sort (alphabetically)}\label{wxarraystringsort}
208
209 \func{void}{Sort}{\param{bool}{ reverseOrder = FALSE}}
210
211 Sorts the array in alphabetical order or in reverse alphabetical order if
212 {\it reverseOrder} is TRUE.
213
214 See also: \helpref{Sort}{wxarraystringsortcallback}
215
216 \membersection{wxArrayString::Sort (user defined)}\label{wxarraystringsortcallback}
217
218 \func{void}{Sort}{\param{CompareFunction }{compareFunction}}
219
220 Sorts the array using the specified {\it compareFunction} for item comparison.
221 {\it CompareFunction} is defined as a function taking two {\it const
222 wxString\&} parameters and returning {\it int} value less than, equal to or
223 greater than 0 if the first string is less than, equal to or greater than the
224 second one.
225
226 \wxheading{Example}
227
228 The following example sorts strings by their length.
229
230 \begin{verbatim}
231 static int CompareStringLen(const wxString& first, const wxString& second)
232 {
233 return first.length() - second.length();
234 }
235
236 ...
237
238 wxArrayString array;
239
240 array.Add("one");
241 array.Add("two");
242 array.Add("three");
243 array.Add("four");
244
245 array.Sort(CompareStringLen);
246 \end{verbatim}
247
248 See also: \helpref{Sort}{wxarraystringsort}
249