extras/ignorecase.h
author Ryan C. Gordon <icculus@icculus.org>
Sat, 24 Sep 2011 00:55:15 -0700
changeset 1182 9ba19d71cc4a
parent 809 116b8fe30371
child 1379 dc640da825bf
permissions -rw-r--r--
Put some include-once and extern "C" blocks in the extras' headers.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1182
9ba19d71cc4a Put some include-once and extern "C" blocks in the extras' headers.
Ryan C. Gordon <icculus@icculus.org>
parents: 809
diff changeset
     1
#ifndef INCL_PHYSFSEXT_IGNORECASE_H
9ba19d71cc4a Put some include-once and extern "C" blocks in the extras' headers.
Ryan C. Gordon <icculus@icculus.org>
parents: 809
diff changeset
     2
#define INCL_PHYSFSEXT_IGNORECASE_H
9ba19d71cc4a Put some include-once and extern "C" blocks in the extras' headers.
Ryan C. Gordon <icculus@icculus.org>
parents: 809
diff changeset
     3
555
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     4
/** \file ignorecase.h */
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     5
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     6
/**
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     7
 * \mainpage PhysicsFS ignorecase
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     8
 *
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     9
 * This is an extension to PhysicsFS to let you handle files in a
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    10
 *  case-insensitive manner, regardless of what sort of filesystem or
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    11
 *  archive they reside in. It does this by enumerating directories as
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    12
 *  needed and manually locating matching entries.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    13
 *
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    14
 * Please note that this brings with it some caveats:
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    15
 *  - On filesystems that are case-insensitive to start with, such as those
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    16
 *    used on Windows or MacOS, you are adding extra overhead.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    17
 *  - On filesystems that are case-sensitive, you might select the wrong dir
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    18
 *    or file (which brings security considerations and potential bugs). This
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    19
 *    code favours exact case matches, but you will lose access to otherwise
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    20
 *    duplicate filenames, or you might go down a wrong directory tree, etc.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    21
 *    In practive, this is rarely a problem, but you need to be aware of it.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    22
 *  - This doesn't do _anything_ with the write directory; you're on your
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    23
 *    own for opening the right files for writing. You can sort of get around
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    24
 *    this by adding your write directory to the search path, but then the
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    25
 *    interpolated directory tree can screw you up even more.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    26
 *
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    27
 * This code should be considered an aid for legacy code. New development
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    28
 *  shouldn't do dumbass things that require this aid in the first place.  :)
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    29
 *
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    30
 * Usage: Set up PhysicsFS as you normally would, then use
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    31
 *  PHYSFSEXT_locateCorrectCase() to get a "correct" pathname to pass to
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    32
 *  functions like PHYSFS_openRead(), etc.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    33
 *
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    34
 * License: this code is public domain. I make no warranty that it is useful,
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    35
 *  correct, harmless, or environmentally safe.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    36
 *
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    37
 * This particular file may be used however you like, including copying it
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    38
 *  verbatim into a closed-source project, exploiting it commercially, and
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    39
 *  removing any trace of my name from the source (although I hope you won't
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    40
 *  do that). I welcome enhancements and corrections to this file, but I do
576
5da65f8e9a50 Switched to zlib license.
Ryan C. Gordon <icculus@icculus.org>
parents: 555
diff changeset
    41
 *  not require you to send me patches if you make changes. This code has
5da65f8e9a50 Switched to zlib license.
Ryan C. Gordon <icculus@icculus.org>
parents: 555
diff changeset
    42
 *  NO WARRANTY.
555
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    43
 *
576
5da65f8e9a50 Switched to zlib license.
Ryan C. Gordon <icculus@icculus.org>
parents: 555
diff changeset
    44
 * Unless otherwise stated, the rest of PhysicsFS falls under the zlib license.
809
116b8fe30371 Renamed LICENSE to LICENSE.txt
Ryan C. Gordon <icculus@icculus.org>
parents: 576
diff changeset
    45
 *  Please see LICENSE.txt in the root of the source tree.
555
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    46
 *
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    47
 *  \author Ryan C. Gordon.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    48
 */
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    49
1182
9ba19d71cc4a Put some include-once and extern "C" blocks in the extras' headers.
Ryan C. Gordon <icculus@icculus.org>
parents: 809
diff changeset
    50
#ifdef __cplusplus
9ba19d71cc4a Put some include-once and extern "C" blocks in the extras' headers.
Ryan C. Gordon <icculus@icculus.org>
parents: 809
diff changeset
    51
extern "C" {
9ba19d71cc4a Put some include-once and extern "C" blocks in the extras' headers.
Ryan C. Gordon <icculus@icculus.org>
parents: 809
diff changeset
    52
#endif
555
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    53
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    54
/**
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    55
 * \fn int PHYSFSEXT_locateCorrectCase(char *buf)
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    56
 * \brief Find an existing filename with matching case.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    57
 *
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    58
 * This function will look for a path/filename that matches the passed in
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    59
 *  buffer. Each element of the buffer's path is checked for a
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    60
 *  case-insensitive match. The buffer must specify a null-terminated string
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    61
 *  in platform-independent notation.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    62
 *
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    63
 * Please note results may be skewed differently depending on whether symlinks
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    64
 *  are enabled or not.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    65
 *
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    66
 * Each element of the buffer is overwritten with the actual case of an
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    67
 *  existing match. If there is no match, the search aborts and reports an
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    68
 *  error. Exact matches are favored over case-insensitive matches.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    69
 *
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    70
 * THIS IS RISKY. Please do not use this function for anything but crappy
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    71
 *  legacy code.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    72
 *
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    73
 *   \param buf Buffer with null-terminated string of path/file to locate.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    74
 *               This buffer will be modified by this function.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    75
 *  \return zero if match was found, -1 if the final element (the file itself)
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    76
 *               is missing, -2 if one of the parent directories is missing.
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    77
 */
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    78
int PHYSFSEXT_locateCorrectCase(char *buf);
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    79
1182
9ba19d71cc4a Put some include-once and extern "C" blocks in the extras' headers.
Ryan C. Gordon <icculus@icculus.org>
parents: 809
diff changeset
    80
#ifdef __cplusplus
9ba19d71cc4a Put some include-once and extern "C" blocks in the extras' headers.
Ryan C. Gordon <icculus@icculus.org>
parents: 809
diff changeset
    81
}
9ba19d71cc4a Put some include-once and extern "C" blocks in the extras' headers.
Ryan C. Gordon <icculus@icculus.org>
parents: 809
diff changeset
    82
#endif
9ba19d71cc4a Put some include-once and extern "C" blocks in the extras' headers.
Ryan C. Gordon <icculus@icculus.org>
parents: 809
diff changeset
    83
9ba19d71cc4a Put some include-once and extern "C" blocks in the extras' headers.
Ryan C. Gordon <icculus@icculus.org>
parents: 809
diff changeset
    84
#endif  /* include-once blocker. */
9ba19d71cc4a Put some include-once and extern "C" blocks in the extras' headers.
Ryan C. Gordon <icculus@icculus.org>
parents: 809
diff changeset
    85
555
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    86
/* end of ignorecase.h ... */
cb2a2f1202f1 Initial add.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    87