bits_flexible_strict.md

Note: This document covers API impact only. For more details, see the ABI compatibility page

Change a bits from flexible to strict

Overview

-	init	step 1	step 2	step 3
fidl	link		link
dart	link
go	link
hlcpp	link	link		link
llcpp	link	link
rust	link	link

Initial State {#init}

FIDL {#fidl-init}

type Flags = flexible bits {
    OPTION_A = 1;
    OPTION_B = 2;
};

Dart {#dart-init}

int useBits(fidllib.Flags bits) {
  if (bits.hasUnknownBits()) {
    return bits.getUnknownBits();
  }

  var result = fidllib.Flags.$none;
  if ((bits & fidllib.Flags.optionA).$value != 0) {
    result |= fidllib.Flags.$mask;
  }
  return result.$value;
}

Go {#go-init}

func useBits(bits lib.Flags) uint32 {
	if bits.HasUnknownBits() {
		return uint32(bits.GetUnknownBits())
	}
	var result lib.Flags = 0
	if bits.HasBits(lib.FlagsOptionA) {
		result |= lib.Flags_Mask
	}
	return uint32(result)
}

HLCPP {#hlcpp-init}

fidl_test::Flags use_bits(fidl_test::Flags bits) {
  fidl_test::Flags result = bits | fidl_test::Flags::OPTION_A;
  auto truncated = fidl_test::Flags::TruncatingUnknown(uint32_t(result));
  ZX_ASSERT(!truncated.has_unknown_bits());

  result &= fidl_test::Flags::kMask;
  ZX_ASSERT(truncated == result);
  return result;
}

LLCPP {#llcpp-init}

uint32_t use_bits(fidl_test::wire::Flags bits) {
  auto result = fidl_test::wire::Flags::TruncatingUnknown(7u);
  if (bits & fidl_test::wire::Flags::kOptionA) {
    result |= fidl_test::wire::Flags::kMask;
    printf("%d\n", uint32_t(result.unknown_bits()));
  }
  return uint32_t(result);
}

Rust {#rust-init}

fn use_bits(bits: &fidl_lib::Flags) -> fidl_lib::Flags {
    let mut result = fidl_lib::Flags::empty();
    if bits.contains(fidl_lib::Flags::OptionA) {
        result.set(fidl_lib::Flags::all(), true);
        assert!(!result.has_unknown_bits());
    }
    return result;
}

Update Source Code {#step-1}

HLCPP {#hlcpp-1}

• Remove any usages of the bits mask member. This generated value is renamed for strict bits, so it must be temporarily hardcoded.
• Remove usages of flexible-only APIs

  fidl_test::Flags use_bits(fidl_test::Flags bits) {
    fidl_test::Flags result = bits | fidl_test::Flags::OPTION_A;
-   auto truncated = fidl_test::Flags::TruncatingUnknown(uint32_t(result));
-   ZX_ASSERT(!truncated.has_unknown_bits());
- 
-   result &= fidl_test::Flags::kMask;
-   ZX_ASSERT(truncated == result);
+   fidl_test::Flags mask = fidl_test::Flags::OPTION_A | fidl_test::Flags::OPTION_B;
+   result &= mask;
    return result;
  }

LLCPP {#llcpp-1}

• Remove usages of flexible-specific APIs

  uint32_t use_bits(fidl_test::wire::Flags bits) {
    auto result = fidl_test::wire::Flags::TruncatingUnknown(7u);
    if (bits & fidl_test::wire::Flags::kOptionA) {
      result |= fidl_test::wire::Flags::kMask;
-     printf("%d\n", uint32_t(result.unknown_bits()));
    }
    return uint32_t(result);
  }

Rust {#rust-1}

• Remove usages of flexible-specific APIs

  fn use_bits(bits: &fidl_lib::Flags) -> fidl_lib::Flags {
      let mut result = fidl_lib::Flags::empty();
      if bits.contains(fidl_lib::Flags::OptionA) {
          result.set(fidl_lib::Flags::all(), true);
-         assert!(!result.has_unknown_bits());
      }
      return result;
  }

Update FIDL Library {#step-2}

• Switch from flexible to strict

- type Flags = flexible bits {
+ type Flags = strict bits {
      OPTION_A = 1;
      OPTION_B = 2;
  };

Update Source Code {#step-3}

HLCPP {#hlcpp-3}

• Use the renamed FlagsMask constant

  fidl_test::Flags use_bits(fidl_test::Flags bits) {
    fidl_test::Flags result = bits | fidl_test::Flags::OPTION_A;
-   fidl_test::Flags mask = fidl_test::Flags::OPTION_A | fidl_test::Flags::OPTION_B;
-   result &= mask;
+   result &= fidl_test::FlagsMask;
    return result;
  }