Path.h revision dce4a407a24b04eebc6a376f8e62b41aaa7b071f
1//===- llvm/Support/Path.h - Path Operating System Concept ------*- C++ -*-===// 2// 3// The LLVM Compiler Infrastructure 4// 5// This file is distributed under the University of Illinois Open Source 6// License. See LICENSE.TXT for details. 7// 8//===----------------------------------------------------------------------===// 9// 10// This file declares the llvm::sys::path namespace. It is designed after 11// TR2/boost filesystem (v3), but modified to remove exception handling and the 12// path class. 13// 14//===----------------------------------------------------------------------===// 15 16#ifndef LLVM_SUPPORT_PATH_H 17#define LLVM_SUPPORT_PATH_H 18 19#include "llvm/ADT/SmallString.h" 20#include "llvm/ADT/Twine.h" 21#include "llvm/Support/DataTypes.h" 22#include <iterator> 23 24namespace llvm { 25namespace sys { 26namespace path { 27 28/// @name Lexical Component Iterator 29/// @{ 30 31/// @brief Path iterator. 32/// 33/// This is a bidirectional iterator that iterates over the individual 34/// components in \a path. The forward traversal order is as follows: 35/// * The root-name element, if present. 36/// * The root-directory element, if present. 37/// * Each successive filename element, if present. 38/// * Dot, if one or more trailing non-root slash characters are present. 39/// The backwards traversal order is the reverse of forward traversal. 40/// 41/// Iteration examples. Each component is separated by ',': 42/// @code 43/// / => / 44/// /foo => /,foo 45/// foo/ => foo,. 46/// /foo/bar => /,foo,bar 47/// ../ => ..,. 48/// C:\foo\bar => C:,/,foo,bar 49/// @endcode 50class const_iterator { 51 StringRef Path; ///< The entire path. 52 StringRef Component; ///< The current component. Not necessarily in Path. 53 size_t Position; ///< The iterators current position within Path. 54 55 // An end iterator has Position = Path.size() + 1. 56 friend const_iterator begin(StringRef path); 57 friend const_iterator end(StringRef path); 58 59public: 60 typedef const StringRef value_type; 61 typedef ptrdiff_t difference_type; 62 typedef value_type &reference; 63 typedef value_type *pointer; 64 typedef std::bidirectional_iterator_tag iterator_category; 65 66 reference operator*() const { return Component; } 67 pointer operator->() const { return &Component; } 68 const_iterator &operator++(); // preincrement 69 const_iterator &operator++(int); // postincrement 70 const_iterator &operator--(); // predecrement 71 const_iterator &operator--(int); // postdecrement 72 bool operator==(const const_iterator &RHS) const; 73 bool operator!=(const const_iterator &RHS) const; 74 75 /// @brief Difference in bytes between this and RHS. 76 ptrdiff_t operator-(const const_iterator &RHS) const; 77}; 78 79typedef std::reverse_iterator<const_iterator> reverse_iterator; 80 81/// @brief Get begin iterator over \a path. 82/// @param path Input path. 83/// @returns Iterator initialized with the first component of \a path. 84const_iterator begin(StringRef path); 85 86/// @brief Get end iterator over \a path. 87/// @param path Input path. 88/// @returns Iterator initialized to the end of \a path. 89const_iterator end(StringRef path); 90 91/// @brief Get reverse begin iterator over \a path. 92/// @param path Input path. 93/// @returns Iterator initialized with the first reverse component of \a path. 94inline reverse_iterator rbegin(StringRef path) { 95 return reverse_iterator(end(path)); 96} 97 98/// @brief Get reverse end iterator over \a path. 99/// @param path Input path. 100/// @returns Iterator initialized to the reverse end of \a path. 101inline reverse_iterator rend(StringRef path) { 102 return reverse_iterator(begin(path)); 103} 104 105/// @} 106/// @name Lexical Modifiers 107/// @{ 108 109/// @brief Remove the last component from \a path unless it is the root dir. 110/// 111/// @code 112/// directory/filename.cpp => directory/ 113/// directory/ => directory 114/// filename.cpp => <empty> 115/// / => / 116/// @endcode 117/// 118/// @param path A path that is modified to not have a file component. 119void remove_filename(SmallVectorImpl<char> &path); 120 121/// @brief Replace the file extension of \a path with \a extension. 122/// 123/// @code 124/// ./filename.cpp => ./filename.extension 125/// ./filename => ./filename.extension 126/// ./ => ./.extension 127/// @endcode 128/// 129/// @param path A path that has its extension replaced with \a extension. 130/// @param extension The extension to be added. It may be empty. It may also 131/// optionally start with a '.', if it does not, one will be 132/// prepended. 133void replace_extension(SmallVectorImpl<char> &path, const Twine &extension); 134 135/// @brief Append to path. 136/// 137/// @code 138/// /foo + bar/f => /foo/bar/f 139/// /foo/ + bar/f => /foo/bar/f 140/// foo + bar/f => foo/bar/f 141/// @endcode 142/// 143/// @param path Set to \a path + \a component. 144/// @param a The component to be appended to \a path. 145void append(SmallVectorImpl<char> &path, const Twine &a, 146 const Twine &b = "", 147 const Twine &c = "", 148 const Twine &d = ""); 149 150/// @brief Append to path. 151/// 152/// @code 153/// /foo + [bar,f] => /foo/bar/f 154/// /foo/ + [bar,f] => /foo/bar/f 155/// foo + [bar,f] => foo/bar/f 156/// @endcode 157/// 158/// @param path Set to \a path + [\a begin, \a end). 159/// @param begin Start of components to append. 160/// @param end One past the end of components to append. 161void append(SmallVectorImpl<char> &path, 162 const_iterator begin, const_iterator end); 163 164/// @} 165/// @name Transforms (or some other better name) 166/// @{ 167 168/// Convert path to the native form. This is used to give paths to users and 169/// operating system calls in the platform's normal way. For example, on Windows 170/// all '/' are converted to '\'. 171/// 172/// @param path A path that is transformed to native format. 173/// @param result Holds the result of the transformation. 174void native(const Twine &path, SmallVectorImpl<char> &result); 175 176/// Convert path to the native form in place. This is used to give paths to 177/// users and operating system calls in the platform's normal way. For example, 178/// on Windows all '/' are converted to '\'. 179/// 180/// @param path A path that is transformed to native format. 181void native(SmallVectorImpl<char> &path); 182 183/// @} 184/// @name Lexical Observers 185/// @{ 186 187/// @brief Get root name. 188/// 189/// @code 190/// //net/hello => //net 191/// c:/hello => c: (on Windows, on other platforms nothing) 192/// /hello => <empty> 193/// @endcode 194/// 195/// @param path Input path. 196/// @result The root name of \a path if it has one, otherwise "". 197const StringRef root_name(StringRef path); 198 199/// @brief Get root directory. 200/// 201/// @code 202/// /goo/hello => / 203/// c:/hello => / 204/// d/file.txt => <empty> 205/// @endcode 206/// 207/// @param path Input path. 208/// @result The root directory of \a path if it has one, otherwise 209/// "". 210const StringRef root_directory(StringRef path); 211 212/// @brief Get root path. 213/// 214/// Equivalent to root_name + root_directory. 215/// 216/// @param path Input path. 217/// @result The root path of \a path if it has one, otherwise "". 218const StringRef root_path(StringRef path); 219 220/// @brief Get relative path. 221/// 222/// @code 223/// C:\hello\world => hello\world 224/// foo/bar => foo/bar 225/// /foo/bar => foo/bar 226/// @endcode 227/// 228/// @param path Input path. 229/// @result The path starting after root_path if one exists, otherwise "". 230const StringRef relative_path(StringRef path); 231 232/// @brief Get parent path. 233/// 234/// @code 235/// / => <empty> 236/// /foo => / 237/// foo/../bar => foo/.. 238/// @endcode 239/// 240/// @param path Input path. 241/// @result The parent path of \a path if one exists, otherwise "". 242const StringRef parent_path(StringRef path); 243 244/// @brief Get filename. 245/// 246/// @code 247/// /foo.txt => foo.txt 248/// . => . 249/// .. => .. 250/// / => / 251/// @endcode 252/// 253/// @param path Input path. 254/// @result The filename part of \a path. This is defined as the last component 255/// of \a path. 256const StringRef filename(StringRef path); 257 258/// @brief Get stem. 259/// 260/// If filename contains a dot but not solely one or two dots, result is the 261/// substring of filename ending at (but not including) the last dot. Otherwise 262/// it is filename. 263/// 264/// @code 265/// /foo/bar.txt => bar 266/// /foo/bar => bar 267/// /foo/.txt => <empty> 268/// /foo/. => . 269/// /foo/.. => .. 270/// @endcode 271/// 272/// @param path Input path. 273/// @result The stem of \a path. 274const StringRef stem(StringRef path); 275 276/// @brief Get extension. 277/// 278/// If filename contains a dot but not solely one or two dots, result is the 279/// substring of filename starting at (and including) the last dot, and ending 280/// at the end of \a path. Otherwise "". 281/// 282/// @code 283/// /foo/bar.txt => .txt 284/// /foo/bar => <empty> 285/// /foo/.txt => .txt 286/// @endcode 287/// 288/// @param path Input path. 289/// @result The extension of \a path. 290const StringRef extension(StringRef path); 291 292/// @brief Check whether the given char is a path separator on the host OS. 293/// 294/// @param value a character 295/// @result true if \a value is a path separator character on the host OS 296bool is_separator(char value); 297 298/// @brief Return the preferred separator for this platform. 299/// 300/// @result StringRef of the preferred separator, null-terminated. 301const StringRef get_separator(); 302 303/// @brief Get the typical temporary directory for the system, e.g., 304/// "/var/tmp" or "C:/TEMP" 305/// 306/// @param erasedOnReboot Whether to favor a path that is erased on reboot 307/// rather than one that potentially persists longer. This parameter will be 308/// ignored if the user or system has set the typical environment variable 309/// (e.g., TEMP on Windows, TMPDIR on *nix) to specify a temporary directory. 310/// 311/// @param result Holds the resulting path name. 312void system_temp_directory(bool erasedOnReboot, SmallVectorImpl<char> &result); 313 314/// @brief Get the user's home directory. 315/// 316/// @param result Holds the resulting path name. 317/// @result True if a home directory is set, false otherwise. 318bool home_directory(SmallVectorImpl<char> &result); 319 320/// @brief Has root name? 321/// 322/// root_name != "" 323/// 324/// @param path Input path. 325/// @result True if the path has a root name, false otherwise. 326bool has_root_name(const Twine &path); 327 328/// @brief Has root directory? 329/// 330/// root_directory != "" 331/// 332/// @param path Input path. 333/// @result True if the path has a root directory, false otherwise. 334bool has_root_directory(const Twine &path); 335 336/// @brief Has root path? 337/// 338/// root_path != "" 339/// 340/// @param path Input path. 341/// @result True if the path has a root path, false otherwise. 342bool has_root_path(const Twine &path); 343 344/// @brief Has relative path? 345/// 346/// relative_path != "" 347/// 348/// @param path Input path. 349/// @result True if the path has a relative path, false otherwise. 350bool has_relative_path(const Twine &path); 351 352/// @brief Has parent path? 353/// 354/// parent_path != "" 355/// 356/// @param path Input path. 357/// @result True if the path has a parent path, false otherwise. 358bool has_parent_path(const Twine &path); 359 360/// @brief Has filename? 361/// 362/// filename != "" 363/// 364/// @param path Input path. 365/// @result True if the path has a filename, false otherwise. 366bool has_filename(const Twine &path); 367 368/// @brief Has stem? 369/// 370/// stem != "" 371/// 372/// @param path Input path. 373/// @result True if the path has a stem, false otherwise. 374bool has_stem(const Twine &path); 375 376/// @brief Has extension? 377/// 378/// extension != "" 379/// 380/// @param path Input path. 381/// @result True if the path has a extension, false otherwise. 382bool has_extension(const Twine &path); 383 384/// @brief Is path absolute? 385/// 386/// @param path Input path. 387/// @result True if the path is absolute, false if it is not. 388bool is_absolute(const Twine &path); 389 390/// @brief Is path relative? 391/// 392/// @param path Input path. 393/// @result True if the path is relative, false if it is not. 394bool is_relative(const Twine &path); 395 396} // end namespace path 397} // end namespace sys 398} // end namespace llvm 399 400#endif 401