Lexical Functions - F$CVSI and F$CVUI

Our next lexical functions are F$CVSI and F$CVUI. They convert bit fields from strings into 64-bit integer values. They are identical except that F$CVSI converts into signed integer values while F$CVUI converts into unsigned integer values. Here are the definitions:

F$CVSI

F$CVSI converts the specified bits in a character string to a signed integer value.

Format
F$CVSI(start, count, string)

Return Value
The selected bits from the string converted into a signed integer value.

Arguments
start

The offset of the first bit to be extracted. The least significant (rightmost) bit of a string is position 0. The starting bit must be an integer expression.

If the start value is negative or is a value that exceeds the number of bits in the string, an INVRANGE error is generated.

count

The number of bits from the string to be extracted, starting at the specified start bit.

If the value is negative or if this value plus the start exceeds 64 or the number of bits in the string, an INVRANGE error is generated.

string

Specifies the string from which the bits are taken.

Examples
Example 1:
$ X = F$CSVI(0,4,"+")

In this example, the string contains a plus sign, which has a hex value of 2B. Since we are requesting 4 bits starting with bit 0, we are addressing the low four bits (or hexadecimal B). Because the highest of the 4 bits is set, the sign is extended and the result is -5.

$ X = F$CSVI(0,8," ")

In this example, the string contains a space, which has a value of 32. We grab all 8 bits of the value. Since the highest bit is not set, there is no sign that is set. Thus, the result is 32.

Example 2:
$ X = F$CSVI(0,32,"ABC")

In this example, the string contains three characters, which means there are 24 bits. Since the bit count is larger than the number of available bits, this generates the INVRANGE error.

F$CVUI

F$CVUI converts the specified bits in a character string to an unsigned integer value.

Format
F$CVUI(start, count, string)

Return Value
The selected bits from the string converted into an unsigned integer value.

Arguments
start
The offset of the first bit to be extracted. The least significant (rightmost) bit of a string is position 0. The starting bit must be an integer expression.

If the start value is negative or is a value that exceeds the number of bits in the string, an INVRANGE error is generated.

count
The number of bits from the string to be extracted, starting at the specified start bit.

If the value is negative or if this value plus the start exceeds 63 or the number of bits in the string, an INVRANGE error is generated.

string
Specifies the string from which the bits are taken.

Examples
Example 1:
$ X = F$CSUI(0,4,"+")

In this example, the string contains a plus sign, which has a hex value of 2B. Since we are requesting 4 bits starting with bit 0, we are addressing the low four bits (or hexadecimal B), which is 11.

Example 2:
$ X = F$CSUI(0,32,"ABC")

In this example, the string contains three characters, which means there are 24 bits. Since the bit count is larger than the number of available bits, this generates the INVRANGE error.

        Function_Cvsi : begin
                            if( Missing_Parentheses( '(' ) ) then
                            begin
                                exit ;
                            end ;
                            if( Parse_CVSI( Err, Context, True ) ) then
                            begin
                                exit ;
                            end ;
                            if( Missing_Parentheses( ')' ) ) then
                            begin
                                exit ;
                            end ;
                            Result := tExpression_Node.Create ;
                            Result.Value := Context ;
                        end ;
                        
        Function_Cvui : begin
                            if( Missing_Parentheses( '(' ) ) then
                            begin
                                exit ;
                            end ;
                            if( Parse_CVI( Err, Context, False ) ) then
                            begin
                                exit ;
                            end ;
                            if( Missing_Parentheses( ')' ) ) then
                            begin
                                exit ;
                            end ;
                            S := Context ;
                        end ;

We update the Function_Reference code to handle the F$CVSI and F$CVUI lexical functions. This is just like the previous lexical functions we've added. The only difference between these two is whether we pass true or false for the Signed parameter in Parse_CVI.

function Parse_CVI( var Err : integer ; var Context : string ; Signed : boolean ) : boolean ;

var C, Start, Count, Bit, Offset, Original : integer ;
    N : int64 ;
    S : string ;

