icu/unicode/parseerr.h

   1 /*
   2 **********************************************************************
   3 *   Copyright (C) 1999-2005, International Business Machines
   4 *   Corporation and others.  All Rights Reserved.
   5 **********************************************************************
   6 *   Date        Name        Description
   7 *   03/14/00    aliu        Creation.
   8 *   06/27/00    aliu        Change from C++ class to C struct
   9 **********************************************************************
  10 */
  11 #ifndef PARSEERR_H
  12 #define PARSEERR_H
  13
  14 #include "unicode/utypes.h"
  15
  16
  17 /**
  18  * \file
  19  * \brief C API: Parse Error Information
  20  */
  21 /**
  22  * The capacity of the context strings in UParseError.
  23  * @stable ICU 2.0
  24  */
  25 enum { U_PARSE_CONTEXT_LEN = 16 };
  26
  27 /**
  28  * A UParseError struct is used to returned detailed information about
  29  * parsing errors.  It is used by ICU parsing engines that parse long
  30  * rules, patterns, or programs, where the text being parsed is long
  31  * enough that more information than a UErrorCode is needed to
  32  * localize the error.
  33  *
  34  * <p>The line, offset, and context fields are optional; parsing
  35  * engines may choose not to use to use them.
  36  *
  37  * <p>The preContext and postContext strings include some part of the
  38  * context surrounding the error.  If the source text is "let for=7"
  39  * and "for" is the error (e.g., because it is a reserved word), then
  40  * some examples of what a parser might produce are the following:
  41  *
  42  * <pre>
  43  * preContext   postContext
  44  * ""           ""            The parser does not support context
  45  * "let "       "=7"          Pre- and post-context only
  46  * "let "       "for=7"       Pre- and post-context and error text
  47  * ""           "for"         Error text only
  48  * </pre>
  49  *
  50  * <p>Examples of engines which use UParseError (or may use it in the
  51  * future) are Transliterator, RuleBasedBreakIterator, and
  52  * RegexPattern.
  53  *
  54  * @stable ICU 2.0
  55  */
  56 typedef struct UParseError {
  57
  58     /**
  59      * The line on which the error occured.  If the parser uses this
  60      * field, it sets it to the line number of the source text line on
  61      * which the error appears, which will be be a value >= 1.  If the
  62      * parse does not support line numbers, the value will be <= 0.
  63      * @stable ICU 2.0
  64      */
  65     int32_t        line;
  66
  67     /**
  68      * The character offset to the error.  If the line field is >= 1,
  69      * then this is the offset from the start of the line.  Otherwise,
  70      * this is the offset from the start of the text.  If the parser
  71      * does not support this field, it will have a value < 0.
  72      * @stable ICU 2.0
  73      */
  74     int32_t        offset;
  75
  76     /**
  77      * Textual context before the error.  Null-terminated.  The empty
  78      * string if not supported by parser.
  79      * @stable ICU 2.0
  80      */
  81     UChar          preContext[U_PARSE_CONTEXT_LEN];
  82
  83     /**
  84      * The error itself and/or textual context after the error.
  85      * Null-terminated.  The empty string if not supported by parser.
  86      * @stable ICU 2.0
  87      */
  88     UChar          postContext[U_PARSE_CONTEXT_LEN];
  89
  90 } UParseError;
  91
  92 #endif