include/fst/mutable-fst.h

// mutable-fst.h

// Licensed 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.
//
// Copyright 2005-2010 Google, Inc.
// Author: riley@google.com (Michael Riley)
//
// \file
// Expanded FST augmented with mutators - interface class definition
// and mutable arc iterator interface.
//

#ifndef FST_LIB_MUTABLE_FST_H__
#define FST_LIB_MUTABLE_FST_H__

#include <stddef.h>
#include <sys/types.h>
#include <string>
#include <vector>
using std::vector;

#include <fst/expanded-fst.h>


namespace fst {

template <class A> class MutableArcIteratorData;

// An expanded FST plus mutators (use MutableArcIterator to modify arcs).
template <class A>
class MutableFst : public ExpandedFst<A> {
 public:
  typedef A Arc;
  typedef typename A::Weight Weight;
  typedef typename A::StateId StateId;

  virtual MutableFst<A> &operator=(const Fst<A> &fst) = 0;

  MutableFst<A> &operator=(const MutableFst<A> &fst) {
    return operator=(static_cast<const Fst<A> &>(fst));
  }

  virtual void SetStart(StateId) = 0;           // Set the initial state
  virtual void SetFinal(StateId, Weight) = 0;   // Set a state's final weight
  virtual void SetProperties(uint64 props,
                             uint64 mask) = 0;  // Set property bits wrt mask

  virtual StateId AddState() = 0;               // Add a state, return its ID
  virtual void AddArc(StateId, const A &arc) = 0;   // Add an arc to state

  virtual void DeleteStates(const vector<StateId>&) = 0;  // Delete some states
  virtual void DeleteStates() = 0;              // Delete all states
  virtual void DeleteArcs(StateId, size_t n) = 0;  // Delete some arcs at state
  virtual void DeleteArcs(StateId) = 0;         // Delete all arcs at state

  virtual void ReserveStates(StateId n) { }  // Optional, best effort only.
  virtual void ReserveArcs(StateId s, size_t n) { }  // Optional, Best effort.

  // Return input label symbol table; return NULL if not specified
  virtual const SymbolTable* InputSymbols() const = 0;
  // Return output label symbol table; return NULL if not specified
  virtual const SymbolTable* OutputSymbols() const = 0;

  // Return input label symbol table; return NULL if not specified
  virtual SymbolTable* MutableInputSymbols() = 0;
  // Return output label symbol table; return NULL if not specified
  virtual SymbolTable* MutableOutputSymbols() = 0;

  // Set input label symbol table; NULL signifies not unspecified
  virtual void SetInputSymbols(const SymbolTable* isyms) = 0;
  // Set output label symbol table; NULL signifies not unspecified
  virtual void SetOutputSymbols(const SymbolTable* osyms) = 0;

  // Get a copy of this MutableFst. See Fst<>::Copy() for further doc.
  virtual MutableFst<A> *Copy(bool safe = false) const = 0;

  // Read an MutableFst from an input stream; return NULL on error.
  static MutableFst<A> *Read(istream &strm, const FstReadOptions &opts) {
    FstReadOptions ropts(opts);
    FstHeader hdr;
    if (ropts.header)
      hdr = *opts.header;
    else {
      if (!hdr.Read(strm, opts.source))
        return 0;
      ropts.header = &hdr;
    }
    if (!(hdr.Properties() & kMutable)) {
      LOG(ERROR) << "MutableFst::Read: Not a MutableFst: " << ropts.source;
      return 0;
    }
    FstRegister<A> *registr = FstRegister<A>::GetRegister();
    const typename FstRegister<A>::Reader reader =
      registr->GetReader(hdr.FstType());
    if (!reader) {
      LOG(ERROR) << "MutableFst::Read: Unknown FST type \"" << hdr.FstType()
                 << "\" (arc type = \"" << A::Type()
                 << "\"): " << ropts.source;
      return 0;
    }
    Fst<A> *fst = reader(strm, ropts);
    if (!fst) return 0;
    return static_cast<MutableFst<A> *>(fst);
  }

