Services to support R subscripting operations. More...

#include <Subscripting.hpp>

Static Public Member Functions
template<class VL , class VR >
static VL *	arraySubassign (VL lhs, const ListVector indices, const VR *rhs)
	Assign to selected elements of an R matrix or array.
template<class VL , class VR >
static VL *	arraySubassign (VL lhs, const PairList subscripts, const VR *rhs)
	Assign to selected elements of an R matrix or array.
template<class V >
static V *	arraySubset (const V v, const ListVector indices, bool drop)
	Extract a subset from an R matrix or array.
template<class V >
static V *	arraySubset (const V v, const PairList subscripts, bool drop)
	Extract a subset from an R matrix or array.
static std::pair< const IntVector *, std::size_t >	canonicalize (const IntVector *raw_indices, std::size_t range_size)
	Obtain canonical index vector from an IntVector.
static std::pair< const IntVector *, std::size_t >	canonicalize (const LogicalVector *raw_indices, std::size_t range_size)
	Obtain canonical index vector from a LogicalVector.
static std::pair< const IntVector *, std::size_t >	canonicalize (const RObject raw_indices, std::size_t range_size, const StringVector range_names)
static std::pair< const IntVector *, std::size_t >	canonicalize (const StringVector raw_indices, std::size_t range_size, const StringVector range_names)
	Obtain canonical index vector from an StringVector.
static const ListVector *	canonicalizeArraySubscripts (const VectorBase v, const PairList subscripts)
static bool	dropDimensions (VectorBase *v)
	Remove dimensions of unit extent.
template<class VL , class VR >
static VL *	subassign (VL lhs, const PairList subscripts, const VR *rhs)
	Assign to selected elements of an R vector object.
template<class V >
static V *	subset (const V v, const PairList subscripts, bool drop)
	Extract a subset from an R vector, matrix or array.
template<class VL , class VR >
static VL *	vectorSubassign (VL lhs, const std::pair< const IntVector , std::size_t > &indices_pr, const VR *rhs)
	Assign to selected elements of an R vector object.
template<class VL , class VR >
static VL *	vectorSubassign (VL lhs, const RObject subscripts, const VR *rhs)
	Assign to selected elements of an R vector object.
template<class V >
static V *	vectorSubset (const V v, const IntVector indices)
	Extract a subset of an R vector object.
template<class V >
static V *	vectorSubset (const V v, const RObject subscripts)
	Extract a subset of an R vector object.

Detailed Description

Services to support R subscripting operations.

This class, all of whose members are static, encapsulates services supporting subscripting of R vector objects, including R matrices and arrays. Foremost among its member functions are subset() and subassign(); the other member functions are auxiliary to these two.

Canonical index vectors:: A canonical index vector is an IntVector in which each element is either NA or a strictly positive integer (representing an index into a vector counting from one). Various canonicalize() functions are provided to convert other forms of subscripting to the canonical form.

Note:: Under certain circumstances, a canonical index vector may have a use.names attribute. This attribute should be regarded as private to the Subscripting class, because its implementation (or indeed its use at all) may change in the future.

Todo:: At present this class does not handle the special case (described in sec. 3.4.2 of the R Language Definition) where subscripting is being applied to an array, and there is a single subscript which is a matrix with as many columns as the array has dimensions, each row of the matrix being used to pick out a single element of the array.

Todo:: A matter for possible review is the fact that during subsetting and subassignment operations, CXXR sometimes makes deep copies of vectors of RHandle objects in cases where CR gets away with simple pointer copies.

Member Function Documentation

template<class VL , class VR >

VL * CXXR::Subscripting::arraySubassign	(	VL *	lhs,
		const ListVector *	indices,
		const VR *	rhs
	)

static

Assign to selected elements of an R matrix or array.

Template Parameters:

VL	A type inheriting from VectorBase.
VR	A type inheriting from VectorBase.

Parameters:

lhs	Non-null pointer to a VL object, which is the object to whose elements assignment is to be made. Where feasible, the return value will point to lhs itself, modified appropriately (which is why this parameter is not `const`); otherwise the return value will point to a modified copy of lhs. (Copying will occur if lhs aliases rhs .)
indices	Pointer to a ListVector with as many elements as v has dimensions. Each element of the ListVector is a pointer to a canonical index vector giving the index values (counting from 1) to be selected for the corresponding dimension. All indices must be in range for the relevant dimension of v . NA_INTEGER is a permissible index value only if rhs has length one, in which case the index is ignored.
rhs	Non-null pointer to the vector from which values are to be taken. Successive elements are assigned to the locations within the result defined by the canonical index vectors in indices . If the number of elements selected by indices is greater than the size of rhs , the elements of rhs are repeated in rotation. It is an error for rhs to have zero elements unless no elements at all are selected by indices . A warning will be given if the number of elements selected by indices is not equal to or a multiple of the length of rhs .

