Add decode_with function. (#8)

Author: Julius de Bruijn

src/lib.rs

@@ -92,6 +92,45 @@ where
     Ok(())
 }
 
+/// Decode UCS-2 string to UTF-8 with a custom callback function.
+///
+/// `output` is a function which receives every decoded character.
+pub fn decode_with<F>(input: &[u16], mut output: F) -> Result<usize>
+where
+    F: FnMut(&[u8]) -> Result<()>,
+{
+    let mut written = 0;
+
+    for ch in input.iter() {
+        /*
+         * We need to find how many bytes of UTF-8 this UCS-2 code-point needs. Because UCS-2 can only encode
+         * the Basic Multilingual Plane, a maximum of three bytes are needed.
+         */
+        if (0x000..0x0080).contains(ch) {
+            output(&[*ch as u8])?;
+
+            written += 1;
+        } else if (0x0080..0x0800).contains(ch) {
+            let first = 0b1100_0000 + ch.get_bits(6..11) as u8;
+            let last = 0b1000_0000 + ch.get_bits(0..6) as u8;
+
+            output(&[first, last])?;
+
+            written += 2;
+        } else {
+            let first = 0b1110_0000 + ch.get_bits(12..16) as u8;
+            let mid = 0b1000_0000 + ch.get_bits(6..12) as u8;
+            let last = 0b1000_0000 + ch.get_bits(0..6) as u8;
+
+            output(&[first, mid, last])?;
+
+            written += 3;
+        }
+    }
+
+    Ok(written)
+}
+
 /// Decode an input UCS-2 string into a UTF-8 string.
 ///
 /// The returned `usize` represents the length of the returned buffer,
@@ -100,42 +139,43 @@ pub fn decode(input: &[u16], output: &mut [u8]) -> Result<usize> {
     let buffer_size = output.len();
     let mut i = 0;
 
-    for &ch in input.iter() {
-        /*
-         * We need to find how many bytes of UTF-8 this UCS-2 code-point needs. Because UCS-2 can only encode
-         * the Basic Multilingual Plane, a maximum of three bytes are needed.
-         */
-        if (0x0000..0x0080).contains(&ch) {
+    decode_with(input, |bytes| {
+        if bytes.len() == 1 {
             // Can be encoded in a single byte
             if i >= buffer_size {
                 return Err(Error::BufferOverflow);
             }
 
-            output[i] = ch as u8;
+            output[i] = bytes[0];
+
             i += 1;
-        } else if (0x0080..0x0800).contains(&ch) {
-            // Can be encoded as two bytes
-            if (i + 1) >= buffer_size {
+        } else if bytes.len() == 2 {
+            // Can be encoded two bytes
+            if i + 1 >= buffer_size {
                 return Err(Error::BufferOverflow);
             }
 
-            output[i] = 0b1100_0000 + ch.get_bits(6..11) as u8;
-            output[i + 1] = 0b1000_0000 + ch.get_bits(0..6) as u8;
+            output[i] = bytes[0];
+            output[i + 1] = bytes[1];
+
             i += 2;
-        } else {
-            // Can be encoded as three bytes
-            if (i + 2) >= buffer_size {
+        } else if bytes.len() == 3 {
+            // Can be encoded three bytes
+            if i + 2 >= buffer_size {
                 return Err(Error::BufferOverflow);
             }
 
-            output[i] = 0b1110_0000 + ch.get_bits(12..16) as u8;
-            output[i + 1] = 0b1000_0000 + ch.get_bits(6..12) as u8;
-            output[i + 2] = 0b1000_0000 + ch.get_bits(0..6) as u8;
+            output[i] = bytes[0];
+            output[i + 1] = bytes[1];
+            output[i + 2] = bytes[2];
+
             i += 3;
+        } else {
+            unreachable!("More than three bytes per UCS-2 character.");
         }
-    }
 
-    Ok(i)
+        Ok(())
+    })
 }
 
 #[cfg(test)]
@@ -165,4 +205,28 @@ mod tests {
         assert_eq!(result.unwrap(), 9);
         assert_eq!(core::str::from_utf8(&u8_buffer[0..9]), Ok("$¢ह한"));
     }
+
+    #[test]
+    fn decoding_with() {
+        let input = "$¢ह한";
+
+        let mut u16_buffer = [0u16; 4];
+        let result = encode(input, &mut u16_buffer);
+        assert_eq!(result.unwrap(), 4);
+
+        let mut u8_buffer = [0u8; 9];
+        let mut pos = 0;
+
+        let result = decode_with(&u16_buffer, |bytes| {
+            for byte in bytes.into_iter() {
+                u8_buffer[pos] = *byte;
+                pos += 1;
+            }
+
+            Ok(())
+        });
+
+        assert_eq!(result.unwrap(), 9);
+        assert_eq!(core::str::from_utf8(&u8_buffer[0..9]), Ok("$¢ह한"));
+    }
 }