Plexdata Binary Converter

Overview

The Plexdata Binary Converter represents a library that allows generating a string which represents the hexadecimal interpretation of a binary buffer. Further, it is possible to configure the converter behavior to fit specific needs.

Licensing

The software has been published under the terms of

MIT License

Copyright © 2019 plexdata.de

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Installation

The binary files of the Plexdata Binary Converter are provided as NuGet package and can be obtained from https://www.nuget.org/packages/Plexdata.BinConverter. How to install this NuGet package manually is explained there.

Using the Plexdata Binary Converter together with Visual Studio.

Additionally, all releases can be downloaded from GitHub. Please visit page Plexdata Binary Converter to find all available versions.

Examples

This section wants to show some examples of how to use the Plexdata Binary Converter.

Default Settings

The following code snippet shows how to use the Plexdata Binary Converter with default settings.

private String StandardExample(Byte[] buffer)
{
    return BinConverterFactory.CreateConverter().Convert(buffer);
}

As shown above, a usage with default settings is pretty straightforward. And with these settings an output would look like as shown below.

00000000:  00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F  ................
00000010:  10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F  ................
00000020:  20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F   !"#$%&'()*+,-./
00000030:  30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F  0123456789:;<=>?
00000040:  40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F  @ABCDEFGHIJKLMNO
00000050:  50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F  PQRSTUVWXYZ[\]^_
00000060:  60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F  `abcdefghijklmno
00000070:  70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F  pqrstuvwxyz{|}~.
00000080:  80 81 __ __ __ __ __ __ __ __ __ __ __ __ __ __  ..______________

Two Byte Blocks

The following code snippet shows how to configure the output in a way that each hexadecimal block uses two bytes instead of just one byte.

private String TwoByteBlockExample(Byte[] buffer)
{
    IBinConverterSettings settings = BinConverterFactory.CreateSettings();

    settings.ByteBlockCount = 8;
    settings.ByteBlockWidth = 2;

    return BinConverterFactory.CreateConverter(settings).Convert(buffer);
}

As shown above, the only thing to do is to set properties ByteBlockCount and ByteBlockWidth accordingly. With these settings the output would look like as shown below.

00000000:  0001 0203 0405 0607 0809 0A0B 0C0D 0E0F  ................
00000010:  1011 1213 1415 1617 1819 1A1B 1C1D 1E1F  ................
00000020:  2021 2223 2425 2627 2829 2A2B 2C2D 2E2F   !"#$%&'()*+,-./
00000030:  3031 3233 3435 3637 3839 3A3B 3C3D 3E3F  0123456789:;<=>?
00000040:  4041 4243 4445 4647 4849 4A4B 4C4D 4E4F  @ABCDEFGHIJKLMNO
00000050:  5051 5253 5455 5657 5859 5A5B 5C5D 5E5F  PQRSTUVWXYZ[\]^_
00000060:  6061 6263 6465 6667 6869 6A6B 6C6D 6E6F  `abcdefghijklmno
00000070:  7071 7273 7475 7677 7879 7A7B 7C7D 7E7F  pqrstuvwxyz{|}~.
00000080:  80__ ____ ____ ____ ____ ____ ____ ____  ._______________

Full Byte Block

The following code snippet shows how to configure the output in a way that each hexadecimal block does not use any delimiter in between.

private String FullByteBlockExample(Byte[] buffer)
{
    IBinConverterSettings settings = BinConverterFactory.CreateSettings();

    settings.ByteBlockCount = 1;
    settings.ByteBlockWidth = 16;

    return BinConverterFactory.CreateConverter(settings).Convert(buffer);
}

As shown above, the only thing to do is to set properties ByteBlockCount and ByteBlockWidth accordingly. With these settings the output would look like as shown below.

