docs/development/languages/fidl/guides/compatibility/bits_strict_flexible.md

<!-- WARNING: This file is machine generated by //src/tests/fidl/source_compatibility/gen, do not edit. -->

Note: This document covers API impact only. For more details, see the
[ABI compatibility page](/docs/development/languages/fidl/guides/compatibility/README.md)

# Change a bits from strict to flexible

## Overview

-|[init](#init)|[step 1](#step-1)|[step 2](#step-2)|[step 3](#step-3)
---|---|---|---|---
fidl|[link](#fidl-init)||[link](#fidl-2)|
dart|[link](#dart-init)|||
go|[link](#go-init)|||
hlcpp|[link](#hlcpp-init)|[link](#hlcpp-1)||[link](#hlcpp-3)
llcpp|[link](#llcpp-init)|||[link](#llcpp-3)
rust|[link](#rust-init)|||[link](#rust-3)

## Initial State {#init}

### FIDL {#fidl-init}

```fidl
strict bits Flags {
    OPTION_A = 1;
    OPTION_B = 2;
};
```

### Dart {#dart-init}

```dart
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}

```go
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}

```cpp
template <fidl_test::Flags flag_value>
class BitsTemplate {};

fidl_test::Flags use_bits(fidl_test::Flags bits) {
  fidl_test::Flags result = bits | fidl_test::Flags::OPTION_A;
  result &= fidl_test::FlagsMask;
  return result;
}
```

### LLCPP {#llcpp-init}

```cpp
uint32_t use_bits(fidl_test::Flags bits) {
  auto result = fidl_test::Flags::TruncatingUnknown(7u);
  if (bits & fidl_test::Flags::OPTION_A) {
    result |= fidl_test::Flags::kMask;
  }
  return uint32_t(result);
}
```

### Rust {#rust-init}

```rust
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);
    }
    return result;
}
```

## Update Source Code {#step-1}

### HLCPP {#hlcpp-1}

- Remove any usages of the bits type as a non-type template parameter. This is not supported for flexible bits since they are implemented as a regular `class`, which cannot be used as a non-type template parameter.
- Remove any usages of the bits mask member. This generated value is renamed for flexible bits, so it must be temporarily hardcoded.

```diff
- template <fidl_test::Flags flag_value>
- class BitsTemplate {};
- 
  fidl_test::Flags use_bits(fidl_test::Flags bits) {
    fidl_test::Flags result = bits | fidl_test::Flags::OPTION_A;
-   result &= fidl_test::FlagsMask;
+   fidl_test::Flags mask = fidl_test::Flags::OPTION_A | fidl_test::Flags::OPTION_B;
+   result &= mask;
    return result;
  }

```

## Update FIDL Library {#step-2}

- Switch from `strict` to `flexible`

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

```

## Update Source Code {#step-3}

### HLCPP {#hlcpp-3}

- Use the renamed ::kMask constant
- You can now use flexible-specific APIs

```diff
  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;
+   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-3}

- You can now use flexible-specific APIs

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

```

### Rust {#rust-3}

- You can now use flexible-specific APIs

```diff
  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);
+         println!("{}", result.get_unknown_bits());
      }
      return result;
  }

```