Final API changes

Add tests

.github/workflows/text_ble_uuid.yml

@@ -0,0 +1,36 @@
+name: BleUuid Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Flutter
+      uses: subosito/flutter-action@v2
+      with:
+        channel: stable
+
+    - name: Install dependencies
+      run: flutter pub get
+
+    - name: Analyze project source
+      run: flutter analyze
+
+    - name: Run Flutter tests
+      run: flutter test
+
+    - name: Install Chrome
+      uses: browser-actions/setup-chrome@latest
+
+    - name: Run Flutter tests on Chrome
+      uses: coactions/setup-xvfb@v1
+      with:
+        run: flutter test --platform chrome

CHANGELOG.md

@@ -1,6 +1,6 @@
 ## 0.11.0
 * Unify UUID format across all platforms, 128-bit lowercase
-* Add BleUUID utility methods for UUID parsing
+* Add BleUuid utility methods for UUID parsing
 * Improve Android error handling
 * Fix Android disconnection events sometimes missed
 * Improve cleanup after disconnection on Apple and Android

README.md

@@ -265,28 +265,28 @@ UniversalBle.timeout = null;
 All characteristic and service UUIDs will be returned in lowercase and in 128 bit format, across all platforms.
 e.g. `0000180a-0000-1000-8000-00805f9b34fb`
 
-When passing a UUID you can pass it in any character case or format (long/short) you want. The plugin will take care of conversions.
+When passing a UUID you can pass it in any character case or format (long/short) you want. The plugin will take care of conversions across all platforms so that you don't need to worry about platform differences.
 
 ### Utility methods
 
-`BleUuid.parse()` converts a string to 128 bit UUID format:
+`BleUuid.string()` converts a string to a 128-bit UUID format string:
 
 ```dart
-BleUuid.parse("180A"); // "0000180a-0000-1000-8000-00805f9b34fb"
+BleUuidParser.string("180A"); // "0000180a-0000-1000-8000-00805f9b34fb"
 
-BleUuid.parse("0000180A-0000-1000-8000-00805F9B34FB"); // "0000180a-0000-1000-8000-00805f9b34fb"
+BleUuidParser.string("0000180A-0000-1000-8000-00805F9B34FB"); // "0000180a-0000-1000-8000-00805f9b34fb"
 ```
 
-`BleUuid.extend()` creates a 128 bit Bluetooth UUID from short (16 or 32 bit) format:
+`BleUuidParser.number()` converts a number to a 128-bit UUID format string:
 
 ```dart
-BleUuid.extend(0x180A); // "0000180a-0000-1000-8000-00805f9b34fb"
+BleUuid.number(0x180A); // "0000180a-0000-1000-8000-00805f9b34fb"
 ```
 
-`BleUuid.equals()` compares two UUIDs:
+`BleUuid.compare()` compares two differently formatted UUIDs:
 
 ```dart
-BleUuid.equals("180a","0000180A-0000-1000-8000-00805F9B34FB"); // true
+BleUuid.compare("180a","0000180A-0000-1000-8000-00805F9B34FB"); // true
 ```
 
 ## Platform-Specific Setup

lib/src/models/ble_service.dart

@@ -5,7 +5,7 @@ class BleService {
   List<BleCharacteristic> characteristics;
 
   BleService(String uuid, this.characteristics) {
-    this.uuid = BleUuid.parse(uuid);
+    this.uuid = BleUuidParser.string(uuid);
   }
 }
 
@@ -14,7 +14,7 @@ class BleCharacteristic {
   List<CharacteristicProperty> properties;
 
   BleCharacteristic(String uuid, this.properties) {
-    this.uuid = BleUuid.parse(uuid);
+    this.uuid = BleUuidParser.string(uuid);
   }
 }
 

lib/src/models/ble_uuid.dart → lib/src/models/ble_uuid_parser.dart