00000000:  000102030405060708090A0B0C0D0E0F  ................
00000010:  101112131415161718191A1B1C1D1E1F  ................
00000020:  202122232425262728292A2B2C2D2E2F   !"#$%&'()*+,-./
00000030:  303132333435363738393A3B3C3D3E3F  0123456789:;<=>?
00000040:  404142434445464748494A4B4C4D4E4F  @ABCDEFGHIJKLMNO
00000050:  505152535455565758595A5B5C5D5E5F  PQRSTUVWXYZ[\]^_
00000060:  606162636465666768696A6B6C6D6E6F  `abcdefghijklmno
00000070:  707172737475767778797A7B7C7D7E7F  pqrstuvwxyz{|}~.
00000080:  8081____________________________  ..______________

Only Byte Block

The following code snippet shows how to configure the output in a way that only hexadecimal block is created.

private String OnlyByteBlockExample(Byte[] buffer)
{
    IBinConverterSettings settings = BinConverterFactory.CreateSettings();

    settings.IsShowTextBlock = false;

    return BinConverterFactory.CreateConverter(settings).Convert(buffer);
}

As shown above, the only thing to do is to set property IsShowTextBlock accordingly. With these settings the output would look like as shown below.

00000000:  00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
00000010:  10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F
00000020:  20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F
00000030:  30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F
00000040:  40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F
00000050:  50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F
00000060:  60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F
00000070:  70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F
00000080:  80 81 __ __ __ __ __ __ __ __ __ __ __ __ __ __

Only Text Block

The following code snippet shows how to configure the output in a way that only text block is created.

private String OnlyTextBlockExample(Byte[] buffer)
{
    IBinConverterSettings settings = BinConverterFactory.CreateSettings();

    settings.IsShowByteBlock = false;

    return BinConverterFactory.CreateConverter(settings).Convert(buffer);
}

As shown above, the only thing to do is to set property IsShowByteBlock accordingly. With these settings the output would look like as shown below.

00000000:  ................
00000010:  ................
00000020:   !"#$%&'()*+,-./
00000030:  0123456789:;<=>?
00000040:  @ABCDEFGHIJKLMNO
00000050:  PQRSTUVWXYZ[\]^_
00000060:  `abcdefghijklmno
00000070:  pqrstuvwxyz{|}~.
00000080:  ..______________

Long Address

The following code snippet shows how to configure the output in a way that long addresses will be used.

private String LongAddressExample(Byte[] buffer)
{
    IBinConverterSettings settings = BinConverterFactory.CreateSettings();

    settings.AddressSize = 8;

    return BinConverterFactory.CreateConverter(settings).Convert(buffer);
}

As shown above, the only thing to do is to set property AddressSize accordingly. With these settings the output would look like as shown below.

0000000000000000:  00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F  ................
0000000000000010:  10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F  ................
0000000000000020:  20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F   !"#$%&'()*+,-./
0000000000000030:  30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F  0123456789:;<=>?
0000000000000040:  40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F  @ABCDEFGHIJKLMNO
0000000000000050:  50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F  PQRSTUVWXYZ[\]^_
0000000000000060:  60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F  `abcdefghijklmno
0000000000000070:  70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F  pqrstuvwxyz{|}~.
0000000000000080:  80 81 __ __ __ __ __ __ __ __ __ __ __ __ __ __  ..______________

Disable Address Delimiter

The following code snippet shows how to configure the output in a way that the address delimiter will be disabled.

private String DisableAddressDelimiterExample(Byte[] buffer)
{
    IBinConverterSettings settings = BinConverterFactory.CreateSettings();

    settings.AddressDelimiterWidth = 0;

    return BinConverterFactory.CreateConverter(settings).Convert(buffer);
}

As shown above, the only thing to do is to set property AddressDelimiterWidth accordingly. With these settings the output would look like as shown below.

00000000  00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F  ................
00000010  10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F  ................
00000020  20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F   !"#$%&'()*+,-./
00000030  30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F  0123456789:;<=>?
00000040  40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F  @ABCDEFGHIJKLMNO
00000050  50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F  PQRSTUVWXYZ[\]^_
00000060  60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F  `abcdefghijklmno
00000070  70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F  pqrstuvwxyz{|}~.
00000080  80 81 __ __ __ __ __ __ __ __ __ __ __ __ __ __  ..______________

Change Address Delimiter

The following code snippet shows how to configure the output in a way that a different address delimiter will be used instead.

private String ChangeAddressDelimiterExample(Byte[] buffer)
{
    IBinConverterSettings settings = BinConverterFactory.CreateSettings();

    settings.AddressDelimiterValue = '#';

    return BinConverterFactory.CreateConverter(settings).Convert(buffer);
}