  // Read a MutableFst from a file; return NULL on error.
  // Empty filename reads from standard input. If 'convert' is true,
  // convert to a mutable FST of type 'convert_type' if file is
  // a non-mutable FST.
  static MutableFst<A> *Read(const string &filename, bool convert = false,
                             const string &convert_type = "vector") {
    if (convert == false) {
      if (!filename.empty()) {
        ifstream strm(filename.c_str(), ifstream::in | ifstream::binary);
        if (!strm) {
          LOG(ERROR) << "MutableFst::Read: Can't open file: " << filename;
          return 0;
        }
        return Read(strm, FstReadOptions(filename));
      } else {
        return Read(cin, FstReadOptions("standard input"));
      }
    } else {  // Converts to 'convert_type' if not mutable.
      Fst<A> *ifst = Fst<A>::Read(filename);
      if (!ifst) return 0;
      if (ifst->Properties(kMutable, false)) {
        return static_cast<MutableFst *>(ifst);
      } else {
        Fst<A> *ofst = Convert(*ifst, convert_type);
        delete ifst;
        if (!ofst) return 0;
        if (!ofst->Properties(kMutable, false))
          LOG(ERROR) << "MutableFst: bad convert type: " << convert_type;
        return static_cast<MutableFst *>(ofst);
      }
    }
  }

  // For generic mutuble arc iterator construction; not normally called
  // directly by users.
  virtual void InitMutableArcIterator(StateId s,
                                      MutableArcIteratorData<A> *) = 0;
};

// Mutable arc iterator interface, templated on the Arc definition; used
// for mutable Arc iterator specializations that are returned by
// the InitMutableArcIterator MutableFst method.
template <class A>
class MutableArcIteratorBase : public ArcIteratorBase<A> {
 public:
  typedef A Arc;

  void SetValue(const A &arc) { SetValue_(arc); }  // Set current arc's content

 private:
  virtual void SetValue_(const A &arc) = 0;
};

template <class A>
struct MutableArcIteratorData {
  MutableArcIteratorBase<A> *base;  // Specific iterator
};

// Generic mutable arc iterator, templated on the FST definition
// - a wrapper around pointer to specific one.
// Here is a typical use: \code
//   for (MutableArcIterator<StdFst> aiter(&fst, s);
//        !aiter.Done();
//         aiter.Next()) {
//     StdArc arc = aiter.Value();
//     arc.ilabel = 7;
//     aiter.SetValue(arc);
//     ...
//   } \endcode
// This version requires function calls.
template <class F>
class MutableArcIterator {
 public:
  typedef F FST;
  typedef typename F::Arc Arc;
  typedef typename Arc::StateId StateId;

  MutableArcIterator(F *fst, StateId s) {
    fst->InitMutableArcIterator(s, &data_);
  }
  ~MutableArcIterator() { delete data_.base; }

  bool Done() const { return data_.base->Done(); }
  const Arc& Value() const { return data_.base->Value(); }
  void Next() { data_.base->Next(); }
  size_t Position() const { return data_.base->Position(); }
  void Reset() { data_.base->Reset(); }
  void Seek(size_t a) { data_.base->Seek(a); }
  void SetValue(const Arc &a) { data_.base->SetValue(a); }
  uint32 Flags() const { return data_.base->Flags(); }
  void SetFlags(uint32 f, uint32 m) {
    return data_.base->SetFlags(f, m);
  }

 private:
  MutableArcIteratorData<Arc> data_;
  DISALLOW_COPY_AND_ASSIGN(MutableArcIterator);
};


namespace internal {

//  MutableFst<A> case - abstract methods.
template <class A> inline
typename A::Weight Final(const MutableFst<A> &fst, typename A::StateId s) {
  return fst.Final(s);
}

template <class A> inline
ssize_t NumArcs(const MutableFst<A> &fst, typename A::StateId s) {
  return fst.NumArcs(s);
}

template <class A> inline
ssize_t NumInputEpsilons(const MutableFst<A> &fst, typename A::StateId s) {
  return fst.NumInputEpsilons(s);
}

template <class A> inline
ssize_t NumOutputEpsilons(const MutableFst<A> &fst, typename A::StateId s) {
  return fst.NumOutputEpsilons(s);
}

}  // namespace internal


// A useful alias when using StdArc.
typedef MutableFst<StdArc> StdMutableFst;


// This is a helper class template useful for attaching a MutableFst
// interface to its implementation, handling reference counting and
// copy-on-write.
template <class I, class F = MutableFst<typename I::Arc> >
class ImplToMutableFst : public ImplToExpandedFst<I, F> {
 public:
  typedef typename I::Arc Arc;
  typedef typename Arc::Weight Weight;
  typedef typename Arc::StateId StateId;

