/src/core/pystring/pystring.h

http://github.com/imageworks/OpenColorIO · C Header · 438 lines · 87 code · 73 blank · 278 comment · 0 complexity · 2260a3dd59dfc8c431360a15b62c4195 MD5 · raw file

  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. #ifndef INCLUDED_OCIO_PYSTRING_H
  34. #define INCLUDED_OCIO_PYSTRING_H
  35. #include <OpenColorIO/OpenColorIO.h>
  36. #include <string>
  37. #include <vector>
  38. OCIO_NAMESPACE_ENTER
  39. {
  40. // Version 1.1.2
  41. // https://github.com/imageworks/pystring/tarball/v1.1.2
  42. namespace pystring
  43. {
  44. //////////////////////////////////////////////////////////////////////////////////////////////
  45. /// @mainpage pystring
  46. ///
  47. /// This is a set of functions matching the interface and behaviors of python string methods
  48. /// (as of python 2.3) using std::string.
  49. ///
  50. /// Overlapping functionality ( such as index and slice/substr ) of std::string is included
  51. /// to match python interfaces.
  52. ///
  53. //////////////////////////////////////////////////////////////////////////////////////////////
  54. /// @defgroup functions pystring
  55. /// @{
  56. #define MAX_32BIT_INT 2147483647
  57. //////////////////////////////////////////////////////////////////////////////////////////////
  58. /// @brief Return a copy of the string with only its first character capitalized.
  59. ///
  60. std::string capitalize( const std::string & str );
  61. //////////////////////////////////////////////////////////////////////////////////////////////
  62. /// @brief Return centered in a string of length width. Padding is done using spaces.
  63. ///
  64. std::string center( const std::string & str, int width );
  65. //////////////////////////////////////////////////////////////////////////////////////////////
  66. /// @brief Return the number of occurrences of substring sub in string S[start:end]. Optional
  67. /// arguments start and end are interpreted as in slice notation.
  68. ///
  69. int count( const std::string & str, const std::string & substr, int start = 0, int end = MAX_32BIT_INT);
  70. //////////////////////////////////////////////////////////////////////////////////////////////
  71. /// @brief Return True if the string ends with the specified suffix, otherwise return False. With
  72. /// optional start, test beginning at that position. With optional end, stop comparing at that position.
  73. ///
  74. bool endswith( const std::string & str, const std::string & suffix, int start = 0, int end = MAX_32BIT_INT );
  75. //////////////////////////////////////////////////////////////////////////////////////////////
  76. /// @brief Return a copy of the string where all tab characters are expanded using spaces. If tabsize
  77. /// is not given, a tab size of 8 characters is assumed.
  78. ///
  79. std::string expandtabs( const std::string & str, int tabsize = 8);
  80. //////////////////////////////////////////////////////////////////////////////////////////////
  81. /// @brief Return the lowest index in the string where substring sub is found, such that sub is
  82. /// contained in the range [start, end). Optional arguments start and end are interpreted as
  83. /// in slice notation. Return -1 if sub is not found.
  84. ///
  85. int find( const std::string & str, const std::string & sub, int start = 0, int end = MAX_32BIT_INT );
  86. //////////////////////////////////////////////////////////////////////////////////////////////
  87. /// @brief Synonym of find right now. Python version throws exceptions. This one currently doesn't
  88. ///
  89. int index( const std::string & str, const std::string & sub, int start = 0, int end = MAX_32BIT_INT );
  90. //////////////////////////////////////////////////////////////////////////////////////////////
  91. /// @brief Return true if all characters in the string are alphanumeric and there is at least one
  92. /// character, false otherwise.
  93. ///
  94. bool isalnum( const std::string & str );
  95. //////////////////////////////////////////////////////////////////////////////////////////////
  96. /// @brief Return true if all characters in the string are alphabetic and there is at least one
  97. /// character, false otherwise
  98. ///
  99. bool isalpha( const std::string & str );
  100. //////////////////////////////////////////////////////////////////////////////////////////////
  101. /// @brief Return true if all characters in the string are digits and there is at least one
  102. /// character, false otherwise.
  103. ///
  104. bool isdigit( const std::string & str );
  105. //////////////////////////////////////////////////////////////////////////////////////////////
  106. /// @brief Return true if all cased characters in the string are lowercase and there is at least one
  107. /// cased character, false otherwise.
  108. ///
  109. bool islower( const std::string & str );
  110. //////////////////////////////////////////////////////////////////////////////////////////////
  111. /// @brief Return true if there are only whitespace characters in the string and there is at least
  112. /// one character, false otherwise.
  113. ///
  114. bool isspace( const std::string & str );
  115. //////////////////////////////////////////////////////////////////////////////////////////////
  116. /// @brief Return true if the string is a titlecased string and there is at least one character,
  117. /// i.e. uppercase characters may only follow uncased characters and lowercase characters only
  118. /// cased ones. Return false otherwise.
  119. ///
  120. bool istitle( const std::string & str );
  121. //////////////////////////////////////////////////////////////////////////////////////////////
  122. /// @brief Return true if all cased characters in the string are uppercase and there is at least one
  123. /// cased character, false otherwise.
  124. ///
  125. bool isupper( const std::string & str );
  126. //////////////////////////////////////////////////////////////////////////////////////////////
  127. /// @brief Return a string which is the concatenation of the strings in the sequence seq.
  128. /// The separator between elements is the str argument
  129. ///
  130. std::string join( const std::string & str, const std::vector< std::string > & seq );
  131. //////////////////////////////////////////////////////////////////////////////////////////////
  132. /// @brief Return the string left justified in a string of length width. Padding is done using
  133. /// spaces. The original string is returned if width is less than str.size().
  134. ///
  135. std::string ljust( const std::string & str, int width );
  136. //////////////////////////////////////////////////////////////////////////////////////////////
  137. /// @brief Return a copy of the string converted to lowercase.
  138. ///
  139. std::string lower( const std::string & str );
  140. //////////////////////////////////////////////////////////////////////////////////////////////
  141. /// @brief Return a copy of the string with leading characters removed. If chars is omitted or None,
  142. /// whitespace characters are removed. If given and not "", chars must be a string; the
  143. /// characters in the string will be stripped from the beginning of the string this method
  144. /// is called on (argument "str" ).
  145. ///
  146. std::string lstrip( const std::string & str, const std::string & chars = "" );
  147. //////////////////////////////////////////////////////////////////////////////////////////////
  148. /// @brief Return a copy of the string, concatenated N times, together.
  149. /// Corresponds to the __mul__ operator.
  150. ///
  151. std::string mul( const std::string & str, int n);
  152. //////////////////////////////////////////////////////////////////////////////////////////////
  153. /// @brief Split the string around first occurance of sep.
  154. /// Three strings will always placed into result. If sep is found, the strings will
  155. /// be the text before sep, sep itself, and the remaining text. If sep is
  156. /// not found, the original string will be returned with two empty strings.
  157. ///
  158. void partition( const std::string & str, const std::string & sep, std::vector< std::string > & result );
  159. //////////////////////////////////////////////////////////////////////////////////////////////
  160. /// @brief Return a copy of the string with all occurrences of substring old replaced by new. If
  161. /// the optional argument count is given, only the first count occurrences are replaced.
  162. ///
  163. std::string replace( const std::string & str, const std::string & oldstr, const std::string & newstr, int count = -1);
  164. //////////////////////////////////////////////////////////////////////////////////////////////
  165. /// @brief Return the highest index in the string where substring sub is found, such that sub is
  166. /// contained within s[start,end]. Optional arguments start and end are interpreted as in
  167. /// slice notation. Return -1 on failure.
  168. ///
  169. int rfind( const std::string & str, const std::string & sub, int start = 0, int end = MAX_32BIT_INT );
  170. //////////////////////////////////////////////////////////////////////////////////////////////
  171. /// @brief Currently a synonym of rfind. The python version raises exceptions. This one currently
  172. /// does not
  173. ///
  174. int rindex( const std::string & str, const std::string & sub, int start = 0, int end = MAX_32BIT_INT );
  175. //////////////////////////////////////////////////////////////////////////////////////////////
  176. /// @brief Return the string right justified in a string of length width. Padding is done using
  177. /// spaces. The original string is returned if width is less than str.size().
  178. ///
  179. std::string rjust( const std::string & str, int width);
  180. //////////////////////////////////////////////////////////////////////////////////////////////
  181. /// @brief Split the string around last occurance of sep.
  182. /// Three strings will always placed into result. If sep is found, the strings will
  183. /// be the text before sep, sep itself, and the remaining text. If sep is
  184. /// not found, the original string will be returned with two empty strings.
  185. ///
  186. void rpartition( const std::string & str, const std::string & sep, std::vector< std::string > & result );
  187. //////////////////////////////////////////////////////////////////////////////////////////////
  188. /// @brief Return a copy of the string with trailing characters removed. If chars is "", whitespace
  189. /// characters are removed. If not "", the characters in the string will be stripped from the
  190. /// end of the string this method is called on.
  191. ///
  192. std::string rstrip( const std::string & str, const std::string & chars = "" );
  193. //////////////////////////////////////////////////////////////////////////////////////////////
  194. /// @brief Fills the "result" list with the words in the string, using sep as the delimiter string.
  195. /// If maxsplit is > -1, at most maxsplit splits are done. If sep is "",
  196. /// any whitespace string is a separator.
  197. ///
  198. void split( const std::string & str, std::vector< std::string > & result, const std::string & sep = "", int maxsplit = -1);
  199. //////////////////////////////////////////////////////////////////////////////////////////////
  200. /// @brief Fills the "result" list with the words in the string, using sep as the delimiter string.
  201. /// Does a number of splits starting at the end of the string, the result still has the
  202. /// split strings in their original order.
  203. /// If maxsplit is > -1, at most maxsplit splits are done. If sep is "",
  204. /// any whitespace string is a separator.
  205. ///
  206. void rsplit( const std::string & str, std::vector< std::string > & result, const std::string & sep = "", int maxsplit = -1);
  207. //////////////////////////////////////////////////////////////////////////////////////////////
  208. /// @brief Return a list of the lines in the string, breaking at line boundaries. Line breaks
  209. /// are not included in the resulting list unless keepends is given and true.
  210. ///
  211. void splitlines( const std::string & str, std::vector< std::string > & result, bool keepends = false );
  212. //////////////////////////////////////////////////////////////////////////////////////////////
  213. /// @brief Return True if string starts with the prefix, otherwise return False. With optional start,
  214. /// test string beginning at that position. With optional end, stop comparing string at that
  215. /// position
  216. ///
  217. bool startswith( const std::string & str, const std::string & prefix, int start = 0, int end = MAX_32BIT_INT );
  218. //////////////////////////////////////////////////////////////////////////////////////////////
  219. /// @brief Return a copy of the string with leading and trailing characters removed. If chars is "",
  220. /// whitespace characters are removed. If given not "", the characters in the string will be
  221. /// stripped from the both ends of the string this method is called on.
  222. ///
  223. std::string strip( const std::string & str, const std::string & chars = "" );
  224. //////////////////////////////////////////////////////////////////////////////////////////////
  225. /// @brief Return a copy of the string with uppercase characters converted to lowercase and vice versa.
  226. ///
  227. std::string swapcase( const std::string & str );
  228. //////////////////////////////////////////////////////////////////////////////////////////////
  229. /// @brief Return a titlecased version of the string: words start with uppercase characters,
  230. /// all remaining cased characters are lowercase.
  231. ///
  232. std::string title( const std::string & str );
  233. //////////////////////////////////////////////////////////////////////////////////////////////
  234. /// @brief Return a copy of the string where all characters occurring in the optional argument
  235. /// deletechars are removed, and the remaining characters have been mapped through the given
  236. /// translation table, which must be a string of length 256.
  237. ///
  238. std::string translate( const std::string & str, const std::string & table, const std::string & deletechars = "");
  239. //////////////////////////////////////////////////////////////////////////////////////////////
  240. /// @brief Return a copy of the string converted to uppercase.
  241. ///
  242. std::string upper( const std::string & str );
  243. //////////////////////////////////////////////////////////////////////////////////////////////
  244. /// @brief Return the numeric string left filled with zeros in a string of length width. The original
  245. /// string is returned if width is less than str.size().
  246. ///
  247. std::string zfill( const std::string & str, int width );
  248. //////////////////////////////////////////////////////////////////////////////////////////////
  249. /// @brief function matching python's slice functionality.
  250. ///
  251. std::string slice( const std::string & str, int start = 0, int end = MAX_32BIT_INT);
  252. ///
  253. /// @ }
  254. ///
  255. namespace os
  256. {
  257. namespace path
  258. {
  259. // All of the function below have three versions.
  260. // Example:
  261. // join(...)
  262. // join_nt(...)
  263. // join_posix(...)
  264. //
  265. // The regular function dispatches to the other versions - based on the OS
  266. // at compile time - to match the result you'd get from the python
  267. // interepreter on the same operating system
  268. //
  269. // Should you want to 'lock off' to a particular version of the string
  270. // manipulation across *all* operating systems, use the version with the
  271. // _OS you are interested in. I.e., you can use posix style path joining,
  272. // even on Windows, with join_posix.
  273. //
  274. // The naming, (nt, posix) matches the cpython source implementation.
  275. //////////////////////////////////////////////////////////////////////////////////////////////
  276. /// @defgroup functions pystring::os::path
  277. /// @{
  278. //////////////////////////////////////////////////////////////////////////////////////////////
  279. /// @brief Return the base name of pathname path. This is the second half of the pair returned
  280. /// by split(path). Note that the result of this function is different from the Unix basename
  281. /// program; where basename for '/foo/bar/' returns 'bar', the basename() function returns an
  282. /// empty string ('').
  283. std::string basename(const std::string & path);
  284. std::string basename_nt(const std::string & path);
  285. std::string basename_posix(const std::string & path);
  286. //////////////////////////////////////////////////////////////////////////////////////////////
  287. /// @brief Return the directory name of pathname path. This is the first half of the pair
  288. /// returned by split(path).
  289. std::string dirname(const std::string & path);
  290. std::string dirname_nt(const std::string & path);
  291. std::string dirname_posix(const std::string & path);
  292. //////////////////////////////////////////////////////////////////////////////////////////////
  293. /// @brief Return True if path is an absolute pathname. On Unix, that means it begins with a
  294. /// slash, on Windows that it begins with a (back)slash after chopping off a potential drive
  295. /// letter.
  296. bool isabs(const std::string & path);
  297. bool isabs_nt(const std::string & path);
  298. bool isabs_posix(const std::string & s);
  299. //////////////////////////////////////////////////////////////////////////////////////////////
  300. /// @brief Return a normalized absolutized version of the pathname path.
  301. ///
  302. /// NOTE: This differs from the interface of the python equivalent in that it requires you
  303. /// to pass in the current working directory as an argument.
  304. std::string abspath(const std::string & path, const std::string & cwd);
  305. std::string abspath_nt(const std::string & path, const std::string & cwd);
  306. std::string abspath_posix(const std::string & path, const std::string & cwd);
  307. //////////////////////////////////////////////////////////////////////////////////////////////
  308. /// @brief Join one or more path components intelligently. If any component is an absolute
  309. /// path, all previous components (on Windows, including the previous drive letter, if there
  310. /// was one) are thrown away, and joining continues. The return value is the concatenation of
  311. /// path1, and optionally path2, etc., with exactly one directory separator (os.sep) inserted
  312. /// between components, unless path2 is empty. Note that on Windows, since there is a current
  313. /// directory for each drive, os.path.join("c:", "foo") represents a path relative to the
  314. /// current directory on drive C: (c:foo), not c:\foo.
  315. /// This dispatches based on the compilation OS
  316. std::string join(const std::string & path1, const std::string & path2);
  317. std::string join_nt(const std::string & path1, const std::string & path2);
  318. std::string join_posix(const std::string & path1, const std::string & path2);
  319. std::string join(const std::vector< std::string > & paths);
  320. std::string join_nt(const std::vector< std::string > & paths);
  321. std::string join_posix(const std::vector< std::string > & paths);
  322. //////////////////////////////////////////////////////////////////////////////////////////////
  323. /// @brief Normalize a pathname. This collapses redundant separators and up-level references
  324. /// so that A//B, A/B/, A/./B and A/foo/../B all become A/B. It does not normalize the case
  325. /// (use normcase() for that). On Windows, it converts forward slashes to backward slashes.
  326. /// It should be understood that this may change the meaning of the path if it contains
  327. /// symbolic links!
  328. std::string normpath(const std::string & path);
  329. std::string normpath_nt(const std::string & path);
  330. std::string normpath_posix(const std::string & path);
  331. //////////////////////////////////////////////////////////////////////////////////////////////
  332. /// @brief Split the pathname path into a pair, (head, tail) where tail is the last pathname
  333. /// component and head is everything leading up to that. The tail part will never contain a
  334. /// slash; if path ends in a slash, tail will be empty. If there is no slash in path, head
  335. /// will be empty. If path is empty, both head and tail are empty. Trailing slashes are
  336. /// stripped from head unless it is the root (one or more slashes only). In all cases,
  337. /// join(head, tail) returns a path to the same location as path (but the strings may
  338. /// differ).
  339. void split(std::string & head, std::string & tail, const std::string & path);
  340. void split_nt(std::string & head, std::string & tail, const std::string & path);
  341. void split_posix(std::string & head, std::string & tail, const std::string & path);
  342. //////////////////////////////////////////////////////////////////////////////////////////////
  343. /// @brief Split the pathname path into a pair (drive, tail) where drive is either a drive
  344. /// specification or the empty string. On systems which do not use drive specifications,
  345. /// drive will always be the empty string. In all cases, drive + tail will be the same as
  346. /// path.
  347. void splitdrive(std::string & drivespec, std::string & pathspec, const std::string & path);
  348. void splitdrive_nt(std::string & drivespec, std::string & pathspec, const std::string & p);
  349. void splitdrive_posix(std::string & drivespec, std::string & pathspec, const std::string & path);
  350. //////////////////////////////////////////////////////////////////////////////////////////////
  351. /// @brief Split the pathname path into a pair (root, ext) such that root + ext == path, and
  352. /// ext is empty or begins with a period and contains at most one period. Leading periods on
  353. /// the basename are ignored; splitext('.cshrc') returns ('.cshrc', '').
  354. void splitext(std::string & root, std::string & ext, const std::string & path);
  355. void splitext_nt(std::string & root, std::string & ext, const std::string & path);
  356. void splitext_posix(std::string & root, std::string & ext, const std::string & path);
  357. ///
  358. /// @ }
  359. ///
  360. } // namespace path
  361. } // namespace os
  362. } // namespace pystring
  363. }
  364. OCIO_NAMESPACE_EXIT
  365. #endif