ajrange.c


Section: Range Constructors

All constructors return a new object by pointer. It is the responsibility of the user to first destroy any previous object. The target pointer does not need to be initialised to NULL, but it is good programming practice to do so anyway.

Functions: ajRangeNewI ajRangeNewFilename ajRangeNewFilenameLimits ajRangeNewRange ajRangeNewString ajRangeNewStringLimits


Function ajRangeNewI

Default constructor for AJAX range objects.

Synopsis

Prototype
AjPRange ajRangeNewI (
      ajuint n
);

TypeNameRead/WriteDescription
ajuintnInputnumber of ranges
AjPRange RETURNPointer to a range object

Input
n:(Input)number of ranges
Returns
AjPRange:Pointer to a range object

Description

Default constructor for AJAX range objects.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeNewFilename

Load a range object from a file

The format of the range file is: Comment lines start with '#' in the first column. Comment lines and blank lines are ignored. The line may start with white-space. There are two positive numbers per line separated by white-space. The second number must be greater or equal to the first number. There is optional text after the two numbers. White-space before or after the text is removed.

e.g.:

# this is my set of ranges 12 23 4 5 this is like 12-23, but smaller 67 10348 interesting region

Synopsis

Prototype
AjPRange ajRangeNewFilename (
      const AjPStr name
);

TypeNameRead/WriteDescription
const AjPStrnameInputrange file name
AjPRange RETURNrange object

Input
name:(Input)range file name
Returns
AjPRange:range object

Description

Load a range object from a file

The format of the range file is: Comment lines start with '#' in the first column. Comment lines and blank lines are ignored. The line may start with white-space. There are two positive numbers per line separated by white-space. The second number must be greater or equal to the first number. There is optional text after the two numbers. White-space before or after the text is removed.

e.g.:

# this is my set of ranges 12 23 4 5 this is like 12-23, but smaller 67 10348 interesting region

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeNewFilenameLimits

Load a range object from a file

The format of the range file is: Comment lines start with '#' in the first column. Comment lines and blank lines are ignored. The line may start with white-space. There are two positive numbers per line separated by white-space. The second number must be greater or equal to the first number. There is optional text after the two numbers. White-space before or after the text is removed.

e.g.:

# this is my set of ranges 12 23 4 5 this is like 12-23, but smaller 67 10348 interesting region

Synopsis

Prototype
AjPRange ajRangeNewFilenameLimits (
      const AjPStr name,
      ajuint imin,
      ajuint imax,
      ajuint minsize,
      ajuint size
);

TypeNameRead/WriteDescription
const AjPStrnameInputrange file name
ajuintiminInputMinimum value
ajuintimaxInputMaximum value
ajuintminsizeInputMinimum number of values
ajuintsizeInputRequired number of values, zero for unlimited
AjPRange RETURNrange object

Input
name:(Input)range file name
imin:(Input)Minimum value
imax:(Input)Maximum value
minsize:(Input)Minimum number of values
size:(Input)Required number of values, zero for unlimited
Returns
AjPRange:range object

Description

Load a range object from a file

The format of the range file is: Comment lines start with '#' in the first column. Comment lines and blank lines are ignored. The line may start with white-space. There are two positive numbers per line separated by white-space. The second number must be greater or equal to the first number. There is optional text after the two numbers. White-space before or after the text is removed.

e.g.:

# this is my set of ranges 12 23 4 5 this is like 12-23, but smaller 67 10348 interesting region

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeNewRange

Copy constructor for AJAX range objects.

Synopsis

Prototype
AjPRange ajRangeNewRange (
      const AjPRange src
);

TypeNameRead/WriteDescription
const AjPRangesrcInputSource range
AjPRange RETURNPointer to a range object

Input
src:(Input)Source range
Returns
AjPRange:Pointer to a range object

Description

Copy constructor for AJAX range objects.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeNewString

Create a range object from a string

Synopsis

Prototype
AjPRange ajRangeNewString (
      const AjPStr str
);

TypeNameRead/WriteDescription
const AjPStrstrInputrange string
AjPRange RETURNrange object

Input
str:(Input)range string
Returns
AjPRange:range object

Description

Create a range object from a string

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeNewStringLimits

Create a range object from a string

Synopsis

Prototype
AjPRange ajRangeNewStringLimits (
      const AjPStr str,
      ajuint imin,
      ajuint imax,
      ajuint minsize,
      ajuint size
);

