Loading...
Searching...
No Matches
Frame Sets

## Topics

| Frame Set Iterators
| Iterator support for frame sets.

## Typedefs

typedef struct _cpl_frameset_ | cpl_frameset
| The frame set data type.

## Functions

int | cpl_frameset_count_tags (const cpl_frameset *self, const char *tag)
| Counts the frames stored in a frame set having the given tag.
void | cpl_frameset_delete (cpl_frameset *self)
| Destroy a frame set.
void | cpl_frameset_dump (const cpl_frameset *self, FILE *stream)
| Dump the frameset debugging information to the given stream.
cpl_frameset * | cpl_frameset_duplicate (const cpl_frameset *other)
| Create a copy of the given frame set.
cpl_size | cpl_frameset_erase (cpl_frameset *self, const char *tag)
| Erase all frames with the given tag from a frame set.
cpl_error_code | cpl_frameset_erase_frame (cpl_frameset *self, cpl_frame *frame)
| Erase the given frame from a frame set.
cpl_frameset * | cpl_frameset_extract (const cpl_frameset *self, const cpl_size *labels, cpl_size desired_label)
| Extract a subset of frames from a set of frames.
cpl_frame * | cpl_frameset_find (cpl_frameset *self, const char *tag)
| Find a frame with the given tag in a frame set.
const cpl_frame * | cpl_frameset_find_const (const cpl_frameset *self, const char *tag)
| Find a frame with the given tag in a frame set.
cpl_frame * | cpl_frameset_get_first (cpl_frameset *self)
| Get the first frame in the given set.
const cpl_frame * | cpl_frameset_get_first_const (const cpl_frameset *self)
| Get the first frame in the given set.
cpl_frame * | cpl_frameset_get_frame (cpl_frameset *set, cpl_size position)
| Get a frame from a frame set.
const cpl_frame * | cpl_frameset_get_frame_const (const cpl_frameset *set, cpl_size position)
| Get a frame from a frame set.
cpl_frame * | cpl_frameset_get_next (cpl_frameset *self)
| Get the next frame in the given set.
const cpl_frame * | cpl_frameset_get_next_const (const cpl_frameset *self)
| Get the next frame in the given set.
cpl_frame * | cpl_frameset_get_position (cpl_frameset *self, cpl_size position)
| Get the frame at a given position in the frame set.
const cpl_frame * | cpl_frameset_get_position_const (const cpl_frameset *self, cpl_size position)
| Get the frame at a given iterator position.
cpl_size | cpl_frameset_get_size (const cpl_frameset *self)
| Get the current size of a frame set.
cpl_error_code | cpl_frameset_insert (cpl_frameset *self, cpl_frame *frame)
| Insert a frame into the given frame set.
int | cpl_frameset_is_empty (const cpl_frameset *self)
| Check whether a frame set is empty.
cpl_error_code | cpl_frameset_join (cpl_frameset *self, const cpl_frameset *other)
| Join two frame sets.
cpl_size * | cpl_frameset_labelise (const cpl_frameset *self, int(*compare)(const cpl_frame *, const cpl_frame *), cpl_size *nb_labels)
| Separate a list of frames into groups, using a comparison function.
cpl_frameset * | cpl_frameset_new (void)
| Create a new, empty frame set.
cpl_error_code | cpl_frameset_sort (cpl_frameset *self, cpl_frame_compare_func compare)
| Sort a frame set.

## Detailed Description

