Teradata Package for Python Function Reference - 17.00 - subbitstr - Teradata Package for Python

Teradata® Package for Python Function Reference

Product
Teradata Package for Python
Release Number
17.00
Release Date
November 2021
Content Type
Programming Reference
Publication ID
B700-4008-070K
Language
English (United States)
 
 
subbitstr

 
Functions
       
subbitstr(target_arg, position_arg, num_bits_arg)
DESCRIPTION:
    Function extracts a bit substring from the target_arg input expression
    based on the specified bit position. Function returns a VARBYTE string,
    thus resulting number of bits returned are rounded to the byte boundary
    greater than the number of bits requested.
    The bits returned are right-justified, and the excess bits (those exceeding
    the requested number of bits) are filled with zeros.
 
PARAMETERS:
    target_arg:
        Required Argument.
        Specifies a ColumnExpression of an integer or byte column or a numeric or byte
        literal value.
        If the argument is NULL, the function returns NULL.
        Format of a ColumnExpression of a column: '<dataframe>.<dataframe_column>.expression'.
        Supported SQL column types: BYTEINT, SMALLINT, INTEGER, BIGINT, and VARBYTE(n)
 
    position_arg:
        Required Argument.
        Specifies a ColumnExpression of an integer column or an integer literal
        indicating the starting position of the bit substring to be extracted.
        If position_arg is negative or out-of-range (meaning that it exceeds
        the size of target_arg), an error is returned.
        If the argument is NULL, the function returns NULL.
        Format of a ColumnExpression of a column: '<dataframe>.<dataframe_column>.expression'.
        Supported SQL column types: INTEGER
 
    num_bits_arg:
        Required Argument.
        Specifies a ColumnExpression of an integer column or an integer literal
        indicating the length of the bit substring to be extracted. This
        specifies the number of bits for the function to return.
        If num_bits_arg is negative, or is greater than the number of bits
        remaining after the starting position_arg is taken into account, an error
        is returned.
        If the argument is NULL, the function returns NULL.
        Format of a ColumnExpression of a column: '<dataframe>.<dataframe_column>.expression'.
        Supported SQL column types: INTEGER
 
NOTE:
    Function accepts positional arguments only.
 
EXAMPLES:
    # Load the data to run the example.
    >>> load_example_data("dataframe", "bytes_table")
    >>>
 
    # Create a DataFrame on 'bytes_table' table.
    >>> bytes_table = DataFrame("bytes_table")
    >>> bytes_table
           byte_col      varbyte_col             blob_col
    id_col
    2         b'61'  b'616263643132'  b'6162636431323233'
    1         b'62'      b'62717765'  b'3331363136323633'
    0         b'63'      b'627A7863'  b'3330363136323633'
    >>>
 
    # Example requests that 3 bits be returned starting at the third bit
    # from values in "varbyte_col" column.
    # Import func from sqlalchemy to execute subbitstr function.
    >>> from sqlalchemy import func
 
    # Note: Function name case does not matter. We can use the function name in
    #       lower case, upper case or mixed case.
    >>> df = bytes_table.assign(subbitstr_varbyte_= func.subbitstr(bytes_table.varbyte_col.expression, 2, 3))
    >>> print(df)
           byte_col      varbyte_col             blob_col subbitstr_varbyte_
    id_col
    2         b'61'  b'616263643132'  b'6162636431323233'               b'4'
    1         b'62'      b'62717765'  b'3331363136323633'               b'1'
    0         b'63'      b'627A7863'  b'3330363136323633'               b'0'
    >>>