le_pathIter.h File Reference

Go to the source code of this file.

Typedefs

typedef struct le_pathIter_t * le_pathIter_Ref_t
 

Functions

le_pathIter_Ref_t le_pathIter_Create (const char *pathPtr, const char *separatorPtr, const char *parentSpecPtr, const char *currentSpecPtr)
 
le_pathIter_Ref_t le_pathIter_CreateForUnix (const char *pathPtr)
 
le_pathIter_Ref_t le_pathIter_Clone (le_pathIter_Ref_t originalRef)
 
void le_pathIter_Delete (le_pathIter_Ref_t iterRef)
 
le_result_t le_pathIter_GetSeparator (le_pathIter_Ref_t iterRef, char *bufferPtr, size_t bufferSize)
 
le_result_t le_pathIter_GetParentSpecifier (le_pathIter_Ref_t iterRef, char *bufferPtr, size_t bufferSize)
 
le_result_t le_pathIter_GetCurrentSpecifier (le_pathIter_Ref_t iterRef, char *bufferPtr, size_t bufferSize)
 
le_result_t le_pathIter_GetPath (le_pathIter_Ref_t iterRef, char *bufferPtr, size_t bufferSize)
 
le_result_t le_pathIter_GoToStart (le_pathIter_Ref_t iterRef)
 
le_result_t le_pathIter_GoToEnd (le_pathIter_Ref_t iterRef)
 
le_result_t le_pathIter_GoToNext (le_pathIter_Ref_t iterRef)
 
le_result_t le_pathIter_GoToPrev (le_pathIter_Ref_t iterRef)
 
le_result_t le_pathIter_GetCurrentNode (le_pathIter_Ref_t iterRef, char *bufferPtr, size_t bufferSize)
 
void le_pathIter_Truncate (le_pathIter_Ref_t iterRef)
 
le_result_t le_pathIter_Append (le_pathIter_Ref_t iterRef, const char *pathStr)
 
bool le_pathIter_IsAbsolute (le_pathIter_Ref_t iterRef)
 
bool le_pathIter_IsEmpty (le_pathIter_Ref_t iterRef)
 

Detailed Description

Legato Path Iterator API include file.

Typedef Documentation

typedef struct le_pathIter_t* le_pathIter_Ref_t

Objects of this type are used to iterate and manipulate path strings.

Function Documentation

le_result_t le_pathIter_Append ( le_pathIter_Ref_t  iterRef,
const char *  pathStr 
)

Take the new string path and combine it with the object's existing path.

Note
This function looks for the current and parent node strings and treats them specially. So, (assuming defaults,) combining the path "/a/b" with the path "../x" will give you the combined path of: "/a/x".
Appending a non-relative path onto an existing path effectivly replaces the current path, for example, appending /a/rooted/path, onto the existing /a/seperate/path will given you the path: /a/rooted/path.
This will automatically reset the internal iterator to point at the end of the newly formed path. Also, this function always appends to the end of a path, ignoring the current position of the iterator.
Returns
LE_OK if successful. LE_OVERFLOW if the output buffer is too small for the new string. LE_UNDERFLOW if combining the path the new path tries to traverse past the root. For example: "/a/b" + "../../../x" will result in LE_UNDERFLOW. However if the base path is relative, "a/b", then the resulting string will be "../x" and a return code of LE_OK.
Parameters
[in]iterRefThe path object to write to.
[in]pathStrThe new path segment to append.
le_pathIter_Ref_t le_pathIter_Clone ( le_pathIter_Ref_t  originalRef)

Create a clone of an existing path iterator object.

Returns
A new path iterator object that is a duplicate of the original one.
Parameters
[in]originalRefThe path object to duplicate.
le_pathIter_Ref_t le_pathIter_Create ( const char *  pathPtr,
const char *  separatorPtr,
const char *  parentSpecPtr,
const char *  currentSpecPtr 
)

Create a new path iterator object. On creation, the default position of the iterator is at the end of the path.

Returns
A new path object setup with the given parameters.
Parameters
[in]pathPtrOptional. Pointer to the inital path to use.
[in]separatorPtrRequired. Path separator to use. The separator can not be NULL or empty.
[in]parentSpecPtrOptional. Used to traverse upwards in a path. Leave as NULL or empty to not use. This acts like how ".." is used in a filesystem path.
[in]currentSpecPtrOptional. Used to refer to a current node. Much like how a '.' is used in a filesystem path.
le_pathIter_Ref_t le_pathIter_CreateForUnix ( const char *  pathPtr)

Create a new path iterator object that is pre-configured for Unix styled paths. On creation, the default position of the iterator is at the end of the path.

The parameters are configured as follows:

  • separator: "/"
  • parentSpec: ".."
  • currentSpec: "."
