docs/latex/wx/filename.tex

   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$
   8 %% Copyright:   (c) 2001 Vadim Zeitlin
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxFileName}}\label{wxfilename}
  13
  14 wxFileName encapsulates a file name. This class serves two purposes: first, it
  15 provides the functions to split the file names into components and to recombine
  16 these components in the full file name which can then be passed to the OS file
  17 functions (and \helpref{wxWidgets functions}{filefunctions} wrapping them).
  18 Second, it includes the functions for working with the files itself. Note that
  19 to change the file data you should use \helpref{wxFile}{wxfile} class instead.
  20 wxFileName provides functions for working with the file attributes.
  21
  22 When working with directory names (i.e. without filename and extension)
  23 make sure not to misuse the file name part of this class with the last
  24 directory. Instead initialize the wxFileName instance like this:
  25
  26 \begin{verbatim}
  27 wxFileName dirname( wxT("C:\mydir"), wxEmptyString );
  28 MyMethod( dirname.GetPath() );
  29 \end{verbatim}
  30
  31 The same can be done using the static method \helpref{wxFileName::DirName}{wxfilenamedirname}:
  32
  33 \begin{verbatim}
  34 wxFileName dirname = wxFileName::DirName( wxT("C:\mydir") );
  35 MyMethod( dirname.GetPath() );
  36 \end{verbatim}
  37
  38 Accordingly, methods dealing with directories or directory names
  39 like \helpref{IsDirReadable}{wxfilenameisdirreadable} use
  40 \helpref{GetPath}{wxfilenamegetpath} whereas methods dealing
  41 with file names like \helpref{IsFileReadable}{wxfilenameisfilereadable}
  42 use \helpref{GetFullPath}{wxfilenamegetfullpath}.
  43
  44 If it is not known wether a string contains a directory name or
  45 a complete file name (such as when interpreting user input) you need to use
  46 the static function \helpref{wxFileName::DirExists}{wxfilenamedirexists}
  47 (or its identical variants \helpref{wxDir::Exists}{wxdirexists} and
  48 \helpref{wxDirExists}{functionwxdirexists}) and construct the wxFileName
  49 instance accordingly. This will only work if the directory actually exists,
  50 of course:
  51
  52 \begin{verbatim}
  53 wxString user_input;
  54 // get input from user
  55
  56 wxFileName fname;
  57 if (wxDirExists(user_input))
  58     fname.AssignDir( user_input );
  59 else
  60     fname.Assign( user_input );
  61 \end{verbatim}
  62
  63 \wxheading{Derived from}
  64
  65 No base class
  66
  67 \wxheading{Include files}
  68
  69 <wx/filename.h>
  70
  71 \wxheading{Data structures}
  72
  73 Many 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
  75 current platform.
  76
  77 The path format affects the operation of wxFileName functions in several ways:
  78 first and foremost, it defines the path separator character to use, but it also
  79 affects other things such as whether the path has the drive part or not.
  80
  81 \begin{verbatim}
  82 enum 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
 102 wxFileName currently supports the file names in the Unix, DOS/Windows, Mac OS
 103 and VMS formats. Although these formats are quite different, wxFileName tries
 104 to treat them all in the same generic way. It supposes that all file names
 105 consist of the following parts: the volume (also known as drive under Windows
 106 or device under VMS), the path which is a sequence of directory names separated
 107 by the \helpref{path separators}{wxfilenamegetpathseparators} and the full
 108 filename itself which, in turn, is composed from the base file name and the
 109 extension. All of the individual components of the file name may be empty and,
 110 for example, the volume name is always empty under Unix, but if they are all
 111 empty simultaneously, the filename object is considered to be in an invalid
 112 state and \helpref{IsOk}{wxfilenameisok} returns {\tt false} for it.
 113
 114 File names can be case-sensitive or not, the function\rtfsp
 115 \helpref{IsCaseSensitive}{wxfilenameiscasesensitive} allows to determine this.
 116
 117 The rules for determining whether the file name is absolute or relative also
 118 depend on the file name format and the only portable way to answer this
 119 question is to use \helpref{IsAbsolute}{wxfilenameisabsolute} or\rtfsp
 120 \helpref{IsRelative}{wxfilenameisrelative} method. Note that on Windows, "X:"
 121 refers to the current working directory on drive X. Therefore, a wxFileName
 122 instance constructed from for example "X:dir/file.ext" treats the portion
 123 beyond drive separator as being relative to that directory.
 124
 125 To ensure that the filename is absolute, you may use\rtfsp
 126 \helpref{MakeAbsolute}{wxfilenamemakeabsolute}. There is also an inverse
 127 function \helpref{MakeRelativeTo}{wxfilenamemakerelativeto} which undoes
 128 what \helpref{Normalize(wxPATH\_NORM\_DOTS)}{wxfilenamenormalize} does.
 129
 130 Other functions returning information about the file format provided by this
 131 class are \helpref{GetVolumeSeparator}{wxfilenamegetvolumeseparator},\rtfsp
 132 \helpref{IsPathSeparator}{wxfilenameispathseparator}.
 133
 134
 135 \membersection{File name construction}\label{filenameconstruction}
 136
 137 You 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}{wxfilenameassigndirname}\\
 146 \helpref{FileName}{wxfilenameassignfilename}\\
 147 \helpref{operator $=$}{wxfilenameoperatorassign}
 148
 149
 150 \membersection{File tests}\label{filetests}
 151
 152 Before doing other tests, you should use \helpref{IsOk}{wxfilenameisok} to
 153 verify that the filename is well defined. If it is,\rtfsp
 154 \helpref{FileExists}{wxfilenamefileexists} can be used to test whether a file
 155 with such name exists and \helpref{DirExists}{wxfilenamedirexists} can be used
 156 to test for directory existence.
 157
 158 File names should be compared using \helpref{SameAs}{wxfilenamesameas} method
 159 or \helpref{operator $==$}{wxfilenameoperatorequal}.
 160
 161 For 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
 172 These functions allow to examine and modify the individual directories of the
 173 path:
 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
 182 To change the components of the file name individually you can use the
 183 following 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
 200 These methods allow to work with the file creation, access and modification
 201 times. Note that not all filesystems under all platforms implement these times
 202 in the same way. For example, the access time under Windows has a resolution of
 203 one day (so it is really the access date and not time). The access time may be
 204 updated 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
 211 Other 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
 223 Default constructor.
 224
 225 \func{}{wxFileName}{\param{const wxFileName\& }{filename}}
 226
 227 Copy constructor.
 228
 229 \func{}{wxFileName}{\param{const wxString\& }{fullpath}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 230
 231 Constructor taking a full filename. If it terminates with a '/', a directory path
 232 is constructed (the name will be empty), otherwise a file name and
 233 extension are extracted from it.
 234
 235 \func{}{wxFileName}{\param{const wxString\& }{path}, \param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 236
 237 Constructor 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
 241 Constructor 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
 245 Constructor 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
 252 Appends a directory component to the path. This component should contain a
 253 single directory name level, i.e. not contain any path or volume separators nor
 254 should it be empty, otherwise the function does nothing (and generates an
 255 assert 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
 272 Creates 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
 279 Makes this object refer to the current working directory on the specified
 280 volume (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
 291 Sets this file name object to the given directory name. The name and extension
 292 will be empty.
 293
 294
 295 \membersection{wxFileName::AssignHomeDir}\label{wxfilenameassignhomedir}
 296
 297 \func{void}{AssignHomeDir}{\void}
 298
 299 Sets 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
 306 The function calls \helpref{CreateTempFileName}{wxfilenamecreatetempfilename} to
 307 create a temporary file and sets this object to the name of the file. If a
 308 temporary 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
 316 Reset all components to default, uninitialized state.
 317
 318
 319 \membersection{wxFileName::ClearExt}\label{wxfilenameclearext}
 320
 321 \func{void}{SetClearExt}{\void}
 322
 323 Removes the extension from the file name resulting in a
 324 file 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
 335 Returns a temporary file name starting with the given {\it prefix}. If
 336 the {\it prefix} is an absolute path, the temporary file is created in this
 337 directory, otherwise it is created in the default system directory for the
 338 temporary files or in the current directory.
 339
 340 If 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
 342 the temporary file. When possible, this is done in an atomic way ensuring that
 343 no race condition occurs between the temporary file name generation and opening
 344 it which could often lead to security compromise on the multiuser systems.
 345 If {\it fileTemp} is {\tt NULL}, the file is only created, but not opened.
 346
 347 Under Unix, the temporary file will have read and write permissions for the
 348 owner 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
 358 The 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
 367 Returns {\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
 374 Returns the object corresponding to the directory with the given name.
 375 The {\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
 385 Returns {\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
 397 Returns the file name object corresponding to the given {\it file}. This
 398 function 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
 406 Retrieves the value of the current working directory on the specified volume. If
 407 the volume is empty, the program's current working directory is returned for the
 408 current volume.
 409
 410 \wxheading{Return value}
 411
 412 The string containing the current working directory or an empty string on
 413 error.
 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
 424 Returns the number of directories in the file name.
 425
 426
 427 \membersection{wxFileName::GetDirs}\label{wxfilenamegetdirs}
 428
 429 \constfunc{const wxArrayString\&}{GetDirs}{\void}
 430
 431 Returns the directories in string array form.
 432
 433
 434 \membersection{wxFileName::GetExt}\label{wxfilenamegetext}
 435
 436 \constfunc{wxString}{GetExt}{\void}
 437
 438 Returns the file name extension.
 439
 440
 441 \membersection{wxFileName::GetForbiddenChars}\label{wxfilenamegetforbiddenchars}
 442
 443 \func{static wxString}{GetForbiddenChars}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 444
 445 Returns 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
 452 Returns the canonical path format for this platform.
 453
 454
 455 \membersection{wxFileName::GetFullName}\label{wxfilenamegetfullname}
 456
 457 \constfunc{wxString}{GetFullName}{\void}
 458
 459 Returns 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
 466 Returns the full path with name and extension.
 467
 468
 469 \membersection{wxFileName::GetHomeDir}\label{wxfilenamegethomedir}
 470
 471 \func{static wxString}{GetHomeDir}{\void}
 472
 473 Returns the home directory.
 474
 475
 476 \membersection{wxFileName::GetLongPath}\label{wxfilenamegetlongpath}
 477
 478 \constfunc{wxString}{GetLongPath}{\void}
 479
 480 Return 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
 487 Returns the last time the file was last modified.
 488
 489
 490 \membersection{wxFileName::GetName}\label{wxfilenamegetname}
 491
 492 \constfunc{wxString}{GetName}{\void}
 493
 494 Returns 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
 506 Returns the path part of the filename (without the name or extension). The
 507 possible 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
 512 nothing for the filename formats without volumes), otherwise the path without
 513 volume part is returned.}
 514 \twocolitem{{\bf wxPATH\_GET\_SEPARATOR}}{Return the path with the trailing
 515 separator, if this flag is not given there will be no separator at the end of
 516 the path.}
 517 \end{twocollist}
 518
 519
 520 \membersection{wxFileName::GetPathSeparator}\label{wxfilenamegetpathseparator}
 521
 522 \func{static wxChar}{GetPathSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 523
 524 Returns 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
 526 are two of them and the native one, i.e. the backslash is returned by this
 527 method.
 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
 538 Returns the string containing all the path separators for this format. For all
 539 formats but {\tt wxPATH\_DOS} this string contains only one character but for
 540 DOS and Windows both {\tt '/'} and {\tt '\textbackslash'} may be used as
 541 separators.
 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
 552 Returns the string of characters which may terminate the path part. This is the
 553 same as \helpref{GetPathSeparators}{wxfilenamegetpathseparators} except for VMS
 554 path 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
 561 Returns the path with the trailing separator, useful for appending the name to
 562 the given path.
 563
 564 This 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
 572 Return 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
 581 Returns the size of this file (first form) or the size of the given file (second form).
 582 If the file does not exist or its size could not be read (because e.g. the file is locked
 583 by 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
 592 Returns the size of this file (first form) or the given number of bytes (second form)
 593 in a human-readable form.
 594
 595 If the size could not be retrieved the {\tt failmsg} string is returned (first form).
 596 If {\tt bytes} is {\tt wxInvalidSize} or zero, then {\tt nullsize} is returned (second form).
 597
 598 In case of success, the returned string is a floating-point number with {\tt precision} decimal digits
 599 followed 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
 606 Returns 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
 613 Returns the last access, last modification and creation times. The last access
 614 time is updated whenever the file is read or written (or executed in the case
 615 of Windows), last modification time is only changed when the file is written
 616 to. Finally, the creation time is indeed the time when the file was created
 617 under Windows and the inode change time under Unix (as it is impossible to
 618 retrieve the real file creation time there anyhow) which can also be changed
 619 by many operations after the file creation.
 620
 621 If no filename or extension is specified in this instance of wxFileName
 622 (and therefore \helpref{IsDir}{wxfilenameisdir} returns {\tt true}) then
 623 this function will return the directory times of the path specified by
 624 \helpref{GetPath}{wxfilenamegetpath}, otherwise the file times of the
 625 file specified by \helpref{GetFullPath}{wxfilenamegetfullpath}.
 626
 627 Any of the pointers may be {\tt NULL} if the corresponding time is not
 628 needed.
 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
 639 Returns the string containing the volume for this file name, empty if it
 640 doesn't have one or if the file system doesn't support volumes at all (for
 641 example, Unix).
 642
 643
 644 \membersection{wxFileName::GetVolumeSeparator}\label{wxfilenamegetvolumeseparator}
 645
 646 \func{static wxString}{GetVolumeSeparator}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 647
 648 Returns 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
 655 Returns {\tt true} if an extension is present.
 656
 657
 658 \membersection{wxFileName::HasName}\label{wxfilenamehasname}
 659
 660 \constfunc{bool}{HasName}{\void}
 661
 662 Returns {\tt true} if a name is present.
 663
 664
 665 \membersection{wxFileName::HasVolume}\label{wxfilenamehasvolume}
 666
 667 \constfunc{bool}{HasVolume}{\void}
 668
 669 Returns {\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
 676 Inserts a directory component before the zero-based position in the directory
 677 list. 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
 684 Returns {\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
 691 Returns {\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
 700 Returns {\tt true} if the directory component of this instance (or given \arg{dir})
 701 is an existing directory and this process has read permissions on it.
 702 Read permissions on a directory mean that you can list the directory contents but it
 703 doesn'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
 712 Returns {\tt true} if the directory component of this instance (or given \arg{dir})
 713 is an existing directory and this process has write permissions on it.
 714 Write 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
 723 Returns {\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
 732 Returns {\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
 741 Returns {\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
 748 Returns {\tt true} if the filename is valid, {\tt false} if it is not
 749 initialized yet. The assignment functions and
 750 \helpref{Clear}{wxfilenameclear} may reset the object to the uninitialized,
 751 invalid 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
 758 Returns {\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
 765 Returns {\tt true} if this filename is not absolute.
 766
 767
 768 \membersection{wxFileName::IsDir}\label{wxfilenameisdir}
 769
 770 \constfunc{bool}{IsDir}{\void}
 771
 772 Returns {\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
 774 directory 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
 782 On 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
 788 On 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
 794 On 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
 800 Make 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
 814 This function tries to put this file name in a form relative to {\it pathBase}.
 815 In other words, it returns the file name which should be used to access this
 816 file if the current directory were {\it pathBase}.
 817
 818 \docparam{pathBase}{the directory to use as root, current directory is used by
 819 default}
 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
 826 anything with it (currently this only happens if the file name is on a volume
 827 different 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,
 845 try to create each directory in the path and also don't return an error
 846 if the target directory already exists.}
 847
 848 \wxheading{Return value}
 849
 850 Returns {\tt true} if the directory was successfully created, {\tt false}
 851 otherwise.
 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
 858 Normalize the path. With the default flags value, the path will be
 859 made absolute, without any ".." and "." and all environment
 860 variables will be expanded in it.
 861
 862 \docparam{flags}{The kind of normalization to do with the file name. It can be
 863 any 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
 878 working 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
 892 Prepends 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
 901 Removes 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
 912 Removes 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
 921 Deletes 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
 928 Compares 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
 937 Changes the current working directory.
 938
 939
 940 \membersection{wxFileName::SetExt}\label{wxfilenamesetext}
 941
 942 \func{void}{SetExt}{\param{const wxString\& }{ext}}
 943
 944 Sets the extension of the file name. Setting an empty string
 945 as the extension will remove the extension resulting in a file
 946 name 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
 958 Sets the extension of the file name to be an empty extension.
 959 This is different from having no extension at all as the file
 960 name 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
 971 The 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
 978 Sets 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
 989 Sets 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
 996 Sets 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
1007 This function splits a full file name into components: the volume (with the
1008 first version) path (including the volume in the second version), the base name
1009 and 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
1011 value of a particular component. Also, {\it fullpath} may be empty on entry.
1012
1013 On 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
1015 without leading dot. All three of them may be empty if the corresponding
1016 component is. The old contents of the strings pointed to by these parameters
1017 will be overwritten in any case (if the pointers are not {\tt NULL}).
1018
1019 Note that for a filename ``foo.'' the extension is present, as indicated by the
1020 trailing 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
1028 Splits the given \arg{fullpath} into the volume part (which may be empty) and
1029 the 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
1040 Sets 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
1049 Assigns 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
1058 Returns {\tt true} if the filenames are equal. The string {\it filenames} is
1059 interpreted 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
1068 Returns {\tt true} if the filenames are different. The string {\it filenames}
1069 is interpreted as a path in the native filename format.
1070