  using ImplToFst<I, F>::GetImpl;
  using ImplToFst<I, F>::SetImpl;

  virtual void SetStart(StateId s) {
    MutateCheck();
    GetImpl()->SetStart(s);
  }

  virtual void SetFinal(StateId s, Weight w) {
    MutateCheck();
    GetImpl()->SetFinal(s, w);
  }

  virtual void SetProperties(uint64 props, uint64 mask) {
    // Can skip mutate check if extrinsic properties don't change,
    // since it is then safe to update all (shallow) copies
    uint64 exprops = kExtrinsicProperties & mask;
    if (GetImpl()->Properties(exprops) != (props & exprops))
      MutateCheck();
    GetImpl()->SetProperties(props, mask);
  }

  virtual StateId AddState() {
    MutateCheck();
    return GetImpl()->AddState();
  }

  virtual void AddArc(StateId s, const Arc &arc) {
    MutateCheck();
    GetImpl()->AddArc(s, arc);
  }

  virtual void DeleteStates(const vector<StateId> &dstates) {
    MutateCheck();
    GetImpl()->DeleteStates(dstates);
  }

  virtual void DeleteStates() {
    MutateCheck();
    GetImpl()->DeleteStates();
  }

  virtual void DeleteArcs(StateId s, size_t n) {
    MutateCheck();
    GetImpl()->DeleteArcs(s, n);
  }

  virtual void DeleteArcs(StateId s) {
    MutateCheck();
    GetImpl()->DeleteArcs(s);
  }

  virtual void ReserveStates(StateId s) {
    MutateCheck();
    GetImpl()->ReserveStates(s);
  }

  virtual void ReserveArcs(StateId s, size_t n) {
    MutateCheck();
    GetImpl()->ReserveArcs(s, n);
  }

  virtual const SymbolTable* InputSymbols() const {
    return GetImpl()->InputSymbols();
  }

  virtual const SymbolTable* OutputSymbols() const {
    return GetImpl()->OutputSymbols();
  }

  virtual SymbolTable* MutableInputSymbols() {
    MutateCheck();
    return GetImpl()->InputSymbols();
  }

  virtual SymbolTable* MutableOutputSymbols() {
    MutateCheck();
    return GetImpl()->OutputSymbols();
  }

  virtual void SetInputSymbols(const SymbolTable* isyms) {
    MutateCheck();
    GetImpl()->SetInputSymbols(isyms);
  }

  virtual void SetOutputSymbols(const SymbolTable* osyms) {
    MutateCheck();
    GetImpl()->SetOutputSymbols(osyms);
  }

 protected:
  ImplToMutableFst() : ImplToExpandedFst<I, F>() {}

  ImplToMutableFst(I *impl) : ImplToExpandedFst<I, F>(impl) {}


  ImplToMutableFst(const ImplToMutableFst<I, F> &fst)
      : ImplToExpandedFst<I, F>(fst) {}

  ImplToMutableFst(const ImplToMutableFst<I, F> &fst, bool safe)
      : ImplToExpandedFst<I, F>(fst, safe) {}

  void MutateCheck() {
    // Copy on write
    if (GetImpl()->RefCount() > 1)
      SetImpl(new I(*this));
  }

 private:
  // Disallow
  ImplToMutableFst<I, F>  &operator=(const ImplToMutableFst<I, F> &fst);

  ImplToMutableFst<I, F> &operator=(const Fst<Arc> &fst) {
    FSTERROR() << "ImplToMutableFst: Assignment operator disallowed";
    GetImpl()->SetProperties(kError, kError);
    return *this;
  }
};


}  // namespace fst

#endif  // FST_LIB_MUTABLE_FST_H__