include/unicode/ucharstriebuilder.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) 2010-2016, International Business Machines
0006 *   Corporation and others.  All Rights Reserved.
0007 *******************************************************************************
0008 *   file name:  ucharstriebuilder.h
0009 *   encoding:   UTF-8
0010 *   tab size:   8 (not used)
0011 *   indentation:4
0012 *
0013 *   created on: 2010nov14
0014 *   created by: Markus W. Scherer
0015 */
0016
0017 #ifndef __UCHARSTRIEBUILDER_H__
0018 #define __UCHARSTRIEBUILDER_H__
0019
0020 #include "unicode/utypes.h"
0021
0022 #if U_SHOW_CPLUSPLUS_API
0023
0024 #include "unicode/stringtriebuilder.h"
0025 #include "unicode/ucharstrie.h"
0026 #include "unicode/unistr.h"
0027
0028 /**
0029  * \file
0030  * \brief C++ API: Builder for icu::UCharsTrie
0031  */
0032
0033 U_NAMESPACE_BEGIN
0034
0035 class UCharsTrieElement;
0036
0037 /**
0038  * Builder class for UCharsTrie.
0039  *
0040  * This class is not intended for public subclassing.
0041  * @stable ICU 4.8
0042  */
0043 class U_COMMON_API UCharsTrieBuilder : public StringTrieBuilder {
0044 public:
0045     /**
0046      * Constructs an empty builder.
0047      * @param errorCode Standard ICU error code.
0048      * @stable ICU 4.8
0049      */
0050     UCharsTrieBuilder(UErrorCode &errorCode);
0051
0052     /**
0053      * Destructor.
0054      * @stable ICU 4.8
0055      */
0056     virtual ~UCharsTrieBuilder();
0057
0058     /**
0059      * Adds a (string, value) pair.
0060      * The string must be unique.
0061      * The string contents will be copied; the builder does not keep
0062      * a reference to the input UnicodeString or its buffer.
0063      * @param s The input string.
0064      * @param value The value associated with this string.
0065      * @param errorCode Standard ICU error code. Its input value must
0066      *                  pass the U_SUCCESS() test, or else the function returns
0067      *                  immediately. Check for U_FAILURE() on output or use with
0068      *                  function chaining. (See User Guide for details.)
0069      * @return *this
0070      * @stable ICU 4.8
0071      */
0072     UCharsTrieBuilder &add(const UnicodeString &s, int32_t value, UErrorCode &errorCode);
0073
0074     /**
0075      * Builds a UCharsTrie for the add()ed data.
0076      * Once built, no further data can be add()ed until clear() is called.
0077      *
0078      * A UCharsTrie cannot be empty. At least one (string, value) pair
0079      * must have been add()ed.
0080      *
0081      * This method passes ownership of the builder's internal result array to the new trie object.
0082      * Another call to any build() variant will re-serialize the trie.
0083      * After clear() has been called, a new array will be used as well.
0084      * @param buildOption Build option, see UStringTrieBuildOption.
0085      * @param errorCode Standard ICU error code. Its input value must
0086      *                  pass the U_SUCCESS() test, or else the function returns
0087      *                  immediately. Check for U_FAILURE() on output or use with
0088      *                  function chaining. (See User Guide for details.)
0089      * @return A new UCharsTrie for the add()ed data.
0090      * @stable ICU 4.8
0091      */
0092     UCharsTrie *build(UStringTrieBuildOption buildOption, UErrorCode &errorCode);
0093
0094     /**
0095      * Builds a UCharsTrie for the add()ed data and char16_t-serializes it.
0096      * Once built, no further data can be add()ed until clear() is called.
0097      *
0098      * A UCharsTrie cannot be empty. At least one (string, value) pair
0099      * must have been add()ed.
0100      *
0101      * Multiple calls to buildUnicodeString() set the UnicodeStrings to the
0102      * builder's same char16_t array, without rebuilding.
0103      * If buildUnicodeString() is called after build(), the trie will be
0104      * re-serialized into a new array (because build() passes on ownership).
0105      * If build() is called after buildUnicodeString(), the trie object returned
0106      * by build() will become the owner of the underlying data for the
0107      * previously returned UnicodeString.
0108      * After clear() has been called, a new array will be used as well.
0109      * @param buildOption Build option, see UStringTrieBuildOption.
0110      * @param result A UnicodeString which will be set to the char16_t-serialized
0111      *               UCharsTrie for the add()ed data.
0112      * @param errorCode Standard ICU error code. Its input value must
0113      *                  pass the U_SUCCESS() test, or else the function returns
0114      *                  immediately. Check for U_FAILURE() on output or use with
0115      *                  function chaining. (See User Guide for details.)
0116      * @return result
0117      * @stable ICU 4.8
0118      */
0119     UnicodeString &buildUnicodeString(UStringTrieBuildOption buildOption, UnicodeString &result,
0120                                       UErrorCode &errorCode);
0121
0122     /**
0123      * Removes all (string, value) pairs.
0124      * New data can then be add()ed and a new trie can be built.
0125      * @return *this
0126      * @stable ICU 4.8
0127      */
0128     UCharsTrieBuilder &clear() {
0129         strings.remove();
0130         elementsLength=0;
0131         ucharsLength=0;
0132         return *this;
0133     }
0134
0135 private:
0136     UCharsTrieBuilder(const UCharsTrieBuilder &other) = delete;  // no copy constructor
0137     UCharsTrieBuilder &operator=(const UCharsTrieBuilder &other) = delete;  // no assignment operator
0138
0139     void buildUChars(UStringTrieBuildOption buildOption, UErrorCode &errorCode);
0140
0141     virtual int32_t getElementStringLength(int32_t i) const override;
0142     virtual char16_t getElementUnit(int32_t i, int32_t unitIndex) const override;
0143     virtual int32_t getElementValue(int32_t i) const override;
0144
0145     virtual int32_t getLimitOfLinearMatch(int32_t first, int32_t last, int32_t unitIndex) const override;
0146
0147     virtual int32_t countElementUnits(int32_t start, int32_t limit, int32_t unitIndex) const override;
0148     virtual int32_t skipElementsBySomeUnits(int32_t i, int32_t unitIndex, int32_t count) const override;
0149     virtual int32_t indexOfElementWithNextUnit(int32_t i, int32_t unitIndex, char16_t unit) const override;
0150
0151     virtual UBool matchNodesCanHaveValues() const override { return true; }
0152
0153     virtual int32_t getMaxBranchLinearSubNodeLength() const override { return UCharsTrie::kMaxBranchLinearSubNodeLength; }
0154     virtual int32_t getMinLinearMatch() const override { return UCharsTrie::kMinLinearMatch; }
0155     virtual int32_t getMaxLinearMatchLength() const override { return UCharsTrie::kMaxLinearMatchLength; }
0156
0157     class UCTLinearMatchNode : public LinearMatchNode {
0158     public:
0159         UCTLinearMatchNode(const char16_t *units, int32_t len, Node *nextNode);
0160         virtual bool operator==(const Node &other) const override;
0161         virtual void write(StringTrieBuilder &builder) override;
0162     private:
0163         const char16_t *s;
0164     };
0165
0166     virtual Node *createLinearMatchNode(int32_t i, int32_t unitIndex, int32_t length,
0167                                         Node *nextNode) const override;
0168
0169     UBool ensureCapacity(int32_t length);
0170     virtual int32_t write(int32_t unit) override;
0171     int32_t write(const char16_t *s, int32_t length);
0172     virtual int32_t writeElementUnits(int32_t i, int32_t unitIndex, int32_t length) override;
0173     virtual int32_t writeValueAndFinal(int32_t i, UBool isFinal) override;
0174     virtual int32_t writeValueAndType(UBool hasValue, int32_t value, int32_t node) override;
0175     virtual int32_t writeDeltaTo(int32_t jumpTarget) override;
0176
0177     UnicodeString strings;
0178     UCharsTrieElement *elements;
0179     int32_t elementsCapacity;
0180     int32_t elementsLength;
0181
0182     // char16_t serialization of the trie.
0183     // Grows from the back: ucharsLength measures from the end of the buffer!
0184     char16_t *uchars;
0185     int32_t ucharsCapacity;
0186     int32_t ucharsLength;
0187 };
0188
0189 U_NAMESPACE_END
0190
0191 #endif /* U_SHOW_CPLUSPLUS_API */
0192
0193 #endif  // __UCHARSTRIEBUILDER_H__