System.Classes.HexToBin

From RAD Studio API Documentation
Jump to: navigation, search

Delphi

function HexToBin(const Text: PChar; TextOffset: Integer; var Buffer: TBytes; BufOffset: Integer; Count: Integer): Integer; overload;
function HexToBin(const Text: TBytes; TextOffset: Integer; var Buffer: TBytes; BufOffset: Integer; Count: Integer): Integer;
function HexToBin(Text: PWideChar; Buffer: PAnsiChar; BufSize: Integer): Integer;
function HexToBin(Text: PAnsiChar; Buffer: PAnsiChar; BufSize: Integer): Integer;
function HexToBin(Text: PWideChar; var Buffer; BufSize: Integer): Integer;
function HexToBin(Text: PAnsiChar; var Buffer; BufSize: Integer): Integer;
function HexToBin(Text: PWideChar; Buffer: Pointer; BufSize: Integer): Integer;
function HexToBin(Text: PAnsiChar; Buffer: Pointer; BufSize: Integer): Integer;

C++

extern DELPHI_PACKAGE int __fastcall HexToBin(const System::WideChar * Text, int TextOffset, System::DynamicArray<System::Byte> &Buffer, int BufOffset, int Count)/* overload */;

Properties

Type Visibility Source Unit Parent
function public
System.Classes.pas
System.Classes.hpp
System.Classes System.Classes

Description

Converts a string of hexadecimal digits to the corresponding binary value.

Call HexToBin to convert the hexadecimal string Text to the binary value that the string represents.

This function receives the following parameters:

Parameter Description

Text

Pointer to a string representing a hexadecimal value.

For example: "1decaf".

Notes:
  • The hexadecimal number must use lowercase characters; HexToBin does not recognize uppercase characters. For example: "ACDC66" is an invalid string, you must use "acdc66" instead.
  • The number of input characters must be even. That is, "3d" and "c3f0" are both valid input strings, but "2" or "fda" are invalid strings. This is because the output, binary value is in bytes (8 bits), and hexadecimal characters only represent 4 bits. You can add zeros on the left-hand side to convert them into valid strings without changing their value: "02", "0fda".
  • This string does not need to be null-terminated.

TextOffset
(optional)

Number of characters to skip at the beginning of the input string.

For example, if Text is "608da975" and TextOffset is 4, only "a975" is converted to binary.

Buffer

Pointer to an array of bytes that will receive the value of the hexadecimal input string.

For example, for the input string "1decaf", the output binary value would be 00011101 11101100 10101111 (3 bytes).

BufOffset
(optional)

Number of bytes to skip at the beginning of the output array of bytes.

For example, if Buffer is 00011101 11101100 10101111 before you call HexToBin and TextOffset is 1, HexToBin starts writing the output value on the second byte, and the first byte (00011101) remains unchanged.

BufSize or
Count

Number of bytes (pairs of hexadecimal characters) to convert into the output array of bytes.

Note: This value should be either equal or lower than both half the length of the input string or the length of the output array. For example:
  • If the input string is 8 characters long, this number should be 4 or lower.
  • If the array is 8 bytes long, this number should be 8 or lower.
  • If the input string is 8 characters long and the array is 8 bytes long, this number should be 4 or lower (because of the string length).

You can call HexToBin with or without specifying an offset for the input string (TextOffset) or the output buffer (BufOffset). However, you must specify either both offsets or specify neither of them.

When HexToBin finds a character that is not a hexadecimal character, it stops converting and returns. For example, given the string "9abcdefg", HexToBin only converts "9abcde", as the next pair of characters ("fg") contains an invalid character ("g").

The return value of HexToBin depends on whether or not you specified offsets in the call to HexToBin:

  • If you did specify offsets, the return value is the number of bytes read from the input string and written in binary into Buffer. For example, given the string "9abcdefg", it returns 3, as it reads 3 bytes ("9abcde", "fg" contains an invalid character).
  • If you did not specify offsets, the return value is the number of bytes that were not read from the input string and written in binary into Buffer (BufSize - bytes written into Buffer). For example, given the string "9abcdefg" and a BufSize of 4, it returns 1, as it reads 3 out of 4 expected bytes ("9abcde", "fg" contains an invalid character).

See Also

Code Examples