Teh first one
[mldemos:kalians-mldemos.git] / _AlgorithmsPlugins / KernelMethods / dlib / string / string_abstract.h
1 // Copyright (C) 2006  Davis E. King (davis@dlib.net)\r
2 // License: Boost Software License   See LICENSE.txt for the full license.\r
3 #undef DLIB_STRINg_ABSTRACT_\r
4 #ifdef DLIB_STRINg_ABSTRACT_\r
5 \r
6 #include <string>\r
7 #include <iostream>\r
8 #include "../error.h"\r
9 \r
10 namespace dlib\r
11 {\r
12 \r
13 // ---------------------------------------------------------------------------------------- \r
14 \r
15     class string_cast_error : public error\r
16     {\r
17     public:\r
18         string_cast_error():error(ECAST_TO_STRING) {}\r
19     };\r
20 \r
21     template <\r
22         typename T,\r
23         typename charT,\r
24         typename traits,\r
25         typename alloc\r
26         >\r
27     const T string_cast (\r
28         const std::basic_string<charT,traits,alloc>& str\r
29     );\r
30     /*!\r
31         requires\r
32             - T is not a pointer type\r
33         ensures\r
34             - returns str converted to T\r
35         throws\r
36             - string_cast_error\r
37                 This exception is thrown if string_cast() is unable to convert\r
38                 str into a T.  Also, string_cast_error::info == str\r
39     !*/\r
40 \r
41 // ----------------------------------------------------------------------------------------\r
42 \r
43     class cast_to_string_error : public error\r
44     {\r
45     public:\r
46         cast_to_string_error():error(ECAST_TO_STRING) {}\r
47     };\r
48 \r
49     template <\r
50         typename T\r
51         >\r
52     const std::string cast_to_string (\r
53         const T& item \r
54     );\r
55     /*!\r
56         requires\r
57             - T is not a pointer type\r
58         ensures\r
59             - returns item converted to std::string\r
60         throws\r
61             - cast_to_string_error\r
62                 This exception is thrown if cast_to_string() is unable to convert\r
63                 item into a std::string.  \r
64     !*/\r
65 \r
66     template <\r
67         typename T\r
68         >\r
69     const std::wstring cast_to_wstring (\r
70         const T& item \r
71     );\r
72     /*!\r
73         requires\r
74             - T is not a pointer type\r
75         ensures\r
76             - returns item converted to std::wstring\r
77         throws\r
78             - cast_to_string_error\r
79                 This exception is thrown if cast_to_string() is unable to convert\r
80                 item into a std::string.  \r
81     !*/\r
82 \r
83 // ----------------------------------------------------------------------------------------\r
84 \r
85     template <\r
86         typename charT,\r
87         typename traits,\r
88         typename alloc\r
89         >\r
90     const std::string narrow (\r
91         const std::basic_string<charT,traits,alloc>& str\r
92     );\r
93     /*!\r
94         ensures\r
95             - returns str as a std::string by converting every character in it to a char.\r
96               Note that any characters that do not have a mapping to type char will be \r
97               converted to a space.\r
98     !*/\r
99 \r
100 // ----------------------------------------------------------------------------------------\r
101 \r
102     template <\r
103         typename charT,\r
104         typename traits,\r
105         typename alloc\r
106         >\r
107     const std::basic_string<charT,traits,alloc> wrap_string (\r
108         const std::basic_string<charT,traits,alloc>& str,\r
109         const unsigned long first_pad,\r
110         const unsigned long rest_pad,\r
111         const unsigned long max_per_line = 79\r
112     );\r
113     /*!\r
114         requires\r
115             - first_pad < max_per_line\r
116             - rest_pad < max_per_line\r
117             - rest_pad >= first_pad\r
118         ensures\r
119             - returns a copy of str S such that:\r
120                 - S is broken up into lines separated by the \n character.\r
121                 - The first line starts with first_pad space characters.\r
122                 - The second and all subsequent lines start with rest_pad space characters.\r
123                 - The first line is no longer than max_per_line - (rest_pad-first_pad) characters.\r
124                 - The second and all subsequent lines are no longer than max_per_line characters. \r
125     !*/\r
126 \r
127 // ----------------------------------------------------------------------------------------\r
128 \r
129     template <\r
130         typename traits \r
131         typename alloc\r
132         >\r
133     const std::basic_string<char,traits,alloc> tolower (\r
134         const std::basic_string<char,traits,alloc>& str\r
135     );\r
136     /*!\r
137         ensures\r
138             - returns a copy of str S such that:\r
139                 - #S.size() == str.size()\r
140                 - #S[i] == std::tolower(str[i])\r
141     !*/\r
142 \r
143 // ----------------------------------------------------------------------------------------\r
144 \r
145     template <\r
146         typename traits,\r
147         typename alloc\r
148         >\r
149     const std::basic_string<char,traits,alloc> toupper (\r
150         const std::basic_string<char,traits,alloc>& str\r
151     );\r
152     /*!\r
153         ensures\r
154             - returns a copy of str S such that:\r
155                 - #S.size() == str.size()\r
156                 - #S[i] == std::toupper(str[i])\r
157     !*/\r
158 \r
159 // ----------------------------------------------------------------------------------------\r
160 \r
161     template <\r
162         typename traits,\r
163         typename alloc\r
164         >\r
165     bool strings_equal_ignore_case (\r
166         const std::basic_string<char,traits,alloc>& str1,\r
167         const std::basic_string<char,traits,alloc>& str2\r
168     );\r
169     /*!\r
170         ensures\r
171             - returns tolower(str1) == tolower(str2)\r
172     !*/\r
173 \r
174 // ----------------------------------------------------------------------------------------\r
175 \r
176     template <\r
177         typename traits,\r
178         typename alloc\r
179         >\r
180     bool strings_equal_ignore_case (\r
181         const std::basic_string<char,traits,alloc>& str1,\r
182         const std::basic_string<char,traits,alloc>& str2,\r
183         unsigned long num\r
184     );\r
185     /*!\r
186         ensures\r
187             - returns tolower(str1.substr(0,num)) == tolower(str2.substr(0,num))\r
188               (i.e. only compares the first num characters)\r
189     !*/\r
190 \r
191 // ----------------------------------------------------------------------------------------\r
192 \r
193     template <\r
194         typename charT,\r
195         typename traits,\r
196         typename alloc\r
197         >\r
198     const std::basic_string<charT,traits,alloc> ltrim (\r
199         const std::basic_string<charT,traits,alloc>& str,\r
200         const std::basic_string<charT,traits,alloc>& trim_chars \r
201     );\r
202     /*!\r
203         ensures\r
204             - returns a copy of str with any leading trim_chars  \r
205               from the left side of the string removed. \r
206     !*/\r
207 \r
208     template <\r
209         typename charT,\r
210         typename traits,\r
211         typename alloc\r
212         >\r
213     const std::basic_string<charT,traits,alloc> ltrim (\r
214         const std::basic_string<charT,traits,alloc>& str,\r
215         const charT* trim_chars = _dT(charT," \t\r\n")\r
216     );\r
217     /*!\r
218         ensures\r
219             - returns ltrim(str, std::basic_string<charT,traits,alloc>(trim_chars))\r
220     !*/\r
221 \r
222 // ----------------------------------------------------------------------------------------\r
223 \r
224     template <\r
225         typename charT,\r
226         typename traits,\r
227         typename alloc\r
228         >\r
229     const std::basic_string<charT,traits,alloc> rtrim (\r
230         const std::basic_string<charT,traits,alloc>& str,\r
231         const std::basic_string<charT,traits,alloc>& trim_chars \r
232     );\r
233     /*!\r
234         ensures\r
235             - returns a copy of str with any trailing trim_chars \r
236               from the right side of the string removed. \r
237     !*/\r
238 \r
239     template <\r
240         typename charT,\r
241         typename traits,\r
242         typename alloc\r
243         >\r
244     const std::basic_string<charT,traits,alloc> rtrim (\r
245         const std::basic_string<charT,traits,alloc>& str,\r
246         const charT* trim_chars = _dT(charT," \t\r\n")\r
247     );\r
248     /*!\r
249         ensures\r
250             - returns rtrim(str, std::basic_string<charT,traits,alloc>(trim_chars))\r
251     !*/\r
252 \r
253 // ----------------------------------------------------------------------------------------\r
254 \r
255     template <\r
256         typename charT,\r
257         typename traits,\r
258         typename alloc\r
259         >\r
260     const std::basic_string<charT,traits,alloc> trim (\r
261         const std::basic_string<charT,traits,alloc>& str,\r
262         const std::basic_string<charT,traits,alloc>& trim_chars \r
263     );\r
264     /*!\r
265         ensures\r
266             - returns a copy of str with any leading or trailing trim_chars \r
267               from the ends of the string removed. \r
268     !*/\r
269 \r
270     template <\r
271         typename charT,\r
272         typename traits,\r
273         typename alloc\r
274         >\r
275     const std::basic_string<charT,traits,alloc> trim (\r
276         const std::basic_string<charT,traits,alloc>& str,\r
277         const charT* trim_chars = _dT(charT," \t\r\n")\r
278     );\r
279     /*!\r
280         ensures\r
281             - returns trim(str, std::basic_string<charT,traits,alloc>(trim_chars))\r
282     !*/\r
283 \r
284 // ----------------------------------------------------------------------------------------\r
285 \r
286     template <\r
287         typename charT,\r
288         typename traits,\r
289         typename alloc\r
290         >\r
291     const std::basic_string<charT,traits,alloc> rpad (\r
292         const std::basic_string<charT,traits,alloc>& str,\r
293         long pad_length,\r
294         const std::basic_string<charT,traits,alloc>& pad_string \r
295     );\r
296     /*!\r
297         ensures\r
298             - if (pad_length <= str.size()) then\r
299                 - returns str\r
300             - else\r
301                 - let P be a string defined as follows:\r
302                     - P.size() == pad_length - str.size()\r
303                     - P == (pad_string + pad_string + ... + pad_string).substr(0,pad_length - str.size())\r
304                       (i.e. P == a string with the above specified size that contains just\r
305                       repitions of the pad_string)\r
306                 - returns the string str + P \r
307     !*/\r
308 \r
309     template <\r
310         typename charT,\r
311         typename traits,\r
312         typename alloc\r
313         >\r
314     const std::basic_string<charT,traits,alloc> rpad (\r
315         const std::basic_string<charT,traits,alloc>& str,\r
316         long pad_length,\r
317         const charT* pad_string = _dT(charT," ")\r
318     );\r
319     /*!\r
320         ensures\r
321             - returns rpad(str, pad_length, std::basic_string<charT,traits,alloc>(pad_string))\r
322     !*/\r
323 \r
324 // ----------------------------------------------------------------------------------------\r
325 \r
326     template <\r
327         typename charT,\r
328         typename traits,\r
329         typename alloc\r
330         >\r
331     const std::basic_string<charT,traits,alloc> lpad (\r
332         const std::basic_string<charT,traits,alloc>& str,\r
333         long pad_length,\r
334         const std::basic_string<charT,traits,alloc>& pad_string \r
335     );\r
336     /*!\r
337         ensures\r
338             - if (pad_length <= str.size()) then\r
339                 - returns str\r
340             - else\r
341                 - let P be a string defined as follows:\r
342                     - P.size() == pad_length - str.size()\r
343                     - P == (pad_string + pad_string + ... + pad_string).substr(0,pad_length - str.size())\r
344                       (i.e. P == a string with the above specified size that contains just\r
345                       repitions of the pad_string)\r
346                 - returns the string P + str\r
347     !*/\r
348 \r
349     template <\r
350         typename charT,\r
351         typename traits,\r
352         typename alloc\r
353         >\r
354     const std::basic_string<charT,traits,alloc> lpad (\r
355         const std::basic_string<charT,traits,alloc>& str,\r
356         long pad_length,\r
357         const charT* pad_string = _dT(charT," ")\r
358     );\r
359     /*!\r
360         ensures\r
361             - returns lpad(str, pad_length, std::basic_string<charT,traits,alloc>(pad_string))\r
362     !*/\r
363 \r
364 // ----------------------------------------------------------------------------------------\r
365 \r
366     template <\r
367         typename charT,\r
368         typename traits,\r
369         typename alloc\r
370         >\r
371     const std::basic_string<charT,traits,alloc> pad (\r
372         const std::basic_string<charT,traits,alloc>& str,\r
373         long pad_length,\r
374         const std::basic_string<charT,traits,alloc>& pad_string \r
375     );\r
376     /*!\r
377         ensures\r
378             - let str_size == static_cast<long>(str.size())\r
379             - returns rpad( lpad(str, (pad_length-str_size)/2 + str_size, pad_string),  \r
380                             pad_length, \r
381                             pad_string);\r
382     !*/\r
383 \r
384     template <\r
385         typename charT,\r
386         typename traits,\r
387         typename alloc\r
388         >\r
389     const std::basic_string<charT,traits,alloc> pad (\r
390         const std::basic_string<charT,traits,alloc>& str,\r
391         long pad_length,\r
392         const charT* pad_string = _dT(charT," ")\r
393     );\r
394     /*!\r
395         ensures\r
396             - returns pad(str, pad_length, std::basic_string<charT,traits,alloc>(pad_string))\r
397     !*/\r
398 \r
399 // ----------------------------------------------------------------------------------------\r
400 \r
401     template <\r
402         typename charT,\r
403         typename traits,\r
404         typename alloc\r
405         >\r
406     const std::basic_string<charT,traits,alloc> left_substr (\r
407         const std::basic_string<charT,traits,alloc>& str,\r
408         const std::basic_string<charT,traits,alloc>& delim \r
409     );\r
410     /*!\r
411         ensures\r
412             - let delim_pos = str.find_first_of(delim)\r
413             - returns str.substr(0,delim_pos)\r
414     !*/\r
415 \r
416     template <\r
417         typename charT,\r
418         typename traits,\r
419         typename alloc\r
420         >\r
421     const std::basic_string<charT,traits,alloc> left_substr (\r
422         const std::basic_string<charT,traits,alloc>& str,\r
423         const charT* delim = _dT(charT," \n\r\t")\r
424     );\r
425     /*!\r
426         ensures\r
427             - returns left_substr(str, std::basic_string<charT,traits,alloc>(delim))\r
428     !*/\r
429 \r
430 // ----------------------------------------------------------------------------------------\r
431 \r
432     template <\r
433         typename charT,\r
434         typename traits,\r
435         typename alloc\r
436         >\r
437     const std::basic_string<charT,traits,alloc> right_substr (\r
438         const std::basic_string<charT,traits,alloc>& str,\r
439         const std::basic_string<charT,traits,alloc>& delim \r
440     );\r
441     /*!\r
442         ensures\r
443             - let delim_pos = str.find_last_of(delim)\r
444             - if (delim_pos == std::string::npos) then\r
445                 - returns ""\r
446             - else\r
447                 - returns str.substr(delim_pos+1)\r
448     !*/\r
449 \r
450     template <\r
451         typename charT,\r
452         typename traits\r
453         typename alloc\r
454         >\r
455     const std::basic_string<charT,traits,alloc> right_substr (\r
456         const std::basic_string<charT,traits,alloc>& str,\r
457         const charT* delim = _dT(charT," \n\r\t")\r
458     );\r
459     /*!\r
460         ensures\r
461             - returns right_substr(str, std::basic_string<charT,traits,alloc>(delim))\r
462     !*/\r
463 \r
464 // ----------------------------------------------------------------------------------------\r
465 \r
466 }\r
467 \r
468 #endif // DLIB_STRINg_ABSTRACT_\r
469 \r