Bit Operations

Description

Bit operations. Create bit operations used in aerospike_key_operate(). Offset orientation is left-to-right. Negative offsets are supported. If the offset is negative, the offset starts backwards from end of the bitmap. If an offset is out of bounds, a parameter error will be returned.

Code examples:

// Set bitmap bin.
as_operations ops;
as_operations_inita(&ops, 1);
uint8_t val[] = {0x11, 0x22, 0x33, 0x44};
as_operations_bit_set(&ops, "bin", NULL, NULL, 0, 32, sizeof(val), val);
 
as_record* rec = NULL;
as_error err;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
as_operations_destroy(&ops);
as_record_destroy(rec);

Bit operations on bitmap items nested in lists/maps are not currently supported by the server. The as_cdt_ctx argument in bit operations must be set to NULL.

Collaboration diagram for Bit Operations:

Data Structures
struct	as_bit_policy

Enumerations
enum	as_bit_overflow_action { AS_BIT_OVERFLOW_FAIL = 0 , AS_BIT_OVERFLOW_SATURATE = 2 , AS_BIT_OVERFLOW_WRAP = 4 }
enum	as_bit_resize_flags { AS_BIT_RESIZE_DEFAULT = 0 , AS_BIT_RESIZE_FROM_FRONT = 1 , AS_BIT_RESIZE_GROW_ONLY = 2 , AS_BIT_RESIZE_SHRINK_ONLY = 4 }
enum	as_bit_write_flags {   AS_BIT_WRITE_DEFAULT = 0 , AS_BIT_WRITE_CREATE_ONLY = 1 , AS_BIT_WRITE_UPDATE_ONLY = 2 , AS_BIT_WRITE_NO_FAIL = 4 ,   AS_BIT_WRITE_PARTIAL = 8 }

Functions
static void	as_bit_policy_init (as_bit_policy *policy)
static void	as_bit_policy_set_write_flags (as_bit_policy *policy, as_bit_write_flags flags)
static bool	as_operations_bit_add (as_operations *ops, const char *name, as_cdt_ctx *ctx, as_bit_policy *policy, int bit_offset, uint32_t bit_size, uint64_t value, bool sign, as_bit_overflow_action action)
static bool	as_operations_bit_and (as_operations *ops, const char *name, as_cdt_ctx *ctx, as_bit_policy *policy, int bit_offset, uint32_t bit_size, uint32_t value_byte_size, uint8_t *value)
static bool	as_operations_bit_count (as_operations *ops, const char *name, as_cdt_ctx *ctx, int bit_offset, uint32_t bit_size)
static bool	as_operations_bit_get (as_operations *ops, const char *name, as_cdt_ctx *ctx, int bit_offset, uint32_t bit_size)
AS_EXTERN bool	as_operations_bit_get_int (as_operations *ops, const char *name, as_cdt_ctx *ctx, int bit_offset, uint32_t bit_size, bool sign)
AS_EXTERN bool	as_operations_bit_insert (as_operations *ops, const char *name, as_cdt_ctx *ctx, as_bit_policy *policy, int byte_offset, uint32_t value_byte_size, uint8_t *value)
static bool	as_operations_bit_lscan (as_operations *ops, const char *name, as_cdt_ctx *ctx, int bit_offset, uint32_t bit_size, bool value)
static bool	as_operations_bit_lshift (as_operations *ops, const char *name, as_cdt_ctx *ctx, as_bit_policy *policy, int bit_offset, uint32_t bit_size, uint32_t shift)
static bool	as_operations_bit_not (as_operations *ops, const char *name, as_cdt_ctx *ctx, as_bit_policy *policy, int bit_offset, uint32_t bit_size)
static bool	as_operations_bit_or (as_operations *ops, const char *name, as_cdt_ctx *ctx, as_bit_policy *policy, int bit_offset, uint32_t bit_size, uint32_t value_byte_size, uint8_t *value)
static bool	as_operations_bit_remove (as_operations *ops, const char *name, as_cdt_ctx *ctx, as_bit_policy *policy, int byte_offset, uint32_t byte_size)
AS_EXTERN bool	as_operations_bit_resize (as_operations *ops, const char *name, as_cdt_ctx *ctx, as_bit_policy *policy, uint32_t byte_size, as_bit_resize_flags flags)
static bool	as_operations_bit_rscan (as_operations *ops, const char *name, as_cdt_ctx *ctx, int bit_offset, uint32_t bit_size, bool value)
static bool	as_operations_bit_rshift (as_operations *ops, const char *name, as_cdt_ctx *ctx, as_bit_policy *policy, int bit_offset, uint32_t bit_size, uint32_t shift)
static bool	as_operations_bit_set (as_operations *ops, const char *name, as_cdt_ctx *ctx, as_bit_policy *policy, int bit_offset, uint32_t bit_size, uint32_t value_byte_size, uint8_t *value)
AS_EXTERN bool	as_operations_bit_set_int (as_operations *ops, const char *name, as_cdt_ctx *ctx, as_bit_policy *policy, int bit_offset, uint32_t bit_size, int64_t value)
static bool	as_operations_bit_subtract (as_operations *ops, const char *name, as_cdt_ctx *ctx, as_bit_policy *policy, int bit_offset, uint32_t bit_size, uint64_t value, bool sign, as_bit_overflow_action action)
static bool	as_operations_bit_xor (as_operations *ops, const char *name, as_cdt_ctx *ctx, as_bit_policy *policy, int bit_offset, uint32_t bit_size, uint32_t value_byte_size, uint8_t *value)

