include/unicode/parseerr.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 **********************************************************************
0005 *   Copyright (C) 1999-2005, International Business Machines
0006 *   Corporation and others.  All Rights Reserved.
0007 **********************************************************************
0008 *   Date        Name        Description
0009 *   03/14/00    aliu        Creation.
0010 *   06/27/00    aliu        Change from C++ class to C struct
0011 **********************************************************************
0012 */
0013 #ifndef PARSEERR_H
0014 #define PARSEERR_H
0015
0016 #include "unicode/utypes.h"
0017
0018
0019 /**
0020  * \file
0021  * \brief C API: Parse Error Information
0022  */
0023 /**
0024  * The capacity of the context strings in UParseError.
0025  * @stable ICU 2.0
0026  */
0027 enum { U_PARSE_CONTEXT_LEN = 16 };
0028
0029 /**
0030  * A UParseError struct is used to returned detailed information about
0031  * parsing errors.  It is used by ICU parsing engines that parse long
0032  * rules, patterns, or programs, where the text being parsed is long
0033  * enough that more information than a UErrorCode is needed to
0034  * localize the error.
0035  *
0036  * <p>The line, offset, and context fields are optional; parsing
0037  * engines may choose not to use to use them.
0038  *
0039  * <p>The preContext and postContext strings include some part of the
0040  * context surrounding the error.  If the source text is "let for=7"
0041  * and "for" is the error (e.g., because it is a reserved word), then
0042  * some examples of what a parser might produce are the following:
0043  *
0044  * <pre>
0045  * preContext   postContext
0046  * ""           ""            The parser does not support context
0047  * "let "       "=7"          Pre- and post-context only
0048  * "let "       "for=7"       Pre- and post-context and error text
0049  * ""           "for"         Error text only
0050  * </pre>
0051  *
0052  * <p>Examples of engines which use UParseError (or may use it in the
0053  * future) are Transliterator, RuleBasedBreakIterator, and
0054  * RegexPattern.
0055  *
0056  * @stable ICU 2.0
0057  */
0058 typedef struct UParseError {
0059
0060     /**
0061      * The line on which the error occurred.  If the parser uses this
0062      * field, it sets it to the line number of the source text line on
0063      * which the error appears, which will be a value >= 1.  If the
0064      * parse does not support line numbers, the value will be <= 0.
0065      * @stable ICU 2.0
0066      */
0067     int32_t        line;
0068
0069     /**
0070      * The character offset to the error.  If the line field is >= 1,
0071      * then this is the offset from the start of the line.  Otherwise,
0072      * this is the offset from the start of the text.  If the parser
0073      * does not support this field, it will have a value < 0.
0074      * @stable ICU 2.0
0075      */
0076     int32_t        offset;
0077
0078     /**
0079      * Textual context before the error.  Null-terminated.  The empty
0080      * string if not supported by parser.
0081      * @stable ICU 2.0
0082      */
0083     UChar          preContext[U_PARSE_CONTEXT_LEN];
0084
0085     /**
0086      * The error itself and/or textual context after the error.
0087      * Null-terminated.  The empty string if not supported by parser.
0088      * @stable ICU 2.0
0089      */
0090     UChar          postContext[U_PARSE_CONTEXT_LEN];
0091
0092 } UParseError;
0093
0094 #endif