Converts a byte sequence of `from_encoding` encoded text to `to_encoding`.

# Byte order

For UTF-16 and UTF-32 without LE/BE, the byte order of `input` is determined by the BOM (Byte Order Mark) if it exists in the `input`. If the BOM is not present, a default byte order will be assumed which is implementation-defined.

For UTF-16 and UTF-32 without LE/BE, the output byte order is implementation-defined. 

# BOM handling

This function follows the same convention as [libiconv].

For input:

- If BOM is present and is used to determine the byte order for `UTF-16` or `UTF-32`, it will be removed.
- For `UTF-8`, `UTF-16LE`, `UTF-16BE`, `UTF-32LE` and `UTF-32BE`, the "BOM" is actually considered as `U+FEFF` (ZERO WIDTH NO-BREAK SPACE) in the text. It will be preserved.

For output:

- If `to_encoding` is `UTF-16` or `UTF-32`, a BOM will be added to the output.
- Otherwise, no BOM will be added. This includes `UTF-8`, `UTF-16LE`, `UTF-16BE`, `UTF-32LE` and `UTF-32BE`.

# Errors

- If `from_encoding`, `to_encoding` or the conversion pair from `from_encoding` to `to_encoding` is not supported by the underlying implementation, [`ConvertError::UnknownConversion`] is returned.
- If `input` contains invalid sequences for `encoding` or there are characters that cannot be perfectly represented by `to_encoding`, [`ConvertError::InvalidInput`] is returned. If you do not care about them, use [`convert_lossy`](fn.convert_lossy.html) instead. Note that some implementations may not report errors in this case and will return the result with replacement characters.

# Examples

```rust
use iconv_native::{convert, ConvertError};

let output_no_bom = convert(b"\xdc\xbd\xc4\xfe\xc4\xc8", "gb18030", "utf-16be");
let output_bom_added = convert(b"\xdc\xbd\xc4\xfe\xc4\xc8", "gb18030", "utf-16");
let output_bom_removed = convert(
    b"\xff\xfe\x66\x8e\x66\x8e\xb8\x70\x39\x5f",
    "utf-16",
    "utf-32le",
);
let output_bom_inout = convert(
    b"\xfe\xff\x8e\x66\x8e\x66\x70\xb8\x5f\x39",
    "utf-16",
    "utf-32",
);
let output_not_a_bom = convert(
    b"\xef\xbb\xbf\xe8\x8a\x99\xe5\xae\x81\xe5\xa8\x9c",
    "utf-8",
    "utf-32be",
);
let output_invalid_encoding = convert(b"\x11\x45", "invalid-encoding", "utf-8");
let output_invalid_input = convert(b"\xff 141919", "utf-8", "gb18030");

const EXPECTED_NO_BOM: &[u8] = b"\x82\x99\x5b\x81\x5a\x1c";
const EXPECTED_BOM_ADDED_BE: &[u8] = b"\xfe\xff\x82\x99\x5b\x81\x5a\x1c";
const EXPECTED_BOM_ADDED_LE: &[u8] = b"\xff\xfe\x99\x82\x81\x5b\x1c\x5a";
const EXPECTED_BOM_REMOVED: &[u8] = b"\x66\x8e\0\0\x66\x8e\0\0\xb8\x70\0\0\x39\x5f\0\0";
const EXPECTED_BOM_INOUT_BE: &[u8] =
    b"\xff\xfe\0\0\x66\x8e\0\0\x66\x8e\0\0\xb8\x70\0\0\x39\x5f\0\0";
const EXPECTED_BOM_INOUT_LE: &[u8] =
    b"\0\0\xfe\xff\0\0\x8e\x66\0\0\x8e\x66\0\0\x70\xb8\0\0\x5f\x39";
const EXPECTED_NOT_A_BOM: &[u8] = b"\0\0\xfe\xff\0\0\x82\x99\0\0\x5b\x81\0\0\x5a\x1c";

assert_eq!(output_no_bom?, EXPECTED_NO_BOM, "no bom");
assert!(
    matches!(
        &*output_bom_added?,
        EXPECTED_BOM_ADDED_BE | EXPECTED_BOM_ADDED_LE
    ),
    "bom added"
);
assert_eq!(output_bom_removed?, EXPECTED_BOM_REMOVED, "bom removed");
assert!(
    matches!(
        &*output_bom_inout?,
        EXPECTED_BOM_INOUT_BE | EXPECTED_BOM_INOUT_LE
    ),
    "bom in-out"
);
assert_eq!(output_not_a_bom?, EXPECTED_NOT_A_BOM, "not a bom");
assert_eq!(
    output_invalid_encoding.unwrap_err(),
    ConvertError::UnknownConversion
);
assert_eq!(
    output_invalid_input.unwrap_err(),
    ConvertError::InvalidInput
);
# Ok::<(), iconv_native::ConvertError>(())
```

[libiconv]: https://www.gnu.org/software/libiconv/