CCharacterRange class

Pipelines v1.6

 

Member variables, Member functions

Home

 

Description

 

The CCharacterRange class object is used by the ParseForCharacterRange() function to extract a character range from your stage command argument. You need not be concerned with actual format of the range specified; the ParseForCharacterRange() function, which determines this format automatically; extracts the range, converts the from and to values to ASCII characters and stores them in the m_szFrom and m_szTo members, respectively.

 

Definition

 

The following class definition is an edited version; it details only those members which are accessible and of use to you. In addition; any examples that may be shown in this document are only intended as a demonstration of how certain functions might be used, they may not represent best practice and they may not take into account the scope and de-allocation of class objects.

 

class CCharacterRange
{
    public:
 
    CCharacterRange( CProcess &a_Process ) :
        m_Process( a_Process ),
        m_bRequired( false ),
        m_nReturnCode( _RC_SUCCESS_ ),
        m_pszSource( NULL ),
        m_szFrom( "" ),
        m_szTo( "" ),
        m_bExpand( false ),
        m_pszExpandedRange( NULL ),
        m_bSkipLeading( true ),
        m_szLeadingDelim( " \n\t" ),
        m_bSkipTrailing( true ),
        m_szTrailingDelim( " \n\t" ) {}
 
    void Reset( void )
    {
        m_bRequired = false;
        m_szFrom = "";
        m_szTo = "";
        m_bExpand = false;
        m_pszExpandedRange = NULL;
        m_bSkipLeading = true;
        m_szLeadingDelim = " \n\t";
        m_bSkipTrailing = true;
        m_szTrailingDelim = m_szLeadingDelim;
    }
 
    CProcess &m_Process;
    bool m_bRequired;
    int m_nReturnCode;
    const char **m_pszSource;
    CString m_szFrom;
    CString m_szTo;
    bool m_bExpand;
    CString *m_pszExpandedRange;
    bool m_bSkipLeading;
    CString m_szLeadingDelim;
    bool m_bSkipTrailing;
    CString m_szTrailingDelim;
};

 

Member variables

 

     ●

CProcess &m_Process

[in] Your CStage (*this ) pointer.

 

     ●

bool m_bRequired

[in,opt] Set this option to true if the range is a required stage command argument and must present, otherwise false; which indicates that the range is an optional argument and may or may not be present.

 

     ●

int m_nReturnCode

[out] The returncode set by the function which uses this object.

 

     ●

const char **m_pszSource

[in,out] The address of a pointer to your stage command argument.

 

     ●

CString m_szFrom

[out] A CString buffer in which to store the from character.

 

     ●

CString m_szTo

[out] A CString buffer in which to store the to character.

 

     ●

bool m_bExpand

[in,opt] Set this option to true if the extracted character range is to be expanded.

 

If the numeric value of the hexadecimal representation of the ending character; m_szTo is less than the starting character m_szFrom; the hexadecimal representation of the character that follows X'FF', is X'01'. For example; the hexadecimal values in the range: xFE.5 are: x’FE’, x’FF’, x’01’, x’02’ and x’03’.

 

     ●

CString *m_pszExpandedRange

[in,out,opt] The address of a CString buffer in which to store the expanded character range.

 

     ●

bool m_bSkipLeading

[in,opt] Set this option to true if leading delimiters are to be skipped.

 

     ●

CString m_szLeadingDelim

[in,opt] A list of characters; any of which are considered to be leading delimiters. By default; the list contains a space, a tab character and new-line character.

 

     ●

bool m_bSkipTrailing

[in,opt] Set this option to true if trailing delimiters are to be skipped.

 

     ●

CString m_szTrailingDelim

[in,opt] A list of characters; any of which are considered to be trailing delimiters. By default; the list contains a space, a tab character and a new-line character.

 

Member functions

 

 
CCharacterRange::CCharacterRange(
    _in                           CProcess &a_Process );

 

     ●

