subs(C++)

Synopsis

   template <class T>
   void subs(
        const T& val1,
        const T& val2,
        T* b,
        T* e
   );
   template <class T>
   void subs_c(
        const T& val1,
        const T& val2,
        T* b1,
        T* e1,
        T* b2
   );
   template <class T>
   void subs_r(
        int (*rel)(const T*,const T*),
        const T& val1,
        const T& val2,
        T* b,
        T* e
   );
   template <class T>
   void subs_rc(
        int (*rel)(const T*,const T*),
        const T& val1,
        const T& val2,
        T* b1,
        T* e1,
        T* b2
   );

Assumptions

(C)

For the non-relational versions, T::operator== defines an equivalence relation on T.

(S)

For the relational versions, rel defines an equivalence relation on T.

(S)

For the copy versions, the output array and the input array do not overlap.

(F)

For the copy versions, the output array has at least as many cells as the input array.

(M)

T has operator=.

Description

These functions assign the value val2 to every cell in the array which currently contains an element equal to val1.

   template <class T>
   void subs(
       const T& val1,
       const T& val2,
       T* b,
       T* e
       );

Uses T::operator== to define equality.

   template <class T>
   void subs_c(
       const T& val1,
       const T& val2,
       T* b1,
       T* e1,
       T* b2
       );

Like subs except that the input array is preserved and the result is written to a new array beginning at location b2.

   template <class T>
   void subs_r(
       int (*rel)(const T*,const T*),
       const T& val1,
       const T& val2,
       T* b,
       T* e
       );

Uses rel to define equality. That is, if p is a pointer into the array and rel(p,&val) initially gives zero, then after the call to subs p will point to a cell containing new_val.

   template <class T>
   void subs_rc(
       int (*rel)(const T*,const T*),
       const T& val1,
       const T& val2,
       T* b1,
       T* e1,
       T* b2
       );

Like subs_r except that the input array is preserved and the result is written to a new array beginning at location b2.

Complexity

If N is the size of the array, then complexity is O(N) for all versions. More precisely,

non-copy versions

Exactly N equality tests and at most N assignments are done.

copy versions

Exactly N equality tests and exactly N assignments are done.

Notes

Because a Block (see Block(3C++)) can always be used wherever an array is called for, Array Algorithms can also be used with Blocks. In fact, these two components were actually designed to be used together.

References