Enumeration Type Documentation

as_bit_overflow_action

enum as_bit_overflow_action

Action to take when bitwise add/subtract results in overflow/underflow.

Enumerator
AS_BIT_OVERFLOW_FAIL	Fail operation with error.
AS_BIT_OVERFLOW_SATURATE	If add/subtract overflows/underflows, set to max/min value. Example: MAXINT + 1 = MAXINT
AS_BIT_OVERFLOW_WRAP	If add/subtract overflows/underflows, wrap the value. Example: MAXINT + 1 = -1

Definition at line 126 of file as_bit_operations.h.

as_bit_resize_flags

enum as_bit_resize_flags

Bitmap resize flags.

Enumerator
AS_BIT_RESIZE_DEFAULT	Default.
AS_BIT_RESIZE_FROM_FRONT	Add/remove bytes from the beginning instead of the end.
AS_BIT_RESIZE_GROW_ONLY	Only allow the bitmap size to increase.
AS_BIT_RESIZE_SHRINK_ONLY	Only allow the bitmap size to decrease.

Definition at line 99 of file as_bit_operations.h.

as_bit_write_flags

enum as_bit_write_flags

Bitmap write flags.

Enumerator
AS_BIT_WRITE_DEFAULT	Default. Allow create or update.
AS_BIT_WRITE_CREATE_ONLY	If the bin already exists, the operation will be denied. If the bin does not exist, a new bin will be created.
AS_BIT_WRITE_UPDATE_ONLY	If the bin already exists, the bin will be overwritten. If the bin does not exist, the operation will be denied.
AS_BIT_WRITE_NO_FAIL	Do not raise error if operation is denied.
AS_BIT_WRITE_PARTIAL	Don't fail if the bit operation would increase the blob size. Instead, apply the bit operation without increasing the blob size.

Definition at line 64 of file as_bit_operations.h.

Function Documentation

as_bit_policy_init()

static void as_bit_policy_init ( as_bit_policy * policy )

inlinestatic

Initialize bit policy to default.

Definition at line 230 of file as_bit_operations.h.

References AS_BIT_WRITE_DEFAULT, and as_bit_policy::flags.

as_bit_policy_set_write_flags()

static void as_bit_policy_set_write_flags ( as_bit_policy * policy, as_bit_write_flags flags )

inlinestatic

Set bit write flags in bit policy.

Definition at line 241 of file as_bit_operations.h.

References as_bit_policy::flags.

as_operations_bit_add()

static bool as_operations_bit_add ( as_operations * ops, const char * name, as_cdt_ctx * ctx, as_bit_policy * policy, int bit_offset, uint32_t bit_size, uint64_t value, bool sign, as_bit_overflow_action action )

inlinestatic

Create bit "add" operation. Server adds value to bitmap starting at bit_offset for bit_size. bit_size must be <= 64. Sign indicates if bits should be treated as a signed number. If add overflows/underflows, as_bit_overflow_action is used. Server does not return a value. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• bit_offset = 24
• bit_size = 16
• value = 128
• sign = false
• bin result = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b10000101]

Definition at line 500 of file as_bit_operations.h.

References as_bit_math(), and AS_BIT_OP_ADD.

as_operations_bit_and()

static bool as_operations_bit_and ( as_operations * ops, const char * name, as_cdt_ctx * ctx, as_bit_policy * policy, int bit_offset, uint32_t bit_size, uint32_t value_byte_size, uint8_t * value )

inlinestatic

Create bit "and" operation. Server performs bitwise "and" on value and bitmap at bit_offset for bit_size. Server does not return a value. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• bit_offset = 23
• bit_size = 9
• value_byte_size = 2
• value = [0b00111100, 0b10000000]
• bin result = [0b00000001, 0b01000010, 0b00000010, 0b00000000, 0b00000101]

Definition at line 402 of file as_bit_operations.h.

References as_bit_byte_math(), and AS_BIT_OP_AND.

as_operations_bit_count()

static bool as_operations_bit_count ( as_operations * ops, const char * name, as_cdt_ctx * ctx, int bit_offset, uint32_t bit_size )

