| | |
- 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'
>>>
|