]>
Commit | Line | Data |
---|---|---|
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 |