1 /* @source ensprojectionsegment ***********************************************
2 **
3 ** Ensembl Projection Segment functions
4 **
5 ** @author Copyright (C) 1999 Ensembl Developers
6 ** @author Copyright (C) 2006 Michael K. Schuster
7 ** @version $Revision: 1.30 $
8 ** @modified 2009 by Alan Bleasby for incorporation into EMBOSS core
9 ** @modified $Date: 2013/02/17 13:02:40 $ by $Author: mks $
10 ** @@
11 **
12 ** This library is free software; you can redistribute it and/or
13 ** modify it under the terms of the GNU Lesser General Public
14 ** License as published by the Free Software Foundation; either
15 ** version 2.1 of the License, or (at your option) any later version.
16 **
17 ** This library is distributed in the hope that it will be useful,
18 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 ** Lesser General Public License for more details.
21 **
22 ** You should have received a copy of the GNU Lesser General Public
23 ** License along with this library; if not, write to the Free Software
24 ** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
25 ** MA 02110-1301, USA.
26 **
27 ******************************************************************************/
28
29 /* ========================================================================= */
30 /* ============================= include files ============================= */
31 /* ========================================================================= */
32
33 #include "ensprojectionsegment.h"
34
35
36
37
38 /* ========================================================================= */
39 /* =============================== constants =============================== */
40 /* ========================================================================= */
41
42
43
44
45 /* ========================================================================= */
46 /* =========================== global variables ============================ */
47 /* ========================================================================= */
48
49
50
51
52 /* ========================================================================= */
53 /* ============================= private data ============================== */
54 /* ========================================================================= */
55
56
57
58
59 /* ========================================================================= */
60 /* =========================== private constants =========================== */
61 /* ========================================================================= */
62
63
64
65
66 /* ========================================================================= */
67 /* =========================== private variables =========================== */
68 /* ========================================================================= */
69
70
71
72
73 /* ========================================================================= */
74 /* =========================== private functions =========================== */
75 /* ========================================================================= */
76
77
78
79
80 /* ========================================================================= */
81 /* ======================= All functions by section ======================== */
82 /* ========================================================================= */
83
84
85
86
87 /* @filesection ensprojectionsegment ******************************************
88 **
89 ** @nam1rule ens Function belongs to the Ensembl library
90 **
91 ******************************************************************************/
92
93
94
95
96 /* @datasection [EnsPProjectionsegment] Ensembl Projection Segment ************
97 **
98 ** @nam2rule Projectionsegment Functions for manipulating
99 ** Ensembl Projection Segment objects
100 **
101 ** @cc Bio::EnsEMBL::ProjectionSegment
102 ** @cc CVS Revision: 1.8
103 ** @cc CVS Tag: branch-ensembl-68
104 **
105 ******************************************************************************/
106
107
108
109
110 /* @section constructors ******************************************************
111 **
112 ** All constructors return a new Ensembl Projection Segment by pointer.
113 ** It is the responsibility of the user to first destroy any previous
114 ** Projection Segment. The target pointer does not need to be initialised to
115 ** NULL, but it is good programming practice to do so anyway.
116 **
117 ** @fdata [EnsPProjectionsegment]
118 **
119 ** @nam3rule New Constructor
120 ** @nam4rule Cpy Constructor with existing object
121 ** @nam4rule Ini Constructor with initial values
122 ** @nam4rule Ref Constructor by incrementing the reference counter
123 **
124 ** @argrule Cpy ps [const EnsPProjectionsegment] Ensembl Projection Segment
125 ** @argrule Ini srcstart [ajuint] Source start coordinate
126 ** @argrule Ini srcend [ajuint] Source end coordinate
127 ** @argrule Ini trgslice [EnsPSlice] Target Ensembl Slice
128 ** @argrule Ref ps [EnsPProjectionsegment] Ensembl Projection Segment
129 **
130 ** @valrule * [EnsPProjectionsegment] Ensembl Projection Segment or NULL
131 **
132 ** @fcategory new
133 ******************************************************************************/
134
135
136
137
138 /* @func ensProjectionsegmentNewCpy *******************************************
139 **
140 ** Object-based constructor function, which returns an independent object.
141 **
142 ** @param [r] ps [const EnsPProjectionsegment] Ensembl Projection Segment
143 **
144 ** @return [EnsPProjectionsegment] Ensembl Projection Segment or NULL
145 **
146 ** @release 6.4.0
147 ** @@
148 ******************************************************************************/
149
ensProjectionsegmentNewCpy(const EnsPProjectionsegment ps)150 EnsPProjectionsegment ensProjectionsegmentNewCpy(
151 const EnsPProjectionsegment ps)
152 {
153 EnsPProjectionsegment pthis = NULL;
154
155 if (!ps)
156 return NULL;
157
158 AJNEW0(pthis);
159
160 pthis->SourceStart = ps->SourceStart;
161 pthis->SourceEnd = ps->SourceEnd;
162 pthis->TargetSlice = ensSliceNewRef(ps->TargetSlice);
163 pthis->Use = 1U;
164
165 return pthis;
166 }
167
168
169
170
171 /* @func ensProjectionsegmentNewIni *******************************************
172 **
173 ** Constructor for an Ensembl Projection Segment with initial values.
174 **
175 ** @param [r] srcstart [ajuint] Source start coordinate
176 ** @param [r] srcend [ajuint] Source end coordinate
177 ** @param [u] trgslice [EnsPSlice] Target Ensembl Slice
178 **
179 ** @return [EnsPProjectionsegment] Ensembl Projection Segment or NULL
180 **
181 ** @release 6.4.0
182 ** @@
183 ******************************************************************************/
184
ensProjectionsegmentNewIni(ajuint srcstart,ajuint srcend,EnsPSlice trgslice)185 EnsPProjectionsegment ensProjectionsegmentNewIni(ajuint srcstart,
186 ajuint srcend,
187 EnsPSlice trgslice)
188 {
189 EnsPProjectionsegment ps = NULL;
190
191 if (ajDebugTest("ensProjectionsegmentNewIni"))
192 {
193 ajDebug("ensProjectionsegmentNewIni\n"
194 " srcstart %u\n"
195 " srcend %u\n"
196 " trgslice %p\n",
197 srcstart,
198 srcend,
199 trgslice);
200
201 ensSliceTrace(trgslice, 1);
202 }
203
204 if (!trgslice)
205 return NULL;
206
207 AJNEW0(ps);
208
209 ps->SourceStart = srcstart;
210 ps->SourceEnd = srcend;
211 ps->TargetSlice = ensSliceNewRef(trgslice);
212 ps->Use = 1U;
213
214 return ps;
215 }
216
217
218
219
220 /* @func ensProjectionsegmentNewRef *******************************************
221 **
222 ** Ensembl Object referencing function, which returns a pointer to the
223 ** Ensembl Object passed in and increases its reference count.
224 **
225 ** @param [u] ps [EnsPProjectionsegment] Ensembl Projection Segment
226 **
227 ** @return [EnsPProjectionsegment] Ensembl Projection Segment or NULL
228 **
229 ** @release 6.2.0
230 ** @@
231 ******************************************************************************/
232
ensProjectionsegmentNewRef(EnsPProjectionsegment ps)233 EnsPProjectionsegment ensProjectionsegmentNewRef(EnsPProjectionsegment ps)
234 {
235 if (!ps)
236 return NULL;
237
238 ps->Use++;
239
240 return ps;
241 }
242
243
244
245
246 /* @section destructors *******************************************************
247 **
248 ** Destruction destroys all internal data structures and frees the memory
249 ** allocated for an Ensembl Projection Segment object.
250 **
251 ** @fdata [EnsPProjectionsegment]
252 **
253 ** @nam3rule Del Destroy (free) an Ensembl Projection Segment
254 **
255 ** @argrule * Pps [EnsPProjectionsegment*] Ensembl Projection Segment address
256 **
257 ** @valrule * [void]
258 **
259 ** @fcategory delete
260 ******************************************************************************/
261
262
263
264
265 /* @func ensProjectionsegmentDel **********************************************
266 **
267 ** Default destructor for an Ensembl Projection Segment.
268 **
269 ** @param [d] Pps [EnsPProjectionsegment*] Ensembl Projection Segment address
270 **
271 ** @return [void]
272 **
273 ** @release 6.2.0
274 ** @@
275 ******************************************************************************/
276
ensProjectionsegmentDel(EnsPProjectionsegment * Pps)277 void ensProjectionsegmentDel(EnsPProjectionsegment *Pps)
278 {
279 EnsPProjectionsegment pthis = NULL;
280
281 if (!Pps)
282 return;
283
284 #if defined(AJ_DEBUG) && AJ_DEBUG >= 1
285 if (ajDebugTest("ensProjectionsegmentDel"))
286 {
287 ajDebug("ensProjectionsegmentDel\n"
288 " *Pps %p\n",
289 *Pps);
290
291 ensProjectionsegmentTrace(*Pps, 1);
292 }
293 #endif /* defined(AJ_DEBUG) && AJ_DEBUG >= 1 */
294
295 if (!(pthis = *Pps) || --pthis->Use)
296 {
297 *Pps = NULL;
298
299 return;
300 }
301
302 ensSliceDel(&pthis->TargetSlice);
303
304 ajMemFree((void **) Pps);
305
306 return;
307 }
308
309
310
311
312 /* @section member retrieval **************************************************
313 **
314 ** Functions for returning members of an Ensembl Projection Segment.
315 **
316 ** @fdata [EnsPProjectionsegment]
317 **
318 ** @nam3rule Get Get an attribute of an Ensembl Projection Segment
319 ** @nam4rule Source Get source members
320 ** @nam5rule End Get source end member
321 ** @nam5rule Start Get source start member
322 ** @nam4rule Target Get tagret members
323 ** @nam5rule Slice Get the target Ensembl Slice
324 **
325 ** @argrule * ps [const EnsPProjectionsegment] Projection Segment object
326 ** address
327 **
328 ** @valrule SourceEnd [ajuint] Source end or 0U
329 ** @valrule SourceStart [ajuint] Source start or 0U
330 ** @valrule TargetSlice [EnsPSlice] Target Ensembl Slice or NULL
331 **
332 ** @fcategory delete
333 ******************************************************************************/
334
335
336
337
338 /* @func ensProjectionsegmentGetSourceEnd *************************************
339 **
340 ** Get the source end member of an Ensembl Projection Segment.
341 **
342 ** @param [r] ps [const EnsPProjectionsegment] Ensembl Projection Segment
343 **
344 ** @return [ajuint] Source end coordinate or 0U
345 **
346 ** @release 6.4.0
347 ** @@
348 ******************************************************************************/
349
ensProjectionsegmentGetSourceEnd(const EnsPProjectionsegment ps)350 ajuint ensProjectionsegmentGetSourceEnd(const EnsPProjectionsegment ps)
351 {
352 return (ps) ? ps->SourceEnd : 0U;
353 }
354
355
356
357
358 /* @func ensProjectionsegmentGetSourceStart ***********************************
359 **
360 ** Get the source start member of an Ensembl Projection Segment.
361 **
362 ** @param [r] ps [const EnsPProjectionsegment] Ensembl Projection Segment
363 **
364 ** @return [ajuint] Source start coordinate or 0U
365 **
366 ** @release 6.4.0
367 ** @@
368 ******************************************************************************/
369
ensProjectionsegmentGetSourceStart(const EnsPProjectionsegment ps)370 ajuint ensProjectionsegmentGetSourceStart(const EnsPProjectionsegment ps)
371 {
372 return (ps) ? ps->SourceStart : 0U;
373 }
374
375
376
377
378 /* @func ensProjectionsegmentGetTargetSlice ***********************************
379 **
380 ** Get the target Ensembl Slice member of an Ensembl Projection Segment.
381 **
382 ** @param [r] ps [const EnsPProjectionsegment] Ensembl Projection Segment
383 **
384 ** @return [EnsPSlice] Target Ensembl Slice or NULL
385 **
386 ** @release 6.4.0
387 ** @@
388 ******************************************************************************/
389
ensProjectionsegmentGetTargetSlice(const EnsPProjectionsegment ps)390 EnsPSlice ensProjectionsegmentGetTargetSlice(const EnsPProjectionsegment ps)
391 {
392 return (ps) ? ps->TargetSlice : NULL;
393 }
394
395
396
397
398 /* @section debugging *********************************************************
399 **
400 ** Functions for reporting of an Ensembl Projection Segment object.
401 **
402 ** @fdata [EnsPProjectionsegment]
403 **
404 ** @nam3rule Trace Report Ensembl Projection Segment members to debug file
405 **
406 ** @argrule Trace ps [const EnsPProjectionsegment] Ensembl Projection Segment
407 ** @argrule Trace level [ajuint] Indentation level
408 **
409 ** @valrule * [AjBool] ajTrue upon success, ajFalse otherwise
410 **
411 ** @fcategory misc
412 ******************************************************************************/
413
414
415
416
417 /* @func ensProjectionsegmentTrace ********************************************
418 **
419 ** Trace an Ensembl Projection Segment.
420 **
421 ** @param [r] ps [const EnsPProjectionsegment] Ensembl Projection Segment
422 ** @param [r] level [ajuint] Indentation level
423 **
424 ** @return [AjBool] ajTrue upon success, ajFalse otherwise
425 **
426 ** @release 6.2.0
427 ** @@
428 ******************************************************************************/
429
ensProjectionsegmentTrace(const EnsPProjectionsegment ps,ajuint level)430 AjBool ensProjectionsegmentTrace(const EnsPProjectionsegment ps, ajuint level)
431 {
432 AjPStr indent = NULL;
433
434 if (!ps)
435 return ajFalse;
436
437 indent = ajStrNew();
438
439 ajStrAppendCountK(&indent, ' ', level * 2);
440
441 ajDebug("%SensProjectionsegmentTrace %p\n"
442 "%S SourceStart %d\n"
443 "%S SourceEnd %d\n"
444 "%S TargetSlice %p\n"
445 "%S Use %u\n",
446 indent, ps,
447 indent, ps->SourceStart,
448 indent, ps->SourceEnd,
449 indent, ps->TargetSlice,
450 indent, ps->Use);
451
452 ensSliceTrace(ps->TargetSlice, level + 1);
453
454 ajStrDel(&indent);
455
456 return ajTrue;
457 }
458
459
460
461
462 /* @section calculate *********************************************************
463 **
464 ** Functions for calculating information from an
465 ** Ensembl Projection Segment object.
466 **
467 ** @fdata [EnsPProjectionsegment]
468 **
469 ** @nam3rule Calculate Calculate Ensembl Projection Segment information
470 ** @nam4rule Memsize Calculate the memory size in bytes
471 **
472 ** @argrule Memsize ps [const EnsPProjectionsegment] Ensembl Projection Segment
473 **
474 ** @valrule Memsize [size_t] Memory size in bytes or 0
475 **
476 ** @fcategory misc
477 ******************************************************************************/
478
479
480
481
482 /* @func ensProjectionsegmentCalculateMemsize *********************************
483 **
484 ** Calculate the memory size in bytes of an Ensembl Projection Segment.
485 **
486 ** @param [r] ps [const EnsPProjectionsegment] Ensembl Projection Segment
487 **
488 ** @return [size_t] Memory size in bytes or 0
489 **
490 ** @release 6.4.0
491 ** @@
492 ******************************************************************************/
493
ensProjectionsegmentCalculateMemsize(const EnsPProjectionsegment ps)494 size_t ensProjectionsegmentCalculateMemsize(const EnsPProjectionsegment ps)
495 {
496 size_t size = 0;
497
498 if (!ps)
499 return 0;
500
501 size += sizeof (EnsOProjectionsegment);
502
503 size += ensSliceCalculateMemsize(ps->TargetSlice);
504
505 return size;
506 }
507