Returns
A new path iterator object that's ready for iterating on Unix style paths.
Parameters
[in]pathPtrOptional. Create an iterator for this path, or start with an empty path.
void le_pathIter_Delete ( le_pathIter_Ref_t  iterRef)

Delete an iterator object and free it's memory.

Parameters
[in]iterRefThe iterator object to destroy.
le_result_t le_pathIter_GetCurrentNode ( le_pathIter_Ref_t  iterRef,
char *  bufferPtr,
size_t  bufferSize 
)

Get the text for the node the itrator is pointing at.

Returns
LE_OK if succesful. LE_OVERFLOW if the bufferPtr is too small to hold the whole string. LE_NOT_FOUND if the iterator is at the end of the path. Or if the path is empty, or simply consists of a separator.
Parameters
[in]iterRefThe iterator object to read.
[out]bufferPtrThe utf-8 formatted text buffer to write to.
[in]bufferSizeThe size in bytes of the text buffer.
le_result_t le_pathIter_GetCurrentSpecifier ( le_pathIter_Ref_t  iterRef,
char *  bufferPtr,
size_t  bufferSize 
)

Read the iterators string for the current node specifier. For Unix style paths for this is ".". If an empty string is used, then this is ignored for the purposes of appending and normalizing paths.

Parameters
[in]iterRefThe iterator object to read.
[out]bufferPtrThe string buffer to write to.
[in]bufferSizeThe size of the string buffer being written to.
le_result_t le_pathIter_GetParentSpecifier ( le_pathIter_Ref_t  iterRef,
char *  bufferPtr,
size_t  bufferSize 
)

Read the string that represents parent nodes in a path string. By for Unix style paths this is "..". If an empty string is used, then it is ignored for the purposes of appending and normalizing paths.

Parameters
[in]iterRefThe iterator object to read.
[out]bufferPtrThe string buffer to write to.
[in]bufferSizeThe size of the buffer being written to.
le_result_t le_pathIter_GetPath ( le_pathIter_Ref_t  iterRef,
char *  bufferPtr,
size_t  bufferSize 
)

Get a copy of the path currently contained within the iterator.

Returns
LE_OK if the copy is successful. LE_OVERFLOW if the buffer isn't big enough for the path string.
Parameters
[in]iterRefThe iterator object to read.
[out]bufferPtrThe string buffer to write to.
[in]bufferSizeThe size of the buffer being written to.
le_result_t le_pathIter_GetSeparator ( le_pathIter_Ref_t  iterRef,
char *  bufferPtr,
size_t  bufferSize 
)

Read the string that is being used to represent path separators in this iterator object.

Parameters
[in]iterRefThe iterator object to read.
[out]bufferPtrThe string buffer to write to.
[in]bufferSizeThe size of the buffer being written to.
le_result_t le_pathIter_GoToEnd ( le_pathIter_Ref_t  iterRef)

Jump the iterator to the end of the path.

Returns
LE_OK if the move was successful. LE_NOT_FOUND if the path is empty, or only contains a separator.
Parameters
[in]iterRefThe iterator object to update.
le_result_t le_pathIter_GoToNext ( le_pathIter_Ref_t  iterRef)

Move to the next node in the path.

Returns
LE_OK if the itrator was successful in jumping to the next node. LE_NOT_FOUND is returned if there are no more nodes to move to in the path.
Parameters
[in]iterRefThe iterator object to update.
le_result_t le_pathIter_GoToPrev ( le_pathIter_Ref_t  iterRef)

Move to the previous node in the path.

Returns
LE_OK if the iterator was successfuly moved, LE_NOT_FOUND if there are no prior nodes to move to.
Parameters
[in]iterRefThe iterator object to update.
le_result_t le_pathIter_GoToStart ( le_pathIter_Ref_t  iterRef)

Jump the iterator to the beginning of the path.

Returns
LE_OK if the move was successful. LE_NOT_FOUND if the path is empty, or only contains a separator.
Parameters
[in]iterRefThe iterator object to update.
bool le_pathIter_IsAbsolute ( le_pathIter_Ref_t  iterRef)

Is this an absolute or relative path?

Returns
True if the path is absolute, that is that it begins with a separator. False if the path is considered relative.
Parameters
[in]iterRefThe iterator object to read.
bool le_pathIter_IsEmpty ( le_pathIter_Ref_t  iterRef)

Is the path object holding an empty string?

Returns
True if the path is empty, false if not.
Parameters
iterRefThe path object to read.
void le_pathIter_Truncate ( le_pathIter_Ref_t  iterRef)

Truncate the path at the current iterator node. If the iterator is at the beginning of the path, then the whole path is cleared. If the iterator is at the end of the path, then nothing happens.

Once done, then the iterator will be pointing at the new end of the path.

Parameters
[in]iterRefThe iterator to update.