# subs(3C++)

**subs --
substitute a new value for elements of an array equal to a given value
**

## 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

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

(2)-
For the relational versions,
**rel** defines an equivalence
relation on **T**.

(3)-
For the copy versions, the output array and the input array do not overlap.

(4)-
For the copy versions, the output array has at least as many cells as the
input array.

(5)-
**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

**Array_alg**(3C++),
**Block**(3C++),
**fill**(3C++),
**for_each**(3C++),
**generate**(3C++)

*
© 2004 The SCO Group, Inc. All rights reserved.
*

UnixWare 7 Release 7.1.4 - 25 April 2004