le_path.h

    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 //--------------------------------------------------------------------------------------------------
   65 le_result_t le_path_GetDir
   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 //--------------------------------------------------------------------------------------------------
   83 char* le_path_GetBasenamePtr
   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 //--------------------------------------------------------------------------------------------------
  110 le_result_t le_path_Concat
  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 //--------------------------------------------------------------------------------------------------
  135 bool le_path_IsSubpath
  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 //--------------------------------------------------------------------------------------------------
  157 bool le_path_IsEquivalent
  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 //--------------------------------------------------------------------------------------------------
  180 char *le_path_FindTrailing
  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_path_Concat
le_result_t le_path_Concat(const char *separatorPtr, char *pathPtr, size_t pathSize,...)
le_path_FindTrailing
char * le_path_FindTrailing(const char *pathPtr, const char *extPtr)
le_result_t
le_result_t
Definition: le_basics.h:45
le_path_GetBasenamePtr
char * le_path_GetBasenamePtr(const char *pathPtr, const char *separatorPtr)
le_path_IsSubpath
bool le_path_IsSubpath(const char *path1Ptr, const char *path2Ptr, const char *separatorPtr)
le_path_GetDir
le_result_t le_path_GetDir(const char *pathPtr, const char *separatorPtr, char *dirPtr, size_t dirBuffSize)
le_path_IsEquivalent
bool le_path_IsEquivalent(const char *path1Ptr, const char *path2Ptr, const char *separatorPtr)