nanocoat/include/sjme/path.h

   1 /* -*- Mode: C; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the Mozilla Public License Version 2.0.
   7 // See license.mkd for licensing and copyright information.
   8 // -------------------------------------------------------------------------*/
   9
  10 /**
  11  * Path handling abstraction.
  12  *
  13  * @since 2024/08/09
  14  */
  15
  16 #ifndef SQUIRRELJME_PATH_H
  17 #define SQUIRRELJME_PATH_H
  18
  19 #include "sjme/config.h"
  20 #include "sjme/error.h"
  21 #include "sjme/stdTypes.h"
  22
  23 /* Anti-C++. */
  24 #ifdef __cplusplus
  25         #ifndef SJME_CXX_IS_EXTERNED
  26                 #define SJME_CXX_IS_EXTERNED
  27                 #define SJME_CXX_SQUIRRELJME_PATH_H
  28 extern "C"
  29 {
  30         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  31 #endif /* #ifdef __cplusplus */
  32
  33 /*--------------------------------------------------------------------------*/
  34
  35 /** The maximum file name length in SquirrelJME. */
  36 #define SJME_MAX_FILE_NAME 128
  37
  38 /** The maximum path length in SquirrelJME. */
  39 #define SJME_MAX_PATH 1024
  40
  41 #if defined(SJME_CONFIG_HAS_DOS)
  42         /** Short paths. */
  43         #defne SJME_PATH_SHORT
  44 #endif
  45
  46 #if defined(SJME_CONFIG_HAS_WINDOWS) || defined(SJME_CONFIG_HAS_MACOS_CLASSIC)
  47         /** Separator for PATH and classpath. */
  48         #define SJME_CONFIG_PATH_SEPARATOR ";"
  49 #else
  50         /** Separator for PATH and classpath. */
  51         #define SJME_CONFIG_PATH_SEPARATOR ":"
  52 #endif
  53
  54 /** DOS path style. */
  55 #define SJME_CONFIG_PATH_STYLE_DOS 1
  56
  57 /** Macintosh path style. */
  58 #define SJME_CONFIG_PATH_STYLE_MACOS_CLASSIC 2
  59
  60 /** UNIX path style. */
  61 #define SJME_CONFIG_PATH_STYLE_UNIX 3
  62
  63 #if defined(SJME_CONFIG_HAS_WINDOWS) || defined(SJME_CONFIG_HAS_DOS)
  64         /** Path style in use. */
  65         #define SJME_CONFIG_PATH_STYLE SJME_CONFIG_PATH_STYLE_DOS
  66 #elif defined(SJME_CONFIG_HAS_MACOS_CLASSIC)
  67         /** Path style in use. */
  68         #define SJME_CONFIG_PATH_STYLE SJME_CONFIG_PATH_STYLE_MACOS_CLASSIC
  69 #else
  70         /** Path style in use. */
  71         #define SJME_CONFIG_PATH_STYLE SJME_CONFIG_PATH_STYLE_UNIX
  72 #endif
  73
  74 #if SJME_CONFIG_PATH_STYLE == SJME_CONFIG_PATH_STYLE_DOS
  75         /** Separator for file paths. */
  76         #define SJME_CONFIG_FILE_SEPARATOR "\\"
  77 #elif SJME_CONFIG_PATH_STYLE == SJME_CONFIG_PATH_STYLE_MACOS_CLASSIC
  78         /** Separator for file paths. */
  79         #define SJME_CONFIG_FILE_SEPARATOR ":"
  80 #elif SJME_CONFIG_PATH_STYLE == SJME_CONFIG_PATH_STYLE_UNIX
  81         /** Separator for file paths. */
  82         #define SJME_CONFIG_FILE_SEPARATOR "/"
  83 #else
  84         #error Unknown native path style.
  85 #endif
  86
  87 /**
  88  * Gets the given name at the given index, usage is more basic than the
  89  * full version.
  90  *
  91  * @param inPath The input path.
  92  * @param inPathLen The input path length.
  93  * @param inName The name index to get, if @c -1 this will return the
  94  * root component if there is one.
  95  * @param outBase The pointer to the path base.
  96  * @param outLen The length of the path name.
  97  * @return Any resultant error, if any. Returns @c SJME_ERROR_NO_SUCH_ELEMENT
  98  * if the root component was requested and there was none.
  99  * @since 2024/08/10
 100  */
 101 sjme_errorCode sjme_path_getName(
 102         sjme_attrInNotNull sjme_lpcstr inPath,
 103         sjme_attrInPositive sjme_jint inPathLen,
 104         sjme_attrInNegativeOnePositive sjme_jint inName,
 105         sjme_attrOutNullable sjme_lpcstr* outBase,
 106         sjme_attrOutNullable sjme_jint* outLen);
 107
 108 /**
 109  * Gets the given name at the given index.
 110  *
 111  * @param inPath The input path.
 112  * @param inPathLen The input path length.
 113  * @param inName The name index to get, if @c -1 this will return the
 114  * root component if there is one.
 115  * @param outBase The pointer to the path base.
 116  * @param outBaseDx The index of the path base.
 117  * @param outEnd The pointer to the path end.
 118  * @param outEndDx The index of the path end.
 119  * @param outLen The length of the path name.
 120  * @param outCount The number of name components, exclusive to all the
 121  * other arguments.
 122  * @return Any resultant error, if any. Returns @c SJME_ERROR_NO_SUCH_ELEMENT
 123  * if the root component was requested and there was none.
 124  * @since 2024/08/10
 125  */
 126 sjme_errorCode sjme_path_getNameF(
 127         sjme_attrInNotNull sjme_lpcstr inPath,
 128         sjme_attrInPositive sjme_jint inPathLen,
 129         sjme_attrInNegativeOnePositive sjme_jint inName,
 130         sjme_attrOutNullable sjme_lpcstr* outBase,
 131         sjme_attrOutNullable sjme_jint* outBaseDx,
 132         sjme_attrOutNullable sjme_lpcstr* outEnd,
 133         sjme_attrOutNullable sjme_jint* outEndDx,
 134         sjme_attrOutNullable sjme_jint* outLen,
 135         sjme_attrOutNullable sjme_jint* outCount);
 136
 137 /**
 138  * Gets the number of names that appear in the given path.
 139  *
 140  * @param inPath The input path.
 141  * @param inPathLen The input path length.
 142  * @param outCount The resultant name count.
 143  * @return Any resultant error, if any.
 144  * @since 2024/08/10
 145  */
 146 sjme_errorCode sjme_path_getNameCount(
 147         sjme_attrInNotNull sjme_lpcstr inPath,
 148         sjme_attrInPositive sjme_jint inPathLen,
 149         sjme_attrOutNotNull sjme_attrOutPositive sjme_jint* outCount);
 150
 151 /**
 152  * Returns whether the given path as a root.
 153  *
 154  * @param inPath The path to check.
 155  * @param inPathLen The input path length.
 156  * @param hasRoot If there is a root or not.
 157  * @return Any resultant error, if any.
 158  * @since 2024/08/10
 159  */
 160 sjme_errorCode sjme_path_hasRoot(
 161         sjme_attrInNotNull sjme_lpcstr inPath,
 162         sjme_attrInPositive sjme_jint inPathLen,
 163         sjme_attrOutNotNull sjme_jboolean* hasRoot);
 164
 165 /**
 166  * Resolves the given path onto the given path buffer.
 167  *
 168  * @param outPath The resultant path to be modified.
 169  * @param outPathLen The size of the path buffer.
 170  * @param subPath The sub-path to resolve against.
 171  * @param subPathLen The sub-path length, if @c INT32_MAX this means all
 172  * of it.
 173  * @return Any resultant error, if any.
 174  * @since 2024/08/09
 175  */
 176 sjme_errorCode sjme_path_resolveAppend(
 177         sjme_attrOutNotNull sjme_lpstr outPath,
 178         sjme_attrInPositiveNonZero sjme_jint outPathLen,
 179         sjme_attrInNotNull sjme_lpcstr subPath,
 180         sjme_attrInPositiveNonZero sjme_jint subPathLen);
 181
 182 /*--------------------------------------------------------------------------*/
 183
 184 /* Anti-C++. */
 185 #ifdef __cplusplus
 186         #ifdef SJME_CXX_SQUIRRELJME_PATH_H
 187 }
 188                 #undef SJME_CXX_SQUIRRELJME_PATH_H
 189                 #undef SJME_CXX_IS_EXTERNED
 190         #endif /* #ifdef SJME_CXX_SQUIRRELJME_PATH_H */
 191 #endif /* #ifdef __cplusplus */
 192
 193 #endif /* SQUIRRELJME_PATH_H */