/src/core/pystring/pystring.h

  1///////////////////////////////////////////////////////////////////////////////
  2// Copyright (c) 2008-2010, Sony Pictures Imageworks Inc
  3// All rights reserved.
  4//
  5// Redistribution and use in source and binary forms, with or without
  6// modification, are permitted provided that the following conditions are
  7// met:
  8//
  9// Redistributions of source code must retain the above copyright notice,
 10// this list of conditions and the following disclaimer.
 11// Redistributions in binary form must reproduce the above copyright
 12// notice, this list of conditions and the following disclaimer in the
 13// documentation and/or other materials provided with the distribution.
 14// Neither the name of the organization Sony Pictures Imageworks nor the
 15// names of its contributors
 16// may be used to endorse or promote products derived from this software
 17// without specific prior written permission.
 18// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 19// "AS
 20// IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 21// TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 22// PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 23// OWNER
 24// OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 25// SPECIAL,
 26// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 27// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 28// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 29// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 30// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 31// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 32///////////////////////////////////////////////////////////////////////////////
 33
 34#ifndef INCLUDED_OCIO_PYSTRING_H
 35#define INCLUDED_OCIO_PYSTRING_H
 36
 37#include <OpenColorIO/OpenColorIO.h>
 38
 39#include <string>
 40#include <vector>
 41
 42OCIO_NAMESPACE_ENTER
 43{
 44// Version 1.1.2
 45// https://github.com/imageworks/pystring/tarball/v1.1.2
 46
 47namespace pystring
 48{
 49
 50    //////////////////////////////////////////////////////////////////////////////////////////////
 51    /// @mainpage pystring
 52    ///
 53    /// This is a set of functions matching the interface and behaviors of python string methods
 54    /// (as of python 2.3) using std::string.
 55    ///
 56    /// Overlapping functionality ( such as index and slice/substr ) of std::string is included
 57    /// to match python interfaces.
 58    ///
 59
 60    //////////////////////////////////////////////////////////////////////////////////////////////
 61    /// @defgroup functions pystring
 62    /// @{
 63
 64
 65    #define MAX_32BIT_INT 2147483647
 66
 67    //////////////////////////////////////////////////////////////////////////////////////////////
 68    /// @brief Return a copy of the string with only its first character capitalized.
 69    ///
 70    std::string capitalize( const std::string & str );
 71
 72    //////////////////////////////////////////////////////////////////////////////////////////////
 73    /// @brief Return centered in a string of length width. Padding is done using spaces.
 74    ///
 75    std::string center( const std::string & str, int width );
 76
 77    //////////////////////////////////////////////////////////////////////////////////////////////
 78    /// @brief Return the number of occurrences of substring sub in string S[start:end]. Optional
 79    /// arguments start and end are interpreted as in slice notation.
 80    ///
 81    int count( const std::string & str, const std::string & substr, int start = 0, int end = MAX_32BIT_INT);
 82
 83    //////////////////////////////////////////////////////////////////////////////////////////////
 84    /// @brief Return True if the string ends with the specified suffix, otherwise return False. With
 85    /// optional start, test beginning at that position. With optional end, stop comparing at that position.
 86    ///
 87    bool endswith( const std::string & str, const std::string & suffix, int start = 0, int end = MAX_32BIT_INT );
 88
 89    //////////////////////////////////////////////////////////////////////////////////////////////
 90    /// @brief Return a copy of the string where all tab characters are expanded using spaces. If tabsize
 91    /// is not given, a tab size of 8 characters is assumed.
 92    ///
 93    std::string expandtabs( const std::string & str, int tabsize = 8);
 94
 95    //////////////////////////////////////////////////////////////////////////////////////////////
 96    /// @brief Return the lowest index in the string where substring sub is found, such that sub is
 97    /// contained in the range [start, end). Optional arguments start and end are interpreted as
 98    /// in slice notation. Return -1 if sub is not found.
 99    ///
100    int find( const std::string & str, const std::string & sub, int start = 0, int end = MAX_32BIT_INT  );
101
102    //////////////////////////////////////////////////////////////////////////////////////////////
103    /// @brief Synonym of find right now. Python version throws exceptions. This one currently doesn't
104    ///
105    int index( const std::string & str, const std::string & sub, int start = 0, int end = MAX_32BIT_INT  );
106
107    //////////////////////////////////////////////////////////////////////////////////////////////
108    /// @brief Return true if all characters in the string are alphanumeric and there is at least one
109    /// character, false otherwise.
110    ///
111    bool isalnum( const std::string & str );
112
113    //////////////////////////////////////////////////////////////////////////////////////////////
114    /// @brief Return true if all characters in the string are alphabetic and there is at least one
115    /// character, false otherwise
116    ///
117    bool isalpha( const std::string & str );
118
119    //////////////////////////////////////////////////////////////////////////////////////////////
120    /// @brief Return true if all characters in the string are digits and there is at least one
121    /// character, false otherwise.
122    ///
123    bool isdigit( const std::string & str );
124
125    //////////////////////////////////////////////////////////////////////////////////////////////
126    /// @brief Return true if all cased characters in the string are lowercase and there is at least one
127    /// cased character, false otherwise.
128    ///
129    bool islower( const std::string & str );
130
131    //////////////////////////////////////////////////////////////////////////////////////////////
132    /// @brief Return true if there are only whitespace characters in the string and there is at least
133    /// one character, false otherwise.
134    ///
135    bool isspace( const std::string & str );
136
137    //////////////////////////////////////////////////////////////////////////////////////////////
138    /// @brief Return true if the string is a titlecased string and there is at least one character,
139    /// i.e. uppercase characters may only follow uncased characters and lowercase characters only
140    /// cased ones. Return false otherwise.
141    ///
142    bool istitle( const std::string & str );
143
144    //////////////////////////////////////////////////////////////////////////////////////////////
145    /// @brief Return true if all cased characters in the string are uppercase and there is at least one
146    /// cased character, false otherwise.
147    ///
148    bool isupper( const std::string & str );
149
150    //////////////////////////////////////////////////////////////////////////////////////////////
151    /// @brief Return a string which is the concatenation of the strings in the sequence seq.
152    /// The separator between elements is the str argument
153    ///
154    std::string join( const std::string & str, const std::vector< std::string > & seq );
155
156    //////////////////////////////////////////////////////////////////////////////////////////////
157    /// @brief Return the string left justified in a string of length width. Padding is done using
158    /// spaces. The original string is returned if width is less than str.size().
159    ///
160    std::string ljust( const std::string & str, int width );
161
162    //////////////////////////////////////////////////////////////////////////////////////////////
163    /// @brief Return a copy of the string converted to lowercase.
164    ///
165    std::string lower( const std::string & str );
166
167    //////////////////////////////////////////////////////////////////////////////////////////////
168    /// @brief Return a copy of the string with leading characters removed. If chars is omitted or None,
169    /// whitespace characters are removed. If given and not "", chars must be a string; the
170    /// characters in the string will be stripped from the beginning of the string this method
171    /// is called on (argument "str" ).
172    ///
173    std::string lstrip( const std::string & str, const std::string & chars = "" );
174
175    //////////////////////////////////////////////////////////////////////////////////////////////
176    /// @brief Return a copy of the string, concatenated N times, together.
177    /// Corresponds to the __mul__ operator.
178    /// 
179    std::string mul( const std::string & str, int n);
180    
181    //////////////////////////////////////////////////////////////////////////////////////////////
182    /// @brief Split the string around first occurance of sep.
183    /// Three strings will always placed into result. If sep is found, the strings will
184    /// be the text before sep, sep itself, and the remaining text. If sep is
185    /// not found, the original string will be returned with two empty strings.
186    ///
187    void partition( const std::string & str, const std::string & sep, std::vector< std::string > & result );
188
189    //////////////////////////////////////////////////////////////////////////////////////////////
190    /// @brief Return a copy of the string with all occurrences of substring old replaced by new. If
191    /// the optional argument count is given, only the first count occurrences are replaced.
192    ///
193    std::string replace( const std::string & str, const std::string & oldstr, const std::string & newstr, int count = -1);
194
195    //////////////////////////////////////////////////////////////////////////////////////////////
196    /// @brief Return the highest index in the string where substring sub is found, such that sub is
197    /// contained within s[start,end]. Optional arguments start and end are interpreted as in
198    /// slice notation. Return -1 on failure.
199    ///
200    int rfind( const std::string & str, const std::string & sub, int start = 0, int end = MAX_32BIT_INT );
201
202    //////////////////////////////////////////////////////////////////////////////////////////////
203    /// @brief Currently a synonym of rfind. The python version raises exceptions. This one currently
204    /// does not
205    ///
206    int rindex( const std::string & str, const std::string & sub, int start = 0, int end = MAX_32BIT_INT );
207
208    //////////////////////////////////////////////////////////////////////////////////////////////
209    /// @brief Return the string right justified in a string of length width. Padding is done using
210    /// spaces. The original string is returned if width is less than str.size().
211    ///
212    std::string rjust( const std::string & str, int width);
213
214    //////////////////////////////////////////////////////////////////////////////////////////////
215    /// @brief Split the string around last occurance of sep.
216    /// Three strings will always placed into result. If sep is found, the strings will
217    /// be the text before sep, sep itself, and the remaining text. If sep is
218    /// not found, the original string will be returned with two empty strings.
219    ///
220    void rpartition( const std::string & str, const std::string & sep, std::vector< std::string > & result );
221
222    //////////////////////////////////////////////////////////////////////////////////////////////
223    /// @brief Return a copy of the string with trailing characters removed. If chars is "", whitespace
224    /// characters are removed. If not "", the characters in the string will be stripped from the
225    /// end of the string this method is called on.
226    ///
227    std::string rstrip( const std::string & str, const std::string & chars = "" );
228
229    //////////////////////////////////////////////////////////////////////////////////////////////
230    /// @brief Fills the "result" list with the words in the string, using sep as the delimiter string.
231    /// If maxsplit is > -1, at most maxsplit splits are done. If sep is "",
232    /// any whitespace string is a separator.
233    ///
234    void split( const std::string & str, std::vector< std::string > & result, const std::string & sep = "", int maxsplit = -1);
235
236    //////////////////////////////////////////////////////////////////////////////////////////////
237    /// @brief Fills the "result" list with the words in the string, using sep as the delimiter string.
238    /// Does a number of splits starting at the end of the string, the result still has the
239    /// split strings in their original order.
240    /// If maxsplit is > -1, at most maxsplit splits are done. If sep is "",
241    /// any whitespace string is a separator.
242    ///
243    void rsplit( const std::string & str, std::vector< std::string > & result, const std::string & sep = "", int maxsplit = -1);
244
245    //////////////////////////////////////////////////////////////////////////////////////////////
246    /// @brief Return a list of the lines in the string, breaking at line boundaries. Line breaks
247    /// are not included in the resulting list unless keepends is given and true.
248    ///
249    void splitlines(  const std::string & str, std::vector< std::string > & result, bool keepends = false );
250
251    //////////////////////////////////////////////////////////////////////////////////////////////
252    /// @brief Return True if string starts with the prefix, otherwise return False. With optional start,
253    /// test string beginning at that position. With optional end, stop comparing string at that
254    /// position
255    ///
256    bool startswith( const std::string & str, const std::string & prefix, int start = 0, int end = MAX_32BIT_INT );
257
258    //////////////////////////////////////////////////////////////////////////////////////////////
259    /// @brief Return a copy of the string with leading and trailing characters removed. If chars is "",
260    /// whitespace characters are removed. If given not "",  the characters in the string will be
261    /// stripped from the both ends of the string this method is called on.
262    ///
263    std::string strip( const std::string & str, const std::string & chars = "" );
264
265    //////////////////////////////////////////////////////////////////////////////////////////////
266    /// @brief Return a copy of the string with uppercase characters converted to lowercase and vice versa.
267    ///
268    std::string swapcase( const std::string & str );
269
270    //////////////////////////////////////////////////////////////////////////////////////////////
271    /// @brief Return a titlecased version of the string: words start with uppercase characters,
272    /// all remaining cased characters are lowercase.
273    ///
274    std::string title( const std::string & str );
275
276    //////////////////////////////////////////////////////////////////////////////////////////////
277    /// @brief Return a copy of the string where all characters occurring in the optional argument
278    /// deletechars are removed, and the remaining characters have been mapped through the given
279    /// translation table, which must be a string of length 256.
280    ///
281    std::string translate( const std::string & str, const std::string & table, const std::string & deletechars = "");
282
283    //////////////////////////////////////////////////////////////////////////////////////////////
284    /// @brief Return a copy of the string converted to uppercase.
285    ///
286    std::string upper( const std::string & str );
287
288    //////////////////////////////////////////////////////////////////////////////////////////////
289    /// @brief Return the numeric string left filled with zeros in a string of length width. The original
290    /// string is returned if width is less than str.size().
291    ///
292    std::string zfill( const std::string & str, int width );
293
294    //////////////////////////////////////////////////////////////////////////////////////////////
295    /// @brief function matching python's slice functionality.
296    ///
297    std::string slice( const std::string & str, int start = 0, int end = MAX_32BIT_INT);
298
299    ///
300    /// @ }
301    ///
302
303
304namespace os
305{
306namespace path
307{
308    // All of the function below have three versions.
309    // Example:
310    //   join(...)
311    //   join_nt(...)
312    //   join_posix(...)
313    //
314    // The regular function dispatches to the other versions - based on the OS
315    // at compile time - to match the result you'd get from the python
316    // interepreter on the same operating system
317    // 
318    // Should you want to 'lock off' to a particular version of the string
319    // manipulation across *all* operating systems, use the version with the
320    // _OS you are interested in.  I.e., you can use posix style path joining,
321    // even on Windows, with join_posix.
322    //
323    // The naming, (nt, posix) matches the cpython source implementation.
324    
325    //////////////////////////////////////////////////////////////////////////////////////////////
326    /// @defgroup functions pystring::os::path
327    /// @{
328    
329    //////////////////////////////////////////////////////////////////////////////////////////////
330    /// @brief Return the base name of pathname path. This is the second half of the pair returned
331    /// by split(path). Note that the result of this function is different from the Unix basename
332    /// program; where basename for '/foo/bar/' returns 'bar', the basename() function returns an
333    /// empty string ('').
334    
335    std::string basename(const std::string & path);
336    std::string basename_nt(const std::string & path);
337    std::string basename_posix(const std::string & path);
338
339    //////////////////////////////////////////////////////////////////////////////////////////////
340    /// @brief Return the directory name of pathname path. This is the first half of the pair
341    /// returned by split(path).
342    
343    std::string dirname(const std::string & path);
344    std::string dirname_nt(const std::string & path);
345    std::string dirname_posix(const std::string & path);
346
347    //////////////////////////////////////////////////////////////////////////////////////////////
348    /// @brief Return True if path is an absolute pathname. On Unix, that means it begins with a
349    /// slash, on Windows that it begins with a (back)slash after chopping off a potential drive
350    /// letter.
351
352    bool isabs(const std::string & path);
353    bool isabs_nt(const std::string & path);
354    bool isabs_posix(const std::string & s);
355
356    //////////////////////////////////////////////////////////////////////////////////////////////
357    /// @brief Return a normalized absolutized version of the pathname path.
358    /// 
359    /// NOTE: This differs from the interface of the python equivalent in that it requires you
360    /// to pass in the current working directory as an argument.
361    
362    std::string abspath(const std::string & path, const std::string & cwd);
363    std::string abspath_nt(const std::string & path, const std::string & cwd);
364    std::string abspath_posix(const std::string & path, const std::string & cwd);
365    
366
367    //////////////////////////////////////////////////////////////////////////////////////////////
368    /// @brief Join one or more path components intelligently. If any component is an absolute
369    /// path, all previous components (on Windows, including the previous drive letter, if there
370    /// was one) are thrown away, and joining continues. The return value is the concatenation of
371    /// path1, and optionally path2, etc., with exactly one directory separator (os.sep) inserted
372    /// between components, unless path2 is empty. Note that on Windows, since there is a current
373    /// directory for each drive, os.path.join("c:", "foo") represents a path relative to the
374    /// current directory on drive C: (c:foo), not c:\foo.
375    
376    /// This dispatches based on the compilation OS
377    std::string join(const std::string & path1, const std::string & path2);
378    std::string join_nt(const std::string & path1, const std::string & path2);
379    std::string join_posix(const std::string & path1, const std::string & path2);
380    
381    std::string join(const std::vector< std::string > & paths);
382    std::string join_nt(const std::vector< std::string > & paths);
383    std::string join_posix(const std::vector< std::string > & paths);
384
385    //////////////////////////////////////////////////////////////////////////////////////////////
386    /// @brief Normalize a pathname. This collapses redundant separators and up-level references
387    /// so that A//B, A/B/, A/./B and A/foo/../B all become A/B. It does not normalize the case
388    /// (use normcase() for that). On Windows, it converts forward slashes to backward slashes.
389    /// It should be understood that this may change the meaning of the path if it contains
390    /// symbolic links!
391
392    std::string normpath(const std::string & path);
393    std::string normpath_nt(const std::string & path);
394    std::string normpath_posix(const std::string & path);
395
396    //////////////////////////////////////////////////////////////////////////////////////////////
397    /// @brief Split the pathname path into a pair, (head, tail) where tail is the last pathname
398    /// component and head is everything leading up to that. The tail part will never contain a
399    /// slash; if path ends in a slash, tail will be empty. If there is no slash in path, head
400    /// will be empty. If path is empty, both head and tail are empty. Trailing slashes are
401    /// stripped from head unless it is the root (one or more slashes only). In all cases,
402    /// join(head, tail) returns a path to the same location as path (but the strings may
403    /// differ).
404
405    void split(std::string & head, std::string & tail, const std::string & path);
406    void split_nt(std::string & head, std::string & tail, const std::string & path);
407    void split_posix(std::string & head, std::string & tail, const std::string & path);
408
409    //////////////////////////////////////////////////////////////////////////////////////////////
410    /// @brief Split the pathname path into a pair (drive, tail) where drive is either a drive
411    /// specification or the empty string. On systems which do not use drive specifications,
412    /// drive will always be the empty string. In all cases, drive + tail will be the same as
413    /// path.
414    
415    void splitdrive(std::string & drivespec, std::string & pathspec, const std::string & path);
416    void splitdrive_nt(std::string & drivespec, std::string & pathspec, const std::string & p);
417    void splitdrive_posix(std::string & drivespec, std::string & pathspec, const std::string & path);
418    
419    //////////////////////////////////////////////////////////////////////////////////////////////
420    /// @brief Split the pathname path into a pair (root, ext) such that root + ext == path, and
421    /// ext is empty or begins with a period and contains at most one period. Leading periods on
422    /// the basename are ignored; splitext('.cshrc') returns ('.cshrc', '').
423
424    void splitext(std::string & root, std::string & ext, const std::string & path);
425    void splitext_nt(std::string & root, std::string & ext, const std::string & path);
426    void splitext_posix(std::string & root, std::string & ext, const std::string & path);
427    
428    ///
429    /// @ }
430    ///
431} // namespace path
432} // namespace os
433
434} // namespace pystring
435}
436OCIO_NAMESPACE_EXIT
437
438#endif