[Dune] VTKWriter::pwrite()

[Jö Fahlke]

Am Mon,  7. Jun 2010, 16:57:25 +0200 schrieb joe at dune-project.org:
> Especially the path construction of pwrite() neede some light.

The path construction in the pwrite() method is a complicated mess at the
moment.  I have tried to document what happens currently[1]:

> +     * \param name       Base name of the output files.  This should not
> +     *                   contain any directory part and no filename
> +     *                   extensions.  It will be used both for each processes
> +     *                   piece as well as the parallel collection file.
> +     * \param path       Directory where to put the parallel collection file.
> +     * \param extendpath Directory where to put the piece file of this process.
> +     * \param type       How to encode the data in the file (e.g. ascii).
> +     *
> +     * The path variable determines the directory where the .pvtu/.pvtp file
> +     * is written.  The directory where each processors .vtu/.vtp is written
> +     * depends on both the argument path and extendpath.  The parallel header
> +     * (.pvtu/.pvtp) actually contains relative paths to the .vtu/.vtp files,
> +     * denoted here as relpiecepath:
> +     * <ul>
> +     * <li>If path both starts and ends with a '/', then extendpath is a
> +     *     absolute path starting at the root directory (no matter whether
> +     *     extenpath actually starts with '/' or not).  relpiecepath starts
> +     *     with as many ".." seperated by '/' as path contains '/', followed
> +     *     by the value of extendpath with a leading and a trailing '/' added
> +     *     if they were not present already.
> +     * <li>Otherwise, extendpath is relative to path (again, no matter whether
> +     *     extenpath actually starts with '/' or not).  relpiecepath is
> +     *     exactly identical to extendpath -- this implies that a leading '/'
> +     *     in extendpath is not permissible in this case, otherwise
> +     *     relpiecepath would not be relative.
> +     * </ul>
>       */

I'm going to try tow make that a little more intuitive.  Specifically:

 * path is either absolute or relative to the current directory, as determined
   by the presence or absence of a leading '/' in path.

 * extenpath is either absolute or relative to path, as determined by the
   presence or absence of a leading '/' in extendpath.  Another possible
   interpretation for relative paths would be relative to the current
   directory, but relative to path is closer to what currently happens.

 * In the case of a relative path but absolute extendpath a the value for the
   current directory is actually required.  I am tempted to simply not support
   this case and throw an exception instead.

The differences to the current situation are in the following cases:

 * path begins and ends with '/', extendpath does not begin with '/':
   before: extendpath was absolute
   after:  extendpath is relative to path

 * path and extendpath begin with '/', path does not end with '/':
   before: (silent) error in the computation of relpiecepath
   after:  extendpath is absolute

 * path does not begin with '/', extendpath begins with '/':
   before: (silent) error in the computation of relpiecepath
   after:  either extendpath is absolute, or exception thrown

If anyone does not like the planned changes, please cry foul now.

Thanks,
Jö.

[1] As usual, what actually happens seems to contradict the comments in the
    code...

-- 
A programmer is a device to turn coffee and pizza into bugs.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 828 bytes
Desc: Digital signature
URL: <https://lists.dune-project.org/pipermail/dune/attachments/20100607/5b59bef2/attachment.sig>