nucleus/library/textual/byte_formatter.h

   1 #ifndef BYTE_FORMATTER_CLASS
   2 #define BYTE_FORMATTER_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : byte_formatter                                                    *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 1992-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include <basis/astring.h>
  19 #include <basis/definitions.h>
  20
  21 namespace textual {
  22
  23 //! Provides functions for manipulating arrays of bytes.
  24
  25 class byte_formatter : public virtual basis::root_object
  26 {
  27 public:
  28   virtual ~byte_formatter() {}
  29
  30   DEFINE_CLASS_NAME("byte_formatter");
  31
  32   static void print_char(basis::abyte to_print, basis::astring &out,
  33         char replace = '_');
  34     //!< prints the byte "to_print" into "out" as long as "to_print" is readable.
  35     /*!< if it's not readable, then the "replace" is printed. */
  36
  37   static void print_chars(const basis::abyte *to_print, int length,
  38           basis::astring &out, char replace = '_');
  39     //!< sends the bytes in "to_print" of "length" bytes into the string "out".
  40
  41   static void text_dump(basis::astring &output, const basis::abyte *location,
  42           basis::un_int length, basis::un_int label = 0, const char *eol = "\n");
  43     //!< prints out a block of memory in a human readable form.
  44     /*!< it is stored in the "output" string.  the "location" is where to dump,
  45     the "length" is the number of bytes to dump, and the "label" is where to
  46     start numbering the location label on the first line.  the "eol" supplies
  47     the line ending sequence to be used for the output file.  this should be
  48     "\r\n" for win32. */
  49
  50   static basis::astring text_dump(const basis::abyte *location, basis::un_int length,
  51           basis::un_int label = 0, const char *eol = "\n");
  52     //!< this is a less efficient version of text_dump that returns a string.
  53     /*!< it's easier to use when combining astrings. */
  54
  55   static void text_dump(basis::astring &output,
  56           const basis::byte_array &to_dump, basis::un_int label = 0, const char *eol = "\n");
  57     //!< a version that operates on a byte_array and stores into a string.
  58   static basis::astring text_dump(const basis::byte_array &to_dump,
  59           basis::un_int label = 0, const char *eol = "\n");
  60     //!< a version that operates on a byte_array and returns a string.
  61
  62   //! this operation performs the inverse of a text_dump.
  63   static void parse_dump(const basis::astring &dumped_form,
  64           basis::byte_array &bytes_found);
  65
  66 //////////////
  67
  68   static void bytes_to_string(const basis::byte_array &to_convert,
  69           basis::astring &as_string, bool space_delimited = true);
  70     //!< converts a byte_array into a string.
  71     /*!< takes an array of bytes "to_convert" and spits out the equivalent form
  72     "as_string".  if "space_delimited" is true, then the bytes are separated
  73     by spaces. */
  74
  75   static void string_to_bytes(const basis::astring &to_convert,
  76           basis::byte_array &as_array);
  77     //!< wrangles the string "to_convert" into an equivalent byte form "as_array".
  78     /*!< this is a fairly forgiving conversion; it will accept any string and
  79     strip out the hexadecimal bytes.  spacing is optional, but every two
  80     hex nibbles together will be taken as a byte.  if there are an odd number
  81     of nibbles, then the odd one will be taken as the least significant half
  82     of a byte. */
  83
  84   static void bytes_to_string(const basis::abyte *to_convert, int length,
  85           basis::astring &as_string, bool space_delimited = true);
  86     //!< a version that accepts a byte pointer and length, rather than byte_array.
  87
  88   static void string_to_bytes(const char *to_convert,
  89           basis::byte_array &as_array);
  90     //!< a version that works with the char pointer rather than an astring.
  91
  92 //////////////
  93
  94   static void bytes_to_shifted_string
  95           (const basis::byte_array &to_convert, basis::astring &as_string);
  96     //!< this is a special purpose converter from bytes to character strings.
  97     /*!< it merely ensures that the "as_string" version has no zero bytes
  98     besides the end of string null byte.  this packs 7 bits of data into each
  99     character, resulting in an 87.5% efficient string packing of the array.
 100     the resulting string is not readable.  the "as_string" parameter is not
 101     reset; any data will be appended to it. */
 102
 103   static void shifted_string_to_bytes(const basis::astring &to_convert,
 104           basis::byte_array &as_array);
 105     //!< unshifts a string "to_convert" back into a byte_array.
 106     /*!< converts a string "to_convert" created by bytes_to_shifted_string() into
 107     the original array of bytes and stores it in "as_array".  the "as_array"
 108     parameter is not reset; any data will be appended to it. */
 109
 110 //////////////
 111
 112   // utility methods to help building the formatted strings.
 113
 114   static void make_eight(basis::un_int num, basis::astring &out);
 115
 116   static bool in_hex_range(char to_check);
 117 };
 118
 119 } //namespace.
 120
 121 #endif
 122