TypeNameRead/WriteDescription
const AjPStrstrInputrange string
ajuintiminInputMinimum value
ajuintimaxInputMaximum value
ajuintminsizeInputMinimum number of values
ajuintsizeInputRequired number of values, zero for unlimited
AjPRange RETURNrange object

Input
str:(Input)range string
imin:(Input)Minimum value
imax:(Input)Maximum value
minsize:(Input)Minimum number of values
size:(Input)Required number of values, zero for unlimited
Returns
AjPRange:range object

Description

Create a range object from a string

See Also

See other functions in this section

Availability

In release 6.4.0

Section: Range Destructors

Default destructor for AJAX range objects

Functions: ajRangeDel


Function ajRangeDel

Default destructor for AJAX range objects.

Synopsis

Prototype
void ajRangeDel (
      AjPRange* thys
);

TypeNameRead/WriteDescription
AjPRange*thysDeleterange structure
void RETURN

Output
thys:(Delete)range structure
Returns
void:No return value

Description

Default destructor for AJAX range objects.

See Also

See other functions in this section

Availability

In release 6.4.0

Section: Range Functions

Other functions for AJAX range objects

Functions: ajRangeGetSize ajRangeElementGetText ajRangeElementGetValues ajRangeElementSet ajRangeSetOffset ajRangeSeqExtractList ajRangeSeqExtract ajRangeSeqExtractPep ajRangeSeqStuff ajRangeSeqStuffPep ajRangeSeqMask ajRangeSeqToLower ajRangeStrExtractList ajRangeStrExtract ajRangeStrStuff ajRangeStrMask ajRangeStrToLower ajRangeElementTypeOverlap ajRangeCountOverlaps ajRangeIsOrdered ajRangeIsWhole


Function ajRangeGetSize

Return the number of ranges in a range object

Synopsis

