le_path.h

Go to the documentation of this file.
1 
2 //--------------------------------------------------------------------------------------------------
3 /**
4  * @page c_path Path API
5  *
6  * @subpage le_path.h "API Reference"
7  *
8  * <HR>
9  *
10  * Paths are text strings that contain nodes separated by character separators. Paths are used in
11  * many common applications like file system addressing, URLs, etc. so being able to parse them
12  * is quite important.
13  *
14  * The Path API is intended for general purpose use and supports UTF-8 null-terminated
15  * strings and multi-character separators.
16  *
17  * @section c_path_dirAndBasename Directory and Basename
18  *
19  * The function @c le_path_GetDir() is a convenient way to get the path's directory without having
20  * to create an iterator. The directory is the portion of the path up to and including the last
21  * separator. le_path_GetDir() does not modify the path in anyway (i.e., consecutive paths are left
22  * as is), except to drop the node after the last separator.
23  *
24  * The function le_path_GetBasenamePtr() is an efficient and convenient function for accessing the
25  * last node in the path without having to create an iterator. The returned pointer points to the
26  * character following the last separator in the path. Because the basename is actually a portion
27  * of the path string, not a copy, any changes to the returned basename will also affect the
28  * original path string.
29  *
30  * @section c_path_threads Thread Safety
31  *
32  * All the functions in this API are thread safe and reentrant unless of course the path iterators
33  * or the buffers passed into the functions are shared between threads. If the path iterators or
34  * buffers are shared by multiple threads then some other mechanism must be used to ensure these
35  * functions are thread safe.
36  *
37  * <HR>
38  *
39  * Copyright (C) Sierra Wireless Inc.
40  * license.
41  */
42 
43 //--------------------------------------------------------------------------------------------------
44 /** @file le_path.h
45  *
46  * Legato @ref c_path include file.
47  *
48  * Copyright (C) Sierra Wireless Inc.
49  * license.
50  */
51 
52 #ifndef LEGATO_PATH_INCLUDE_GUARD
53 #define LEGATO_PATH_INCLUDE_GUARD
54 
55 
56 //--------------------------------------------------------------------------------------------------
57 /**
58  * Gets the directory, which is the entire path up to and including the last separator.
59  *
60  * @return
61  * LE_OK if succesful.
62  * LE_OVERFLOW if the dirPtr buffer is too small.
63  */
64 //--------------------------------------------------------------------------------------------------
66 (
67  const char* pathPtr, ///< [IN] Path string.
68  const char* separatorPtr, ///< [IN] Separator string.
69  char* dirPtr, ///< [OUT] Buffer to store the directory string.
70  size_t dirBuffSize ///< [IN] Size of the directory buffer in bytes.
71 );
72 
73 
74 //--------------------------------------------------------------------------------------------------
75 /**
76  * Gets a pointer to the basename (the last node in the path). This function gets the basename by
77  * returning a pointer to the character following the last separator.
78  *
79  * @return
80  * Pointer to the character following the last separator.
81  */
82 //--------------------------------------------------------------------------------------------------
84 (
85  const char* pathPtr, ///< [IN] Path string.
86  const char* separatorPtr ///< [IN] Separator string.
87 );
88 
89 
90 //--------------------------------------------------------------------------------------------------
91 /**
92  * Concatenates multiple path segments together.
93  *
94  * Concatenates the path in the pathPtr buffer with all path segments and stores the result in the
95  * pathPtr. Ensures that where path segments are joined there is only one separator between them.
96  * Duplicate trailing separators in the resultant path are also dropped.
97  *
98  * If there is not enough space in pathPtr for all segments, as many characters from the segments
99  * that will fit in the buffer will be copied and LE_OVERFLOW will be returned. Partial UTF-8
100  * characters and partial separators will never be copied.
101  *
102  * @warning The (char*)NULL at the end of the list of path segments is mandatory. If this NULL is
103  * omitted the behaviour is undefined.
104  *
105  * @return
106  * LE_OK if successful.
107  * LE_OVERFLOW if there was not enough buffer space in pathPtr for all segments.
108  */
109 //--------------------------------------------------------------------------------------------------
111 (
112  const char* separatorPtr, ///< [IN] Separator string.
113  char* pathPtr, ///< [IN/OUT] Buffer containing the first segment and where
114  /// the resultant path will be stored.
115  size_t pathSize, ///< [IN] Buffer size.
116  ... ///< [IN] Path segments to concatenate. The list of segments
117  /// must be terminated by (char*)NULL.
118 )
119 __attribute__((__sentinel__));
120 
121 
122 //--------------------------------------------------------------------------------------------------
123 /**
124  * Checks if path2 is a subpath of path1. That is path2 has the same starting nodes as path2. For
125  * example, path2 is a subpath of path1 if:
126  *
127  * path1 = /a/b/c
128  * path2 = /a/b/c/d/e
129  *
130  * @return
131  * true if path2 is a subpath of path1.
132  * false otherwise.
133  */
134 //--------------------------------------------------------------------------------------------------
136 (
137  const char* path1Ptr, ///< [IN] Path 1 string.
138  const char* path2Ptr, ///< [IN] Path 2 string.
139  const char* separatorPtr ///< [IN] Separator string.
140 );
141 
142 
143 //--------------------------------------------------------------------------------------------------
144 /**
145  * Checks if path1 and path2 are equivalent, ignoring trailing separators. For example, all the
146  * following paths are equivalent.
147  *
148  * /a/b/c
149  * /a/b/c/
150  * /a/b/c///
151  *
152  * @return
153  * true if path1 is equivalent to path2.
154  * false otherwise.
155  */
156 //--------------------------------------------------------------------------------------------------
158 (
159  const char* path1Ptr, ///< [IN] Path 1 string.
160  const char* path2Ptr, ///< [IN] Path 2 string.
161  const char* separatorPtr ///< [IN] Separator string.
162 );
163 
164 
165 //--------------------------------------------------------------------------------------------------
166 /**
167  * Checks if a path has a particular trailing substring. For example, path
168  *
169  * pathPtr = /path/to/file.txt
170  *
171  * contains a trailing substring
172  *
173  * extPtr = .txt
174  *
175  * @return
176  * pointer to existing trailing susbstring within path, or
177  * NULL otherwise.
178  */
179 //--------------------------------------------------------------------------------------------------
181 (
182  const char *pathPtr, ///< [IN] Path string.
183  const char *extPtr ///< [IN] Trailing substring.
184 );
185 
186 
187 #endif // LEGATO_PATH_INCLUDE_GUARD
le_result_t le_path_Concat(const char *separatorPtr, char *pathPtr, size_t pathSize,...)
char * le_path_FindTrailing(const char *pathPtr, const char *extPtr)
le_result_t
Definition: le_basics.h:46
char * le_path_GetBasenamePtr(const char *pathPtr, const char *separatorPtr)
bool le_path_IsSubpath(const char *path1Ptr, const char *path2Ptr, const char *separatorPtr)
le_result_t le_path_GetDir(const char *pathPtr, const char *separatorPtr, char *dirPtr, size_t dirBuffSize)
bool le_path_IsEquivalent(const char *path1Ptr, const char *path2Ptr, const char *separatorPtr)