Returns:: Pointer to the result of the assignment. Its attributes (including dimensions) will be identical to those of lhs .

template<class VL , class VR >

static VL* CXXR::Subscripting::arraySubassign	(	VL *	lhs,
		const PairList *	subscripts,
		const VR *	rhs
	)

inlinestatic

Assign to selected elements of an R matrix or array.

Template Parameters:

VL	A type inheriting from VectorBase.
VR	A type inheriting from VectorBase.

Parameters:

lhs	Non-null pointer to a VL object, which is the object to whose elements assignment is to be made. Where feasible, the return value will point to lhs itself, modified appropriately (which is why this parameter is not `const`); otherwise the return value will point to a modified copy of lhs. (Copying will occur if lhs aliases rhs .)
subscripts	Pointer, possibly null, to a list of objects inheriting from RObject , with the same number of elements as v has dimensions. (subscripts can be null only if v has zero dimensions.) The elements of the list represent the subscripting to be applied for successive dimensions of v . An error will be raised if the type or contents of any element is inappropriate for subscripting from the dimension in question.
rhs	Non-null pointer to the vector from which values are to be taken. Successive elements are assigned to the locations within the result defined by the canonical index vectors in indices . If the number of elements selected by subscripts is greater than the size of rhs , the elements of rhs are repeated in rotation. It is an error for rhs to have zero elements unless no elements at all are selected by subscripts . A warning will be given if the number of elements selected by subscripts is not equal to or a multiple of the length of rhs .

Returns:: Pointer to the result of the assignment. Its attributes (including dimensions) will be identical to those of lhs .

template<class V >

V * CXXR::Subscripting::arraySubset	(	const V *	v,
		const ListVector *	indices,
		bool	drop
	)

static

Extract a subset from an R matrix or array.

This function differs from the next one in that the indices parameter must contain canonical index vectors rather than arbitrary subscripting objects.

Template Parameters:

V	A type inheriting from VectorBase.

Parameters:

v	Non-null pointer to a V object, which is an R matrix or array from which a subset (not necessarily a proper subset) is to be extracted.
indices	Pointer to a ListVector with as many elements as v has dimensions. Each element of the ListVector is a pointer to a canonical index vector giving the index values (counting from 1) to be selected for the corresponding dimension. NA_INTEGER is a permissible index value, in which case any corresponding elements of the output array will have an NA value appropriate to type V . Otherwise, all indices must be in range for the relevant dimension of v .
drop	true iff any dimensions of unit extent are to be removed from the result.

Returns:: Pointer to a newly created object of type V , containing the designated subset of v .

template<class V >

static V* CXXR::Subscripting::arraySubset	(	const V *	v,
		const PairList *	subscripts,
		bool	drop
	)

inlinestatic

Extract a subset from an R matrix or array.

Template Parameters:

V	A type inheriting from VectorBase.

Parameters:

v	Non-null pointer to a V object, which is an R matrix or array from which a subset (not necessarily a proper subset) is to be extracted.
subscripts	Pointer, possibly null, to a list of objects inheriting from RObject , with the same number of elements as v has dimensions. (subscripts can be null only if v has zero dimensions.) The elements of the list represent the subscripting to be applied for successive dimensions of v . An error will be raised if the type or contents of any element is inappropriate for subscripting from the dimension in question.
drop	true iff any dimensions of unit extent are to be removed from the result.

Returns:: Pointer to a newly created object of type V , containing the designated subset of v .

static std::pair<const IntVector*, std::size_t> CXXR::Subscripting::canonicalize	(	const IntVector *	raw_indices,
		std::size_t	range_size
	)

static

Obtain canonical index vector from an IntVector.

Parameters:

raw_indices Non-null pointer to an IntVector. An error is raised if this vector is not of one of the two legal forms: (i) consisting entirely of non-negative integers and/or NAs; or (ii) consisting entirely of non-positive integers with no NAs. In case (i) the returned vector is obtained by omitting any zeroes from raw_indices . In case (ii) the returned vector is the sequence (possibly empty) from 1 to range_size , omitting any values which appear (negated) within raw_indices .

