InfAdoptedStateVector: libinfinity-0.7 Reference Manual

## InfAdoptedStateVector InfAdoptedStateVector — Represents a state in the interaction model |

## Stability Level

Unstable, unless otherwise indicated

## Functions

void | (*InfAdoptedStateVectorForeachFunc) ()
GQuark | inf_adopted_state_vector_error_quark ()
InfAdoptedStateVector * | inf_adopted_state_vector_new ()
InfAdoptedStateVector * | inf_adopted_state_vector_copy ()
void | inf_adopted_state_vector_free ()
guint | inf_adopted_state_vector_get ()
void | inf_adopted_state_vector_set ()
void | inf_adopted_state_vector_add ()
void | inf_adopted_state_vector_foreach ()
int | inf_adopted_state_vector_compare ()
gboolean | inf_adopted_state_vector_causally_before ()
gboolean | inf_adopted_state_vector_causally_before_inc ()
guint | inf_adopted_state_vector_vdiff ()
gchar * | inf_adopted_state_vector_to_string ()
InfAdoptedStateVector * | inf_adopted_state_vector_from_string ()
gchar * | inf_adopted_state_vector_to_string_diff ()
InfAdoptedStateVector * | inf_adopted_state_vector_from_string_diff ()

## Types and Values

| InfAdoptedStateVector
enum | InfAdoptedStateVectorError

## Object Hierarchy

        GBoxed
        ╰── InfAdoptedStateVector

## Includes

    #include <libinfinity/adopted/inf-adopted-state-vector.h>

## Description

The InfAdoptedStateVector represents a state in the current state space. It basically maps user IDs to operation counts and states how many operations of the corresponding user have already been performed.

## Functions

### InfAdoptedStateVectorForeachFunc ()

    void
    (*InfAdoptedStateVectorForeachFunc) (guint id,
                                         guint value,
                                         gpointer user_data);

This function is called for every component in the state vector during the invocation of `inf_adopted_state_vector_foreach()`.

#### Parameters

id | The ID of the entry. |
value | The value of the entry. |
user_data | The user data passed to `inf_adopted_state_vector_foreach()`. |

### inf_adopted_state_vector_error_quark ()

    GQuark
    inf_adopted_state_vector_error_quark (void);

The domain for InfAdoptedStateVectorError errors.

#### Returns

A GQuark for that domain.

### inf_adopted_state_vector_new ()

    InfAdoptedStateVector *
    inf_adopted_state_vector_new (void);

Returns a new state vector with all components set to zero.

[constructor]

#### Returns

A new InfAdoptedStateVector.

[transfer full]

### inf_adopted_state_vector_copy ()

    InfAdoptedStateVector *
    inf_adopted_state_vector_copy (InfAdoptedStateVector *vec);

Returns a copy of `vec` .

#### Parameters

vec | The InfAdoptedStateVector to copy |

#### Returns

A copy of `vec` .

[transfer full]

### inf_adopted_state_vector_free ()

    void
    inf_adopted_state_vector_free (InfAdoptedStateVector *vec);

Frees a state vector allocated by `inf_adopted_state_vector_new()` or `inf_adopted_state_vector_copy()`.

#### Parameters

vec | A InfAdoptedStateVector. |

### inf_adopted_state_vector_get ()

    guint
    inf_adopted_state_vector_get (const InfAdoptedStateVector *vec,
                                  guint id);

Returns the timestamp for the given component. Implicitely, all IDs that the vector does not contain are assigned the timestamp 0.

#### Parameters

vec | A InfAdoptedStateVector. |
id | The component whose timestamp to look for. |

#### Returns

The `component` 'th entry in the vector.

### inf_adopted_state_vector_set ()

    void
    inf_adopted_state_vector_set (InfAdoptedStateVector *vec,
                                  guint id,
                                  guint value);

Sets the given component of `vec` to `value` .

#### Parameters

vec | A InfAdoptedStateVector. |
id | The component to change. |
value | The value to set the component to. |

### inf_adopted_state_vector_add ()

    void
    inf_adopted_state_vector_add (InfAdoptedStateVector *vec,
                                  guint id,
                                  gint value);

Adds `value` to the current value of `component` . `value` may be negative in which case the current value is actually decreased. Make sure to not drop below zero this way.

#### Parameters

vec | A InfAdoptedStateVector. |
id | The component to change. |
value | The value by which to change the component. |

### inf_adopted_state_vector_foreach ()

    void
    inf_adopted_state_vector_foreach (const InfAdoptedStateVector *vec,
                                      InfAdoptedStateVectorForeachFunc func,
                                      gpointer user_data);

Calls `func` for each component in `vec` . Note that there may be users for which `func` will not be called if their timestamp is 0.

#### Parameters

vec | A InfAdoptedStateVector. |
func | The function to call. | [scope call]
user_data | Additional data to pass to `func` . |

### inf_adopted_state_vector_compare ()

    int
    inf_adopted_state_vector_compare (const InfAdoptedStateVector *first,
                                      const InfAdoptedStateVector *second);