The module implements a container type for frames. Frames can be stored in a frame set and retrieved, either by searching for a particular frame tag or by sequential access. Frame sets can be created, filled and saved to a so called `set of frames' file or loaded from such a file.

Synopsis:
  #include <cpl_frameset.h>
  */

/**

## Typedef Documentation

## cpl_frameset

typedef struct _cpl_frameset_ cpl_frameset

The frame set data type.

This data type is opaque.

## Function Documentation

## cpl_frameset_count_tags()

int cpl_frameset_count_tags | ( | const cpl_frameset * | self,
|  | const char * | tag )

Counts the frames stored in a frame set having the given tag.

Parameters

  self | A frame set.
  tag | The frame tag.

Returns
  The number of frames with tag tag. The function returns 0 if an error occurs and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self or tag is a NULL pointer.

@enderror

The function scans the frame set self for frames with the tag tag and returns the number of frames found.

References CPL_ERROR_NULL_INPUT.

## cpl_frameset_delete()

void cpl_frameset_delete | ( | cpl_frameset * | self | ) |

Destroy a frame set.

Parameters

  self | The frame set to destroy.

Returns
  Nothing.

The function destroys the frame set self and its whole contents. If self is `NULL`, nothing is done and no error is set.

## cpl_frameset_dump()

void cpl_frameset_dump | ( | const cpl_frameset * | self,
|  | FILE * | stream )

Dump the frameset debugging information to the given stream.

Parameters

  self | The frameset.
  stream | The output stream to use.

Returns
  Nothing.

The function dumps the contents of the frameset self to the output stream stream. If stream is `NULL` the function writes to the standard output. If self is `NULL` or the frameset is empty, the function does nothing.

References CPL_ERROR_ACCESS_OUT_OF_RANGE, cpl_error_get_code(), cpl_errorstate_get(), cpl_errorstate_set(), cpl_frame_dump(), cpl_frameset_get_size(), cpl_frameset_iterator_advance(), cpl_frameset_iterator_delete(), cpl_frameset_iterator_get_const(), and cpl_frameset_iterator_new().

## cpl_frameset_duplicate()

cpl_frameset * cpl_frameset_duplicate | ( | const cpl_frameset * | other | ) |

Create a copy of the given frame set.

Parameters

  other | The frame set to be copied.

Returns
  A handle for the created clone. The function returns `NULL` if an error occurs and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter other is a NULL pointer.

@enderror

The function creates a deep copy, i.e. the frame set object and its contents, of the frame set other. The created copy and the original set do not share any resources.

References CPL_ERROR_NULL_INPUT, cpl_frame_duplicate(), cpl_frame_get_tag(), and cpl_frameset_new().

## cpl_frameset_erase()

cpl_size cpl_frameset_erase | ( | cpl_frameset * | self,
|  | const char * | tag )

Erase all frames with the given tag from a frame set.

Parameters

  self | A frame set.
  tag | The tag used to locate the frames to remove.

Returns
  The function returns the number of frames removed. If an error occurs 0 is returned and an appropriate error code is set.

@error

CPL_ERROR_NULL_INPUT | The parameter self or tag is a NULL pointer.

@enderror

The function searches the frame set self for frames having the tag tag and removes them from the set. The removed frames are destroyed. If no frame with the tag tag is found the function has no effect.

References CPL_ERROR_NULL_INPUT.

## cpl_frameset_erase_frame()

cpl_error_code cpl_frameset_erase_frame | ( | cpl_frameset * | self,
|  | cpl_frame * | frame )

Erase the given frame from a frame set.

Parameters

  self | A frame set.
  frame | The frame to remove.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self or frame is a NULL pointer.

@enderror

The function searches the frame set self for the first occurrance of frame. If it is present, the frame is removed from the set and destroyed. If frame is not present in self the function has no effect.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_frame_get_tag().

## cpl_frameset_extract()

cpl_frameset * cpl_frameset_extract | ( | const cpl_frameset * | self,
|  | const cpl_size * | labels,
|  | cpl_size | desired_label )

Extract a subset of frames from a set of frames.

Parameters

  self | Input frame set
  labels | The array of labels associated to each input frame
  desired_label | The label identifying the requested frames

Note
  The array of labels must have (at least) the length of the frame set

Returns
  A pointer to a newly allocated frame set or NULL on error

@error

CPL_ERROR_NULL_INPUT | The parameter self or labels is a NULL pointer.

@enderror

The returned object must be deallocated with cpl_frameset_delete()

References cpl_ensure, CPL_ERROR_ACCESS_OUT_OF_RANGE, cpl_error_get_code(), CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), cpl_errorstate_set(), cpl_frame_duplicate(), cpl_frameset_insert(), cpl_frameset_iterator_advance(), cpl_frameset_iterator_delete(), cpl_frameset_iterator_get_const(), cpl_frameset_iterator_new(), and cpl_frameset_new().

## cpl_frameset_find()

cpl_frame * cpl_frameset_find | ( | cpl_frameset * | self,
|  | const char * | tag )

Find a frame with the given tag in a frame set.

Parameters

  self | A frame set.
  tag | The frame tag to search for.

Returns
  The handle for a frame with tag tag, or `NULL` if no such frame was found. The function returns `NULL` if an error occurs and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self or tag is a NULL pointer.

@enderror

The function searches the frame set self for the frames with the tag tag. If such a frame is present, a handle for it is returned. If the set contains several frames with the tag tag the first one is returned. The remaining frames with this tag can be accessed sequentially by using `NULL` as tag when calling this function repeatedly, since the most recent frame accessed is cached. This cache is reset whenever the provided tag is not `NULL`. If no frame with the tag tag is present in self or no more frames with this tag are found the function returns `NULL`.

Note
  Since the most recently accessed frame is cached in the frameset this function is not re-entrant!

References cpl_error_set_where, cpl_errorstate_get(), cpl_errorstate_is_equal(), and cpl_frameset_find_const().

## cpl_frameset_find_const()

const cpl_frame * cpl_frameset_find_const | ( | const cpl_frameset * | self,
|  | const char * | tag )

Find a frame with the given tag in a frame set.

Parameters

  self | A frame set.
  tag | The frame tag to search for.

Returns
  The handle for a frame with tag tag, or `NULL` if no such frame was found. The function returns `NULL` if an error occurs and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self or tag is a NULL pointer.

@enderror

The function searches the frame set self for the frames with the tag tag. If such a frame is present, a handle for it is returned. If the set contains several frames with the tag tag the first one is returned. The remaining frames with this tag can be accessed sequentially by using `NULL` as tag when calling this function repeatedly, since the most recent frame accessed is cached. This cache is reset whenever the provided tag is not `NULL`. If no frame with the tag tag is present in self or no more frames with this tag are found the function returns `NULL`.

Note
  Since the most recently accessed frame is cached in the frameset this function is not re-entrant!

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_frameset_find().

## cpl_frameset_get_first()

cpl_frame * cpl_frameset_get_first | ( | cpl_frameset * | self | ) |

Get the first frame in the given set.

Parameters

  self | A frame set.

Returns
  A handle for the first frame in the set, or `NULL` if the set is empty. The function returns `NULL` if an error occurs and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

The function returns the first frame in the frame set self if it exists. If a first frame does not exist, i.e. the frame set is empty, `NULL` is returned. The function also updates the internal cache.

See also
  cpl_frameset_get_next()

Deprecated
  This function will be removed from CPL version 7. Code using these functions should be ported to make use of frame set iterators instead!

References CPL_ERROR_NULL_INPUT.

## cpl_frameset_get_first_const()

const cpl_frame * cpl_frameset_get_first_const | ( | const cpl_frameset * | self | ) |

Get the first frame in the given set.

Parameters

  self | A frame set.

Returns
  A handle for the first frame in the set, or `NULL` if the set is empty. The function returns `NULL` if an error occurs and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

The function returns the first frame in the frame set self if it exists. If a first frame does not exist, i.e. the frame set is empty, `NULL` is returned. The function also updates the internal cache.

See also
  cpl_frameset_get_next_const()

Deprecated
  This function will be removed from CPL version 7. Code using these functions should be ported to make use of frame set iterators instead!

References CPL_ERROR_NULL_INPUT.

## cpl_frameset_get_frame()

cpl_frame * cpl_frameset_get_frame | ( | cpl_frameset * | set,
|  | cpl_size | position )

Get a frame from a frame set.

Parameters

  set | Input frame set.
  position | The requested frame.

Returns
  The function returns a handle to the frame at position position in the set, or `NULL` in case an error occurs.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT | The parameter position is out of range.

@enderror

The function returns a handle to the frame at the index position in the set. The frame position ranges from `0` to one less than the size of the frame set.

The returned frame is still owned by the frame set set, i.e. the obtained frame must not be deleted through the returned handle and also its tag must not be modified.

As an alternative to using this function, the functions cpl_frameset_get_first() and cpl_frameset_get_next() should be considered, if performance is an issue.

See also
  cpl_frameset_get_size(), cpl_frameset_get_first(), cpl_frameset_get_next()

Deprecated
  This function will be removed from CPL version 7. Code using these functions should use cpl_frameset_get_position() instead!

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_frameset_get_position(), and cpl_frameset_get_size().

## cpl_frameset_get_frame_const()

const cpl_frame * cpl_frameset_get_frame_const | ( | const cpl_frameset * | set,
|  | cpl_size | position )

Get a frame from a frame set.

Parameters

  set | Input frame set.
  position | The requested frame.

Returns
  The function returns a handle to the frame at position position in the set, or `NULL` in case an error occurs.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT | The parameter position is out of range.

@enderror

The function returns a handle to the frame at the index position in the set. The frame position ranges from `0` to one less than the size of the frame set.

The returned frame is still owned by the frame set set, i.e. the obtained frame must not be deleted through the returned handle and also its tag must not be modified.

As an alternative to using this function, the functions cpl_frameset_get_first_const() and cpl_frameset_get_next_const() should be considered, if performance is an issue.

See also
  cpl_frameset_get_size(), cpl_frameset_get_first_const(), cpl_frameset_get_next_const()

Deprecated
  This function will be removed from CPL version 7. Code using these functions should use cpl_frameset_get_position_const() instead!

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_frameset_get_position_const(), and cpl_frameset_get_size().

## cpl_frameset_get_next()

cpl_frame * cpl_frameset_get_next | ( | cpl_frameset * | self | ) |

Get the next frame in the given set.

Parameters

  self | A frame set.

Returns
  A handle for the next frame in a set. If there are no more frames in the set the function returns `NULL`. The function returns `NULL` if an error occurs and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

The function returns the next frame in the frame set self if it exists and otherwise `NULL`. The function uses the internal cache to determine the most recently accessed frame. This means that the function only works as expected if self has been initialised by a call to cpl_frameset_get_first(), and if no function updating the internal cache was called between two subsequent calls to this function.

See also
  cpl_frameset_get_first()

Deprecated
  This function will be removed from CPL version 7. Code using these functions should be ported to make use of frame set iterators instead!

References CPL_ERROR_NULL_INPUT.

## cpl_frameset_get_next_const()

const cpl_frame * cpl_frameset_get_next_const | ( | const cpl_frameset * | self | ) |

Get the next frame in the given set.

Parameters

  self | A frame set.

Returns
  A handle for the next frame in a set. If there are no more frames in the set the function returns `NULL`. The function returns `NULL` if an error occurs and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

The function returns the next frame in the frame set self if it exists and otherwise `NULL`. The function uses the internal cache to determine the most recently accessed frame. This means that the function only works as expected if self has been initialised by a call to cpl_frameset_get_first_const(), and if no function updating the internal cache was called between two subsequent calls to this function.

See also
  cpl_frameset_get_first_const()

Deprecated
  This function will be removed from CPL version 7. Code using these functions should be ported to make use of frame set iterators instead!

References CPL_ERROR_NULL_INPUT.

## cpl_frameset_get_position()

cpl_frame * cpl_frameset_get_position | ( | cpl_frameset * | self,
|  | cpl_size | position )

Get the frame at a given position in the frame set.

Parameters

  self | The frame set
  position | Frame position.

Returns
  The function returns the frame at the given position, or `NULL` if an error occurs.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT | The parameter position is invalid, i.e. the given value is outside of its domain.

@enderror

The function retrieves the frame stored in the frame set self at the index position position. The index positions are counted from zero, and reach up to one less than the number of frames in the frame set.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and cpl_frameset_get_size().

Referenced by cpl_frameset_get_frame().

## cpl_frameset_get_position_const()

const cpl_frame * cpl_frameset_get_position_const | ( | const cpl_frameset * | self,
|  | cpl_size | position )

Get the frame at a given iterator position.

Parameters

  self | The iterator to dereference
  position | Iterator offset from the beginning of the frame set.

Returns
  The function returns the frame at the iterator position, or `NULL` if an error occurs.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT | The parameter position is invalid, i.e. the given value is outside of its domain.

@enderror

The function retrieves the frame stored in the frame set self at the index position position. The index positions are counted from zero, and reach up to one less than the number of frames in the frame set.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, and cpl_frameset_get_size().

Referenced by cpl_frameset_get_frame_const().

## cpl_frameset_get_size()

cpl_size cpl_frameset_get_size | ( | const cpl_frameset * | self | ) |

Get the current size of a frame set.

Parameters

  self | A frame set.

Returns
  The frame set's current size, or 0 if it is empty. The function returns 0 if an error occurs and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

The reports the current number of frames stored in the frame set self.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_dfs_setup_product_header(), cpl_frameset_dump(), cpl_frameset_get_frame(), cpl_frameset_get_frame_const(), cpl_frameset_get_position(), cpl_frameset_get_position_const(), and cpl_frameset_labelise().

## cpl_frameset_insert()

cpl_error_code cpl_frameset_insert | ( | cpl_frameset * | self,
|  | cpl_frame * | frame )

Insert a frame into the given frame set.

Parameters

  self | A frame set.
  frame | The frame to insert.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self or frame is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT | The parameter frame has an invalid tag.

@enderror

The function adds the frame frame to the frame set self using the frame's tag as key.

The insertion of a frame into a frameset transfers the ownership of the frame frame to the frameset self. This means that the frame must not be deallocated through the pointer frame.

In addition, the frame pointer returned by any member function call returning a handle to a frameset's member frame, must not be used to insert the returned frame into another frameset without prior duplication of this frame, and, it must not be used to modify the frames tag without removing it from the frameset first and re-inserting it with the new tag afterwards.

References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and cpl_frame_get_tag().

Referenced by cpl_frameset_extract(), and cpl_frameset_join().

## cpl_frameset_is_empty()

int cpl_frameset_is_empty | ( | const cpl_frameset * | self | ) |

Check whether a frame set is empty.

Parameters

  self | A frame set.

Returns
  The function returns 1 if the set is empty, and 0 otherwise. If an error occurs 0 is returned and an appropriate error code is set.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

The function checks if self contains any frames.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_dfs_sign_products(), and cpl_frameset_join().

## cpl_frameset_join()

cpl_error_code cpl_frameset_join | ( | cpl_frameset * | self,
|  | const cpl_frameset * | other )

Join two frame sets.

Parameters

  self | The target frame set
  other | The source frame set

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self or frame is a NULL pointer.

@enderror

The function adds the contents of the frame set other to self by inserting copies of the elements of the frame set other. If the source frame set other is `NULL`, or if it is empty, the function has no effect.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_frame_delete(), cpl_frame_duplicate(), cpl_frameset_insert(), and cpl_frameset_is_empty().

## cpl_frameset_labelise()

cpl_size * cpl_frameset_labelise | ( | const cpl_frameset * | self,
|  | int(* | compare )(const cpl_frame *, const cpl_frame *),
|  | cpl_size * | nb_labels )

Separate a list of frames into groups, using a comparison function.

Parameters

  self | Input frame set
  compare | Pointer to comparison function to use.
  nb_labels | Number of different sets or undefined on error

Returns
  array of labels defining the selection or NULL on error

@error

CPL_ERROR_NULL_INPUT | The parameter self, compare or nb_labels is a NULL pointer.

@enderror

This function takes a set of frames and groups the frames that are 'identical' together. The user provided comparison function defines what being identical means for two frames. A label (non-negative int) is associated to each group of identical frames, these labels are returned in an array of length equal to the size of the frameset.

The comparison function should be commutative, must take two frames and return 1 if they are identical, 0 if they are different, and -1 on error.

The number of calls to the comparison functions is O(n*m), where n is the number of frames in the set, and m is the number of different labels found in the set. In the worst case m equals n, and the call requires n(n-1)/2 calls to the comparison function. If all identical frames appear together in the list, the number of required calls is only n + O(m^2).

The returned array must be deallocated with cpl_free().

References cpl_ensure, CPL_ERROR_ACCESS_OUT_OF_RANGE, cpl_error_get_code(), CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), cpl_errorstate_set(), cpl_frameset_get_size(), cpl_frameset_iterator_advance(), cpl_frameset_iterator_delete(), cpl_frameset_iterator_get(), cpl_frameset_iterator_new(), cpl_msg_debug(), and CPL_SIZE_FORMAT.

## cpl_frameset_new()

cpl_frameset * cpl_frameset_new | ( | void |  | ) |

Create a new, empty frame set.

Returns
  The handle for the newly created frame set.

The function allocates the memory for the new frame set, initialises the set to be empty and returns a handle for it.

References cpl_frame_delete().

Referenced by cpl_frameset_duplicate(), and cpl_frameset_extract().

## cpl_frameset_sort()

cpl_error_code cpl_frameset_sort | ( | cpl_frameset * | self,
|  | cpl_frame_compare_func | compare )

Sort a frame set.

Parameters

  self | The frame set to sort.
  compare | Comparison function for frames.

Returns
  The function returns `CPL_ERROR_NONE` on success, or an appropriate CPL error code otherwise.

@error

- CPL_ERROR_NULL_INPUT | The parameter self or compare is a NULL pointer.

  @enderror

The function replaces the existing order of the frame set self by sorting its contents according to the comparison function compare.

By default, the order of a frame set, i.e. the order of any newly created frame set object, is defined by the order in which frames are inserted into the frame set. By calling this function, this order will be lost. If this order has to be preserved, sorting has to be done on a copy of self.

The function compare compares two frames and must return -1, 0, or 1 if the first frame is considered to be less than, equal or larger than the second frame, respectively.

See also
  cpl_frame_compare_func

References CPL_ERROR_NULL_INPUT.