libfossil
fossil-path.h
Go to the documentation of this file.
1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim: set ts=2 et sw=2 tw=80: */
3 #if !defined(NET_FOSSIL_SCM_FSL_PATH_H_INCLUDED)
4 #define NET_FOSSIL_SCM_FSL_PATH_H_INCLUDED
5 /*
6  Copyright (c) 2013 D. Richard Hipp
7 
8  This program is free software; you can redistribute it and/or
9  modify it under the terms of the Simplified BSD License (also
10  known as the "2-Clause License" or "FreeBSD License".)
11 
12  This program 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.
15 
16  Author contact information:
17  drh@hwaci.com
18  http://www.hwaci.com/drh/
19 
20  *****************************************************************************
21  This file declares public APIs relating to generating hash values
22  hashing.
23 */
24 
25 #include "fossil-internal.h" /* MUST come first b/c of config macros */
26 
27 #if defined(__cplusplus)
28 extern "C" {
29 #endif
30 
32 typedef struct fsl_path fsl_path;
33 
34 
35 /**
36 
37  Holds information for a single node in a path of checkin versions.
38 
39  @see fsl_path
40 */
41 struct fsl_path_node {
42  /** ID for this node */
44  /** True if pFrom is the parent of rid */
46  /** True if primary side of common ancestor */
47  char isPrimary;
48  /* HISTORICAL: Abbreviate output in "fossil bisect ls" */
49  char isHidden;
50  /** Node this one came from. */
52  union {
53  /** List of nodes of the same generation */
55  /** Next on path from beginning to end */
57  } u;
58  /** List of all nodes */
60 };
61 
62 /**
63  A utility type for collecting "paths" between two checkin versions.
64 */
65 struct fsl_path{
66  /** Current generation of nodes */
68  /** All nodes */
70  /** Nodes seen before */
72  /** Number of steps from first to last. */
73  int nStep;
74  /** Earliest node in the path. */
76  /** Common ancestor of pStart and pEnd */
78  /** Most recent node in the path. */
80 };
81 
82 /**
83  An empty-initialize fsl_path object, intended for const-copy
84  initialization.
85 */
86 #define fsl_path_empty_m {0,0,fsl_id_bag_empty_m,0,0,0,0}
87 
88 /**
89  An empty-initialize fsl_path object, intended for copy
90  initialization.
91 */
93 
94 
95 /**
96  Returns the first node in p's path.
97 
98  The returned node is owned by path may be invalidated by any APIs
99  which manipulate path.
100 */
102 
103 /**
104  Returns the last node in p's path.
105 
106  The returned node is owned by path may be invalidated by any APIs
107  which manipulate path.
108 */
110 
111 /**
112  Returns the next node p's path.
113 
114  The returned node is owned by path may be invalidated by any APIs
115  which manipulate path.
116 
117  Intended to be used like this:
118 
119  @code
120  for( p = fsl_path_first(path) ;
121  p ;
122  p = fsl_path_next(p)){
123  ...
124  }
125  @endcode
126 */
128 
129 /**
130  Returns p's path length.
131 */
132 FSL_EXPORT int fsl_path_length(fsl_path const * p);
133 
134 /**
135  Frees all nodes in path (which must not be NULL) and resets all
136  state in path. Does not free path.
137 */
139 
140 /**
141  Find the mid-point of the path. If the path contains fewer than
142  2 steps, returns 0. The returned node is owned by path may be
143  invalidated by any APIs which manipulate path.
144 */
146 
147 
148 /**
149  Computes the shortest path from checkin versions iFrom to iTo
150  (inclusive), storing the result state in path. If path has
151  state before this is called, it is cleared by this call.
152 
153  iFrom and iTo must both be valid checkin version RIDs.
154 
155  If directOnly is true, then use only the "primary" links from
156  parent to child. In other words, ignore merges.
157 
158  On success, returns 0 and path->pStart will point to the
159  beginning of the path (the iFrom node). If pStart is 0 then no
160  path could be found but 0 is still returned.
161 
162  Elements of the path can be traversed like so:
163 
164  @code
165  fsl_path path = fsl_path_empty;
166  fsl_path_node * n = 0;
167  int rc = fsl_path_shortest(f, &path, versionFrom, versionTo, 1, 0);
168  if(rc) { ... error ... }
169  for( n = fsl_path_first(&path); n; n = fsl_path_next(n) ){
170  ...
171  }
172  fsl_path_clear(&path);
173  @endcode
174 
175  On error, f's error state may be updated with a description of the
176  problem.
177 */
179  fsl_id_t iFrom, fsl_id_t iTo,
180  char directOnly, char oneWayOnly );
181 
182 
183 
184 #if defined(__cplusplus)
185 } /*extern "C"*/
186 #endif
187 #endif
188 /* NET_FOSSIL_SCM_FSL_PATH_H_INCLUDED */
FSL_EXPORT fsl_path_node * fsl_path_first(fsl_path *p)
Returns the first node in p's path.
The main Fossil "context" type.
char fromIsParent
True if pFrom is the parent of rid.
Definition: fossil-path.h:45
FSL_EXPORT const fsl_path fsl_path_empty
An empty-initialize fsl_path object, intended for copy initialization.
Definition: fossil-path.h:92
FSL_EXPORT int fsl_path_length(fsl_path const *p)
Returns p's path length.
A utility type for collecting "paths" between two checkin versions.
Definition: fossil-path.h:65
#define FSL_EXPORT
Definition: fossil-config.h:19
char isPrimary
True if primary side of common ancestor.
Definition: fossil-path.h:47
FSL_EXPORT fsl_path_node * fsl_path_midpoint(fsl_path *path)
Find the mid-point of the path.
fsl_path_node * pAll
List of all nodes.
Definition: fossil-path.h:59
fsl_int32_t fsl_id_t
fsl_id_t is a signed integer type used to store database record IDs.
fsl_path_node * pTo
Next on path from beginning to end.
Definition: fossil-path.h:56
FSL_EXPORT void fsl_path_clear(fsl_path *path)
Frees all nodes in path (which must not be NULL) and resets all state in path.
fsl_id_t rid
ID for this node.
Definition: fossil-path.h:43
FSL_EXPORT int fsl_path_shortest(fsl_cx *f, fsl_path *path, fsl_id_t iFrom, fsl_id_t iTo, char directOnly, char oneWayOnly)
Computes the shortest path from checkin versions iFrom to iTo (inclusive), storing the result state i...
FSL_EXPORT fsl_path_node * fsl_path_next(fsl_path_node *p)
Returns the next node p's path.
fsl_path_node * pPivot
Common ancestor of pStart and pEnd.
Definition: fossil-path.h:77
A container type for lists of db record IDs.
Definition: fossil-util.h:3986
fsl_path_node * pEnd
Most recent node in the path.
Definition: fossil-path.h:79
fsl_path_node * pStart
Earliest node in the path.
Definition: fossil-path.h:75
union fsl_path_node::@14 u
fsl_path_node * pFrom
Node this one came from.
Definition: fossil-path.h:51
fsl_path_node * pPeer
List of nodes of the same generation.
Definition: fossil-path.h:54
int nStep
Number of steps from first to last.
Definition: fossil-path.h:73
fsl_path_node * pCurrent
Current generation of nodes.
Definition: fossil-path.h:67
FSL_EXPORT fsl_path_node * fsl_path_last(fsl_path *p)
Returns the last node in p's path.
Holds information for a single node in a path of checkin versions.
Definition: fossil-path.h:41
fsl_id_bag seen
Nodes seen before.
Definition: fossil-path.h:71
fsl_path_node * pAll
All nodes.
Definition: fossil-path.h:69