Prototype
ajuint ajRangeGetSize (
      const AjPRange thys
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
ajuint RETURNnumber of ranges

Input
thys:(Input)range object
Returns
ajuint:number of ranges

Description

Return the number of ranges in a range object

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeElementGetText

Return (as parameters) text value of a range element

The text value of a range is any non-digit after the pair of range numbers e.g. in a pair of range '10-20 potential exon 50-60 repeat' the text values of the two ranges are: 'potential exon' and 'repeat'

Synopsis

Prototype
AjBool ajRangeElementGetText (
      const AjPRange thys,
      ajuint element,
      AjPStr* text
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
ajuintelementInputrange element (0 to n-1)
AjPStr*textOutputtext value
AjBool RETURNtrue if range exists

Input
thys:(Input)range object
element:(Input)range element (0 to n-1)
Output
text:(Output)text value
Returns
AjBool:true if range exists

Description

Return (as parameters) text value of a range element

The text value of a range is any non-digit after the pair of range numbers e.g. in a pair of range '10-20 potential exon 50-60 repeat' the text values of the two ranges are: 'potential exon' and 'repeat'

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeElementGetValues

Return (as parameters) start and end values in a range

Synopsis

Prototype
AjBool ajRangeElementGetValues (
      const AjPRange thys,
      ajuint element,
      ajuint* start,
      ajuint* end
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
ajuintelementInputrange element (0 to n-1)
ajuint*startOutputstart value
ajuint*endOutputend value
AjBool RETURNtrue if range exists

Input
thys:(Input)range object
element:(Input)range element (0 to n-1)
Output
start:(Output)start value
end:(Output)end value
Returns
AjBool:true if range exists

Description

Return (as parameters) start and end values in a range

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeElementSet

Set the values of a start and end in a (pre-existing) range element

Synopsis

Prototype
AjBool ajRangeElementSet (
      AjPRange thys,
      ajuint element,
      ajuint start,
      ajuint end
);

TypeNameRead/WriteDescription
AjPRangethysOutputrange object
ajuintelementInputrange element (0 to n-1)
ajuintstartInputstart value
ajuintendInputend value
AjBool RETURNtrue if range exists

Input
element:(Input)range element (0 to n-1)
start:(Input)start value
end:(Input)end value
Output
thys:(Output)range object
Returns
AjBool:true if range exists

Description

Set the values of a start and end in a (pre-existing) range element

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeSetOffset

Sets the range values offset relative to the Begin value.

Used when a sequence has -sbegin= and -send= parameters set and we have extracted the specified subsequence. So if -sbeg 11 has been set and the range is 11-12 the resulting range is changed to 1-2

Synopsis

Prototype
AjBool ajRangeSetOffset (
      AjPRange thys,
      ajuint begin
);

TypeNameRead/WriteDescription
AjPRangethysModifyrange object
ajuintbeginInputbegin parameter obtained from ajSeqGetBegin(seq)
AjBool RETURNtrue if region values modified

Input
begin:(Input)begin parameter obtained from ajSeqGetBegin(seq)
Input & Output
thys:(Modify)range object
Returns
AjBool:true if region values modified

Description

Sets the range values offset relative to the Begin value.

Used when a sequence has -sbegin= and -send= parameters set and we have extracted the specified subsequence. So if -sbeg 11 has been set and the range is 11-12 the resulting range is changed to 1-2

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeSeqExtractList

Extract the range from a sequence and place the resulting text in a list of strings.

N.B. the resulting list will be regions of the input sequence listed in the order specified in the set of ranges. If these are not in ascending order, the resulting list of strings will not be in ascending order either.

Synopsis

Prototype
AjBool ajRangeSeqExtractList (
      const AjPRange thys,
      const AjPSeq seq,
      AjPList outliststr
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
const AjPSeqseqInputsequence to extract from
AjPListoutliststrOutputresulting list of strings
AjBool RETURNtrue if result is not the whole sequence

Input
thys:(Input)range object
seq:(Input)sequence to extract from
Output
outliststr:(Output)resulting list of strings
Returns
AjBool:true if result is not the whole sequence

Description

Extract the range from a sequence and place the resulting text in a list of strings.

N.B. the resulting list will be regions of the input sequence listed in the order specified in the set of ranges. If these are not in ascending order, the resulting list of strings will not be in ascending order either.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeSeqExtract

Extract the range from a sequence (Remove regions not in the range(s)) N.B. the resulting sequence will be regions of the original concatenated in the order specified in the set of ranges. If these are not in ascending order, the resulting sequence will not be in position order either.

Synopsis

Prototype
AjBool ajRangeSeqExtract (
      const AjPRange thys,
      AjPSeq seq
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
AjPSeqseqModifySequence
AjBool RETURNtrue if sequence was modified

Input
thys:(Input)range object
Input & Output
seq:(Modify)Sequence
Returns
AjBool:true if sequence was modified

Description

Extract the range from a sequence (Remove regions not in the range(s)) N.B. the resulting sequence will be regions of the original concatenated in the order specified in the set of ranges. If these are not in ascending order, the resulting sequence will not be in position order either.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeSeqExtractPep

Extract the range from a sequence (Remove regions not in the range(s)) and translate to protein.

N.B. the resulting sequence will be regions of the original concatenated in the order specified in the set of ranges. If these are not in ascending order, the resulting sequence will not be in position order either.

Synopsis

Prototype
AjPSeq ajRangeSeqExtractPep (
      const AjPRange thys,
      AjPSeq seq,
      const AjPTrn trntable,
      ajint frame
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
AjPSeqseqModifySequence
const AjPTrntrntableInputTranslation table
ajintframeInputReading frame 1..3 or -1..-3
AjPSeq RETURNTranslated protein sequence

Input
thys:(Input)range object
trntable:(Input)Translation table
frame:(Input)Reading frame 1..3 or -1..-3
Input & Output
seq:(Modify)Sequence
Returns
AjPSeq:Translated protein sequence

Description

Extract the range from a sequence (Remove regions not in the range(s)) and translate to protein.

N.B. the resulting sequence will be regions of the original concatenated in the order specified in the set of ranges. If these are not in ascending order, the resulting sequence will not be in position order either.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeSeqStuff

The opposite of ajRangeSeqExtract() Stuff space characters into a string to pad out to the range.

It takes a string and an ordered, non-overlapping set of ranges and puts spaces into the string between the ranges. So starting with the string 'abcde' and the ranges 3-5,7-8 it will produce: ' abc de'

Synopsis

Prototype
AjBool ajRangeSeqStuff (
      const AjPRange thys,
      AjPSeq seq
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
AjPSeqseqModifySequence to be modified
AjBool RETURNtrue if sequence was modified

Input
thys:(Input)range object
Input & Output
seq:(Modify)Sequence to be modified
Returns
AjBool:true if sequence was modified

Description

The opposite of ajRangeSeqExtract() Stuff space characters into a string to pad out to the range.

It takes a string and an ordered, non-overlapping set of ranges and puts spaces into the string between the ranges. So starting with the string 'abcde' and the ranges 3-5,7-8 it will produce: ' abc de'

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeSeqStuffPep

The opposite of ajRangeSeqExtractPep() Stuff space characters into a translated string to pad out to the range.

It takes a string and an ordered, non-overlapping set of ranges and puts spaces into the string between the ranges. So starting with the string 'abcde' and the ranges 3-5,7-8 it will produce: ' abc de'

Synopsis

Prototype
AjBool ajRangeSeqStuffPep (
      const AjPRange thys,
      AjPSeq seq,
      ajint frame
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
AjPSeqseqModifySequence to be modified
ajintframeInputReading frame 1..3 or -1..-3
AjBool RETURNtrue if sequence was modified

Input
thys:(Input)range object
frame:(Input)Reading frame 1..3 or -1..-3
Input & Output
seq:(Modify)Sequence to be modified
Returns
AjBool:true if sequence was modified

Description

The opposite of ajRangeSeqExtractPep() Stuff space characters into a translated string to pad out to the range.

It takes a string and an ordered, non-overlapping set of ranges and puts spaces into the string between the ranges. So starting with the string 'abcde' and the ranges 3-5,7-8 it will produce: ' abc de'

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeSeqMask

Mask the range in a String

Synopsis

Prototype
AjBool ajRangeSeqMask (
      const AjPRange thys,
      const AjPStr maskchar,
      AjPSeq seq
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
const AjPStrmaskcharInputcharacter to mask with
AjPSeqseqModifysequence to be masked
AjBool RETURNtrue if string modified

Input
thys:(Input)range object
maskchar:(Input)character to mask with
Input & Output
seq:(Modify)sequence to be masked
Returns
AjBool:true if string modified

Description

Mask the range in a String

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeSeqToLower

Change the range in a String to lower-case

Synopsis

Prototype
AjBool ajRangeSeqToLower (
      const AjPRange thys,
      AjPSeq seq
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
AjPSeqseqModifysequence to be lower-cased
AjBool RETURNtrue if sequence was modified

Input
thys:(Input)range object
Input & Output
seq:(Modify)sequence to be lower-cased
Returns
AjBool:true if sequence was modified

Description

Change the range in a String to lower-case

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeStrExtractList

Extract the range from a String and place the resulting text in a list of strings.

N.B. the resulting list will be regions of the input string listed in the order specified in the set of ranges. If these are not in ascending order, the resulting list of strings will not be in ascending order either.

Synopsis

Prototype
AjBool ajRangeStrExtractList (
      const AjPRange thys,
      const AjPStr instr,
      AjPList outliststr
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
const AjPStrinstrInputstring to extract from
AjPListoutliststrOutputresulting list of strings
AjBool RETURNtrue if string modified

Input
thys:(Input)range object
instr:(Input)string to extract from
Output
outliststr:(Output)resulting list of strings
Returns
AjBool:true if string modified

Description

Extract the range from a String and place the resulting text in a list of strings.

N.B. the resulting list will be regions of the input string listed in the order specified in the set of ranges. If these are not in ascending order, the resulting list of strings will not be in ascending order either.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeStrExtract

Extract the range from a String (Remove regions not in the range(s))

N.B. the resulting string will be regions of the input string appended in the order specified in the set of ranges. If these are not in ascending order, the resulting string will not be in ascending order either.

Intended for use in extracting exon ranges from the sequence of a transcript.

Synopsis

Prototype
AjBool ajRangeStrExtract (
      const AjPRange thys,
      const AjPStr instr,
      AjPStr* outstr
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
const AjPStrinstrInputstring to extract from
AjPStr*outstrOutputresulting extracted string
AjBool RETURNtrue if string modified

Input
thys:(Input)range object
instr:(Input)string to extract from
Output
outstr:(Output)resulting extracted string
Returns
AjBool:true if string modified

Description

Extract the range from a String (Remove regions not in the range(s))

N.B. the resulting string will be regions of the input string appended in the order specified in the set of ranges. If these are not in ascending order, the resulting string will not be in ascending order either.

Intended for use in extracting exon ranges from the sequence of a transcript.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeStrStuff

The opposite of ajRangeStrExtract() Stuff space characters into a string to pad out to the range.

It takes a string and an ordered, non-overlapping set of ranges and puts spaces into the string between the ranges. So starting with the string 'abcde' and the ranges 3-5,7-8 it will produce: ' abc de'

Synopsis

Prototype
AjBool ajRangeStrStuff (
      const AjPRange thys,
      const AjPStr instr,
      AjPStr* outstr
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
const AjPStrinstrInputstring to stuff
AjPStr*outstrOutputresulting stuffed string
AjBool RETURNtrue if string modified

Input
thys:(Input)range object
instr:(Input)string to stuff
Output
outstr:(Output)resulting stuffed string
Returns
AjBool:true if string modified

Description

The opposite of ajRangeStrExtract() Stuff space characters into a string to pad out to the range.

It takes a string and an ordered, non-overlapping set of ranges and puts spaces into the string between the ranges. So starting with the string 'abcde' and the ranges 3-5,7-8 it will produce: ' abc de'

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeStrMask

Mask the positions defined by a range in a string

Synopsis

Prototype
AjBool ajRangeStrMask (
      const AjPRange thys,
      const AjPStr maskchar,
      AjPStr* str
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
const AjPStrmaskcharInputcharacter to mask with
AjPStr*strOutputstring to be masked
AjBool RETURNtrue if string modified

Input
thys:(Input)range object
maskchar:(Input)character to mask with
Output
str:(Output)string to be masked
Returns
AjBool:true if string modified

Description

Mask the positions defined by a range in a string

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeStrToLower

Change positions defined by the range in a string to lower-case

Synopsis

Prototype
AjBool ajRangeStrToLower (
      const AjPRange thys,
      AjPStr* str
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
AjPStr*strOutputstring to be lower-cased
AjBool RETURNtrue if string modified

Input
thys:(Input)range object
Output
str:(Output)string to be lower-cased
Returns
AjBool:true if string modified

Description

Change positions defined by the range in a string to lower-case

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeElementTypeOverlap

Detect an overlap of a single range element to a region of a sequence

Synopsis

Prototype
ajuint ajRangeElementTypeOverlap (
      const AjPRange thys,
      ajuint element,
      ajuint pos,
      ajuint length
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
ajuintelementInputrange element (0 to n-1)
ajuintposInputposition in sequence of start of region of sequence
ajuintlengthInputlength of region of sequence
ajuint RETURN0=no overlap 1=internal 2=complete 3=at left 4=at right

Input
thys:(Input)range object
element:(Input)range element (0 to n-1)
pos:(Input)position in sequence of start of region of sequence
length:(Input)length of region of sequence
Returns
ajuint:0=no overlap 1=internal 2=complete 3=at left 4=at right

Description

Detect an overlap of a single range element to a region of a sequence

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeCountOverlaps

Detect overlaps of a set of ranges to a region of a sequence

Synopsis

Prototype
ajuint ajRangeCountOverlaps (
      const AjPRange thys,
      ajuint pos,
      ajuint length
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
ajuintposInputposition in sequence of start of region of sequence
ajuintlengthInputlength of region of sequence
ajuint RETURNNumber of ranges in range object with overlaps to the region

Input
thys:(Input)range object
pos:(Input)position in sequence of start of region of sequence
length:(Input)length of region of sequence
Returns
ajuint:Number of ranges in range object with overlaps to the region

Description

Detect overlaps of a set of ranges to a region of a sequence

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeIsOrdered

Tests to see if the set of ranges are in ascending non-overlapping order

Synopsis

Prototype
AjBool ajRangeIsOrdered (
      const AjPRange thys
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
AjBool RETURNajTrue if in ascending non-overlapping order

Input
thys:(Input)range object
Returns
AjBool:ajTrue if in ascending non-overlapping order

Description

Tests to see if the set of ranges are in ascending non-overlapping order

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajRangeIsWhole

Test whether the default range is used for a sequence

The test is whether the given range is a single range from the start to the end of a sequence string.

Synopsis

Prototype
AjBool ajRangeIsWhole (
      const AjPRange thys,
      const AjPSeq s
);

TypeNameRead/WriteDescription
const AjPRangethysInputrange object
const AjPSeqsInputsequence
AjBool RETURNtrue if default range

Input
thys:(Input)range object
s:(Input)sequence
Returns
AjBool:true if default range

Description

Test whether the default range is used for a sequence

The test is whether the given range is a single range from the start to the end of a sequence string.

See Also

See other functions in this section

Availability

In release 6.4.0