core/library/textual/string_manipulation.h

   1 #ifndef STRING_MANIPULATION_CLASS
   2 #define STRING_MANIPULATION_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : string_manipulation                                               *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2000-$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
  20 namespace textual {
  21
  22 //! Provides various functions for massaging strings.
  23
  24 class string_manipulation
  25 {
  26 public:
  27
  28 //////////////
  29
  30   static basis::astring make_random_name(int min = 1, int max = 64);
  31     //!< creates a random name, where the letters are between 'a' and 'z'.
  32     /*!< the underscore will also be used occasionally.  the size is random,
  33     but the minimum size is "min" while the maximum is "max". */
  34
  35 //////////////
  36
  37   static basis::astring long_line(char line_item = '/', int repeat = 76);
  38     //!< produces a long line of "line_item" characters.
  39     /*!< returns a string of text that is somewhat long compared to an 80 column
  40     output window and which consists of a single character repeated.  the
  41     character used and the repeat count are both variable. */
  42
  43   static basis::astring indentation(int spaces);
  44     //!< Returns a string made of white space that is "spaces" long.
  45
  46 //////////////
  47
  48   static void carriage_returns_to_spaces(basis::astring &to_strip);
  49     //!< converts carriage returns in "to_strip" into spaces.
  50     /*!< processes the string "to_strip" by replacing all single carriage
  51     returns with spaces and by turning two or more carriage returns into a
  52     single CR plus spaces. */
  53
  54 //////////////
  55
  56   static void split_lines(const basis::astring &input, basis::astring &output,
  57           int min_column = 0, int max_column = 79);
  58     //!< formats blocks of text for a maximum width.
  59     /*!< processes the "input" text by splitting any lines that are longer
  60     than the "max_column".  the "min_column" is used to specify how much
  61     indentation should be included. */
  62
  63 //////////////
  64
  65   // numerical manipulation functions:
  66
  67   static basis::abyte char_to_hex(char to_convert);
  68     //!< Converts a single character into the corresponding hex nibble.
  69     /*!< If the character is not valid, an arbitrary value is returned. */
  70   static char hex_to_char(basis::abyte to_convert);
  71     //!< Converts a byte between 0 and 15 into a corresponding hexadecimal character.
  72
  73   static basis::byte_array string_to_hex(const basis::astring &character_form);
  74     //!< Turns a string form of a set of hex numbers into an array of bytes.
  75     /*!< This functions takes a string in "character_form" and returns an array
  76     of bytes that is half as long and which contains the hexadecimal
  77     interpretation of the string.  This is currently geared to even length
  78     strings... */
  79   static basis::astring hex_to_string(const basis::byte_array &byte_form);
  80     //!< The inverse of string_to_hex prints "byte_form" as text.
  81     /*!< This function takes an array of bytes and converts them into their
  82     equivalent hexadecimal character representation. */
  83 };
  84
  85 } //namespace.
  86
  87 #endif
  88