Purpose

Use CCharacterRange() to create a character range parser object.

 

The CCharacterRange class object is used by the ParseForCharacterRange() function to extract a character range from your stage command argument. Simply initialise the members as you require and call the ParseForCharacterRange() function to extract the range.

 

     ●

Parameters

 

 

●

CProcess &a_Process

[in] is your CStage (*this ) pointer.

 

     ●

Returns

n/a

 

     ●

Messages

None

 

     ●

Usage

To extract a character range from your stage command argument:

 

bool CMyStage::Initialise( void )
{
    // Access the manager.
    CStageManager *pManager = Manager();
    // Access my stage.
    CStage *pStage = pManager->GetStage( *this );
 
    ...
 
    // Point to my stage command argument.
    const char *pszArgument = pStage->Argument();

 

    // My stage requires an expanded character range as its command argument.
 
    CString szExpandedRange;
    CCharacterRange *pCharRange = new CCharacterRange( *this );

    pCharRange->m_pszSource = &pszArgument;

    pCharRange->m_bRequired = true;

    pCharRange->m_bExpand = true;

    pCharRange->m_pszExpandedRange = &szExpandedRange;

 

    // Extract the range.

    if( !pManager->ParseForCharacterRange( pCharRange ) )

        return( false );
 
    ...
 
    return( true );

}

 

 
void CCharacterRange::Reset( void );

 

     ●

Purpose

Use Reset() to reset the default extraction settings.

 

The function will reset the extraction switches and re-initialise the delimiter definitions with their default values, but, leaving the m_Process and m_pszSource members unchanged; you can re-use a CCharacterRange parser object when extracting range arguments, one after another.

 

     ●

Parameters

 

●

void

 

     ●

Returns

 

●

void

 

     ●

Messages

None

 

     ●

Usage

The Reset() function clears the CCharacterRange class object’s extraction settings, but leaves the m_Process and m_pszSource members unchanged; which means that you only need provide these values the first time that you use the object. The m_pszSource member (common to all the parsing class types; CCharacterRange, CIntegerString, etc..) automatically keeps track of your stage command argument pointer. Provided that you use the ParseFor…() functions to extract tokens, strings and ranges from your stage command argument; the m_pszSource member will always be pointing to the next stage command argument position.

 

bool CMyStage::Initialise( void )
{
    // Access the manager.
    CStageManager *pManager = Manager();
    // Access my stage.
    CStage *pStage = pManager->GetStage( *this );
 
    ...
 
    // Point to my stage command argument.
    const char *pszArgument = pStage->Argument();

 

    // My stage requires two character ranges; the first is
    // a required argument, which may be surrounded by brackets,
    // followed by any number of other arguments, followed by
    // the second, expanded and optional character range.
 
    CCharacterRange *pCharRange = new CCharacterRange( *this );
 
    // Extract the first character range.
 

    pCharRange->m_pszSource = &pszArgument;

    // Skip any leading whitespace and left bracket character(s).

    pCharRange->m_szLeadingDelim += ‘(’;
    // Skip any trailing whitespace and right bracket character(s).
    pCharRange->m_szTrailingDelim += ‘)’;

    pCharRange->m_bRequired = true;

 

    // Extract the range.

    if( !pManager->ParseForCharacterRange( pCharRange ) )

        return( false );
 
    // Record the ‘from’ and ‘to’ characters.

    CString szFrom = pCharRange->m_szFrom;

    CString szTo = pCharRange->m_szTo;

 
    //
    // Extract any number of other arguments here.
    //
 
    ...
 
    // Extract the second (optional) character range.
 
    CString szExpandedRange;
 
    // Reset the object.
    pCharRange->Reset();
    pCharRange->m_bExpand = true;

    pCharRange->m_pszExpandedRange = &szExpandedRange;

 

    // Extract the range.

    pManager->ParseForCharacterRange( pCharRange );

 

    ...
 
    return( true );
}