1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: filename.tex 3%% Purpose: wxFileName documentation 4%% Author: Vadim Zeitlin 5%% Modified by: 6%% Created: 30.11.01 7%% RCS-ID: $Id: filename.tex 44096 2007-01-05 14:30:39Z VZ $ 8%% Copyright: (c) 2001 Vadim Zeitlin 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxFileName}}\label{wxfilename} 13 14wxFileName encapsulates a file name. This class serves two purposes: first, it 15provides the functions to split the file names into components and to recombine 16these components in the full file name which can then be passed to the OS file 17functions (and \helpref{wxWidgets functions}{filefunctions} wrapping them). 18Second, it includes the functions for working with the files itself. Note that 19to change the file data you should use \helpref{wxFile}{wxfile} class instead. 20wxFileName provides functions for working with the file attributes. 21 22When working with directory names (i.e. without filename and extension) 23make sure not to misuse the file name part of this class with the last 24directory. Instead initialize the wxFileName instance like this: 25 26\begin{verbatim} 27wxFileName dirname( wxT("C:\mydir"), wxEmptyString ); 28MyMethod( dirname.GetPath() ); 29\end{verbatim} 30 31The same can be done using the static method \helpref{wxFileName::DirName}{wxfilenamedirname}: 32 33\begin{verbatim} 34wxFileName dirname = wxFileName::DirName( wxT("C:\mydir") ); 35MyMethod( dirname.GetPath() ); 36\end{verbatim} 37 38Accordingly, methods dealing with directories or directory names 39like \helpref{IsDirReadable}{wxfilenameisdirreadable} use 40\helpref{GetPath}{wxfilenamegetpath} whereas methods dealing 41with file names like \helpref{IsFileReadable}{wxfilenameisfilereadable} 42use \helpref{GetFullPath}{wxfilenamegetfullpath}. 43 44If it is not known wether a string contains a directory name or 45a complete file name (such as when interpreting user input) you need to use 46the static function \helpref{wxFileName::DirExists}{wxfilenamedirexists} 47(or its identical variants \helpref{wxDir::Exists}{wxdirexists} and 48\helpref{wxDirExists}{functionwxdirexists}) and construct the wxFileName 49instance accordingly. This will only work if the directory actually exists, 50of course: 51 52\begin{verbatim} 53wxString user_input; 54// get input from user 55 56wxFileName fname; 57if (wxDirExists(user_input)) 58 fname.AssignDir( user_input ); 59else 60 fname.Assign( user_input ); 61\end{verbatim} 62 63\wxheading{Derived from} 64 65No base class 66 67\wxheading{Include files} 68 69<wx/filename.h> 70 71\wxheading{Data structures} 72 73Many wxFileName methods accept the path format argument which is by\rtfsp 74{\tt wxPATH\_NATIVE} by default meaning to use the path format native for the 75current platform. 76 77The path format affects the operation of wxFileName functions in several ways: 78first and foremost, it defines the path separator character to use, but it also 79affects other things such as whether the path has the drive part or not. 80 81\begin{verbatim} 82enum wxPathFormat 83{ 84 wxPATH_NATIVE = 0, // the path format for the current platform 85 wxPATH_UNIX, 86 wxPATH_BEOS = wxPATH_UNIX, 87 wxPATH_MAC, 88 wxPATH_DOS, 89 wxPATH_WIN = wxPATH_DOS, 90 wxPATH_OS2 = wxPATH_DOS, 91 wxPATH_VMS, 92 93 wxPATH_MAX // Not a valid value for specifying path format 94} 95\end{verbatim} 96 97\latexignore{\rtfignore{\wxheading{Function groups}}} 98 99 100\membersection{File name format}\label{filenameformat} 101 102wxFileName currently supports the file names in the Unix, DOS/Windows, Mac OS 103and VMS formats. Although these formats are quite different, wxFileName tries 104to treat them all in the same generic way. It supposes that all file names 105consist of the following parts: the volume (also known as drive under Windows 106or device under VMS), the path which is a sequence of directory names separated 107by the \helpref{path separators}{wxfilenamegetpathseparators} and the full 108filename itself which, in turn, is composed from the base file name and the 109extension. All of the individual components of the file name may be empty and, 110for example, the volume name is always empty under Unix, but if they are all 111empty simultaneously, the filename object is considered to be in an invalid 112state and \helpref{IsOk}{wxfilenameisok} returns {\tt false} for it. 113 114File names can be case-sensitive or not, the function\rtfsp 115\helpref{IsCaseSensitive}{wxfilenameiscasesensitive} allows to determine this. 116 117The rules for determining whether the file name is absolute or relative also 118depend on the file name format and the only portable way to answer this 119question is to use \helpref{IsAbsolute}{wxfilenameisabsolute} or\rtfsp 120\helpref{IsRelative}{wxfilenameisrelative} method. Note that on Windows, "X:" 121refers to the current working directory on drive X. Therefore, a wxFileName 122instance constructed from for example "X:dir/file.ext" treats the portion 123beyond drive separator as being relative to that directory. 124 125To ensure that the filename is absolute, you may use\rtfsp 126\helpref{MakeAbsolute}{wxfilenamemakeabsolute}. There is also an inverse 127function \helpref{MakeRelativeTo}{wxfilenamemakerelativeto} which undoes 128what \helpref{Normalize(wxPATH\_NORM\_DOTS)}{wxfilenamenormalize} does. 129 130Other functions returning information about the file format provided by this 131class are \helpref{GetVolumeSeparator}{wxfilenamegetvolumeseparator},\rtfsp 132\helpref{IsPathSeparator}{wxfilenameispathseparator}. 133 134 135\membersection{File name construction}\label{filenameconstruction} 136 137You can initialize a wxFileName instance using one of the following functions: 138 139\helpref{wxFileName constructors}{wxfilenamewxfilename}\\ 140\helpref{Assign}{wxfilenameassign}\\ 141\helpref{AssignCwd}{wxfilenameassigncwd}\\ 142\helpref{AssignDir}{wxfilenameassigndir}\\ 143\helpref{AssignHomeDir}{wxfilenameassignhomedir}\\ 144\helpref{AssignHomeTempFileName}{wxfilenameassigntempfilename}\\ 145\helpref{DirName}{wxfilenamedirname}\\ 146\helpref{FileName}{wxfilenamefilename}\\ 147\helpref{operator $=$}{wxfilenameoperatorassign} 148 149 150\membersection{File tests}\label{filetests} 151 152Before doing other tests, you should use \helpref{IsOk}{wxfilenameisok} to 153verify that the filename is well defined. If it is,\rtfsp 154\helpref{FileExists}{wxfilenamefileexists} can be used to test whether a file 155with such name exists and \helpref{DirExists}{wxfilenamedirexists} can be used 156to test for directory existence. 157 158File names should be compared using \helpref{SameAs}{wxfilenamesameas} method 159or \helpref{operator $==$}{wxfilenameoperatorequal}. 160 161For testing basic access modes, you can use: 162 163\helpref{IsDirWritable}{wxfilenameisdirwritable}\\ 164\helpref{IsDirReadable}{wxfilenameisdirreadable}\\ 165\helpref{IsFileWritable}{wxfilenameisfilewritable}\\ 166\helpref{IsFileReadable}{wxfilenameisfilereadable}\\ 167\helpref{IsFileExecutable}{wxfilenameisfileexecutable} 168 169 170\membersection{File name components}\label{filenamecomponents} 171 172These functions allow to examine and modify the individual directories of the 173path: 174 175\helpref{AppendDir}{wxfilenameappenddir}\\ 176\helpref{InsertDir}{wxfilenameinsertdir}\\ 177\helpref{GetDirCount}{wxfilenamegetdircount} 178\helpref{PrependDir}{wxfilenameprependdir}\\ 179\helpref{RemoveDir}{wxfilenameremovedir}\\ 180\helpref{RemoveLastDir}{wxfilenameremovelastdir} 181 182To change the components of the file name individually you can use the 183following functions: 184 185\helpref{GetExt}{wxfilenamegetext}\\ 186\helpref{GetName}{wxfilenamegetname}\\ 187\helpref{GetVolume}{wxfilenamegetvolume}\\ 188\helpref{HasExt}{wxfilenamehasext}\\ 189\helpref{HasName}{wxfilenamehasname}\\ 190\helpref{HasVolume}{wxfilenamehasvolume}\\ 191\helpref{SetExt}{wxfilenamesetext}\\ 192\helpref{ClearExt}{wxfilenameclearext}\\ 193\helpref{SetEmptyExt}{wxfilenamesetemptyext}\\ 194\helpref{SetName}{wxfilenamesetname}\\ 195\helpref{SetVolume}{wxfilenamesetvolume}\\ 196 197 198\membersection{Operations}\label{filenameoperations} 199 200These methods allow to work with the file creation, access and modification 201times. Note that not all filesystems under all platforms implement these times 202in the same way. For example, the access time under Windows has a resolution of 203one day (so it is really the access date and not time). The access time may be 204updated when the file is executed or not depending on the platform. 205 206\helpref{GetModificationTime}{wxfilenamegetmodificationtime}\\ 207\helpref{GetTimes}{wxfilenamegettimes}\\ 208\helpref{SetTimes}{wxfilenamesettimes}\\ 209\helpref{Touch}{wxfilenametouch} 210 211Other file system operations functions are: 212 213\helpref{Mkdir}{wxfilenamemkdir}\\ 214\helpref{Rmdir}{wxfilenamermdir} 215 216\latexignore{\rtfignore{\wxheading{Members}}} 217 218 219\membersection{wxFileName::wxFileName}\label{wxfilenamewxfilename} 220 221\func{}{wxFileName}{\void} 222 223Default constructor. 224 225\func{}{wxFileName}{\param{const wxFileName\& }{filename}} 226 227Copy constructor. 228 229\func{}{wxFileName}{\param{const wxString\& }{fullpath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 230 231Constructor taking a full filename. If it terminates with a '/', a directory path 232is constructed (the name will be empty), otherwise a file name and 233extension are extracted from it. 234 235\func{}{wxFileName}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 236 237Constructor from a directory name and a file name. 238 239\func{}{wxFileName}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 240 241Constructor from a directory name, base file name and extension. 242 243\func{}{wxFileName}{\param{const wxString\& }{volume}, \param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 244 245Constructor from a volume name, a directory name, base file name and extension. 246 247 248\membersection{wxFileName::AppendDir}\label{wxfilenameappenddir} 249 250\func{void}{AppendDir}{\param{const wxString\& }{dir}} 251 252Appends a directory component to the path. This component should contain a 253single directory name level, i.e. not contain any path or volume separators nor 254should it be empty, otherwise the function does nothing (and generates an 255assert failure in debug build). 256 257 258\membersection{wxFileName::Assign}\label{wxfilenameassign} 259 260\func{void}{Assign}{\param{const wxFileName\& }{filepath}} 261 262\func{void}{Assign}{\param{const wxString\& }{fullpath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 263 264\func{void}{Assign}{\param{const wxString\& }{volume}, \param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{bool }{hasExt}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 265 266\func{void}{Assign}{\param{const wxString\& }{volume}, \param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 267 268\func{void}{Assign}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 269 270\func{void}{Assign}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{const wxString\& }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 271 272Creates the file name from various combinations of data. 273 274 275\membersection{wxFileName::AssignCwd}\label{wxfilenameassigncwd} 276 277\func{static void}{AssignCwd}{\param{const wxString\& }{volume = wxEmptyString}} 278 279Makes this object refer to the current working directory on the specified 280volume (or current volume if {\it volume} is empty). 281 282\wxheading{See also} 283 284\helpref{GetCwd}{wxfilenamegetcwd} 285 286 287\membersection{wxFileName::AssignDir}\label{wxfilenameassigndir} 288 289\func{void}{AssignDir}{\param{const wxString\& }{dir}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 290 291Sets this file name object to the given directory name. The name and extension 292will be empty. 293 294 295\membersection{wxFileName::AssignHomeDir}\label{wxfilenameassignhomedir} 296 297\func{void}{AssignHomeDir}{\void} 298 299Sets this file name object to the home directory. 300 301 302\membersection{wxFileName::AssignTempFileName}\label{wxfilenameassigntempfilename} 303 304\func{void}{AssignTempFileName}{\param{const wxString\& }{prefix}, \param{wxFile *}{fileTemp = {\tt NULL}}} 305 306The function calls \helpref{CreateTempFileName}{wxfilenamecreatetempfilename} to 307create a temporary file and sets this object to the name of the file. If a 308temporary file couldn't be created, the object is put into the\rtfsp 309\helpref{invalid}{wxfilenameisok} state. 310 311 312\membersection{wxFileName::Clear}\label{wxfilenameclear} 313 314\func{void}{Clear}{\void} 315 316Reset all components to default, uninitialized state. 317 318 319\membersection{wxFileName::ClearExt}\label{wxfilenameclearext} 320 321\func{void}{SetClearExt}{\void} 322 323Removes the extension from the file name resulting in a 324file name with no trailing dot. 325 326\wxheading{See also} 327 328\helpref{SetExt}{wxfilenamesetext} 329\helpref{SetEmptyExt}{wxfilenamesetemptyext} 330 331\membersection{wxFileName::CreateTempFileName}\label{wxfilenamecreatetempfilename} 332 333\func{static wxString}{CreateTempFileName}{\param{const wxString\& }{prefix}, \param{wxFile *}{fileTemp = {\tt NULL}}} 334 335Returns a temporary file name starting with the given {\it prefix}. If 336the {\it prefix} is an absolute path, the temporary file is created in this 337directory, otherwise it is created in the default system directory for the 338temporary files or in the current directory. 339 340If the function succeeds, the temporary file is actually created. If\rtfsp 341{\it fileTemp} is not {\tt NULL}, this file will be opened using the name of 342the temporary file. When possible, this is done in an atomic way ensuring that 343no race condition occurs between the temporary file name generation and opening 344it which could often lead to security compromise on the multiuser systems. 345If {\it fileTemp} is {\tt NULL}, the file is only created, but not opened. 346 347Under Unix, the temporary file will have read and write permissions for the 348owner only to minimize the security problems. 349 350\wxheading{Parameters} 351 352\docparam{prefix}{Prefix to use for the temporary file name construction} 353 354\docparam{fileTemp}{The file to open or {\tt NULL} to just get the name} 355 356\wxheading{Return value} 357 358The full temporary file name or an empty string on error. 359 360 361\membersection{wxFileName::DirExists}\label{wxfilenamedirexists} 362 363\constfunc{bool}{DirExists}{\void} 364 365\func{static bool}{DirExists}{\param{const wxString\& }{dir}} 366 367Returns {\tt true} if the directory with this name exists. 368 369 370\membersection{wxFileName::DirName}\label{wxfilenamedirname} 371 372\func{static wxFileName}{DirName}{\param{const wxString\& }{dir}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 373 374Returns the object corresponding to the directory with the given name. 375The {\it dir} parameter may have trailing path separator or not. 376 377 378 379\membersection{wxFileName::FileExists}\label{wxfilenamefileexists} 380 381\constfunc{bool}{FileExists}{\void} 382 383\func{static bool}{FileExists}{\param{const wxString\& }{file}} 384 385Returns {\tt true} if the file with this name exists. 386 387\wxheading{See also} 388 389\helpref{DirExists}{wxfilenamedirexists} 390 391 392 393\membersection{wxFileName::FileName}\label{wxfilenamefilename} 394 395\func{static wxFileName}{FileName}{\param{const wxString\& }{file}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 396 397Returns the file name object corresponding to the given {\it file}. This 398function exists mainly for symmetry with \helpref{DirName}{wxfilenamedirname}. 399 400 401 402\membersection{wxFileName::GetCwd}\label{wxfilenamegetcwd} 403 404\func{static wxString}{GetCwd}{\param{const wxString\& }{volume = ""}} 405 406Retrieves the value of the current working directory on the specified volume. If 407the volume is empty, the program's current working directory is returned for the 408current volume. 409 410\wxheading{Return value} 411 412The string containing the current working directory or an empty string on 413error. 414 415\wxheading{See also} 416 417\helpref{AssignCwd}{wxfilenameassigncwd} 418 419 420\membersection{wxFileName::GetDirCount}\label{wxfilenamegetdircount} 421 422\constfunc{size\_t}{GetDirCount}{\void} 423 424Returns the number of directories in the file name. 425 426 427\membersection{wxFileName::GetDirs}\label{wxfilenamegetdirs} 428 429\constfunc{const wxArrayString\&}{GetDirs}{\void} 430 431Returns the directories in string array form. 432 433 434\membersection{wxFileName::GetExt}\label{wxfilenamegetext} 435 436\constfunc{wxString}{GetExt}{\void} 437 438Returns the file name extension. 439 440 441\membersection{wxFileName::GetForbiddenChars}\label{wxfilenamegetforbiddenchars} 442 443\func{static wxString}{GetForbiddenChars}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} 444 445Returns the characters that can't be used in filenames and directory names for the specified format. 446 447 448\membersection{wxFileName::GetFormat}\label{wxfilenamegetformat} 449 450\func{static wxPathFormat}{GetFormat}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} 451 452Returns the canonical path format for this platform. 453 454 455\membersection{wxFileName::GetFullName}\label{wxfilenamegetfullname} 456 457\constfunc{wxString}{GetFullName}{\void} 458 459Returns the full name (including extension but excluding directories). 460 461 462\membersection{wxFileName::GetFullPath}\label{wxfilenamegetfullpath} 463 464\constfunc{wxString}{GetFullPath}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} 465 466Returns the full path with name and extension. 467 468 469\membersection{wxFileName::GetHomeDir}\label{wxfilenamegethomedir} 470 471\func{static wxString}{GetHomeDir}{\void} 472 473Returns the home directory. 474 475 476\membersection{wxFileName::GetLongPath}\label{wxfilenamegetlongpath} 477 478\constfunc{wxString}{GetLongPath}{\void} 479 480Return the long form of the path (returns identity on non-Windows platforms) 481 482 483\membersection{wxFileName::GetModificationTime}\label{wxfilenamegetmodificationtime} 484 485\constfunc{wxDateTime}{GetModificationTime}{\void} 486 487Returns the last time the file was last modified. 488 489 490\membersection{wxFileName::GetName}\label{wxfilenamegetname} 491 492\constfunc{wxString}{GetName}{\void} 493 494Returns the name part of the filename (without extension). 495 496\wxheading{See also} 497 498\helpref{GetFullName}{wxfilenamegetfullname} 499 500 501 502\membersection{wxFileName::GetPath}\label{wxfilenamegetpath} 503 504\constfunc{wxString}{GetPath}{\param{int }{flags = {\tt wxPATH\_GET\_VOLUME}}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 505 506Returns the path part of the filename (without the name or extension). The 507possible flags values are: 508 509\twocolwidtha{5cm} 510\begin{twocollist}\itemsep=0pt 511\twocolitem{{\bf wxPATH\_GET\_VOLUME}}{Return the path with the volume (does 512nothing for the filename formats without volumes), otherwise the path without 513volume part is returned.} 514\twocolitem{{\bf wxPATH\_GET\_SEPARATOR}}{Return the path with the trailing 515separator, if this flag is not given there will be no separator at the end of 516the path.} 517\end{twocollist} 518 519 520\membersection{wxFileName::GetPathSeparator}\label{wxfilenamegetpathseparator} 521 522\func{static wxChar}{GetPathSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} 523 524Returns the usually used path separator for this format. For all formats but 525{\tt wxPATH\_DOS} there is only one path separator anyhow, but for DOS there 526are two of them and the native one, i.e. the backslash is returned by this 527method. 528 529\wxheading{See also} 530 531\helpref{GetPathSeparators}{wxfilenamegetpathseparators} 532 533 534\membersection{wxFileName::GetPathSeparators}\label{wxfilenamegetpathseparators} 535 536\func{static wxString}{GetPathSeparators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} 537 538Returns the string containing all the path separators for this format. For all 539formats but {\tt wxPATH\_DOS} this string contains only one character but for 540DOS and Windows both {\tt '/'} and {\tt '\textbackslash'} may be used as 541separators. 542 543\wxheading{See also} 544 545\helpref{GetPathSeparator}{wxfilenamegetpathseparator} 546 547 548\membersection{wxFileName::GetPathTerminators}\label{wxfilenamegetpathterminators} 549 550\func{static wxString}{GetPathTerminators}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} 551 552Returns the string of characters which may terminate the path part. This is the 553same as \helpref{GetPathSeparators}{wxfilenamegetpathseparators} except for VMS 554path format where $]$ is used at the end of the path part. 555 556 557\membersection{wxFileName::GetPathWithSep}\label{wxfilenamegetpathwithsep} 558 559\constfunc{wxString}{GetPathWithSep}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} 560 561Returns the path with the trailing separator, useful for appending the name to 562the given path. 563 564This is the same as calling \helpref{GetPath}{wxfilenamegetpath} 565\texttt{(wxPATH\_GET\_VOLUME | wxPATH\_GET\_SEPARATOR, format)}. 566 567 568\membersection{wxFileName::GetShortPath}\label{wxfilenamegetshortpath} 569 570\constfunc{wxString}{GetShortPath}{\void} 571 572Return the short form of the path (returns identity on non-Windows platforms). 573 574 575\membersection{wxFileName::GetSize}\label{wxfilenamegetsize} 576 577\constfunc{wxULongLong}{GetSize}{\void} 578 579\func{static wxULongLong}{GetSize}{\param{const wxString\& }{filename}} 580 581Returns the size of this file (first form) or the size of the given file (second form). 582If the file does not exist or its size could not be read (because e.g. the file is locked 583by another process) the returned value is {\tt wxInvalidSize}. 584 585 586\membersection{wxFileName::GetHumanReadableSize}\label{wxfilenamegethumanreadablesize} 587 588\constfunc{wxString}{GetHumanReadableSize}{\param{const wxString\& }{failmsg = "Not available"}, \param{int }{precision = 1}} 589 590\func{static wxString}{GetHumanReadableSize}{\param{const wxULongLong\& }{bytes}, \param{const wxString\& }{nullsize = "Not available"}, \param{int }{precision = 1}} 591 592Returns the size of this file (first form) or the given number of bytes (second form) 593in a human-readable form. 594 595If the size could not be retrieved the {\tt failmsg} string is returned (first form). 596If {\tt bytes} is {\tt wxInvalidSize} or zero, then {\tt nullsize} is returned (second form). 597 598In case of success, the returned string is a floating-point number with {\tt precision} decimal digits 599followed by the size unit (B, kB, MB, GB, TB: respectively bytes, kilobytes, megabytes, gigabytes, terabytes). 600 601 602\membersection{wxFileName::GetTempDir}\label{wxfilenamegettempdir} 603 604\func{static wxString}{GetTempDir}{\void} 605 606Returns the directory used for temporary files. 607 608 609\membersection{wxFileName::GetTimes}\label{wxfilenamegettimes} 610 611\constfunc{bool}{GetTimes}{\param{wxDateTime* }{dtAccess}, \param{wxDateTime* }{dtMod}, \param{wxDateTime* }{dtCreate}} 612 613Returns the last access, last modification and creation times. The last access 614time is updated whenever the file is read or written (or executed in the case 615of Windows), last modification time is only changed when the file is written 616to. Finally, the creation time is indeed the time when the file was created 617under Windows and the inode change time under Unix (as it is impossible to 618retrieve the real file creation time there anyhow) which can also be changed 619by many operations after the file creation. 620 621If no filename or extension is specified in this instance of wxFileName 622(and therefore \helpref{IsDir}{wxfilenameisdir} returns {\tt true}) then 623this function will return the directory times of the path specified by 624\helpref{GetPath}{wxfilenamegetpath}, otherwise the file times of the 625file specified by \helpref{GetFullPath}{wxfilenamegetfullpath}. 626 627Any of the pointers may be {\tt NULL} if the corresponding time is not 628needed. 629 630\wxheading{Return value} 631 632{\tt true} on success, {\tt false} if we failed to retrieve the times. 633 634 635\membersection{wxFileName::GetVolume}\label{wxfilenamegetvolume} 636 637\constfunc{wxString}{GetVolume}{\void} 638 639Returns the string containing the volume for this file name, empty if it 640doesn't have one or if the file system doesn't support volumes at all (for 641example, Unix). 642 643 644\membersection{wxFileName::GetVolumeSeparator}\label{wxfilenamegetvolumeseparator} 645 646\func{static wxString}{GetVolumeSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} 647 648Returns the string separating the volume from the path for this format. 649 650 651\membersection{wxFileName::HasExt}\label{wxfilenamehasext} 652 653\constfunc{bool}{HasExt}{\void} 654 655Returns {\tt true} if an extension is present. 656 657 658\membersection{wxFileName::HasName}\label{wxfilenamehasname} 659 660\constfunc{bool}{HasName}{\void} 661 662Returns {\tt true} if a name is present. 663 664 665\membersection{wxFileName::HasVolume}\label{wxfilenamehasvolume} 666 667\constfunc{bool}{HasVolume}{\void} 668 669Returns {\tt true} if a volume specifier is present. 670 671 672\membersection{wxFileName::InsertDir}\label{wxfilenameinsertdir} 673 674\func{void}{InsertDir}{\param{size\_t }{before}, \param{const wxString\& }{dir}} 675 676Inserts a directory component before the zero-based position in the directory 677list. Please see \helpref{AppendDir}{wxfilenameappenddir} for important notes. 678 679 680\membersection{wxFileName::IsAbsolute}\label{wxfilenameisabsolute} 681 682\func{bool}{IsAbsolute}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} 683 684Returns {\tt true} if this filename is absolute. 685 686 687\membersection{wxFileName::IsCaseSensitive}\label{wxfilenameiscasesensitive} 688 689\func{static bool}{IsCaseSensitive}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} 690 691Returns {\tt true} if the file names of this type are case-sensitive. 692 693 694\membersection{wxFileName::IsDirReadable}\label{wxfilenameisdirreadable} 695 696\constfunc{bool}{IsDirReadable}{\void} 697 698\func{static bool}{IsDirReadable}{\param{const wxString\& }{dir}} 699 700Returns {\tt true} if the directory component of this instance (or given \arg{dir}) 701is an existing directory and this process has read permissions on it. 702Read permissions on a directory mean that you can list the directory contents but it 703doesn't imply that you have read permissions on the files contained. 704 705 706\membersection{wxFileName::IsDirWritable}\label{wxfilenameisdirwritable} 707 708\constfunc{bool}{IsDirWritable}{\void} 709 710\func{static bool}{IsDirWritable}{\param{const wxString\& }{dir}} 711 712Returns {\tt true} if the directory component of this instance (or given \arg{dir}) 713is an existing directory and this process has write permissions on it. 714Write permissions on a directory mean that you can create new files in the directory. 715 716 717\membersection{wxFileName::IsFileExecutable}\label{wxfilenameisfileexecutable} 718 719\constfunc{bool}{IsFileExecutable}{\void} 720 721\func{static bool}{IsFileExecutable}{\param{const wxString\& }{file}} 722 723Returns {\tt true} if a file with this name exists and if this process has execute permissions on it. 724 725 726\membersection{wxFileName::IsFileReadable}\label{wxfilenameisfilereadable} 727 728\constfunc{bool}{IsFileReadable}{\void} 729 730\func{static bool}{IsFileReadable}{\param{const wxString\& }{file}} 731 732Returns {\tt true} if a file with this name exists and if this process has read permissions on it. 733 734 735\membersection{wxFileName::IsFileWritable}\label{wxfilenameisfilewritable} 736 737\constfunc{bool}{IsFileWritable}{\void} 738 739\func{static bool}{IsFileWritable}{\param{const wxString\& }{file}} 740 741Returns {\tt true} if a file with this name exists and if this process has write permissions on it. 742 743 744\membersection{wxFileName::IsOk}\label{wxfilenameisok} 745 746\constfunc{bool}{IsOk}{\void} 747 748Returns {\tt true} if the filename is valid, {\tt false} if it is not 749initialized yet. The assignment functions and 750\helpref{Clear}{wxfilenameclear} may reset the object to the uninitialized, 751invalid state (the former only do it on failure). 752 753 754\membersection{wxFileName::IsPathSeparator}\label{wxfilenameispathseparator} 755 756\func{static bool}{IsPathSeparator}{\param{wxChar }{ch}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 757 758Returns {\tt true} if the char is a path separator for this format. 759 760 761\membersection{wxFileName::IsRelative}\label{wxfilenameisrelative} 762 763\func{bool}{IsRelative}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} 764 765Returns {\tt true} if this filename is not absolute. 766 767 768\membersection{wxFileName::IsDir}\label{wxfilenameisdir} 769 770\constfunc{bool}{IsDir}{\void} 771 772Returns {\tt true} if this object represents a directory, {\tt false} otherwise 773(i.e. if it is a file). Note that this method doesn't test whether the 774directory or file really exists, you should use 775\helpref{DirExists}{wxfilenamedirexists} or 776\helpref{FileExists}{wxfilenamefileexists} for this. 777 778\membersection{wxFileName::MacFindDefaultTypeAndCreator}\label{wxfilenamemacfinddefaulttypeandcreator} 779 780\func{static bool}{MacFindDefaultTypeAndCreator}{\param{const wxString\& }{ext}, \param{wxUint32* }{type}, \param{wxUint32* }{creator}} 781 782On Mac OS, gets the common type and creator for the given extension. 783 784\membersection{wxFileName::MacRegisterDefaultTypeAndCreator}\label{wxfilenamemacregisterdefaulttypeandcreator} 785 786\func{static void}{MacRegisterDefaultTypeAndCreator}{\param{const wxString\& }{ext}, \param{wxUint32 }{type}, \param{wxUint32 }{creator}} 787 788On Mac OS, registers application defined extensions and their default type and creator. 789 790\membersection{wxFileName::MacSetDefaultTypeAndCreator}\label{wxfilenamemacsetdefaulttypeandcreator} 791 792\func{bool}{MacSetDefaultTypeAndCreator}{\void} 793 794On Mac OS, looks up the appropriate type and creator from the registration and then sets it. 795 796\membersection{wxFileName::MakeAbsolute}\label{wxfilenamemakeabsolute} 797 798\func{bool}{MakeAbsolute}{\param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 799 800Make the file name absolute. This is a shortcut for 801{\tt \helpref{Normalize}{wxfilenamenormalize}(wxPATH\_NORM\_DOTS | wxPATH\_NORM\_ABSOLUTE | wxPATH\_NORM\_TILDE, cwd, format)}. 802 803\wxheading{See also} 804 805\helpref{MakeRelativeTo}{wxfilenamemakerelativeto}, 806\helpref{Normalize}{wxfilenamenormalize}, 807\helpref{IsAbsolute}{wxfilenameisabsolute} 808 809 810\membersection{wxFileName::MakeRelativeTo}\label{wxfilenamemakerelativeto} 811 812\func{bool}{MakeRelativeTo}{\param{const wxString\& }{pathBase = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 813 814This function tries to put this file name in a form relative to {\it pathBase}. 815In other words, it returns the file name which should be used to access this 816file if the current directory were {\it pathBase}. 817 818\docparam{pathBase}{the directory to use as root, current directory is used by 819default} 820 821\docparam{format}{the file name format, native by default} 822 823\wxheading{Return value} 824 825{\tt true} if the file name has been changed, {\tt false} if we failed to do 826anything with it (currently this only happens if the file name is on a volume 827different from the volume specified by {\it pathBase}). 828 829\wxheading{See also} 830 831\helpref{Normalize}{wxfilenamenormalize} 832 833 834\membersection{wxFileName::Mkdir}\label{wxfilenamemkdir} 835 836\func{bool}{Mkdir}{\param{int }{perm = 0777}, \param{int }{flags = $0$}} 837 838\func{static bool}{Mkdir}{\param{const wxString\& }{dir}, \param{int }{perm = 0777}, \param{int }{flags = $0$}} 839 840\docparam{dir}{the directory to create} 841 842\docparam{parm}{the permissions for the newly created directory} 843 844\docparam{flags}{if the flags contain {\tt wxPATH\_MKDIR\_FULL} flag, 845try to create each directory in the path and also don't return an error 846if the target directory already exists.} 847 848\wxheading{Return value} 849 850Returns {\tt true} if the directory was successfully created, {\tt false} 851otherwise. 852 853 854\membersection{wxFileName::Normalize}\label{wxfilenamenormalize} 855 856\func{bool}{Normalize}{\param{int }{flags = wxPATH\_NORM\_ALL}, \param{const wxString\& }{cwd = wxEmptyString}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 857 858Normalize the path. With the default flags value, the path will be 859made absolute, without any ".." and "." and all environment 860variables will be expanded in it. 861 862\docparam{flags}{The kind of normalization to do with the file name. It can be 863any or-combination of the following constants: 864 865\begin{twocollist} 866\twocolitem{{\bf wxPATH\_NORM\_ENV\_VARS}}{replace env vars with their values} 867\twocolitem{{\bf wxPATH\_NORM\_DOTS}}{squeeze all .. and . when possible; if there are too many .. and thus they cannot be all removed, \false will be returned} 868\twocolitem{{\bf wxPATH\_NORM\_CASE}}{if filesystem is case insensitive, transform to lower case} 869\twocolitem{{\bf wxPATH\_NORM\_ABSOLUTE}}{make the path absolute prepending \arg{cwd}} 870\twocolitem{{\bf wxPATH\_NORM\_LONG}}{make the path the long form} 871\twocolitem{{\bf wxPATH\_NORM\_SHORTCUT}}{resolve if it is a shortcut (Windows only)} 872\twocolitem{{\bf wxPATH\_NORM\_TILDE}}{replace ~ and ~user (Unix only)} 873\twocolitem{{\bf wxPATH\_NORM\_ALL}}{all of previous flags except \texttt{wxPATH\_NORM\_CASE}} 874\end{twocollist} 875}% 876 877\docparam{cwd}{If not empty, this directory will be used instead of current 878working directory in normalization (see wxPATH\_NORM\_ABSOLUTE).} 879 880\docparam{format}{The file name format to use when processing the paths, native by default.} 881 882 883\wxheading{Return value} 884 885\true if normalization was successfully or \false otherwise. 886 887 888\membersection{wxFileName::PrependDir}\label{wxfilenameprependdir} 889 890\func{void}{PrependDir}{\param{const wxString\& }{dir}} 891 892Prepends a directory to the file path. Please see 893\helpref{AppendDir}{wxfilenameappenddir} for important notes. 894 895 896 897\membersection{wxFileName::RemoveDir}\label{wxfilenameremovedir} 898 899\func{void}{RemoveDir}{\param{size\_t }{pos}} 900 901Removes the specified directory component from the path. 902 903\wxheading{See also} 904 905\helpref{GetDirCount}{wxfilenamegetdircount} 906 907 908\membersection{wxFileName::RemoveLastDir}\label{wxfilenameremovelastdir} 909 910\func{void}{RemoveLastDir}{\void} 911 912Removes last directory component from the path. 913 914 915\membersection{wxFileName::Rmdir}\label{wxfilenamermdir} 916 917\func{bool}{Rmdir}{\void} 918 919\func{static bool}{Rmdir}{\param{const wxString\& }{dir}} 920 921Deletes the specified directory from the file system. 922 923 924\membersection{wxFileName::SameAs}\label{wxfilenamesameas} 925 926\constfunc{bool}{SameAs}{\param{const wxFileName\& }{filepath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 927 928Compares the filename using the rules of this platform. 929 930 931\membersection{wxFileName::SetCwd}\label{wxfilenamesetcwd} 932 933\func{bool}{SetCwd}{\void} 934 935\func{static bool}{SetCwd}{\param{const wxString\& }{cwd}} 936 937Changes the current working directory. 938 939 940\membersection{wxFileName::SetExt}\label{wxfilenamesetext} 941 942\func{void}{SetExt}{\param{const wxString\& }{ext}} 943 944Sets the extension of the file name. Setting an empty string 945as the extension will remove the extension resulting in a file 946name without a trailing dot, unlike a call to 947\helpref{SetEmptyExt}{wxfilenamesetemptyext}. 948 949\wxheading{See also} 950 951\helpref{SetEmptyExt}{wxfilenamesetemptyext} 952\helpref{ClearExt}{wxfilenameclearext} 953 954\membersection{wxFileName::SetEmptyExt}\label{wxfilenamesetemptyext} 955 956\func{void}{SetEmptyExt}{\void} 957 958Sets the extension of the file name to be an empty extension. 959This is different from having no extension at all as the file 960name will have a trailing dot after a call to this method. 961 962\wxheading{See also} 963 964\helpref{SetExt}{wxfilenamesetext} 965\helpref{ClearExt}{wxfilenameclearext} 966 967\membersection{wxFileName::SetFullName}\label{wxfilenamesetfullname} 968 969\func{void}{SetFullName}{\param{const wxString\& }{fullname}} 970 971The full name is the file name and extension (but without the path). 972 973 974\membersection{wxFileName::SetName}\label{wxfilenamesetname} 975 976\func{void}{SetName}{\param{const wxString\& }{name}} 977 978Sets the name part (without extension). 979 980\wxheading{See also} 981 982\helpref{SetFullName}{wxfilenamesetfullname} 983 984 985\membersection{wxFileName::SetTimes}\label{wxfilenamesettimes} 986 987\func{bool}{SetTimes}{\param{const wxDateTime* }{dtAccess}, \param{const wxDateTime* }{dtMod}, \param{const wxDateTime* }{dtCreate}} 988 989Sets the file creation and last access/modification times (any of the pointers may be NULL). 990 991 992\membersection{wxFileName::SetVolume}\label{wxfilenamesetvolume} 993 994\func{void}{SetVolume}{\param{const wxString\& }{volume}} 995 996Sets the volume specifier. 997 998 999\membersection{wxFileName::SplitPath}\label{wxfilenamesplitpath} 1000 1001\func{static void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{volume}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{bool }{*hasExt = \texttt{NULL}}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 1002 1003\func{static void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{volume}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 1004 1005\func{static void}{SplitPath}{\param{const wxString\& }{fullpath}, \param{wxString* }{path}, \param{wxString* }{name}, \param{wxString* }{ext}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 1006 1007This function splits a full file name into components: the volume (with the 1008first version) path (including the volume in the second version), the base name 1009and the extension. Any of the output parameters ({\it volume}, {\it path}, 1010{\it name} or {\it ext}) may be {\tt NULL} if you are not interested in the 1011value of a particular component. Also, {\it fullpath} may be empty on entry. 1012 1013On return, {\it path} contains the file path (without the trailing separator), 1014{\it name} contains the file name and {\it ext} contains the file extension 1015without leading dot. All three of them may be empty if the corresponding 1016component is. The old contents of the strings pointed to by these parameters 1017will be overwritten in any case (if the pointers are not {\tt NULL}). 1018 1019Note that for a filename ``foo.'' the extension is present, as indicated by the 1020trailing dot, but empty. If you need to cope with such cases, you should use 1021\arg{hasExt} instead of relying on testing whether \arg{ext} is empty or not. 1022 1023 1024\membersection{wxFileName::SplitVolume}\label{wxfilenamesplitvolume} 1025 1026\func{static void}{SplitVolume}{\param{const wxString\& }{fullpath}, \param{wxString* }{volume}, \param{wxString* }{path}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} 1027 1028Splits the given \arg{fullpath} into the volume part (which may be empty) and 1029the pure path part, not containing any volume. 1030 1031\wxheading{See also} 1032 1033\helpref{SplitPath}{wxfilenamesplitpath} 1034 1035 1036\membersection{wxFileName::Touch}\label{wxfilenametouch} 1037 1038\func{bool}{Touch}{\void} 1039 1040Sets the access and modification times to the current moment. 1041 1042 1043\membersection{wxFileName::operator=}\label{wxfilenameoperatorassign} 1044 1045\func{wxFileName\& operator}{operator=}{\param{const wxFileName\& }{filename}} 1046 1047\func{wxFileName\& operator}{operator=}{\param{const wxString\& }{filename}} 1048 1049Assigns the new value to this filename object. 1050 1051 1052\membersection{wxFileName::operator==}\label{wxfilenameoperatorequal} 1053 1054\constfunc{bool operator}{operator==}{\param{const wxFileName\& }{filename}} 1055 1056\constfunc{bool operator}{operator==}{\param{const wxString\& }{filename}} 1057 1058Returns {\tt true} if the filenames are equal. The string {\it filenames} is 1059interpreted as a path in the native filename format. 1060 1061 1062\membersection{wxFileName::operator!=}\label{wxfilenameoperatornotequal} 1063 1064\constfunc{bool operator}{operator!=}{\param{const wxFileName\& }{filename}} 1065 1066\constfunc{bool operator}{operator!=}{\param{const wxString\& }{filename}} 1067 1068Returns {\tt true} if the filenames are different. The string {\it filenames} 1069is interpreted as a path in the native filename format. 1070 1071