NAG CL Interface
m01esc (reorder_​vector)

Settings help

CL Name Style:


1 Purpose

m01esc rearranges a vector of arbitrary type data objects into the order specified by a vector of indices.

2 Specification

#include <nag.h>
void  m01esc (Pointer vec, size_t n, size_t size, ptrdiff_t stride, size_t indices[], NagError *fail)
The function may be called by the names: m01esc, nag_sort_reorder_vector or nag_reorder_vector.

3 Description

m01esc uses a variant of list merging as described by Knuth (1973). The function rearranges a set of n data objects of arbitrary type, which are stored in an array at intervals of length stride, into the order specified by an array of indices.

4 References

Knuth D E (1973) The Art of Computer Programming (Volume 3) (2nd Edition) Addison–Wesley

5 Arguments

1: vec[n] Pointer  Input/Output
On entry: the array of objects to be rearranged.
On exit: the objects rearranged according to array indices.
2: n size_t Input
On entry: the number, n , of objects to be rearranged.
Constraint: 0nMAX_LENGTH, where MAX_LENGTH is an implementation-dependent value for the maximum size of an array.
3: size size_t Input
On entry: the size of each object to be rearranged.
Constraint: 1sizep, where p is an implementation-dependent value for the maximum size_t size on the system, divided by n if n is positive.
4: stride ptrdiff_t Input
On entry: the increment between data items in vec to be rearranged.
Note: if stride is positive, vec should point at the first data object; otherwise vec should point at the last data object.
Constraint: size|stride|p, where p is an implementation-dependent value for the maximum size_t size on the system, divided by n if n is positive.
5: indices[n] size_t Input
On entry: the indices specifying the order in which the elements of vector are to be rearranged.
6: fail NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_2_INT_ARG_LT
On entry, |stride| = value while size=value . These arguments must satisfy |stride| size .
NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_BAD_RANK
Invalid indices vector.
NE_INT_ARG_GT
On entry, n=value.
Constraint: nvalue, an implementation-dependent size that is printed in the error message.
On entry, size=value.
Constraint: sizevalue, an implementation-dependent size that is printed in the error message.
On entry, stride=value.
Constraint: |stride|value, an implementation-dependent size that is printed in the error message.
NE_INT_ARG_LT
On entry, n=value.
Constraint: n0.
On entry, size=value.
Constraint: size1.

7 Accuracy

Not applicable.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
m01esc is not threaded in any implementation.

9 Further Comments

The average time taken by the function is approximately proportional to n.

10 Example

The example program.

10.1 Program Text

Program Text (m01esce.c)

10.2 Program Data

Program Data (m01esce.d)

10.3 Program Results

Program Results (m01esce.r)