| #ifndef UIMA_LISTFS_HPP |
| #define UIMA_LISTFS_HPP |
| /** \file listfs.hpp . |
| ----------------------------------------------------------------------------- |
| |
| |
| |
| |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| |
| ----------------------------------------------------------------------------- |
| |
| \brief Contains the family of ListFS classes (IntListFS, FloatListFS etc.) |
| |
| Description: |
| |
| ----------------------------------------------------------------------------- |
| |
| |
| -------------------------------------------------------------------------- */ |
| |
| |
| /* ----------------------------------------------------------------------- */ |
| /* Include dependencies */ |
| /* ----------------------------------------------------------------------- */ |
| |
| #include "uima/pragmas.hpp" |
| |
| #include "uima/lowlevel_typedefs.hpp" |
| #include "uima/typesystem.hpp" |
| #include "uima/exceptions.hpp" |
| #include "uima/featurestructure.hpp" |
| #include "uima/internal_typeshortcuts.hpp" |
| |
| #include "unicode/utf.h" |
| /* ----------------------------------------------------------------------- */ |
| /* Constants */ |
| /* ----------------------------------------------------------------------- */ |
| |
| /* ----------------------------------------------------------------------- */ |
| /* Forward declarations */ |
| /* ----------------------------------------------------------------------- */ |
| |
| |
| namespace uima { |
| class CAS; |
| namespace internal { |
| class FSSystem; |
| } |
| } |
| |
| /* ----------------------------------------------------------------------- */ |
| /* Types / Classes */ |
| /* ----------------------------------------------------------------------- */ |
| |
| namespace uima { |
| // exceptions |
| UIMA_EXC_CLASSDECLARE(FSIsNotListException, CASException); |
| UIMA_EXC_CLASSDECLARE(ListIsEmptyException, CASException); |
| UIMA_EXC_CLASSDECLARE(ListIsCircularException, CASException); |
| } // namespace uima |
| |
| /* ----------------------------------------------------------------------- */ |
| /* BasicListFS */ |
| /* ----------------------------------------------------------------------- */ |
| |
| namespace uima { |
| /// @if internal |
| template< class T, |
| const uima::lowlevel::TyFSType LIST_TYPE, |
| const uima::lowlevel::TyFSType ELIST_TYPE, |
| const uima::lowlevel::TyFSType NELIST_TYPE, |
| const uima::lowlevel::TyFSFeature HEAD_FEATURE, |
| const uima::lowlevel::TyFSFeature TAIL_FEATURE > |
| /// @endif internal |
| /** |
| * A on object representing a list of elements from the CAS. |
| * (e.g. they are of type empty list or of type non-empty list). |
| * An element can be either a FeatureStructure or a float or an int or a |
| * string. For each such element type there is a sub-class of BasicListFS |
| * implementing this template interface with type specific methods. |
| * ListFS, IntListFS, FloatListFS, StringListFS. |
| * |
| * All get methods may throw an <code>InvalidFSObjectException</code> if the |
| * feature structure object is not valid. |
| * |
| * Creating a list can be done like this: |
| @code |
| // store elements of a vector of strings in a list feature |
| FeatureStructure fsNewString; // re-used for each new string |
| StringListFS fsNewList = tcas.createListFS(); // create an empty list |
| // build up a fs list from our vector |
| for (size_t i = 0; i < vecStrings.size(); ++i) { |
| // create a string feature structure |
| fsNewList.addLast(vecStrings[i]); |
| } |
| // now that the list is complete, set the feature value to the list |
| fsWithListFeature.setFSValue(fListFeature, fsNewList); |
| @endcode |
| * Accessing a list can be done like this: |
| @code |
| // check if we need to touch our element |
| if (fsWithListFeature.hasListElements(fListFeature) ) { |
| // get list |
| StringListFS fsList = fsWithListFeature.getStringListFSValue(fListFeature); |
| // iterate list |
| while (!fsList.isEmpty()) { |
| cout << fsList.getHead() << " "; // print the string |
| fsList.moveToNext(); |
| } |
| } |
| @endcode |
| * |
| * The example uses StringListFS to show the usage of the interfaces with |
| * strings. Usage of FeatureStructure, int or float values is analogous. |
| * |
| * @see ListFS |
| * @see IntListFS |
| * @see FloatListFS |
| * @see StringListFS |
| */ |
| class UIMA_LINK_IMPORTSPEC BasicListFS : public FeatureStructure { |
| friend class CAS; |
| friend class FeatureStructure; |
| protected: |
| /// @if internal |
| void checkList(lowlevel::TyFS tyFS, TyMessageId tyContext) const; |
| void checkNEList(lowlevel::TyFS tyFS, TyMessageId tyContext) const; |
| void checkCircularity(lowlevel::TyFS tyFS1, lowlevel::TyFS tyFS2, TyMessageId tyContext) const; |
| lowlevel::TyFS getLastListElement(lowlevel::TyFS tyListFS, size_t & rOutSize) const; |
| lowlevel::TyFS addLastLowlevel(lowlevel::TyFS tyListFS, T tyNewElement); |
| void appendLowlevel(lowlevel::TyFS tyListFS1, lowlevel::TyFS tyListFS2); |
| |
| BasicListFS(lowlevel::TyFS anFS, uima::CAS&, bool bDoChecks = true); |
| /// @endif internal |
| public: |
| typedef T HeadType; |
| |
| /** |
| * Default CTOR: Creates an invalid BasicListFS (use CAS::createListFS() instead) |
| */ |
| BasicListFS(); |
| |
| /** |
| * Upgrade/Conversion CTOR: Creates an BasicListFS from an existing FeatureStructure. |
| * fs must be of type List. |
| * |
| * @throws FSIsNotListException |
| */ |
| explicit BasicListFS( FeatureStructure const & fs ); |
| |
| /** |
| * Return true if this element is not valid or of type empty list. |
| * @throws InvalidFSObjectException |
| */ |
| bool isEmpty() const; |
| |
| /** |
| * Get the value of the head feature of this list element. |
| * @throws InvalidFSObjectException |
| * @throws ListIsEmptyException |
| */ |
| T getHead() const; |
| |
| /** |
| * Set the value of the head feature of this list element. |
| * @throws InvalidFSObjectException |
| * @throws ListIsEmptyException |
| */ |
| void setHead( T const & fs ); |
| |
| /** |
| * Get the value of the tail feature of this list element. |
| * @throws InvalidFSObjectException |
| * @throws ListIsEmptyException |
| */ |
| BasicListFS getTail() const; |
| |
| /** |
| * Set the value of the tail feature of this list element. |
| * @throws InvalidFSObjectException |
| * @throws ListIsEmptyException |
| */ |
| void setTail( BasicListFS fs ); |
| |
| /** |
| * Get the length of this list. |
| * @throws InvalidFSObjectException |
| */ |
| size_t getLength() const; |
| |
| /** |
| * Adds the value fs to the begin of this list. |
| * addFirst takes constant time with the length of this list |
| * |
| * @return The list starting with the newly added element. |
| * (i.e. the first element of the full list) |
| * |
| * @throws InvalidFSObjectException |
| */ |
| BasicListFS addFirst( T const & fs ); |
| |
| /** |
| * Adds the value fs to the end of this list. |
| * addLast takes linear time with the length of this list |
| * |
| * @return The list starting with the newly added element |
| * (i.e. the last element of the full list) |
| * |
| * @throws InvalidFSObjectException |
| */ |
| BasicListFS addLast( T const & fs ); |
| |
| /** |
| * Appends the list l to the end of this list. |
| * append takes linear time with the length of this list |
| * |
| * @return The new list. |
| * |
| * @throws InvalidFSObjectException |
| */ |
| BasicListFS append( BasicListFS l ); |
| |
| /** |
| * Appends the list l to the begin of this list. |
| * prepend takes linear time with the length of list <code>l</code> |
| * |
| * @return The new list. |
| * |
| * @throws InvalidFSObjectException |
| */ |
| BasicListFS prepend( BasicListFS l ); |
| |
| /** |
| * Advance this list element to the next element in the list. |
| * Equivalent to <code>this = this.getTailFS();</code> |
| * Assumes that the list is not empty. |
| * |
| * @throws InvalidFSObjectException |
| * @throws ListIsEmptyException |
| */ |
| void moveToNext(); |
| |
| /** |
| * Removes the first occurrence of element from this list. |
| * |
| * @return The singleton list containing the removed element. |
| * |
| * @throws InvalidFSObjectException |
| */ |
| BasicListFS removeElement( T const & element); |
| |
| |
| /// @if internal |
| /** |
| * Check if the list-value for the feature f on feature structure fs |
| * has any elements. |
| * Conceptually this is equivalent to |
| * <code>!fs.getListFSValue(f).isEmpty()</code> |
| * But unlike getListFSValue() hasListElements() will not touch the |
| * feature value for f. |
| * |
| * @param fs The feature structure on which to check the value for f |
| * @param f The feature to check (must be of type list) |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotListException |
| */ |
| static bool hasListElements(FeatureStructure fs, Feature const & f); |
| |
| /** |
| * Return feature structure of type list stored at feature fList. |
| * The return value is guaranteed to be a properly terminated list. |
| * If the feature value for f is untouched a properly terminated list |
| * will be created on the fly. |
| * |
| * @param fList The feature referencing the list to return. |
| * fList must be valid. |
| * fList must be appropriate for this feature strucutre. |
| * fList must be subsumed by type list. |
| * |
| * @throws InvalidFSObjectException |
| * @throws InvalidFSFeatureObjectException |
| * @throws FeatureNotAppropriateException |
| * @throws FSIsNotListException |
| */ |
| static BasicListFS getListFSValue(FeatureStructure const & fs, Feature const & fList); |
| |
| /** |
| * create a feature structure of type empty list (list length is zero) |
| * @param bIsPermanent indicate if the data should be permanent, |
| * i.e., has a lifetime longer than the document |
| */ |
| static BasicListFS createListFS( CAS & cas, bool bIsPermanent = false ); |
| |
| /** |
| * create a feature structure of type non-empty list (list length is 1) |
| * @param fsHead the feature structure to be made the head of the new list. |
| * cas.createListFS(f).getHead() == f |
| * @param bIsPermanent indicate if the data should be permanent, |
| * i.e., has a lifetime longer than the document |
| */ |
| static BasicListFS createListFS( CAS & cas, T const & head, bool bIsPermanent = false ); |
| |
| /// @endif internal |
| } |
| ; // class BasicListFS |
| |
| typedef BasicListFS< FeatureStructure, internal::gs_tyFSListType, internal::gs_tyEListType, internal::gs_tyNEListType, internal::gs_tyHeadFeature, internal::gs_tyTailFeature > BasicFSListFS; |
| /** |
| * A ListFS object implements a list of FeatureStructure objects |
| * It is derived from the BasicListFS template interface so all |
| * interesting member functions are derived from BasicListFS. |
| * @see BasicListFS |
| * @see IntListFS |
| * @see FloatListFS |
| * @see StringListFS |
| */ |
| class UIMA_LINK_IMPORTSPEC ListFS : public BasicFSListFS { |
| /// @if internal |
| friend class CAS; |
| friend class FeatureStructure; |
| protected: |
| ListFS(lowlevel::TyFS anFS, uima::CAS & cas, bool bDoChecks = true) : |
| BasicFSListFS(anFS, cas, bDoChecks) {} |
| public: |
| /** |
| * Default CTOR: Creates an invalid ListFS (use CAS::createListFS() instead) |
| */ |
| ListFS() : |
| BasicFSListFS() {} |
| |
| /** |
| * Upgrade/Conversion CTOR: Creates an ListFS from an existing FeatureStructure. |
| * fs must be of type List. |
| * |
| * @throws FSIsNotListException |
| */ |
| explicit ListFS( FeatureStructure const & fs ) : |
| BasicFSListFS(fs) {} |
| |
| /** |
| * Upgrade/Conversion CTOR: Creates an ListFS from an existing BasicListFS. |
| */ |
| ListFS( BasicFSListFS const & fs ) : |
| BasicFSListFS(fs) {} |
| /// @endif internal |
| }; |
| |
| |
| typedef BasicListFS< float, internal::gs_tyFloatListType, internal::gs_tyEFloatListType, internal::gs_tyNEFloatListType, internal::gs_tyFloatHeadFeature, internal::gs_tyFloatTailFeature > BasicFloatListFS; |
| /** |
| * A FloatListFS object implements a list of float values. |
| * It is derived from the BasicListFS template interface so all |
| * interesting member functions are derived from BasicListFS. |
| * @see BasicListFS |
| * @see ListFS |
| * @see IntListFS |
| * @see StringListFS |
| */ |
| class UIMA_LINK_IMPORTSPEC FloatListFS : public BasicFloatListFS { |
| /// @if internal |
| friend class CAS; |
| friend class FeatureStructure; |
| protected: |
| FloatListFS(lowlevel::TyFS anFS, uima::CAS & cas, bool bDoChecks = true) : |
| BasicFloatListFS(anFS, cas, bDoChecks) {} |
| public: |
| /** |
| * Default CTOR: Creates an invalid ListFS (use CAS::createListFS() instead) |
| */ |
| FloatListFS() : |
| BasicFloatListFS() {} |
| |
| /** |
| * Upgrade/Conversion CTOR: Creates an ListFS from an existing FeatureStructure. |
| * fs must be of type List. |
| * |
| * @throws FSIsNotListException |
| */ |
| explicit FloatListFS( FeatureStructure const & fs ) : |
| BasicFloatListFS(fs) {} |
| |
| /** |
| * Upgrade/Conversion CTOR: Creates an ListFS from an existing BasicListFS. |
| */ |
| FloatListFS( BasicFloatListFS const & fs ) : |
| BasicFloatListFS(fs) {} |
| /// @endif internal |
| }; |
| |
| typedef BasicListFS< int, internal::gs_tyIntListType, internal::gs_tyEIntListType, internal::gs_tyNEIntListType, internal::gs_tyIntHeadFeature, internal::gs_tyIntTailFeature > BasicIntListFS; |
| /** |
| * A IntListFS object implements a list of int values. |
| * It is derived from the BasicListFS template interface so all |
| * interesting member functions are derived from BasicListFS. |
| * @see BasicListFS |
| * @see ListFS |
| * @see FloatListFS |
| * @see StringListFS |
| */ |
| class UIMA_LINK_IMPORTSPEC IntListFS : public BasicIntListFS { |
| /// @if internal |
| friend class CAS; |
| friend class FeatureStructure; |
| protected: |
| IntListFS(lowlevel::TyFS anFS, uima::CAS & cas, bool bDoChecks = true) : |
| BasicIntListFS(anFS, cas, bDoChecks) {} |
| public: |
| /** |
| * Default CTOR: Creates an invalid ListFS (use CAS::createListFS() instead) |
| */ |
| IntListFS() : |
| BasicIntListFS() {} |
| |
| /** |
| * Upgrade/Conversion CTOR: Creates an ListFS from an existing FeatureStructure. |
| * fs must be of type List. |
| * |
| * @throws FSIsNotListException |
| */ |
| explicit IntListFS( FeatureStructure const & fs ) : |
| BasicIntListFS(fs) {} |
| |
| /** |
| * Upgrade/Conversion CTOR: Creates an ListFS from an existing BasicListFS. |
| */ |
| IntListFS( BasicIntListFS const & fs ) : |
| BasicIntListFS(fs) {} |
| /// @endif internal |
| }; |
| |
| |
| typedef BasicListFS< UnicodeStringRef, internal::gs_tyStringListType, internal::gs_tyEStringListType, internal::gs_tyNEStringListType, internal::gs_tyStringHeadFeature, internal::gs_tyStringTailFeature > BasicStringListFS; |
| /** |
| * A StringListFS object implements a list of string values. |
| * It is derived from the BasicListFS template interface so all |
| * interesting member functions are derived from BasicListFS. |
| * @see BasicListFS |
| * @see ListFS |
| * @see IntListFS |
| * @see FloatListFS |
| */ |
| class UIMA_LINK_IMPORTSPEC StringListFS : public BasicStringListFS { |
| /// @if internal |
| friend class CAS; |
| friend class FeatureStructure; |
| protected: |
| StringListFS(lowlevel::TyFS anFS, uima::CAS & cas, bool bDoChecks = true) : |
| BasicStringListFS(anFS, cas, bDoChecks) {} |
| public: |
| /** |
| * Default CTOR: Creates an invalid ListFS (use CAS::createListFS() instead) |
| */ |
| StringListFS() : |
| BasicStringListFS() {} |
| |
| /** |
| * Upgrade/Conversion CTOR: Creates an ListFS from an existing FeatureStructure. |
| * fs must be of type List. |
| * |
| * @throws FSIsNotListException |
| */ |
| explicit StringListFS( FeatureStructure const & fs ) : |
| BasicStringListFS(fs) {} |
| |
| /** |
| * Upgrade/Conversion CTOR: Creates an ListFS from an existing BasicListFS. |
| */ |
| StringListFS( BasicStringListFS const & fs ) : |
| BasicStringListFS(fs) {} |
| /// @endif internal |
| }; |
| |
| } // namespace uima |
| |
| #endif |
| /* <EOF> */ |
| |
| |