range_size The size of the vector or dimension into which indexing is being performed.

Returns:: The first element of the returned value is a pointer to the canonicalised index vector. The second element is the minimum size implied by raw_indices for the vector or dimension into which indexing is being performed. If this exceeds range_size it means that an attempt is being made to read from or write to elements beyond the end of the range.

static std::pair<const IntVector*, std::size_t> CXXR::Subscripting::canonicalize	(	const LogicalVector *	raw_indices,
		std::size_t	range_size
	)

static

Obtain canonical index vector from a LogicalVector.

In the normal case, where raw_indices is non-empty, the action of this function can be understood by imagining that internally the function constructs an effective lvector comprising logical values (including NA). This effective lvector is constructed by starting with a copy of raw_indices. If the resulting lvector is smaller than range_size , its elements are repeated in rotation to bring it up to range_size .

The canonical index vector is then generated by working through the elements of the effective lvector in order. Any element that is zero is ignored. Any element that is NA results in an NA being appended to the canonical index vector. Any element of the lvector that has any other value results in that element's position within the lvector (counting from 1) being appended to the canonical index vector.

Parameters:

raw_indices	Non-null pointer to a LogicalVector. If this is empty, the returned index vector will also be empty. Otherwise the behaviour is as described above.
range_size	The size of the vector or dimension into which indexing is being performed.

Returns:: The first element of the returned value is a pointer to the canonicalised index vector. The second element is the minimum size implied by raw_indices for the vector or dimension into which indexing is being performed; this will be whichever is greater of range_size or the size of raw_indices . If this exceeds range_size it means that an attempt is being made to read or write from elements beyond the end of the range.

static std::pair<const IntVector*, std::size_t> CXXR::Subscripting::canonicalize	(	const RObject *	raw_indices,
		std::size_t	range_size,
		const StringVector *	range_names
	)

static

Obtain canonical index vector from an arbitrary subscript object.

Parameters:

raw_indices	Pointer, possibly null, to an RObject. If the type and contents of this object are legal for subscripting, canonicalization will be performed accordingly; otherwise an error will be raised.
range_size	The size of the vector or dimension into which indexing is being performed.
range_names	Pointer, possibly null, to the vector of names associated with the vector or dimension into which indexing is being performed. If present, the size of this vector must be equal to range_size .

Returns:: The first element of the returned value is a pointer to the canonicalised index vector. The second element is the minimum size implied by subscripts for the vector or dimension into which indexing is being performed. If this exceeds the size of v it means that an attempt is being made to read or write from elements beyond the end of the range.

static std::pair<const IntVector*, std::size_t> CXXR::Subscripting::canonicalize	(	const StringVector *	raw_indices,
		std::size_t	range_size,
		const StringVector *	range_names
	)

static

Obtain canonical index vector from an StringVector.

Parameters:

raw_indices	Non-null pointer to a StringVector. Any element of this which is blank or NA will be mapped to NA in the resulting canonical index vector. Any non-blank, non-NA element which matches a name in range_names will be mapped to the corresponding index. (If there are duplicate names in range_names it will be mapped to the lowest corresponding index.) Any non-blank, non-NA element which does not match a name in range_names will be considered to be associated with a supplementary element of the range into which indexing is being performed; this supplementary element will be allocated the lowest (positive) index number not already used.
range_size	The size of the vector or dimension into which indexing is being performed.
range_names	Pointer, possibly null, to the vector of names associated with the vector or dimension into which indexing is being performed. If present, the size of this vector must be equal to range_size .

Returns:: The first element of the returned value is a pointer to the canonicalised index vector. The second element is normally equal to the size of range_names . However, if raw_indices contained at least one non-blank, non-null name unmatched in range_names , then the second element of the return value will exceed the size of range_names by the number of such names encountered, each of which will have been mapped to a supplementary element of the vector being indexed. In that case, the first element of the return value will have the attribute 'use.names' set to a ListVector of the same size as raw_indices . All the elements of this ListVector are NULL, except where the corresponding element of raw_indices was mapped into a supplementary vector element, in which case the ListVector element will be a String giving the name of that supplementary vector element.

Note:: The use.names attribute should be regarded as private to the Subscripting class, because its implementation (or indeed its use at all) may change in the future.

