Bioplib
Protein Structure C Library
 All Data Structures Files Functions Variables Typedefs Macros Pages
aalist.c
Go to the documentation of this file.
1 /************************************************************************/
2 /**
3 
4  \file aalist.c
5 
6  \version V3.1
7  \date 07.07.14
8  \brief Amino acid linked lists.
9 
10  \copyright (c) UCL / Dr. Andrew C.R. Martin 2006-2014
11  \author Dr. Andrew C.R. Martin
12  \par
13  Institute of Structural & Molecular Biology,
14  University College London,
15  Gower Street,
16  London.
17  WC1E 6BT.
18  \par
19  andrew@bioinf.org.uk
20  andrew.martin@ucl.ac.uk
21 
22 **************************************************************************
23 
24  This code is NOT IN THE PUBLIC DOMAIN, but it may be copied
25  according to the conditions laid out in the accompanying file
26  COPYING.DOC.
27 
28  The code may be modified as required, but any modifications must be
29  documented so that the person responsible can be identified.
30 
31  The code may not be sold commercially or included as part of a
32  commercial product except as described in the file COPYING.DOC.
33 
34 **************************************************************************
35 
36  Description:
37  ============
38 
39 
40 **************************************************************************
41 
42  Usage:
43  ======
44  #include "bioplib/aalist.h" to define AA datatype.
45 
46 **************************************************************************
47 
48  Revision History:
49  =================
50 - V1.0 21.08.06 Original By: ACRM
51 - V3.0 06.11.08 Incorporated into ProFit V3 By: CTP
52 - V3.0 18.02.09 Moved to bioplib. By: CTP
53 - V3.1 07.07.14 Use bl prefix for functions By: CTP
54 
55 *************************************************************************/
56 /* Doxygen
57  -------
58  #GROUP Handling Sequence Data
59  #SUBGROUP Sequence manipulation
60 
61  #FUNCTION blInsertNextResiduesInAAList()
62  Inserts a set of identical residues after the current position in
63  the linked list. The returned value is the last residue which has
64  been inserted so this can be called again on the returned aa to
65  insert another aa
66 
67  #FUNCTION blInsertNextResidueInAAList()
68  Inserts a residues after the current position in the linked list.
69  The returned value is the residue which has been inserted so this
70  can be called again on the returned aa to insert another aa
71 
72  #FUNCTION blBuildSeqFromAAList()
73  Converts the linked list back into a string which is malloc'd
74 
75  #FUNCTION blInsertResidueInAAListAt()
76  Inserts a residue after the specified position in the
77  list. Residues are numbered from 1. If the position is > length of
78  the list then the residue will be added at the end. If the position
79  is zero, it will be at the start of the list in which case the
80  return value for the list will be different from the input value.
81 
82  #FUNCTION blInsertResiduesInAAListAt()
83  Inserts a set of residues after the specified position in the
84  list. Residues are numbered from 1. If the position is > length of
85  the list then the residue will be added at the end. If the position
86  is zero, it will be at the start of the list in which case the
87  return value for the list will be different from the input value.
88 
89  #FUNCTION blBuildAAList()
90  Converts a sequence string into a linked list
91 
92  #FUNCTION blFindAAListOffsetByResnum()
93  Searches the linked list of the specified resnum (i.e. the original
94  residue number in the sequence before any insertions were made) and
95  returns the position of that residue in the list (numbered from 1)
96 
97  #FUNCTION blFindAAListItemByResnum()
98  Searches the linked list of the specified resnum (i.e. the original
99  residue number in the sequence before any insertions were made) and
100  returns a pointer to that item in the list.
101 
102  #FUNCTION blSetAAListFlagByResnum()
103  Searches the linked list of the specified resnum (i.e. the original
104  residue number in the sequence before any insertions were made) and
105  sets the flag in that item in the linked list
106 
107  #FUNCTION blBuildFlagSeqFromAAList()
108  Builds a sequence string with blanks except where the flag in the
109  sequence structure is set. At these positions the character specified
110  in ch is used instead.
111 
112  #FUNCTION blGetAAListLen()
113  Returns the number of items in the linked list
114 */
115 /************************************************************************/
116 /* Includes
117 */
118 #include <stdlib.h>
119 #include "macros.h"
120 #include "aalist.h"
121 
122 /************************************************************************/
123 /* Defines and macros
124 */
125 
126 /************************************************************************/
127 /* Globals
128 */
129 
130 /************************************************************************/
131 /* Prototypes
132 */
133 
134 
135 /************************************************************************/
136 /*>AA *blInsertNextResiduesInAAList(AA *a, char res, int nres)
137  -----------------------------------------------------------
138 *//**
139 
140  \param[in] *a Sequence linked list
141  \param[in] res Residue to insert
142  \param[in] nres Number of residues to insert
143  \return Pointer to the residue that has just been
144  inserted
145 
146  Inserts a set of identical residues after the current position in
147  the linked list. The returned value is the last residue which has
148  been inserted so this can be called again on the returned aa to
149  insert another aa
150 
151 - 21.08.06 Original By: ACRM
152 - 07.07.14 Use bl prefix for functions By: CTP
153 */
154 AA *blInsertNextResiduesInAAList(AA *a, char res, int nres)
155 {
156  int i;
157  for(i=0; i<nres; i++)
158  {
159  a = blInsertNextResidueInAAList(a, res);
160  }
161  return(a);
162 }
163 
164 
165 /************************************************************************/
166 /*>AA *blInsertNextResidueInAAList(AA *a, char res)
167  ------------------------------------------------
168 *//**
169 
170  \param[in] *a Sequence linked list
171  \param[in] res Residue to insert
172  \return Pointer to the residue that has just been
173  inserted
174 
175  Inserts a residues after the current position in the linked list.
176  The returned value is the residue which has been inserted so this
177  can be called again on the returned aa to insert another aa
178 
179 - 21.08.06 Original By: ACRM
180 - 07.07.14 Use bl prefix for functions By: CTP
181 */
183 {
184  AA *b = NULL;
185 
186  if(a!=NULL)
187  {
188  INITPREV(b, AA);
189  if(b==NULL)
190  {
191  FREELIST(a, AA);
192  return(NULL);
193  }
194  b->seqnum = (-1);
195  b->res = res;
196 
197  b->next = a->next;
198  b->prev = a;
199  if(b->next != NULL)
200  b->next->prev = b;
201  a->next = b;
202  }
203 
204  return(b);
205 }
206 
207 
208 /************************************************************************/
209 /*>char *blBuildSeqFromAAList(AA *aa)
210  ----------------------------------
211 *//**
212 
213  \param[in] *aa Sequence linked list
214  \return Sequence as a string (malloc'd)
215 
216  Converts the linked list back into a string which is malloc'd
217 
218 - 21.08.06 Original By: ACRM
219 - 07.07.14 Use bl prefix for functions By: CTP
220 */
222 {
223  AA *a;
224  char *seq=NULL;
225  int count=0;
226 
227  count = blGetAAListLen(aa);
228  if((seq=(char *)malloc((1+count)*sizeof(char)))!=NULL)
229  {
230  count = 0;
231  for(a=aa; a!=NULL; NEXT(a))
232  {
233  seq[count++] = a->res;
234  }
235  seq[count] = '\0';
236  }
237  return(seq);
238 }
239 
240 
241 /************************************************************************/
242 /*>AA *blInsertResidueInAAListAt(AA *aa, char res, int pos)
243  --------------------------------------------------------
244 *//**
245 
246  \param[in] *aa Sequence linked list
247  \param[in] res Residue to insert
248  \param[in] pos Position at which to insert (from 1...)
249  \return Updated sequence linked list
250 
251  Inserts a residue after the specified position in the
252  list. Residues are numbered from 1. If the position is > length of
253  the list then the residue will be added at the end. If the position
254  is zero, it will be at the start of the list in which case the
255  return value for the list will be different from the input value.
256 
257 - 21.08.06 Original By: ACRM
258 - 18.06.08 Set inserted residue's flag to FALSE. By: CTP
259 - 07.07.14 Use bl prefix for functions By: CTP
260 */
261 AA *blInsertResidueInAAListAt(AA *aa, char res, int pos)
262 {
263  AA *a, *b;
264  int count=0;
265 
266  for(a=aa, count=0; a!=NULL && count<pos-1; count++, NEXT(a));
267 
268  if(a!=NULL)
269  {
270  INITPREV(b, AA);
271  if(b==NULL)
272  {
273  FREELIST(aa, AA);
274  return(NULL);
275  }
276  b->seqnum = (-1);
277  b->res = res;
278  b->flag = FALSE;
279 
280  if(pos==0)
281  {
282  b->next = aa;
283  b->prev = NULL;
284  aa->prev = b;
285  aa = b;
286  }
287  else
288  {
289  b->next = a->next;
290  b->prev = a;
291  if(b->next != NULL)
292  b->next->prev = b;
293  a->next = b;
294  }
295  }
296  else /* Append to end of sequence */
297  {
298  a = aa;
299  LAST(a);
300  ALLOCNEXTPREV(a, AA);
301  if(a==NULL)
302  {
303  FREELIST(aa, AA);
304  return(NULL);
305  }
306  a->seqnum = (-1);
307  a->res = res;
308  a->flag = FALSE;
309  }
310 
311  return(aa);
312 }
313 
314 
315 /************************************************************************/
316 /*>AA *blInsertResiduesInAAListAt(AA *aa, char res, int nres, int pos)
317  -------------------------------------------------------------------
318 *//**
319 
320  \param[in] *aa Sequence linked list
321  \param[in] res Residue to insert
322  \param[in] nres Number of residues to insert
323  \param[in] pos Position at which to insert (from 1...)
324  \return Updated sequence linked list
325 
326  Inserts a set of residues after the specified position in the
327  list. Residues are numbered from 1. If the position is > length of
328  the list then the residue will be added at the end. If the position
329  is zero, it will be at the start of the list in which case the
330  return value for the list will be different from the input value.
331 
332 - 21.08.06 Original By: ACRM
333 - 07.07.14 Use bl prefix for functions By: CTP
334 */
335 AA *blInsertResiduesInAAListAt(AA *aa, char res, int nres, int pos)
336 {
337  int i;
338  for(i=0; i<nres; i++)
339  {
340  aa = blInsertResidueInAAListAt(aa, res, pos);
341  }
342  return(aa);
343 }
344 
345 
346 /************************************************************************/
347 /*>AA *blBuildAAList(char *seq)
348  ----------------------------
349 *//**
350 
351  \param[in] *seq The sequence as a string
352  \return A linked list representation
353 
354  Converts a sequence string into a linked list
355 
356 - 21.08.06 Original By: ACRM
357 - 07.07.14 Use bl prefix for functions By: CTP
358 */
359 AA *blBuildAAList(char *seq)
360 {
361  AA *aa = NULL,
362  *a = NULL;
363  int seqnum = 1;
364 
365  while(*seq)
366  {
367  if(aa == NULL)
368  {
369  INITPREV(aa, AA);
370  a = aa;
371  }
372  else
373  {
374  ALLOCNEXTPREV(a, AA);
375  }
376  if(a==NULL)
377  {
378  FREELIST(aa, AA);
379  return(NULL);
380  }
381  a->res = *(seq++);
382  a->seqnum = seqnum++;
383  a->flag = FALSE;
384  }
385 
386  return(aa);
387 }
388 
389 
390 /************************************************************************/
391 /*>int blFindAAListOffsetByResnum(AA *aa, int resnum)
392  --------------------------------------------------
393 *//**
394 
395  \param[in] *aa Sequence linked list
396  \param[in] resnum Residue number
397  \return Linked list offset
398 
399  Searches the linked list of the specified resnum (i.e. the original
400  residue number in the sequence before any insertions were made) and
401  returns the position of that residue in the list (numbered from 1)
402 
403 - 21.08.06 Original By: ACRM
404 - 07.07.14 Use bl prefix for functions By: CTP
405 */
407 {
408  int count=1;
409  AA *a;
410 
411  for(a=aa; a!=NULL; NEXT(a))
412  {
413  if(a->seqnum == resnum)
414  break;
415  count++;
416  }
417 
418  if(a==NULL)
419  return(-1);
420 
421  return(count);
422 }
423 
424 
425 /************************************************************************/
426 /*>AA *blFindAAListItemByResnum(AA *aa, int resnum)
427  ------------------------------------------------
428 *//**
429 
430  \param[in] *aa Sequence linked list
431  \param[in] resnum Residue number
432  \return Linked list item
433 
434  Searches the linked list of the specified resnum (i.e. the original
435  residue number in the sequence before any insertions were made) and
436  returns a pointer to that item in the list.
437 
438 - 21.08.06 Original By: ACRM
439 - 07.07.14 Use bl prefix for functions By: CTP
440 */
442 {
443  AA *a;
444 
445  for(a=aa; a!=NULL; NEXT(a))
446  {
447  if(a->seqnum == resnum)
448  break;
449  }
450 
451  return(a);
452 }
453 
454 
455 /************************************************************************/
456 /*>void blSetAAListFlagByResnum(AA *aa, int resnum)
457  ------------------------------------------------
458 *//**
459 
460  \param[in] *aa Sequence linked list
461  \param[in] resnum Residue number
462 
463  Searches the linked list of the specified resnum (i.e. the original
464  residue number in the sequence before any insertions were made) and
465  sets the flag in that item in the linked list
466 
467 - 21.08.06 Original By: ACRM
468 - 07.07.14 Use bl prefix for functions By: CTP
469 */
470 void blSetAAListFlagByResnum(AA *aa, int resnum)
471 {
472  AA *a;
473  if((a = blFindAAListItemByResnum(aa, resnum))!=NULL)
474  a->flag = TRUE;
475 }
476 
477 
478 /************************************************************************/
479 /*>char *blBuildFlagSeqFromAAList(AA *aa, char ch)
480  -----------------------------------------------
481 *//**
482 
483  \param[in] *aa Sequence linked list
484  \param[in] ch Character to use in the sequence
485  \return Sequence string (malloc'd)
486 
487  Builds a sequence string with blanks except where the flag in the
488  sequence structure is set. At these positions the character specified
489  in ch is used instead.
490 
491 - 21.08.06 Original By: ACRM
492 - 07.07.14 Use bl prefix for functions By: CTP
493 */
495 {
496  AA *a;
497  char *seq=NULL;
498  int count=0;
499 
500  count = blGetAAListLen(aa);
501  if((seq=(char *)malloc((1+count)*sizeof(char)))!=NULL)
502  {
503  count = 0;
504  for(a=aa; a!=NULL; NEXT(a))
505  {
506  seq[count++] = ((a->flag)?ch:' ');
507  }
508  seq[count] = '\0';
509  }
510  return(seq);
511 }
512 
513 
514 /************************************************************************/
515 /*>int blGetAAListLen(AA *aa)
516  --------------------------
517 *//**
518 
519  \param[in] *aa Sequence linked list
520  \return Length of sequence linked list
521 
522  Returns the number of items in the linked list
523 
524 - 21.08.06 Original By: ACRM
525 - 07.07.14 Use bl prefix for functions By: CTP
526 */
528 {
529  AA *a;
530  int count;
531  for(a=aa, count=0; a!=NULL; count++, NEXT(a));
532  return(count);
533 }
#define ALLOCNEXTPREV(x, y)
Definition: macros.h:254
#define LAST(x)
Definition: macros.h:259
#define NULL
Definition: array2.c:99
AA * blInsertResidueInAAListAt(AA *aa, char res, int pos)
Definition: aalist.c:261
AA * blInsertNextResidueInAAList(AA *a, char res)
Definition: aalist.c:182
AA * blInsertResiduesInAAListAt(AA *aa, char res, int nres, int pos)
Definition: aalist.c:335
#define FALSE
Definition: macros.h:223
#define NEXT(x)
Definition: macros.h:249
BOOL flag
Definition: aalist.h:74
Useful macros.
Definition: aalist.h:70
AA * blInsertNextResiduesInAAList(AA *a, char res, int nres)
Definition: aalist.c:154
int blGetAAListLen(AA *aa)
Definition: aalist.c:527
int blFindAAListOffsetByResnum(AA *aa, int resnum)
Definition: aalist.c:406
int seqnum
Definition: aalist.h:73
AA * blFindAAListItemByResnum(AA *aa, int resnum)
Definition: aalist.c:441
char res
Definition: aalist.h:75
struct aa * next
Definition: aalist.h:72
#define TRUE
Definition: macros.h:219
AA * blBuildAAList(char *seq)
Definition: aalist.c:359
char * blBuildSeqFromAAList(AA *aa)
Definition: aalist.c:221
struct aa * prev
Definition: aalist.h:72
Include file for amino acid linked lists.
#define FREELIST(y, z)
Definition: macros.h:264
char * blBuildFlagSeqFromAAList(AA *aa, char ch)
Definition: aalist.c:494
void blSetAAListFlagByResnum(AA *aa, int resnum)
Definition: aalist.c:470
#define INITPREV(x, y)
Definition: macros.h:246