As shown above, the only thing to do is to set property AddressDelimiterValue accordingly. With these settings the output would look like as shown below.

00000000#  00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F  ................
00000010#  10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F  ................
00000020#  20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F   !"#$%&'()*+,-./
00000030#  30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F  0123456789:;<=>?
00000040#  40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F  @ABCDEFGHIJKLMNO
00000050#  50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F  PQRSTUVWXYZ[\]^_
00000060#  60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F  `abcdefghijklmno
00000070#  70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F  pqrstuvwxyz{|}~.
00000080#  80 81 __ __ __ __ __ __ __ __ __ __ __ __ __ __  ..______________

Change Control Character

The following code snippet shows how to configure the output in a way that a different control character replacement will be used.

private String ChangeControlCharacterExample(Byte[] buffer)
{
    IBinConverterSettings settings = BinConverterFactory.CreateSettings();

    settings.ControlCharacterValue = '~';

    return BinConverterFactory.CreateConverter(settings).Convert(buffer);
}

As shown above, the only thing to do is to set property ControlCharacterValue accordingly. With these settings the output would look like as shown below.

00000000:  00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F  ~~~~~~~~~~~~~~~~
00000010:  10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F  ~~~~~~~~~~~~~~~~
00000020:  20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F   !"#$%&'()*+,-./
00000030:  30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F  0123456789:;<=>?
00000040:  40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F  @ABCDEFGHIJKLMNO
00000050:  50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F  PQRSTUVWXYZ[\]^_
00000060:  60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F  `abcdefghijklmno
00000070:  70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F  pqrstuvwxyz{|}~~
00000080:  80 81 __ __ __ __ __ __ __ __ __ __ __ __ __ __  ~~______________

Change Padding Characters

The following code snippet shows how to configure the output in a way that different padding characters will be used. But keep in mind, it is not required to always change both padding characters.

private String ChangePaddingCharactersExample(Byte[] buffer)
{
    IBinConverterSettings settings = BinConverterFactory.CreateSettings();

    settings.ByteBlockPadding = '~';
    settings.TextBlockPadding = '+';

    return BinConverterFactory.CreateConverter(settings).Convert(buffer);
}

As shown above, the only thing to do is to set properties ByteBlockPadding and TextBlockPadding accordingly. With these settings the output would look like as shown below.

00000000:  00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F  ................
00000010:  10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F  ................
00000020:  20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F   !"#$%&'()*+,-./
00000030:  30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F  0123456789:;<=>?
00000040:  40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F  @ABCDEFGHIJKLMNO
00000050:  50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F  PQRSTUVWXYZ[\]^_
00000060:  60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F  `abcdefghijklmno
00000070:  70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F  pqrstuvwxyz{|}~.
00000080:  80 81 ~~ ~~ ~~ ~~ ~~ ~~ ~~ ~~ ~~ ~~ ~~ ~~ ~~ ~~  ..++++++++++++++

Buffer Limitation

To be able to prevent possible trouble with huge buffers, it would be useful to restrict the number of affected bytes. How to configure the output in a way that only a subset of the complete buffer will be used is shown in the following code snippet.

private String BufferLimitationExample(Byte[] buffer)
{
    return BinConverterFactory.CreateConverter().Convert(buffer, 42);
}

As shown above, the only thing to do is to call method Convert() with the maximum number of bytes to be used. With these settings the output would look like as shown below.

00000000:  00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F  ................
00000010:  10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F  ................
00000020:  20 21 22 23 24 25 26 27 28 29 __ __ __ __ __ __   !"#$%&'()______

Lower Cases

The following code snippet shows how to configure the output in a way that lower cases will be used.

private String LowerCasesExample(Byte[] buffer)
{
    IBinConverterSettings settings = BinConverterFactory.CreateSettings();

    settings.IsCapitalLetters = false;

    return BinConverterFactory.CreateConverter(settings).Convert(buffer);
}

As shown above, the only thing to do is to set property IsCapitalLetters accordingly. With these settings the output would look like as shown below.