begin
    // Setup...
    Result := False ;
    Err := 0 ;

    // Get starting bit offset...
    Start := Get_Numeric_Parameter( Err, Context ) ;
    if( Err <> 0 ) then
    begin
        Result := True ;
        exit ;
    end ;
    if( Start < 0 ) then
    begin
        Err := UCL_INVRANGE ;
        Result := True ;
        exit ;
    end ;
    Result := Missing_Comma( Err ) ;
    if( Result ) then
    begin
        exit ;
    end ;

    // Get bit length...
    Count := Get_Numeric_Parameter( Err, Context ) ;
    if( Err <> 0 ) then
    begin
        Result := True ;
        exit ;
    end ;
    if( Count < 0 ) then
    begin
        Err := UCL_INVRANGE ;
        Result := True ;
        exit ;
    end ;
    Result := Missing_Comma( Err ) ;
    if( Result ) then
    begin
        exit ;
    end ;

The Parse_CVI function processes the parameters for the F$CVSI and F$CVUI lexical functions. First we clear the return values, then we use the Get_Numeric_Parameter function to get the starting offset, and the bit count. We exit with the appropriate error if there are any errors when getting the parameters, if there are missing commas, or either the start bit or bit count is less than 0.

    // Get string...
    S := Get_Parameter( Err, Context ) ;
    if( Err <> 0 ) then
    begin
        Result := True ;
        exit ;
    end ;
    if( 
        ( Start >= length( S ) * 8 ) 
        or 
        ( Count > ( length( S ) * 8 ) - Start ) 
        or 
        ( Count > 64 ) 
        or 
        ( ( Count > 63 ) and ( not Signed ) )
      ) then
    begin
        Err := UCL_INVRANGE ;
        Result := True ;
        exit ;
    end ;

Next we get the string value to convert. Once we have the string, we know its length and we can verify that the start and count values are within the bounds of the string. Further, if the user is requesting more than 64 bits (or 63 bits if unsigned) we also return a range error.

    // Convert...
    Original := Count ; // Save count for later
    Offset := ( Start div 8 ) + 1 ;
    Bit := Start mod 8 ;
    C := ord( S[ Offset ] ) ;
    C := C shr Bit ;
    N := 0 ;
    while( Count > 0 ) do
    begin
        dec( Count ) ;

We initialize for the conversion and loop until we have processed all requested bits. We determine the starting string offset and the bit within that character. We then get the character value at that offset and shift the value to the lowest bit position. The bit is normalized to the offset character (Start mod 8).

        // Push the next bit...
        N := N shr 1 ;
        if( ( C and 1 ) <> 0 ) then
        begin
            N := N or $8000000000000000 ;
        end ;

N is the 64-bit integer value that we are going to build from the string. The first thing we do in the loop is shift the accumualted value one bit to the right and then move the lowest bit in C to the highest bit of N.

        // Handle end condition...
        if( Count = 0 ) then // Processed all requested bits
        begin
            if( not Signed ) then
            begin
                C := 0 ;
            end ;
            for Bit := 64 downto Original + 1 do
            begin
                // Sign extend
                N := N shr 1 ;
                if( ( C and 1 ) <> 0 ) then
                begin
                    N := N or $8000000000000000 ;
                end ;
            end ;
            break ;
        end ;

Once Count is 0, we have extracted all the requested bits. However, these bits exist in the highest bits of N, so we need to shift the bits right until they occupy the lowest bits in N. If the last bit we extracted was set, we consider that the sign bit and we extend that through the rest of the bits as we shift them. If we are processing the value as unsigned, we set C to 0 so that no sign is extended. Then we exit the loop.

        // Move to next bit (byte)...
        C := C shr 1 ;
        inc( Bit ) ;
        if( Bit > 7 ) then
        begin
            Bit := 0 ;
            inc( Offset ) ;
            C := ord( S[ Offset ] ) ;
        end ;
    end ; // while( Count > 0 )
    Context := inttostr( N ) ;
end ; // Parse_CVSI

Once we've pushed the next bit into N, we shift C right one bit to move the next bit into position. We increment the Bit, which we use to keep track of when we've finished processing the current character. If we reach 8, we increment the offset, get the character at that offset and set Bit to 0. When the loop completes (or doesn't execute at all due to Count being 0) we set the Context to a string value of N.

In the next article, we will continue our examination of UCL lexical functions.