source/common/unicode/parseerr.h

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