view release on metacpan or  search on metacpan

lib/Image/Leptonica/Func/ptra.pm  view on Meta::CPAN

=head2 ptraGetMaxIndex

l_int32 ptraGetMaxIndex ( L_PTRA *pa, l_int32 *pmaxindex )

  ptraGetMaxIndex()

      Input:  ptra
              &maxindex (<return> index of last item in the array);
      Return: 0 if OK; 1 on error

  Notes:
      (1) The largest index to an item in the array is @maxindex.
          @maxindex is one less than the number of items that would be
          in the array if there were no null pointers between 0
          and @maxindex - 1.  However, because the internal ptr array
          need not be compacted, there may be null pointers at
          indices below @maxindex; for example, if items have
          been removed.
      (2) When an item is added to the end of the array, it goes
          into pa->array[maxindex + 1], and maxindex is then
          incremented by 1.
      (3) If there are no items in the array, this returns @maxindex = -1.

=head2 ptraGetPtrToItem

void * ptraGetPtrToItem ( L_PTRA *pa, l_int32 index )

  ptraGetPtrToItem()

      Input:  ptra
              index (of element to be retrieved)
      Return: a ptr to the element, or null on error

  Notes:
      (1) This returns a ptr to the item.  You must cast it to
          the type of item.  Do not destroy it; the item belongs
          to the Ptra.
      (2) This can access all possible items on the ptr array.
          If an item doesn't exist, it returns null.

=head2 ptraInsert

l_int32 ptraInsert ( L_PTRA *pa, l_int32 index, void *item, l_int32 shiftflag )

  ptraInsert()

      Input:  ptra
              index (location in ptra to insert new value)
              item  (generic ptr to a struct; can be null)
              shiftflag (L_AUTO_DOWNSHIFT, L_MIN_DOWNSHIFT, L_FULL_DOWNSHIFT)
      Return: 0 if OK, 1 on error

  Notes:
      (1) This checks first to see if the location is valid, and
          then if there is presently an item there.  If there is not,
          it is simply inserted into that location.
      (2) If there is an item at the insert location, items must be
          moved down to make room for the insert.  In the downward
          shift there are three options, given by @shiftflag.
            - If @shiftflag == L_AUTO_DOWNSHIFT, a decision is made
              whether, in a cascade of items, to downshift a minimum
              amount or for all items above @index.  The decision is
              based on the expectation of finding holes (null ptrs)
              between @index and the bottom of the array.
              Assuming the holes are distributed uniformly, if 2 or more
              holes are expected, we do a minimum shift.
            - If @shiftflag == L_MIN_DOWNSHIFT, the downward shifting
              cascade of items progresses a minimum amount, until
              the first empty slot is reached.  This mode requires
              some computation before the actual shifting is done.
            - If @shiftflag == L_FULL_DOWNSHIFT, a shifting cascade is
              performed where pa[i] --> pa[i + 1] for all i >= index.
              Then, the item is inserted at pa[index].
      (3) If you are not using L_AUTO_DOWNSHIFT, the rule of thumb is
          to use L_FULL_DOWNSHIFT if the array is compacted (each
          element points to an item), and to use L_MIN_DOWNSHIFT
          if there are a significant number of null pointers.
          There is no penalty to using L_MIN_DOWNSHIFT for a
          compacted array, however, because the full shift is required
          and we don't do the O(n) computation to look for holes.
      (4) This should not be used repeatedly on large arrays,
          because the function is generally O(n).
      (5) However, it can be used repeatedly if we start with an empty
          ptr array and insert only once at each location.  For example,
          you can support an array of Numa, where at each ptr location
          you store either 0 or 1 Numa, and the Numa can be added
          randomly to the ptr array.

=head2 ptraJoin

l_int32 ptraJoin ( L_PTRA *pa1, L_PTRA *pa2 )

  ptraJoin()

      Input:  ptra1 (add to this one)
              ptra2 (appended to ptra1, and emptied of items; can be null)
      Return: 0 if OK, 1 on error

=head2 ptraRemove

void * ptraRemove ( L_PTRA *pa, l_int32 index, l_int32 flag )

  ptraRemove()

      Input:  ptra
              index (element to be removed)
              flag (L_NO_COMPACTION, L_COMPACTION)
      Return: item, or null on error

  Notes:
      (1) If flag == L_NO_COMPACTION, this removes the item and
          nulls the ptr on the array.  If it takes the last item
          in the array, pa->n is reduced to the next item.
      (2) If flag == L_COMPACTION, this compacts the array for
          for all i >= index.  It should not be used repeatedly on
          large arrays, because compaction is O(n).
      (3) The ability to remove without automatic compaction allows
          removal with cost O(1).

=head2 ptraRemoveLast

void * ptraRemoveLast ( L_PTRA *pa )

  ptraRemoveLast()

      Input:  ptra
      Return: item, or null on error or if the array is empty

=head2 ptraReplace

void * ptraReplace ( L_PTRA *pa, l_int32 index, void *item, l_int32 freeflag )