Flags

Flags are one or more boolean values stored in a single number field.

Operations on Flags

This page lists all known flags for each entity which has a flags field. The numbers shown next to each flag are bit ordinal numbers counted from the least significant bit. If a bit is set (1) in the flags field then the corresponding flag is set. If the bit is not set (0) then the flag is not set.

Example

Let's have an entity with flags equal to 257 (the API expects a decimal representation). So 257 = 2^8 + 2^0 meaning that flags for bits 0 and 8 are set, all others are unset.

Keep in mind that when you change a single flag via the PATCH or PUT methods you must keep other flags unchanged. If you send only the value corresponding to a single flag all other flags will be cleared (unset).

The API requests and responses work with a decimal representation and use a signed data types, so you might get a negative value if the most significant bit is set in the flags field. See the flags data type in the entity schema.

Obtaining a flag value

To get the flag value from the bit ordinal number take 1 and shift it left by the bit number, i.e. 1^bit

Example: value for bit 8 flag, Java syntax:

flagValue = 1 << 8; // flagValue == 256

Checking if a flag is set

To check if a flag is set do a binary AND operation with the flag value and compare the result with a zero, i.e. flags AND 1^bit != 0

Example: flags = 257, checking bit 8 flag, Java syntax:

boolean isFlagSet = (257 & (1 << 8)) != 0; // isFlagSet == true

Adding (set) a flag

To set a flag while keeping state of other flags you can use the binary OR operation with the flag value, i.e. flags = flags OR 1^bit

Example: setting bit 8 flag, Java syntax:

flags |= 1 << 8;

Clearing (unset) a flag

To unset a flag while keeping state of other flags you can use the binary AND operation with a binary complement of the flag value, i.e. flags = flags AND NEG 1^bit

Example: clearing bit 8 flag, Java syntax:

flags &= ~(1 << 8);

Toggling (flip) a flag

To toggle a flag while keeping state of other flags you can use the binary XOR operation with the flag value, i.e. flags = flags XOR 1^bit

Example: toggling bit 8 flag, Java syntax:

flags ^= 1 << 8;