Pyrogenesis  trunk
path.h
Go to the documentation of this file.
1 /* Copyright (c) 2013 Wildfire Games
2  *
3  * Permission is hereby granted, free of charge, to any person obtaining
4  * a copy of this software and associated documentation files (the
5  * "Software"), to deal in the Software without restriction, including
6  * without limitation the rights to use, copy, modify, merge, publish,
7  * distribute, sublicense, and/or sell copies of the Software, and to
8  * permit persons to whom the Software is furnished to do so, subject to
9  * the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included
12  * in all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
17  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
18  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
19  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
20  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21  */
22 
23 /*
24  * Path string class, similar to boost::filesystem::basic_path.
25  */
26 
27 // notes:
28 // - this module is independent of lib/file so that it can be used from
29 // other code without pulling in the entire file manager.
30 // - there is no restriction on buffer lengths except the underlying OS.
31 // input buffers must not exceed PATH_MAX chars, while outputs
32 // must hold at least that much.
33 // - unless otherwise mentioned, all functions are intended to work with
34 // native and VFS paths.
35 // when reading, both '/' and SYS_DIR_SEP are accepted; '/' is written.
36 
37 #ifndef INCLUDED_PATH
38 #define INCLUDED_PATH
39 
40 #if CONFIG_ENABLE_BOOST
41 # include "boost/functional/hash.hpp"
42 #endif
43 
44 #include "lib/utf8.h"
45 
46 #include <cstring>
47 
48 namespace ERR
49 {
50  const Status PATH_CHARACTER_ILLEGAL = -100300;
51  const Status PATH_CHARACTER_UNSAFE = -100301;
52  const Status PATH_NOT_FOUND = -100302;
53  const Status PATH_MIXED_SEPARATORS = -100303;
54 }
55 
56 /**
57  * is s2 a subpath of s1, or vice versa? (equal counts as subpath)
58  *
59  * @param s1, s2 comparand strings
60  * @return bool
61  **/
62 LIB_API bool path_is_subpath(const wchar_t* s1, const wchar_t* s2);
63 
64 /**
65  * Get the path component of a path.
66  * Skips over all characters up to the last dir separator, if any.
67  *
68  * @param path Input path.
69  * @return pointer to path component within <path>.
70  **/
71 LIB_API const wchar_t* path_name_only(const wchar_t* path);
72 
73 
74 // NB: there is a need for 'generic' paths (e.g. for Trace entry / archive pathnames).
75 // converting between specialized variants via c_str would be inefficient, and the
76 // Os/VfsPath typedefs are hopefully sufficient to avoid errors.
77 class Path
78 {
79 public:
80  typedef std::wstring String;
81 
82  Path()
83  {
84  DetectSeparator();
85  }
86 
87  Path(const char* p)
88  : path((const unsigned char*)p, (const unsigned char*)p+strlen(p))
89  // interpret bytes as unsigned; makes no difference for ASCII,
90  // and ensures OsPath on Unix will only contain values 0 <= c < 0x100
91  {
92  DetectSeparator();
93  }
94 
95  Path(const wchar_t* p)
96  : path(p, p+wcslen(p))
97  {
98  DetectSeparator();
99  }
100 
101  Path(const std::string& s)
102  : path((const unsigned char*)s.c_str(), (const unsigned char*)s.c_str()+s.length())
103  {
104  DetectSeparator();
105  }
106 
107  Path(const std::wstring& s)
108  : path(s)
109  {
110  DetectSeparator();
111  }
112 
113  Path& operator=(const Path& rhs)
114  {
115  path = rhs.path;
116  DetectSeparator(); // (warns if separators differ)
117  return *this;
118  }
119 
120  bool empty() const
121  {
122  return path.empty();
123  }
124 
125  const String& string() const
126  {
127  return path;
128  }
129 
130  /**
131  * Return a UTF-8 version of the path, in a human-readable but potentially
132  * lossy form. It is *not* safe to take this string and construct a new
133  * Path object from it (it may fail for some non-ASCII paths) - it should
134  * only be used for displaying paths to users.
135  */
136  std::string string8() const
137  {
138  // TODO: On Unixes, this will only be correct for ASCII or ISO-8859-1
139  // encoded paths; we should probably assume UTF-8 encoding by default
140  // (but take care to handle non-valid-UTF-8 paths safely).
141 
142  return utf8_from_wstring(path);
143  }
144 
145  bool operator<(const Path& rhs) const
146  {
147  return path < rhs.path;
148  }
149 
150  bool operator==(const Path& rhs) const
151  {
152  return path == rhs.path;
153  }
154 
155  bool operator!=(const Path& rhs) const
156  {
157  return !operator==(rhs);
158  }
159 
160  bool IsDirectory() const
161  {
162  if(empty()) // (ensure length()-1 is safe)
163  return true; // (the VFS root directory is represented as an empty string)
164  return path[path.length()-1] == separator;
165  }
166 
167  Path Parent() const
168  {
169  const size_t idxSlash = path.find_last_of(separator);
170  if(idxSlash == String::npos)
171  return L"";
172  return path.substr(0, idxSlash);
173  }
174 
175  Path Filename() const
176  {
177  const size_t idxSlash = path.find_last_of(separator);
178  if(idxSlash == String::npos)
179  return path;
180  return path.substr(idxSlash+1);
181  }
182 
183  Path Basename() const
184  {
185  const Path filename = Filename();
186  const size_t idxDot = filename.string().find_last_of('.');
187  if(idxDot == String::npos)
188  return filename;
189  return filename.string().substr(0, idxDot);
190  }
191 
192  // (Path return type allows callers to use our operator==)
193  Path Extension() const
194  {
195  const Path filename = Filename();
196  const size_t idxDot = filename.string().find_last_of('.');
197  if(idxDot == String::npos)
198  return Path();
199  return filename.string().substr(idxDot);
200  }
201 
203  {
204  return Parent() / Path(Basename().string() + extension.string());
205  }
206 
207  Path operator/(Path rhs) const
208  {
209  Path ret = *this;
210  if(ret.path.empty()) // (empty paths assume '/')
211  ret.separator = rhs.separator;
212  if(!ret.IsDirectory())
213  ret.path += ret.separator;
214 
215  if(rhs.path.find((ret.separator == '/')? '\\' : '/') != String::npos)
216  {
217  PrintToDebugOutput();
218  rhs.PrintToDebugOutput();
220  }
221  ret.path += rhs.path;
222  return ret;
223  }
224 
225  /**
226  * Return the path before the common part of both paths
227  * @param other Indicates the start of the path which should be removed
228  * @note other should be a VfsPath, while this should be an OsPath
229  */
230  Path BeforeCommon(Path other) const
231  {
232  Path ret = *this;
233  if(ret.empty() || other.empty())
234  return L"";
235 
236  // Convert the separator to allow for string comparison
237  if(other.separator != ret.separator)
238  replace(other.path.begin(), other.path.end(), other.separator, ret.separator);
239 
240  const size_t idx = ret.path.rfind(other.path);
241  if(idx == String::npos)
242  return L"";
243 
244  return path.substr(0, idx);
245  }
246 
247  static Status Validate(String::value_type c);
248 
249 private:
250  void PrintToDebugOutput() const
251  {
252  debug_printf("Path %s, separator %c\n", string8().c_str(), (char)separator);
253  }
254 
256  {
257  const size_t idxBackslash = path.find('\\');
258 
259  if(path.find('/') != String::npos && idxBackslash != String::npos)
260  {
261  PrintToDebugOutput();
263  }
264 
265  // (default to '/' for empty strings)
266  separator = (idxBackslash == String::npos)? '/' : '\\';
267  }
268 
269  String path;
270 
271  // note: ideally, path strings would only contain '/' or even SYS_DIR_SEP.
272  // however, Windows-specific code (e.g. the sound driver detection)
273  // uses these routines with '\\' strings. the boost::filesystem approach of
274  // converting them all to '/' and then back via external_file_string is
275  // annoying and inefficient. we allow either type of separators,
276  // appending whichever was first encountered. when modifying the path,
277  // we ensure the same separator is used.
278  wchar_t separator;
279 };
280 
281 static inline std::wostream& operator<<(std::wostream& s, const Path& path)
282 {
283  s << path.string();
284  return s;
285 }
286 
287 static inline std::wistream& operator>>(std::wistream& s, Path& path)
288 {
289  Path::String string;
290  s >> string;
291  path = Path(string);
292  return s;
293 }
294 
295 #if CONFIG_ENABLE_BOOST
296 
297 namespace boost {
298 
299 template<>
300 struct hash<Path> : std::unary_function<Path, std::size_t>
301 {
302  std::size_t operator()(const Path& path) const
303  {
304  return hash_value(path.string());
305  }
306 };
307 
308 }
309 
310 #endif // #if CONFIG_ENABLE_BOOST
311 
312 #endif // #ifndef INCLUDED_PATH
void DetectSeparator()
Definition: path.h:255
Path Filename() const
Definition: path.h:175
std::string string8() const
Return a UTF-8 version of the path, in a human-readable but potentially lossy form.
Definition: path.h:136
std::string utf8_from_wstring(const std::wstring &src, Status *err)
opposite of wstring_from_utf8
Definition: utf8.cpp:208
bool IsDirectory() const
Definition: path.h:160
const Status PATH_CHARACTER_ILLEGAL
Definition: path.h:50
bool operator==(const FCDJointWeightPair &a, const FCDJointWeightPair &b)
Definition: GeomReindex.cpp:59
Path Parent() const
Definition: path.h:167
Path(const char *p)
Definition: path.h:87
void PrintToDebugOutput() const
Definition: path.h:250
Path BeforeCommon(Path other) const
Return the path before the common part of both paths.
Definition: path.h:230
LIB_API bool path_is_subpath(const wchar_t *s1, const wchar_t *s2)
is s2 a subpath of s1, or vice versa? (equal counts as subpath)
Definition: path.cpp:51
Path Basename() const
Definition: path.h:183
const Status PATH_CHARACTER_UNSAFE
Definition: path.h:51
wchar_t separator
Definition: path.h:278
bool operator!=(const Path &rhs) const
Definition: path.h:155
Definition: path.h:77
String path
Definition: path.h:269
const String & string() const
Definition: path.h:125
Path(const wchar_t *p)
Definition: path.h:95
std::wstring String
Definition: path.h:80
bool operator==(const Path &rhs) const
Definition: path.h:150
i64 Status
Error handling system.
Definition: status.h:171
Path operator/(Path rhs) const
Definition: path.h:207
const Status PATH_MIXED_SEPARATORS
Definition: path.h:53
void debug_printf(const char *fmt,...)
write a formatted string to the debug channel, subject to filtering (see below).
Definition: debug.cpp:142
Path(const std::wstring &s)
Definition: path.h:107
Path(const std::string &s)
Definition: path.h:101
#define DEBUG_WARN_ERR(status)
display the error dialog with text corresponding to the given error code.
Definition: debug.h:336
Introduction
Definition: debug.h:404
const char * extension
Definition: mongoose.cpp:1733
bool empty() const
Definition: path.h:120
Path ChangeExtension(Path extension) const
Definition: path.h:202
Path Extension() const
Definition: path.h:193
static std::wistream & operator>>(std::wistream &s, Path &path)
Definition: path.h:287
bool operator<(const Path &rhs) const
Definition: path.h:145
Path & operator=(const Path &rhs)
Definition: path.h:113
LIB_API const wchar_t * path_name_only(const wchar_t *path)
Get the path component of a path.
Definition: path.cpp:85
Path()
Definition: path.h:82
size_t hash_value(const CVector4D &v)
Definition: ShaderDefines.cpp:28
static std::wostream & operator<<(std::wostream &s, const Path &path)
Definition: path.h:281
const Status PATH_NOT_FOUND
Definition: path.h:52