src/native_client/src/shared/utils/formatting.h

   1 /*
   2  * Copyright 2009 The Native Client Authors. All rights reserved.
   3  * Use of this source code is governed by a BSD-style license that can be
   4  * found in the LICENSE file.
   5  */
   6
   7 /*
   8  * Some useful formatting tools that allow us to build our own directive
   9  * processing simply. The code assumes that directives of the form
  10  * %X (for some character x). Further, in a format string '\\' is treated
  11  * the backslash character ('\') while '\%' escapes out the interpretation
  12  * of '%' as the beginning of a directive.
  13  *
  14  * If the specified %X directive is not understood by the directive processing
  15  * function, the directive will not be translated while processing the format
  16  * string.
  17  *
  18  * Note: Buffer insertions are based on the routines FormatDataAppend and
  19  * FormatAppend. Each of these routines append text to the buffer, based
  20  * on the current cursor position. The cursor is the index to add the next
  21  * character to the buffer, if the buffer was sufficiently large enough to
  22  * hold the appended text. Therefore, after all text has been appended, if
  23  * the cursor is smaller than the buffer size, no truncation occurs.
  24  *
  25  * Note: Buffer insertions will automatically add the null terminator after
  26  * the appended string, but the cursor is not updated to reflect this change.
  27  * If a buffer overflows, the last character in the buffer will be the null
  28  * terminator, unless the buffer size is empty. If the buffer size is empty,
  29  * there is no room for the null terminator and it is not inserted.
  30  *
  31  * Note: To dynamically compute the amount of space needed to format a string,
  32  * call on an empty buffer with size zero, and the cursor initially set to zero.
  33  * After the call, the value of the cursor, plus one, is the minimum sized
  34  * buffer that will be needed to format that string.
  35  */
  36
  37 #ifndef NATIVE_CLIENT_SRC_SHARED_UTILS_FORMMATTING_H__
  38 #define NATIVE_CLIENT_SRC_SHARED_UTILS_FORMMATTING_H__
  39
  40 #include "native_client/src/shared/utils/types.h"
  41
  42 /*
  43  * Defines the generic format for a fucntion that processses directives
  44  * when they are found. Returns true if the directive was processed and
  45  * the resulting string was added at the given cursor position. When the buffer
  46  * fills, no additional text is added to the buffer, even though the cursor
  47  * is incremented accordingly. Otherwise, the buffer is left unchanged,
  48  * and the function must return false.
  49  *
  50  * arguments:
  51  *   directive - The character X of the found %X directive.
  52  *   buffer - The buffer to add the resulting text of the directive
  53  *   buffer_size - The size of the buffer.
  54  *   data - (Generic) pointer to the data that should be used to process the
  55  *          directive.
  56  *   cursor - The index into the buffer, where the next character
  57  *         should be added, if there is sufficient room in the buffer.
  58  */
  59 typedef Bool (*FormatDataUsingDirectiveFcn)(
  60     char directive,
  61     char* buffer,
  62     size_t buffer_size,
  63     void* data,
  64     size_t* cursor);
  65
  66 /*
  67  * Defines a driver routine to process a format string and put the rsulting
  68  * generated text in at the cursor position. When the buffer fills, no
  69  * additional text is added to the buffer, even though the cursor is
  70  * incremented accordingly.
  71  *
  72  * Note: Buffer overflow occurs iff the cursor is greater than or
  73  * equal to the buffer size.
  74  *
  75  * arguments:
  76  *   buffer - The buffer to fill using the format.
  77  *   buffer_size - The size of the buffer.
  78  *   format - The format string to use.
  79  *   data - (Generic) pointer to the data that should be used to process the
  80  *          directives in the format string.
  81  *   directive_fcn - The function to process directives as they are found.
  82  *   cursor - The index into the buffer, where the next character should
  83  *          be added, if there is sufficient room in the buffer.
  84  */
  85 void FormatDataAppend(char* buffer,
  86                       size_t buffer_size,
  87                       const char* format,
  88                       void* data,
  89                       FormatDataUsingDirectiveFcn directive_fcn,
  90                       size_t* cursor);
  91
  92 /*
  93  * Defines a driver routine to process a format string and put the resulting
  94  * generated text in the given buffer. Returns true iff buffer overflow doesn't
  95  * occur.
  96  *
  97  * arguments:
  98  *   buffer - The buffer to fill using the format.
  99  *   buffer_size - The size of the buffer.
 100  *   format - The format string to use.
 101  *   data - (Generic) pointer to the data that should be used to process the
 102  *          directives in the format string.
 103  *   directive_fcn - The function to process directives as they are found.
 104  */
 105 Bool FormatData(char* buffer,
 106                 size_t buffer_size,
 107                 const char* format,
 108                 void* data,
 109                 FormatDataUsingDirectiveFcn directive_fcn);
 110
 111 /*
 112  * Append the given text at the cursor position. When the buffer fills, no
 113  * additional text is added to the buffer, even though the cursor is incremented
 114  * accordingly.
 115  *
 116  * Note: Buffer overflow occurs iff the cursor is greater than or
 117  * equal to the buffer size.
 118  *
 119  * arguments:
 120  *    buffer - The buffer to fill with the text.
 121  *    buffer_size - The size of the  buffer.
 122  *    text - The text to append.
 123  *    cursor - The index into the buffer, where the next character
 124  *         should be added, if there is sufficient room in the buffer.
 125  */
 126 void FormatAppend(char* buffer,
 127                   size_t buffer_size,
 128                   const char* text,
 129                   size_t* index);
 130
 131 #endif  /* NATIVE_CLIENT_SRC_SHARED_UTILS_FORMMATTING_H__ */