static const ListVector* CXXR::Subscripting::canonicalizeArraySubscripts	(	const VectorBase *	v,
		const PairList *	subscripts
	)

static

Canonicalize a list of subscript objects for indexing an R matrix/array.

Parameters:

v Non-null pointer to the VectorBase to which subscripting is to be applied.

subscripts Pointer, possibly null, to a list of objects inheriting from RObject , with the same number of elements as v has dimensions. (subscripts can be null only if v has zero dimensions.) The elements of the list represent the subscripting to be applied for successive dimensions of v . An error will be raised if the type or contents of any element is inappropriate for subscripting from the dimension in question.

Returns:: Pointer to a ListVector with the same number of elements as subscripts , each element of the ListVector being the canonicalized index vector for the corresponding dimension.

static bool CXXR::Subscripting::dropDimensions ( VectorBase * v )

static

Remove dimensions of unit extent.

If v does not point to an R matrix or array, v is left unchanged and the function returns false.

Otherwise, the function will examine v to determine if it has any dimensions with just one level, in which case those dimensions are removed, and the corresponding 'dimnames' (if any) are discarded.

If, after dropping dimensions, only one dimension is left, then v is converted to a vector, with its 'names' attribute taken from the 'dimnames' (if any) of the surviving dimension.

If all the original dimensions were of unit extent, then again v is converted to a vector (with a single element). This vector is given a 'names' attribute only if just one of the original dimensions had associated 'dimnames', in which case the 'names' are taken from them.

Parameters:

v	Non-null pointer to the vector whose dimensions are to be examined and if necessary modified.

Returns:: true if any dimensions were dropped, otherwise false.

template<class VL , class VR >

VL * CXXR::Subscripting::subassign	(	VL *	lhs,
		const PairList *	subscripts,
		const VR *	rhs
	)

static

Assign to selected elements of an R vector object.

Template Parameters:

VL	A type inheriting from VectorBase.
VR	A type inheriting from VectorBase.

Parameters:

lhs	Non-null pointer to a VL object, which is the object to whose elements assignment is to be made. Where feasible, the return value will point to lhs itself, modified appropriately (which is why this parameter is not `const`); otherwise the return value will point to a modified copy of lhs. (Copying will occur for example if lhs aliases rhs .)
subscripts	Pointer, possibly null, to a list of objects inheriting from RObject . If lhs is an R matrix or array, then it is permissible for the list to have as many elements as lhs has dimensions, and in that case array subassignment is applied, as described for method arraySubassign(). If the foregoing condition does not apply, then the list must have either zero or one elements, and vector subassignment is applied, as described for method vectorSubassign().
rhs	Non-null pointer to the vector from which values are to be taken. Successive elements are assigned to the locations within the result defined by the subscripts. If the return vector is larger than rhs , the elements of rhs are repeated in rotation. It is an error for rhs to have zero elements unless subscripts selects no locations at all. A warning will be given if the number of locations to be assigned to is not equal to or a multiple of the length of rhs .

Returns:: Pointer to the result of the assignment. Refer to the descriptions of vectorSubassign() and arraySubassign() for further details.

template<class V >

V * CXXR::Subscripting::subset	(	const V *	v,
		const PairList *	subscripts,
		bool	drop
	)

static

Extract a subset from an R vector, matrix or array.

Template Parameters:

V	A type inheriting from VectorBase.

Parameters:

v	Non-null pointer to a V object from which a subset (not necessarily a proper subset) is to be extracted.
subscripts	Pointer, possibly null, to a list of objects inheriting from RObject . If v is an R matrix or array, then it is permissible for the list to have as many elements as v has dimensions, and in that case array subsetting is applied, as described for method arraySubset(). If the foregoing condition does not apply, then the list must have either zero or one elements, and vector subsetting is applied, as described for method vectorSubset().
drop	true iff any dimensions of unit extent are to be removed from the result. Ignored if vector subsetting is used.

Returns:: Pointer to a newly created object of type V , containing the designated subset of v .

template<class VL , class VR >

VL * CXXR::Subscripting::vectorSubassign	(	VL *	lhs,
		const std::pair< const IntVector *, std::size_t > &	indices_pr,
		const VR *	rhs
	)

static

Assign to selected elements of an R vector object.

Template Parameters:

VL	A type inheriting from VectorBase.
VR	A type inheriting from VectorBase.

Parameters:

