Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kPath.h
Go to the documentation of this file.
1 /**
2 * @file kPath.h
3 * @brief Declares the kPath class.
4 *
5 * @internal
6 * Copyright (C) 2008-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef K_API_PATH_H
11 #define K_API_PATH_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 #define kPATH_MAX (kxPATH_MAX) ///< Maximum supported path length.
18
19 /**
20 * @class kPath
21 * @ingroup kApi-Io
22 * @brief Collection of path manipulation functions.
23 *
24 * Most of the functions in this class expect paths to be in normal form (canonical
25 * separator character, no trailing slashes). The kPath_Normalize function can be
26 * used to normalize paths prior to calling other kPath functions.
27 *
28 * The kPath_ToNative function can be used to transform a path in normal form to
29 * to a form suitable for the underlying system (native separator).
30 */
31 typedef kObject kPath;
32
33 /**
34 * Returns the normalized path separator character.
35 *
36 * @public @memberof kPath
37 * @return Path separator character.
38 */
39 kFx(kChar) kPath_Separator();
40
41 /**
42 * Determines if the given character is equal to the normalized path separator.
43 *
44 * @public @memberof kPath
45 * @param ch Character to examine.
46 * @return kTRUE if the character is the normalized path separator.
47 */
48 kFx(kBool) kPath_IsSeparator(kChar ch);
49
50 /**
51 * Combines two path segments using the normalized path separator character.
52 *
53 * The path (output) argument can refer to the same memory address as either of the segment (input) arguments.
54 *
55 * @public @memberof kPath
56 * @param segment1 First path segment.
57 * @param segment2 Second path segment.
58 * @param path Receives the combined path segments.
59 * @param capacity Maximum number of characters (including null terminator).
60 * @return Operation status.
61 */
62 kFx(kStatus) kPath_Combine(const kChar* segment1, const kChar* segment2, kChar* path, kSize capacity);
63
64 /**
65 * Returns the parent directory for a given file or directory path.
66 *
67 * The directory (output) argument can refer to the same memory address as the path (input) argument.
68 *
69 * If the path contains embedded relative path components, this function will not attempt
70 * to evaluate the meaning of those components.
71 *
72 * @public @memberof kPath
73 * @param path File or directory path.
74 * @param directory Receives the parent directory.
75 * @param capacity Maximum number of characters (including null terminator).
76 * @return Operation status.
77 */
78 kFx(kStatus) kPath_Directory(const kChar* path, kChar* directory, kSize capacity);
79
80 /**
81 * Given a file path, returns the portion of the path containing the file name.
82 *
83 * The fileName (output) argument can refer to the same memory address as the path (input) argument.
84 *
85 * @public @memberof kPath
86 * @param path File path.
87 * @param fileName Receives the file name portion of the path.
88 * @param capacity Maximum number of characters (including null terminator).
89 * @return Operation status.
90 */
91 kFx(kStatus) kPath_FileName(const kChar* path, kChar* fileName, kSize capacity);
92
93 /**
94 * Given a file path, returns the portion of the path containing the file extension.
95 *
96 * The extension (output) argument can refer to the same memory address as the path (input) argument.
97 *
98 * @public @memberof kPath
99 * @param path File path.
100 * @param extension Receives the file extension portion of the path.
101 * @param capacity Maximum number of characters (including null terminator).
102 * @return Operation status.
103 */
104 kFx(kStatus) kPath_Extension(const kChar* path, kChar* extension, kSize capacity);
105
106 /**
107 * Expresses an absolute path in relative form, in relation to a reference path.
108 *
109 * If pathA and pathB are rooted in different volumes, then bRelativeToA will receive an absolute path equal
110 * to pathB.
111 *
112 * The bRelativeToA (output) argument can refer to the same memory address as either the pathA or pathB
113 * (input) arguments.
114 *
115 * @public @memberof kPath
116 * @param pathA Absolute reference path.
117 * @param pathB Absolute path to be re-expressed as relative to path A.
118 * @param bRelativeToA Receives path b, expressed as relative to path A.
119 * @param capacity Maximum number of characters (including null terminator) for the relative path.
120 * @return Operation status.
121 */
122 kFx(kStatus) kPath_ToRelative(const kChar* pathA, const kChar* pathB, kChar* bRelativeToA, kSize capacity);
123
124 /**
125 * Finds the absolute path expressed by the combination of an absolute path and a relative path.
126 *
127 * If bRelativeToA is already expressed in absolute form, then pathB will receive an absolute path equal
128 * to bRelativeToA.
129 *
130 * The pathB (output) argument can refer to the same memory address as either the pathA or bRelativeToA
131 * (input) arguments.
132 *
133 * @public @memberof kPath
134 * @param pathA Absolute reference path.
135 * @param bRelativeToA Path b, expressed as relative to path A.
136 * @param pathB Receives path b, expressed as an absolute path.
137 * @param capacity Maximum number of characters (including null terminator) for path b.
138 * @return Operation status.
139 */
140 kFx(kStatus) kPath_ToAbsolute(const kChar* pathA, const kChar* bRelativeToA, kChar* pathB, kSize capacity);
141
142 /**
143 * Transforms all path separators to normal form and removes trailing slashes.
144 *
145 * The normalized (output) argument can refer to the same memory address as the path (input) argument.
146 *
147 * @public @memberof kPath
148 * @param path Input path, in native or mixed form.
149 * @param normalized Receives transformed path, in normal form.
150 * @param capacity Maximum number of characters (including null terminator) for normalized path.
151 * @return Operation status.
152 */
153 kFx(kStatus) kPath_Normalize(const kChar* path, kChar* normalized, kSize capacity);
154
155 /**
156 * Transforms all path separators to native form.
157 *
158 * The native (output) argument can refer to the same memory address as the path (input) argument.
159 *
160 * @public @memberof kPath
161 * @param path Input path, in normal or mixed form.
162 * @param native Receives transformed path, in native form.
163 * @param capacity Maximum number of characters (including null terminator) for native path.
164 * @return Operation status.
165 */
166 kFx(kStatus) kPath_ToNative(const kChar* path, kChar* native, kSize capacity);
167
168 kEndHeader()
169
170 #include <kApi/Io/kPath.x.h>
171
172 #endif
kPath::kPath_Directory
kStatus kPath_Directory(const kChar *path, kChar *directory, kSize capacity)
Returns the parent directory for a given file or directory path.
kSize
Represents an unsigned integer that can store a pointer address.
kChar
Represents a single unit (byte) in a UTF-8 character.
kPath::kPath_Combine
kStatus kPath_Combine(const kChar *segment1, const kChar *segment2, kChar *path, kSize capacity)
Combines two path segments using the normalized path separator character.
kPath::kPath_Extension
kStatus kPath_Extension(const kChar *path, kChar *extension, kSize capacity)
Given a file path, returns the portion of the path containing the file extension. ...
kPath::kPath_ToAbsolute
kStatus kPath_ToAbsolute(const kChar *pathA, const kChar *bRelativeToA, kChar *pathB, kSize capacity)
Finds the absolute path expressed by the combination of an absolute path and a relative path...
kApiDef.h
Essential API declarations.
kPath::kPath_ToNative
kStatus kPath_ToNative(const kChar *path, kChar *native, kSize capacity)
Transforms all path separators to native form.
kPath::kPath_IsSeparator
kBool kPath_IsSeparator(kChar ch)
Determines if the given character is equal to the normalized path separator.
kPath::kPath_FileName
kStatus kPath_FileName(const kChar *path, kChar *fileName, kSize capacity)
Given a file path, returns the portion of the path containing the file name.
kPath::kPath_ToRelative
kStatus kPath_ToRelative(const kChar *pathA, const kChar *pathB, kChar *bRelativeToA, kSize capacity)
Expresses an absolute path in relative form, in relation to a reference path.
kObject
Root of all class types in the Zen type system.
kStatus
Represents an enumeration of error codes.
kPath::kPath_Separator
kChar kPath_Separator()
Returns the normalized path separator character.
kBool
Represents a boolean value.
kPath::kPath_Normalize
kStatus kPath_Normalize(const kChar *path, kChar *normalized, kSize capacity)
Transforms all path separators to normal form and removes trailing slashes.
kPath
Collection of path manipulation functions.