00000000:  00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f  ................
00000010:  10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f  ................
00000020:  20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f   !"#$%&'()*+,-./
00000030:  30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f  0123456789:;<=>?
00000040:  40 41 42 43 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f  @ABCDEFGHIJKLMNO
00000050:  50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f  PQRSTUVWXYZ[\]^_
00000060:  60 61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f  `abcdefghijklmno
00000070:  70 71 72 73 74 75 76 77 78 79 7a 7b 7c 7d 7e 7f  pqrstuvwxyz{|}~.
00000080:  80 81 82 83 84 85 86 87 88 89 8a 8b 8c 8d 8e 8f  ................
00000090:  90 91 92 93 94 95 96 97 98 99 9a 9b 9c 9d 9e 9f  ................
000000a0:  a0 a1 a2 a3 a4 a5 a6 a7 a8 a9 aa ab ac ad ae af   ¡¢£¤¥¦§¨©ª«¬­®¯
000000b0:  b0 b1 b2 b3 b4 b5 b6 b7 b8 b9 ba bb bc bd be bf  °±²³´µ¶·¸¹º»¼½¾¿
000000c0:  c0 c1 c2 c3 c4 c5 c6 c7 c8 c9 ca cb cc cd ce cf  ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏ
000000d0:  d0 d1 d2 d3 d4 d5 d6 d7 d8 d9 da db dc dd de df  ÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞß
000000e0:  e0 e1 e2 e3 e4 e5 e6 e7 e8 e9 ea eb ec ed ee ef  àáâãäåæçèéêëìíîï
000000f0:  f0 f1 f2 f3 f4 f5 f6 f7 f8 f9 fa fb fc fd fe ff  ðñòóôõö÷øùúûüýþÿ

Address Size Adjustment

One of the major problems is the width of all addresses. For example, users may want to use an 8‑bit address. But the buffer to convert does have an actual size of 300 bytes. Is such a case the first set of addresses would not be properly aligned. Therefore, the property AddressSize is more or less just some kind of suggestion, because internally the actual address size is automatically adjusted to the minimum required size. See following code snippet and the created result for what is meant in detail.

private String AddressSizeAdjustmentExample(Byte[] buffer)
{
    IBinConverterSettings settings = BinConverterFactory.CreateSettings();

    settings.AddressSize = 1;

    return BinConverterFactory.CreateConverter(settings).Convert(buffer);
}

As shown above, the wanted address size is set to an 8‑bit address. But the actual buffer size is 300 bytes. Against this background, the output below uses a 16‑bit address instead of the configured 8‑bit address.

0000:  00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F  ................
0010:  10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F  ................
0020:  20 21 22 23 24 25 26 27 28 29 2A 2B 2C 2D 2E 2F   !"#$%&'()*+,-./
0030:  30 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F  0123456789:;<=>?
0040:  40 41 42 43 44 45 46 47 48 49 4A 4B 4C 4D 4E 4F  @ABCDEFGHIJKLMNO
0050:  50 51 52 53 54 55 56 57 58 59 5A 5B 5C 5D 5E 5F  PQRSTUVWXYZ[\]^_
0060:  60 61 62 63 64 65 66 67 68 69 6A 6B 6C 6D 6E 6F  `abcdefghijklmno
0070:  70 71 72 73 74 75 76 77 78 79 7A 7B 7C 7D 7E 7F  pqrstuvwxyz{|}~.
0080:  80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F  ................
0090:  90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F  ................
00A0:  A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF   ¡¢£¤¥¦§¨©ª«¬­®¯
00B0:  B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF  °±²³´µ¶·¸¹º»¼½¾¿
00C0:  C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 CA CB CC CD CE CF  ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏ
00D0:  D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 DA DB DC DD DE DF  ÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞß
00E0:  E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC ED EE EF  àáâãäåæçèéêëìíîï
00F0:  F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF  ðñòóôõö÷øùúûüýþÿ
0100:  00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F  ................
0110:  10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F  ................
0120:  20 21 22 23 24 25 26 27 28 29 2A 2B __ __ __ __   !"#$%&'()*+____

Limitation

There are some limitations when using the Plexdata Binary Converter. Clarifying them is task of this section.

The totally supported buffer size is limited to the maximum of a 32‑bit signed integer. In other words, the maximum buffer length should not exceed a size of 2,147,483,647 bytes.

In contrast to the total supported buffer length, the actual possible buffer length depends on the available memory of a particular system environment. This mean in detail that an OutOfMemoryException might be thrown by the underlying system when a provided buffer becomes too long.