inlinestatic

Create bit "count" operation. Server returns integer count of set bits from bitmap starting at bit_offset for bit_size. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• bit_offset = 20
• bit_size = 4
• returns 2

Definition at line 591 of file as_bit_operations.h.

References AS_BIT_OP_COUNT, and as_bit_read().

as_operations_bit_get()

static bool as_operations_bit_get ( as_operations * ops, const char * name, as_cdt_ctx * ctx, int bit_offset, uint32_t bit_size )

inlinestatic

Create bit "get" operation. Server returns bits from bitmap starting at bit_offset for bit_size. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• bit_offset = 9
• bit_size = 5
• returns [0b10000000]

Definition at line 570 of file as_bit_operations.h.

References AS_BIT_OP_GET, and as_bit_read().

as_operations_bit_get_int()

AS_EXTERN bool as_operations_bit_get_int	(	as_operations *	ops,
		const char *	name,
		as_cdt_ctx *	ctx,
		int	bit_offset,
		uint32_t	bit_size,
		bool	sign )

Create bit "get integer" operation. Server returns integer from bitmap starting at bit_offset for bit_size. Sign indicates if bits should be treated as a signed number. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• bit_offset = 8
• bit_size = 16
• sign = false
• returns 16899

as_operations_bit_insert()

AS_EXTERN bool as_operations_bit_insert	(	as_operations *	ops,
		const char *	name,
		as_cdt_ctx *	ctx,
		as_bit_policy *	policy,
		int	byte_offset,
		uint32_t	value_byte_size,
		uint8_t *	value )

Create byte "insert" operation. Server inserts value bytes into bitmap at byte_offset. Server does not return a value. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• byte_offset = 1
• value_byte_size = 2
• value = [0b11111111, 0b11000111]
• bin result = [0b00000001, 0b11111111, 0b11000111, 0b01000010, 0b00000011, 0b00000100, 0b00000101]

as_operations_bit_lscan()

static bool as_operations_bit_lscan ( as_operations * ops, const char * name, as_cdt_ctx * ctx, int bit_offset, uint32_t bit_size, bool value )

inlinestatic

Create bit "left scan" operation. Server returns integer bit offset of the first specified value bit in bitmap starting at bit_offset for bit_size. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• bit_offset = 24
• bit_size = 8
• value = true
• returns 5

Definition at line 614 of file as_bit_operations.h.

References AS_BIT_OP_LSCAN, and as_bit_scan().

as_operations_bit_lshift()

static bool as_operations_bit_lshift ( as_operations * ops, const char * name, as_cdt_ctx * ctx, as_bit_policy * policy, int bit_offset, uint32_t bit_size, uint32_t shift )

inlinestatic

Create bit "left shift" operation. Server shifts left bitmap starting at bit_offset for bit_size. Server does not return a value. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• bit_offset = 32
• bit_size = 8
• shift = 3
• bin result = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00101000]

Definition at line 449 of file as_bit_operations.h.

References AS_BIT_OP_LSHIFT, and as_bit_shift().

as_operations_bit_not()

static bool as_operations_bit_not ( as_operations * ops, const char * name, as_cdt_ctx * ctx, as_bit_policy * policy, int bit_offset, uint32_t bit_size )

inlinestatic

Create bit "not" operation. Server negates bitmap starting at bit_offset for bit_size. Server does not return a value. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• bit_offset = 25
• bit_size = 6
• bin result = [0b00000001, 0b01000010, 0b00000011, 0b01111010, 0b00000101]

Definition at line 425 of file as_bit_operations.h.

References AS_BIT_OP_NOT, and as_bit_write().

as_operations_bit_or()

static bool as_operations_bit_or ( as_operations * ops, const char * name, as_cdt_ctx * ctx, as_bit_policy * policy, int bit_offset, uint32_t bit_size, uint32_t value_byte_size, uint8_t * value )

inlinestatic

Create bit "or" operation. Server performs bitwise "or" on value and bitmap at bit_offset for bit_size. Server does not return a value. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• bit_offset = 17
• bit_size = 6
• value_byte_size = 1
• value = [0b10101000]
• bin result = [0b00000001, 0b01000010, 0b01010111, 0b00000100, 0b00000101]

Definition at line 352 of file as_bit_operations.h.

References as_bit_byte_math(), and AS_BIT_OP_OR.

as_operations_bit_remove()

static bool as_operations_bit_remove ( as_operations * ops, const char * name, as_cdt_ctx * ctx, as_bit_policy * policy, int byte_offset, uint32_t byte_size )

inlinestatic

Create byte "remove" operation. Server removes bytes from bitmap at byte_offset for byte_size. Server does not return a value. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• byte_offset = 2
• byte_size = 3
• bin result = [0b00000001, 0b01000010]

Definition at line 302 of file as_bit_operations.h.