@@ -1,11 +1,17 @@
-class BleUuid {
-  /// Parse a String to valid UUID and convert a 16 bit UUID to 128 bit UUID
-  /// Throws `FormatException` if the UUID is invalid
-  static String parse(String uuid) {
+class BleUuidParser {
+  BleUuidParser._();
+
+  /// Parse a string to a valid 128-bit UUID.
+  /// Throws `FormatException` if the string does not hold a valid UUID format.
+  static String string(String uuid) {
     if (uuid.length < 4) {
       throw const FormatException('Invalid UUID');
     }
 
+    if (uuid.startsWith('0x')) {
+      uuid = uuid.substring(2);
+    }
+
     if (uuid.length <= 8) {
       uuid = "${uuid.padLeft(8, '0')}-0000-1000-8000-00805f9b34fb";
     }
@@ -41,17 +47,22 @@ class BleUuid {
     return uuid.toLowerCase();
   }
 
-  /// Parse 16/32 bit UUID like `0x1800` to 128 bit UUID like `00001800-0000-1000-8000-00805f9b34fb`
-  static String extend(int short) =>
-      parse(short.toRadixString(16).padLeft(4, '0'));
+  /// Parse an int number into a 128-bit UUID string.
+  /// e.g. `0x1800` to `00001800-0000-1000-8000-00805f9b34fb`.
+  static String number(int short) {
+    if (short <= 0xFF || short > 0xFFFF) {
+      throw const FormatException('Invalid UUID');
+    }
+    return string(short.toRadixString(16).padLeft(4, '0'));
+  }
 
-  /// Compare two UUIDs to automatically convert both to 128 bit UUIDs
-  /// Throws `FormatException` if the UUID is invalid
-  static bool equals(String uuid1, String uuid2) =>
-      parse(uuid1) == parse(uuid2);
+  /// Compare two UUIDs regardless of their format.
+  /// Throws `FormatException` if the UUID is invalid.
+  static bool compareStrings(String uuid1, String uuid2) =>
+      string(uuid1) == string(uuid2);
 }
 
-/// Parse a list of strings to a list of UUIDs
+/// Parse a list of strings to a list of UUIDs.
 extension StringListToUUID on List<String> {
-  List<String> toValidUUIDList() => map(BleUuid.parse).toList();
+  List<String> toValidUUIDList() => map(BleUuidParser.string).toList();
 }

lib/src/models/model_exports.dart

@@ -1,5 +1,5 @@
 export 'package:universal_ble/src/models/queue_type.dart';
-export 'package:universal_ble/src/models/ble_uuid.dart';
+export 'package:universal_ble/src/models/ble_uuid_parser.dart';
 export 'package:universal_ble/src/models/scan_filter.dart';
 export 'package:universal_ble/src/models/ble_property.dart';
 export 'package:universal_ble/src/models/ble_service.dart';

lib/src/universal_ble.dart

@@ -111,8 +111,8 @@ class UniversalBle {
     return await _bleCommandQueue.queueCommand(
       () => _platform.setNotifiable(
         deviceId,
-        BleUuid.parse(service),
-        BleUuid.parse(characteristic),
+        BleUuidParser.string(service),
+        BleUuidParser.string(characteristic),
         bleInputProperty,
       ),
       deviceId: deviceId,
@@ -129,8 +129,8 @@ class UniversalBle {
     return await _bleCommandQueue.queueCommand(
       () => _platform.readValue(
         deviceId,
-        BleUuid.parse(service),
-        BleUuid.parse(characteristic),
+        BleUuidParser.string(service),
+        BleUuidParser.string(characteristic),
       ),
       deviceId: deviceId,
     );
@@ -148,8 +148,8 @@ class UniversalBle {
     await _bleCommandQueue.queueCommand(
       () => _platform.writeValue(
         deviceId,
-        BleUuid.parse(service),
-        BleUuid.parse(characteristic),
+        BleUuidParser.string(service),
+        BleUuidParser.string(characteristic),
         value,
         bleOutputProperty,
       ),

lib/src/universal_ble_pigeon/universal_ble_pigeon_channel.dart

@@ -209,7 +209,7 @@ extension _UniversalBleScanResultExtension on UniversalBleScanResult {
       isSystemDevice: isSystemDevice,
       services: services
               ?.where((e) => e != null)
-              .map((e) => BleUuid.parse(e!))
+              .map((e) => BleUuidParser.string(e!))
               .toList() ??
           [],
     );

lib/src/universal_ble_platform_interface.dart

@@ -65,7 +65,8 @@ abstract class UniversalBlePlatform {
   /// `onValueChange` interceptor to parse the native uuids to 128 bit uuid, to keep consistency
   void updateCharacteristicValue(
       String deviceId, String characteristicId, Uint8List value) {
-    onValueChange?.call(deviceId, BleUuid.parse(characteristicId), value);
+    onValueChange?.call(
+        deviceId, BleUuidParser.string(characteristicId), value);
   }
 
   OnAvailabilityChange? onAvailabilityChange;