1 /*==========================================================================
2 SeqAn - The Library for Sequence Analysis
4 ============================================================================
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Lesser General Public
9 License as published by the Free Software Foundation; either
10 version 3 of the License, or (at your option) any later version.
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License for more details.
17 ============================================================================
18 $Id: basic_holder.h,v 1.1 2008/08/25 16:20:01 langmead Exp $
19 ==========================================================================*/
21 #ifndef SEQAN_HEADER_BASIC_HOLDER_H
22 #define SEQAN_HEADER_BASIC_HOLDER_H
24 namespace SEQAN_NAMESPACE_MAIN
27 //////////////////////////////////////////////////////////////////////////////
29 //////////////////////////////////////////////////////////////////////////////
32 ..summary:Called when dependency is added.
33 ..cat:Dependent Objects
34 ..signature:addRef(host)
35 ..param.host:The host object.
36 ..remarks.text:A call of this function denotes that a client object is about to become
38 ..remarks.text:The default behavior is: Do nothing.
45 {// general: do nothing
50 addRef(T const & /*me*/)
51 {// general: do nothing
55 //////////////////////////////////////////////////////////////////////////////
57 //////////////////////////////////////////////////////////////////////////////
60 ..summary:Called when dependency is released.
61 ..cat:Dependent Objects
62 ..signature:releaseRef(host)
63 ..param.host:The host object.
64 ..remarks.text:A call of this function denotes that a former dependent client object
65 ceases to be dependent on $host$.
66 ..remarks.text:The default behavior is: Do nothing.
72 releaseRef(T & /*me*/)
73 {// general: do nothing
78 releaseRef(T const & /*me*/)
79 {// general: do nothing
83 //////////////////////////////////////////////////////////////////////////////
90 //////////////////////////////////////////////////////////////////////////////
92 //////////////////////////////////////////////////////////////////////////////
97 ..summary:Manages relationship to another object.
98 ..signature:Holder<TValue, TSpec>
99 ..param.TValue:Type of the managed object.
100 ...metafunction:Metafunction.Value
101 ..param.TSpec:The specializing type.
102 ...metafunction:Metafunction.Spec
103 ...default:$Tristate$
104 ..remarks.text:The main purpose of this class is to facilitate the handling of
105 member objects. If we want class $A$ to be dependent on or the owner of another object of class $B$,
106 then we add a data member of type $Holder<B>$ to $A$.
107 $Holder$ offers some useful access functions, stores the kind of relationship between $A$ and $B$,
108 and executes all needed @Function.addRef@ and @Function.releaseRef@ calls.
111 template <typename TValue, typename TSpec = Tristate>
115 //////////////////////////////////////////////////////////////////////////////
117 //////////////////////////////////////////////////////////////////////////////
119 ///.Metafunction.Value.param.T.type:Class.Holder
121 template <typename TValue, typename TSpec>
122 struct Value< Holder<TValue, TSpec> >
124 typedef typename _RemoveConst<TValue>::Type Type;
126 template <typename TValue, typename TSpec>
127 struct Value< Holder<TValue, TSpec> const>
129 typedef typename _RemoveConst<TValue>::Type Type;
132 //////////////////////////////////////////////////////////////////////////////
134 ///.Metafunction.Spec.param.T.type:Class.Holder
136 template <typename TValue, typename TSpec>
137 struct Spec< Holder<TValue, TSpec> >
141 template <typename TValue, typename TSpec>
142 struct Spec< Holder<TValue, TSpec> const>
147 //////////////////////////////////////////////////////////////////////////////
149 ///.Metafunction.Reference.param.T.type:Class.Holder
151 template <typename TValue, typename TSpec>
152 struct Reference< Holder<TValue, TSpec> >
154 typedef typename Value< Holder<TValue, TSpec> >::Type & Type;
156 template <typename TValue, typename TSpec>
157 struct Reference< Holder<TValue, TSpec> const>
159 typedef typename Value< Holder<TValue, TSpec> const>::Type & Type;
163 //////////////////////////////////////////////////////////////////////////////
164 //////////////////////////////////////////////////////////////////////////////
166 //////////////////////////////////////////////////////////////////////////////
168 .Spec.Tristate Holder
170 ..summary:Holder that can be empty, dependent, or owner.
171 ..signature:Holder<TValue, Tristate>
172 ..param.TValue:Type of the managed object.
173 ..general:Class.Holder
174 ..remarks.text:A tristate holder $A$ that holds an object $B$ has one of the following states:
175 ..remarks.text:- owner: $A$ is the owner of $B$. If $A$ is destroyed, $B$ will be destroyed automatically.
176 ..remarks.text:- dependent: $A$ depends on $B$. $B$ should not be destroyed as long as $A$ is used.
177 ..remarks.text:- empty: there is currently no object reference stored in the holder $A$.
178 ..remarks.text:The state of the holder can be determined by @Function.empty@ and @Function.dependent@.
181 template <typename TValue>
182 struct Holder<TValue, Tristate>
192 // typedef typename _RemoveConst<TValue>::Type TValue_NotConst;
193 typedef typename Value<Holder>::Type THostValue;
195 typename _Pointer<THostValue>::Type data_value;
196 EHolderState data_state;
198 //____________________________________________________________________________
203 ..summary:Constructor
204 ..signature:Holder<TValue, TInfix> ()
205 ..signature:Holder<TValue, TInfix> (holder)
206 ..signature:Holder<TValue, TInfix> (value)
207 ..param.holder:Another holder object.
208 ..param.value:An object of type $TValue$.
210 The default constructor creates a holder that is in state 'empty'.
211 If a $value$ is passed to the constructor, the holder will be in state 'dependent'.
219 Holder(Holder const & source_):
223 assign(*this, source_);
225 Holder(typename _Parameter<THostValue>::Type value_):
229 setValue(*this, value_);
231 Holder(typename _ConstParameter<THostValue>::Type value_):
235 assignValue(*this, value_);
242 ..signature:~Holder()
244 If the holder is in state 'owner', the holded object will be destoyed too.
252 //____________________________________________________________________________
255 operator = (Holder const & source_)
258 assign(*this, source_);
263 operator = (typename _ConstParameter<THostValue>::Type value_)
266 assignValue(*this, value_);
270 operator typename _Parameter<THostValue>::Type()
275 //____________________________________________________________________________
279 //////////////////////////////////////////////////////////////////////////////
281 //////////////////////////////////////////////////////////////////////////////
283 ///.Function.empty.param.object.type:Class.Holder
285 template <typename TValue>
287 empty(Holder<TValue, Tristate> const & me)
290 return (me.data_state == Holder<TValue, Tristate>::EMPTY);
293 //////////////////////////////////////////////////////////////////////////////
295 ///.Function.dependent.param.object.type:Class.Holder
297 template <typename TValue>
299 dependent(Holder<TValue, Tristate> const & me)
302 return (me.data_state == Holder<TValue, Tristate>::DEPENDENT);
305 //////////////////////////////////////////////////////////////////////////////
307 ///.Function.clear.param.object.type:Class.Holder
308 ///.Function.clear.remarks.text:If $clear$ is applied on a @Class.Holder@ object,
309 ///the state of this object is set to 'empty'.
311 template <typename TValue>
313 clear(Holder<TValue, Tristate> & me)
315 switch (me.data_state)
317 case Holder<TValue, Tristate>::EMPTY:
320 case Holder<TValue, Tristate>::DEPENDENT:
323 releaseRef(_toParameter<TValue>(me.data_value));
324 me.data_state = Holder<TValue, Tristate>::EMPTY;
328 default: /*Holder<TValue, TSpec>::OWNER*/
331 valueDestruct(me.data_value);
332 deallocate(me, me.data_value, 1);
333 me.data_state = Holder<TValue, Tristate>::EMPTY;
339 //////////////////////////////////////////////////////////////////////////////
342 ..summary:Makes an object to owner of its content.
343 ..cat:Dependent Objects
344 ..signature:create(holder [, object])
345 ..param.holder:A holder object.
347 ..param.object:Object from which a copy is made and stored in $holder$. (optional)
348 ...type:Metafunction.Value.Value<Holder>::Type
349 ..remarks.text:After this operation, $holder$ will be in state 'owner'.
350 If $object$ is specified, $holder$ will hold a copy of $object$ at the end of this function.
351 If $object$ is not specified, the action depends on the former state of $holder$:
352 ..remarks.text:- If the state of $holder$ was 'empty', a new object is default constructed and stored into $holder$.
353 ..remarks.text:- If the state of $holder$ was 'dependent', a copy of the former object is made and stored into $holder$.
354 ..remarks.text:- If the state of $holder$ was already 'owner', nothing happens.
358 template <typename TValue>
360 create(Holder<TValue, Tristate> & me)
362 typedef Holder<TValue, Tristate> THolder;
364 switch (me.data_state)
366 case Holder<TValue, Tristate>::EMPTY:
369 allocate(me, me.data_value, 1);
370 valueConstruct(me.data_value);
371 me.data_state = THolder::OWNER;
375 case THolder::DEPENDENT:
378 typename _Parameter<TValue>::Type old_value = value(me);
379 allocate(me, me.data_value, 1);
380 valueConstruct(me.data_value, old_value);
381 me.data_state = THolder::OWNER;
382 releaseRef(old_value);
389 //____________________________________________________________________________
391 template <typename TValue>
393 create(Holder<TValue, Tristate> & me,
394 typename _Parameter<TValue const>::Type value_)
398 if (me.data_state == Holder<TValue, Tristate>::OWNER)
400 assign(_toParameter(me.data_value), value_);
405 allocate(me, me.data_value, 1);
406 valueConstruct(me.data_value, value_);
407 me.data_state = Holder<TValue, Tristate>::OWNER;
410 //////////////////////////////////////////////////////////////////////////////
413 ..summary:Makes an object independent from other objects.
414 ..cat:Dependent Objects
415 ..signature:detach(object)
416 ..param.object:An object.
419 After this function, $object$ does not depends from any other entity outside of $object$,
420 like a @Function.source@ or a @Function.host@, and @Function.dependent.dependent(object)@ returns $false$
421 ..see:Function.source
423 ..see:Function.createSource
424 ..see:Function.create
427 template <typename TValue>
429 detach(Holder<TValue, Tristate> & me)
435 //////////////////////////////////////////////////////////////////////////////
438 ..cat:Content Manipulation
439 ..summary:Makes holder dependent.
440 ..signature:setValue(holder, object)
441 ..param.holder:A holder object.
443 ..param.object:Object from which $holder$ will be dependent.
444 ...type:Metafunction.Value.Value<Holder>::Type
445 ..remarks.text:After this operation, $holder$ will be dependent in state 'dependent'.
449 template <typename TValue>
451 setValue(Holder<TValue, Tristate> & me,
452 typename _Parameter<TValue>::Type value_)
455 typedef typename Value<Holder<TValue, Tristate> >::Type THolderType;
458 me.data_value = _toPointer(value_);
459 me.data_state = Holder<TValue, Tristate>::DEPENDENT;
460 addRef(_toParameter<THolderType>(me.data_value));
463 template <typename TValue, typename TValue2>
465 setValue(Holder<TValue, Tristate> & me,
466 TValue2 const & value_)
469 set(value(me), value_);
472 //////////////////////////////////////////////////////////////////////////////
474 ///.Function.value.param.object.type:Class.Holder
476 template <typename TValue>
477 inline typename Reference<Holder<TValue, Tristate> >::Type
478 value(Holder<TValue, Tristate> & me)
481 typedef Holder<TValue, Tristate> THolder;
485 allocate(me, me.data_value, 1);
486 valueConstruct(me.data_value);
487 me.data_state = THolder::OWNER;
490 typedef typename Value<Holder<TValue, Tristate> >::Type THolderType;
491 return _toParameter<THolderType>(me.data_value);
493 template <typename TValue>
494 inline typename Reference<Holder<TValue, Tristate> const>::Type
495 value(Holder<TValue, Tristate> const & me)
498 SEQAN_ASSERT(!empty(me));
500 typedef typename Value<Holder<TValue, Tristate> >::Type THolderType;
501 return _toParameter<THolderType>(me.data_value);
504 //////////////////////////////////////////////////////////////////////////////
506 ///.Function.assignValue.param.object.type:Class.Holder
508 template <typename TValue, typename TSource>
510 assignValue(Holder<TValue, Tristate> & me,
511 TSource const & value_)
514 typedef typename Value<Holder<TValue, Tristate> >::Type THostValue;
521 assign(_toParameter<THostValue>(me.data_value), value_);
525 //////////////////////////////////////////////////////////////////////////////
527 ///.Function.moveValue.param.object.type:Class.Holder
529 template <typename TValue, typename TSource>
531 moveValue(Holder<TValue, Tristate> & me,
532 TSource const & value_)
541 move(value(me), value_);
545 //////////////////////////////////////////////////////////////////////////////
547 ///.Function.assign.param.target.type:Class.Holder
548 ///.Function.assign.param.source.type:Class.Holder
550 template <typename TValue>
552 assign(Holder<TValue, Tristate> & target_,
553 Holder<TValue, Tristate> const & source_)
556 switch(source_.data_state)
558 case Holder<TValue, Tristate>::EMPTY:
564 case Holder<TValue, Tristate>::OWNER:
566 assignValue(target_, value(source_));
570 default: /*case Holder<TValue, Tristate>::DEPENDENT*/
572 setValue(target_, value(source_));
578 //////////////////////////////////////////////////////////////////////////////
579 //////////////////////////////////////////////////////////////////////////////
581 //////////////////////////////////////////////////////////////////////////////
582 //??? TODO: Documentation of Simple Holder
584 template <typename TValue>
585 struct Holder<TValue, Simple>
587 typedef typename Value<Holder>::Type THolderValue;
588 typedef typename _Parameter<THolderValue>::Type THolderParameter;
590 mutable THolderValue data_value;
591 //____________________________________________________________________________
597 Holder(Holder & source_):
598 data_value(source_.data_value)
602 Holder(Holder const & source_):
603 data_value(source_.data_value)
607 template <typename TSource>
608 Holder(TSource & value_):
613 template <typename TSource>
614 Holder(TSource const & value_):
620 Holder(TValue const & value_):
631 //____________________________________________________________________________
634 operator = (Holder const & source_)
637 data_value = source_.data_value;
642 operator = (THolderValue const & value_)
649 operator THolderParameter()
654 //____________________________________________________________________________
658 //////////////////////////////////////////////////////////////////////////////
660 //////////////////////////////////////////////////////////////////////////////
662 template <typename TValue>
664 empty(Holder<TValue, Simple> const & me)
670 //////////////////////////////////////////////////////////////////////////////
672 template <typename TValue>
674 dependent(Holder<TValue, Simple> const & me)
680 //////////////////////////////////////////////////////////////////////////////
682 template <typename TValue>
684 clear(Holder<TValue, Simple> & me)
689 //////////////////////////////////////////////////////////////////////////////
691 template <typename TValue>
693 create(Holder<TValue, Simple> & me)
698 //____________________________________________________________________________
700 template <typename TValue>
702 create(Holder<TValue, Simple> & me,
703 TValue const & value_)
706 me.data_value = value_;
709 //////////////////////////////////////////////////////////////////////////////
711 template <typename TValue>
713 detach(Holder<TValue, Simple> & me)
718 //////////////////////////////////////////////////////////////////////////////
720 template <typename TValue>
722 setValue(Holder<TValue, Simple> & me,
723 TValue const & value_)
726 me.data_value = value_;
729 //////////////////////////////////////////////////////////////////////////////
731 template <typename TValue>
732 inline typename Reference<Holder<TValue, Simple> >::Type
733 value(Holder<TValue, Simple> & me)
736 return me.data_value;
738 template <typename TValue>
739 inline typename Reference<Holder<TValue, Simple> const>::Type
740 value(Holder<TValue, Simple> const & me)
743 return me.data_value;
746 //////////////////////////////////////////////////////////////////////////////
748 template <typename TValue, typename TSource>
750 assignValue(Holder<TValue, Simple> & me,
751 TSource const & value_)
754 assignValue(me.data_value, value_);
757 //////////////////////////////////////////////////////////////////////////////
759 template <typename TValue, typename TSource>
761 moveValue(Holder<TValue, Simple> & me,
762 TSource const & value_)
765 move(me.data_value, value_);
768 //////////////////////////////////////////////////////////////////////////////
770 template <typename TValue>
772 assign(Holder<TValue, Simple> & target_,
773 Holder<TValue, Simple> const & source_)
776 assignValue(target_, source_);
780 //////////////////////////////////////////////////////////////////////////////
781 //////////////////////////////////////////////////////////////////////////////
786 //////////////////////////////////////////////////////////////////////////////
787 // New Tristate Holder that works also on pointers
788 //////////////////////////////////////////////////////////////////////////////
792 template <typename TValue>
793 struct Holder<TValue, Tristate2>
803 typedef typename Value<Holder>::Type THostValue;
806 EHolderState data_state;
808 //____________________________________________________________________________
815 Holder(Holder const & source_):
819 assign(*this, source_);
821 Holder(typename _Parameter<THostValue>::Type value_):
825 setValue(*this, value_);
827 Holder(typename _ConstParameter<THostValue>::Type value_):
831 assignValue(*this, value_);
839 //____________________________________________________________________________
842 operator = (Holder const & source_)
845 assign(*this, source_);
850 operator = (TValue const & value_)
853 assignValue(*this, value_);
862 //____________________________________________________________________________
866 //////////////////////////////////////////////////////////////////////////////
868 //////////////////////////////////////////////////////////////////////////////
870 ///.Function.empty.param.object.type:Class.Holder
872 template <typename TValue>
874 empty(Holder<TValue, Tristate2> const & me)
877 return (me.data_state == Holder<TValue, Tristate2>::EMPTY);
880 //////////////////////////////////////////////////////////////////////////////
882 ///.Function.dependent.param.object.type:Class.Holder
884 template <typename TValue>
886 dependent(Holder<TValue, Tristate2> const & me)
889 return (me.data_state == Holder<TValue, Tristate2>::DEPENDENT);
892 //////////////////////////////////////////////////////////////////////////////
894 ///.Function.clear.param.object.type:Class.Holder
895 ///.Function.clear.remarks.text:If $clear$ is applied on a @Class.Holder@ object,
896 ///the state of this object is set to 'empty'.
898 template <typename TValue>
900 clear(Holder<TValue, Tristate2> & me)
902 switch (me.data_state)
904 case Holder<TValue, Tristate2>::EMPTY:
907 case Holder<TValue, Tristate2>::DEPENDENT:
910 releaseRef(*(me.data_value));
911 me.data_state = Holder<TValue, Tristate2>::EMPTY;
915 default: /*Holder<TValue, TSpec>::OWNER*/
918 valueDestruct(me.data_value);
919 deallocate(me, me.data_value, 1);
920 me.data_state = Holder<TValue, Tristate2>::EMPTY;
926 //////////////////////////////////////////////////////////////////////////////
929 template <typename TValue>
931 create(Holder<TValue, Tristate2> & me)
933 typedef Holder<TValue, Tristate2> THolder;
935 switch (me.data_state)
937 case Holder<TValue, Tristate2>::EMPTY:
940 allocate(me, me.data_value, 1);
941 valueConstruct(me.data_value);
942 me.data_state = THolder::OWNER;
946 case THolder::DEPENDENT:
949 TValue & old_value = value(me);
950 allocate(me, me.data_value, 1);
951 valueConstruct(me.data_value, old_value);
952 me.data_state = THolder::OWNER;
953 releaseRef(old_value);
960 //____________________________________________________________________________
962 template <typename TValue>
964 create(Holder<TValue, Tristate2> & me,
965 TValue const & value_)
969 if (me.data_state == Holder<TValue, Tristate2>::OWNER)
971 assign(*(me.data_value), value_);
976 allocate(me, me.data_value, 1);
977 valueConstruct(me.data_value, value_);
978 me.data_state = Holder<TValue, Tristate2>::OWNER;
981 //////////////////////////////////////////////////////////////////////////////
984 template <typename TValue>
986 detach(Holder<TValue, Tristate2> & me)
992 //////////////////////////////////////////////////////////////////////////////
995 template <typename TValue>
997 setValue(Holder<TValue, Tristate2> & me,
1001 typedef typename Value<Holder<TValue, Tristate2> >::Type THolderType;
1004 me.data_value = & value_;
1005 me.data_state = Holder<TValue, Tristate2>::DEPENDENT;
1009 //////////////////////////////////////////////////////////////////////////////
1011 ///.Function.value.param.object.type:Class.Holder
1013 template <typename TValue>
1014 inline typename Reference<Holder<TValue, Tristate2> >::Type
1015 value(Holder<TValue, Tristate2> & me)
1018 typedef Holder<TValue, Tristate2> THolder;
1022 allocate(me, me.data_value, 1);
1023 valueConstruct(me.data_value);
1024 me.data_state = THolder::OWNER;
1027 typedef typename Value<Holder<TValue, Tristate2> >::Type THolderType;
1028 return *(me.data_value);
1030 template <typename TValue>
1031 inline typename Reference<Holder<TValue, Tristate2> const>::Type
1032 value(Holder<TValue, Tristate2> const & me)
1035 SEQAN_ASSERT(!empty(me));
1037 return *(me.data_value);
1041 //////////////////////////////////////////////////////////////////////////////
1043 ///.Function.assignValue.param.object.type:Class.Holder
1045 template <typename TValue, typename TSource>
1047 assignValue(Holder<TValue, Tristate2> & me,
1048 TSource const & value_)
1051 typedef typename Value<Holder<TValue, Tristate2> >::Type THostValue;
1058 assign(*(me.data_value), value_);
1062 //////////////////////////////////////////////////////////////////////////////
1064 ///.Function.moveValue.param.object.type:Class.Holder
1066 template <typename TValue, typename TSource>
1068 moveValue(Holder<TValue, Tristate2> & me,
1069 TSource const & value_)
1078 move(value(me), value_);
1082 //////////////////////////////////////////////////////////////////////////////
1084 ///.Function.assign.param.target.type:Class.Holder
1085 ///.Function.assign.param.source.type:Class.Holder
1087 template <typename TValue>
1089 assign(Holder<TValue, Tristate2> & target_,
1090 Holder<TValue, Tristate2> const & source_)
1093 switch(source_.data_state)
1095 case Holder<TValue, Tristate2>::EMPTY:
1101 case Holder<TValue, Tristate2>::OWNER:
1103 assignValue(target_, value(source_));
1107 default: /*case Holder<TValue, Tristate2>::DEPENDENT*/
1109 setValue(target_, value(source_));
1114 //////////////////////////////////////////////////////////////////////////////
1116 } //namespace SEQAN_NAMESPACE_MAIN
1118 #endif //#ifndef SEQAN_HEADER_...