lhs	Non-null pointer to a VL object, which is the object to whose elements assignment is to be made. Where feasible, the return value will point to lhs itself, modified appropriately (which is why this parameter is not `const`); otherwise the return value will point to a modified copy of lhs. (Copying will occur if lhs aliases either rhs or the first element of indices_pr , or if the return vector needs to be larger than lhs .)
indices_pr	A pair as returned by one of the canonicalization functions. The first element of the pair points to a canonical index vector, and the second element is the minimum size implied by the supplied subscripts for the returned vector. It is an error for the canonical index vector to contain any NAs if rhs contains more than one element.
rhs	Non-null pointer to the vector from which values are to be taken. Successive elements are assigned to the locations within the result defined by the canonical index vector in indices_pr . If the return vector is larger than rhs , the elements of rhs are repeated in rotation. It is an error for rhs to have zero elements, unless subscripts selects no locations at all. A warning will be given if the number of indices in the canonical index vector is not equal to or a multiple of the length of rhs .

Returns:: Pointer to the result of the assignment. The size of the this vector will be whichever is larger of the the size of lhs or the second element of indices_pr . If the result is larger than lhs , then any supplementary elements not assigned to by the specified indices will be set to the NA value of VL::value_type .

template<class VL , class VR >

static VL* CXXR::Subscripting::vectorSubassign	(	VL *	lhs,
		const RObject *	subscripts,
		const VR *	rhs
	)

inlinestatic

Assign to selected elements of an R vector object.

Template Parameters:

VL	A type inheriting from VectorBase.
VR	A type inheriting from VectorBase.

Parameters:

lhs	Non-null pointer to a VL object, which is the object to whose elements assignment is to be made. Where feasible, the return value will point to lhs itself, modified appropriately (which is why this parameter is not `const`); otherwise the return value will point to a modified copy of lhs. (Copying will occur if lhs aliases either rhs or the first element of indices_pr , or if the return vector needs to be larger than lhs .)
subscripts	Pointer, possibly null, to an RObject. If the type and context of this object are legal for subscripting, subassignment will be performed accordingly; otherwise an error will be raised. It is an error for the subscripts to give rise to any NA index values of rhs contains more than one element.
rhs	Non-null pointer to the vector from which values are to be taken. Successive elements are assigned to the locations within the result defined by the subscripts. If the return vector is larger than rhs , the elements of rhs are repeated in rotation. It is an error for rhs to have zero elements, unless subscripts selects no locations at all. A warning will be given if the number of locations to be assigned to is not equal to or a multiple of the length of rhs .

Returns:: Pointer to the result of the assignment. The size of the this vector will be whichever is larger of the the size of lhs or the minimum size implied by subscripts . If the result is larger than lhs , then any supplementary elements not assigned to by the specified subscripts will be set to the NA value of VL::value_type .

template<class V >

V * CXXR::Subscripting::vectorSubset	(	const V *	v,
		const IntVector *	indices
	)

static

Extract a subset of an R vector object.

Template Parameters:

V	A type inheriting from VectorBase.

Parameters:

v Non-null pointer to a V object, which is the object from which a subset (not necessarily a proper subset) is to be extracted.

indices Non-null pointer to a canonical index vector designating the elements of v to be included as successive elements of the output vector, which will be the same size as indices . NA_INTEGER is a permissible index value, in which case the corresponding element of the output vector will have an NA value appropriate to type V . If an index is out of range with respect to v , in that case also the corresponding element of the output vector will have an NA value appropriate to type V .

Returns:: Pointer to a newly created object of type V , containing the designated subset of v .

template<class V >

static V* CXXR::Subscripting::vectorSubset	(	const V *	v,
		const RObject *	subscripts
	)

inlinestatic

Extract a subset of an R vector object.

Template Parameters:

V	A type inheriting from VectorBase.

Parameters:

v	Non-null pointer to a V object, which is the object from which a subset (not necessarily a proper subset) is to be extracted.
subscripts	Pointer, possibly null, to an RObject. If the type and contents of this object are legal for subscripting, subsetting will be performed accordingly; otherwise an error will be raised.

Returns:: Pointer to a newly created object of type V , containing the designated subset of v .

The documentation for this class was generated from the following file:

Subscripting.hpp ($Id: Subscripting.hpp 1348 2013-02-25 17:49:03Z arr $)

Static Public Member Functions

Detailed Description

Member Function Documentation