Performs a comparison suited for strict-weak ordering so that state vectors can be sorted. This function returns -1 if `first` compares before `second` , 0 if they compare equal and 1 if `first` compares after `second` .

#### Parameters

first | A InfAdoptedStateVector. |
second | Another InfAdoptedStateVector. |

#### Returns

-1, 0 or 1.

### inf_adopted_state_vector_causally_before ()

    gboolean
    inf_adopted_state_vector_causally_before
                                   (const InfAdoptedStateVector *first,
                                    const InfAdoptedStateVector *second);

Checks whether an event that occured at time `second` is causally dependant on an event that occured at time `first` , that is all components of `first` are less or equal to the corresponding component in `second` .

#### Parameters

first | A InfAdoptedStateVector. |
second | Another InfAdoptedStateVector. |

#### Returns

Whether `second` depends on `first` .

### inf_adopted_state_vector_causally_before_inc ()

    gboolean
    inf_adopted_state_vector_causally_before_inc
                                   (const InfAdoptedStateVector *first,
                                    const InfAdoptedStateVector *second,
                                    guint inc_component);

This function does the equivalent of

    1
    2
    3
    4
    inf_adopted_state_vector_add(first, inc_component, 1);
    gboolean result = inf_adopted_state_vector_causally_before(first, second);
    inf_adopted_state_vector_add(first, inc_component, -1);
    return result;

But it is more efficient.

#### Parameters

first | A InfAdoptedStateVector. |
second | Another InfAdoptedStateVector. |
inc_component | The component to increment before comparing. |

#### Returns

Whether `second` depends on `first` with the `inc_component` th component increased by one.

### inf_adopted_state_vector_vdiff ()

    guint
    inf_adopted_state_vector_vdiff (const InfAdoptedStateVector *first,
                                    const InfAdoptedStateVector *second);

This function returns the sum of the differences between each component of `first` and `second` . This function can only be called if `inf_adopted_state_vector_causally_before()` returns `TRUE`.

#### Parameters

first | A InfAdoptedStateVector. |
second | Another InfAdoptedStateVector. |

#### Returns

The sum of the differences between each component of `first` and `second` .

### inf_adopted_state_vector_to_string ()

    gchar *
    inf_adopted_state_vector_to_string (const InfAdoptedStateVector *vec);

Returns a string representation of `vec` .

#### Parameters

vec | A InfAdoptedStateVector. |

#### Returns

A newly-allocated string to be freed by the caller.

[transfer full]

### inf_adopted_state_vector_from_string ()

    InfAdoptedStateVector *
    inf_adopted_state_vector_from_string (const gchar *str,
                                          GError **error);

Recreates the InfAdoptedStateVector from its string representation. If an error occurs, the function returns `NULL` and `error` is set.

#### Parameters

str | A string representation of a InfAdoptedStateVector. |
error | Location to place an error, if any. |

#### Returns

A new InfAdoptedStateVector, or `NULL`.

[transfer full]

### inf_adopted_state_vector_to_string_diff ()

    gchar *
    inf_adopted_state_vector_to_string_diff
                                   (const InfAdoptedStateVector *vec,
                                    const InfAdoptedStateVector *orig);

Returns the string representation of a diff between `orig` and `vec` . This is possibly smaller than the representation created by `inf_adopted_state_vector_to_string()`, but the same `orig` vector is needed to recreate `vec` from the string representation. Additionally, inf_adopted_state_vector_causally_before(`orig` , `vec` ) must hold.

#### Parameters

vec | A InfAdoptedStateVector. |
orig | Another InfAdoptedStateVector. |

#### Returns

A newly allocated string to be freed by the caller.

[transfer full]

### inf_adopted_state_vector_from_string_diff ()

    InfAdoptedStateVector *
    inf_adopted_state_vector_from_string_diff
                                   (const gchar *str,
                                    const InfAdoptedStateVector *orig,
                                    GError **error);

Recreates a vector from its string representation diff and the original vector. If an error returns, the function returns `NULL` and `error` is set.

#### Parameters

str | A string representation of a diff between state vectors. |
orig | The state vector used to create `str` in `inf_adopted_state_vector_to_string_diff()`. |
error | Location to place an error, if any. |

#### Returns

The created state vector, or `NULL` on error. Free with `inf_adopted_state_vector_free()` when no longer needed.

[transfer full]

## Types and Values

### InfAdoptedStateVector

    typedef struct _InfAdoptedStateVector InfAdoptedStateVector;

InfAdoptedStateVector is an opaque data type. You should only access it via the public API functions.

### enum InfAdoptedStateVectorError

Error codes for InfAdoptedStateVector.

#### Members

INF_ADOPTED_STATE_VECTOR_BAD_FORMAT | A string representation of an InfAdoptedStateVector as required by `inf_adopted_state_vector_from_string()` or `inf_adopted_state_vector_from_string_diff()` is invalid. |
INF_ADOPTED_STATE_VECTOR_FAILED | No further specified error code. |

## See Also

InfAdoptedAlgorithm