1// © 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 */
27enum { 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 */
58typedef struct UParseError {
59
60    /**
61     * The line on which the error occurred.  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 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
95