References AS_BIT_OP_REMOVE, and as_bit_write().

as_operations_bit_resize()

AS_EXTERN bool as_operations_bit_resize	(	as_operations *	ops,
		const char *	name,
		as_cdt_ctx *	ctx,
		as_bit_policy *	policy,
		uint32_t	byte_size,
		as_bit_resize_flags	flags )

Create byte "resize" operation. Server resizes bitmap to byte_size according to flags. Server does not return a value. Example:

• bin = [0b00000001, 0b01000010]
• byte_size = 4
• flags = 0
• bin result = [0b00000001, 0b01000010, 0b00000000, 0b00000000]

as_operations_bit_rscan()

static bool as_operations_bit_rscan ( as_operations * ops, const char * name, as_cdt_ctx * ctx, int bit_offset, uint32_t bit_size, bool value )

inlinestatic

Create bit "right scan" operation. Server returns integer bit offset of the last specified value bit in bitmap starting at bit_offset for bit_size. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• bit_offset = 32
• bit_size = 8
• value = true
• returns 7

Definition at line 638 of file as_bit_operations.h.

References AS_BIT_OP_RSCAN, and as_bit_scan().

as_operations_bit_rshift()

static bool as_operations_bit_rshift ( as_operations * ops, const char * name, as_cdt_ctx * ctx, as_bit_policy * policy, int bit_offset, uint32_t bit_size, uint32_t shift )

inlinestatic

Create bit "right shift" operation. Server shifts right bitmap starting at bit_offset for bit_size. Server does not return a value. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• bit_offset = 0
• bit_size = 9
• shift = 1
• bin result = [0b00000000, 0b11000010, 0b00000011, 0b00000100, 0b00000101]

Definition at line 473 of file as_bit_operations.h.

References AS_BIT_OP_RSHIFT, and as_bit_shift().

as_operations_bit_set()

static bool as_operations_bit_set ( as_operations * ops, const char * name, as_cdt_ctx * ctx, as_bit_policy * policy, int bit_offset, uint32_t bit_size, uint32_t value_byte_size, uint8_t * value )

inlinestatic

Create bit "set" operation. Server sets value on bitmap at bit_offset for bit_size. Server does not return a value. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• bit_offset = 13
• bit_size = 3
• value_byte_size = 1
• value = [0b11100000]
• bin result = [0b00000001, 0b01000111, 0b00000011, 0b00000100, 0b00000101]

Definition at line 327 of file as_bit_operations.h.

References as_bit_byte_math(), and AS_BIT_OP_SET.

as_operations_bit_set_int()

AS_EXTERN bool as_operations_bit_set_int	(	as_operations *	ops,
		const char *	name,
		as_cdt_ctx *	ctx,
		as_bit_policy *	policy,
		int	bit_offset,
		uint32_t	bit_size,
		int64_t	value )

Create bit "set integer" operation. Server sets value to bitmap starting at bit_offset for bit_size. Size must be <= 64. Server does not return a value. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• bit_offset = 1
• bit_size = 8
• value = 127
• bin result = [0b00111111, 0b11000010, 0b00000011, 0b0000100, 0b00000101]

as_operations_bit_subtract()

static bool as_operations_bit_subtract ( as_operations * ops, const char * name, as_cdt_ctx * ctx, as_bit_policy * policy, int bit_offset, uint32_t bit_size, uint64_t value, bool sign, as_bit_overflow_action action )

inlinestatic

Create bit "subtract" operation. Server subtracts value from bitmap starting at bit_offset for bit_size. bit_size must be <= 64. Sign indicates if bits should be treated as a signed number. If add overflows/underflows, as_bit_overflow_action is used. Server does not return a value. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• bit_offset = 24
• bit_size = 16
• value = 128
• sign = false
• bin result = [0b00000001, 0b01000010, 0b00000011, 0b0000011, 0b10000101]

Definition at line 527 of file as_bit_operations.h.

References as_bit_math(), and AS_BIT_OP_SUBTRACT.

as_operations_bit_xor()

static bool as_operations_bit_xor ( as_operations * ops, const char * name, as_cdt_ctx * ctx, as_bit_policy * policy, int bit_offset, uint32_t bit_size, uint32_t value_byte_size, uint8_t * value )

inlinestatic

Create bit "exclusive or" operation. Server performs bitwise "xor" on value and bitmap at bit_offset for bit_size. Server does not return a value. Example:

• bin = [0b00000001, 0b01000010, 0b00000011, 0b00000100, 0b00000101]
• bit_offset = 17
• bit_size = 6
• value_byte_size = 1
• value = [0b10101100]
• bin result = [0b00000001, 0b01000010, 0b01010101, 0b00000100, 0b00000101]

Definition at line 377 of file as_bit_operations.h.

References as_bit_byte_math(), and AS_BIT_OP_XOR.