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

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

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

                        InfAdoptedStateVector;
    enum                InfAdoptedStateVectorError;
    void                (*InfAdoptedStateVectorForeachFunc) (guint id,
                                                             guint value,
                                                             gpointer user_data);
    GQuark              inf_adopted_state_vector_error_quark
                                                            (void);
    InfAdoptedStateVector * inf_adopted_state_vector_new    (void);
    InfAdoptedStateVector * inf_adopted_state_vector_copy   (InfAdoptedStateVector *vec);
    void                inf_adopted_state_vector_free       (InfAdoptedStateVector *vec);
    guint               inf_adopted_state_vector_get        (InfAdoptedStateVector *vec,
                                                             guint id);
    void                inf_adopted_state_vector_set        (InfAdoptedStateVector *vec,
                                                             guint id,
                                                             guint value);
    void                inf_adopted_state_vector_add        (InfAdoptedStateVector *vec,
                                                             guint id,
                                                             gint value);
    void                inf_adopted_state_vector_foreach    (InfAdoptedStateVector *vec,
                                                             InfAdoptedStateVectorForeachFunc func,
                                                             gpointer user_data);
    int                 inf_adopted_state_vector_compare    (InfAdoptedStateVector *first,
                                                             InfAdoptedStateVector *second);
    gboolean            inf_adopted_state_vector_causally_before
                                                            (InfAdoptedStateVector *first,
                                                             InfAdoptedStateVector *second);
    gboolean            inf_adopted_state_vector_causally_before_inc
                                                            (InfAdoptedStateVector *first,
                                                             InfAdoptedStateVector *second,
                                                             guint inc_component);
    guint               inf_adopted_state_vector_vdiff      (InfAdoptedStateVector *first,
                                                             InfAdoptedStateVector *second);
    gchar *             inf_adopted_state_vector_to_string  (InfAdoptedStateVector *vec);
    InfAdoptedStateVector * inf_adopted_state_vector_from_string
                                                            (const gchar *str,
                                                             GError **error);
    gchar *             inf_adopted_state_vector_to_string_diff
                                                            (InfAdoptedStateVector *vec,
                                                             InfAdoptedStateVector *orig);
    InfAdoptedStateVector * inf_adopted_state_vector_from_string_diff
                                                            (const gchar *str,
                                                             InfAdoptedStateVector *orig,
                                                             GError **error);

## Object Hierarchy

      GBoxed
       +----InfAdoptedStateVector

## 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.

## Details

### InfAdoptedStateVector

    typedef struct _InfAdoptedStateVector InfAdoptedStateVector;

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

### enum InfAdoptedStateVectorError

    typedef enum {
      INF_ADOPTED_STATE_VECTOR_BAD_FORMAT,

      INF_ADOPTED_STATE_VECTOR_FAILED
    } InfAdoptedStateVectorError;

Error codes for InfAdoptedStateVector.

`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.

### 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()`.

`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.

Returns : | A new InfAdoptedStateVector.

### inf_adopted_state_vector_copy ()

    InfAdoptedStateVector * inf_adopted_state_vector_copy   (InfAdoptedStateVector *vec);

Returns a copy of `vec`.

`vec` : | The InfAdoptedStateVector to copy
Returns : | A copy of `vec`.

### 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()`.

`vec` : | A InfAdoptedStateVector.

### inf_adopted_state_vector_get ()

    guint               inf_adopted_state_vector_get        (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.

`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`.

`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.

`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    (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.

`vec` : | A InfAdoptedStateVector.
`func` : | The function to call.
`user_data` : | Additional data to pass to `func`.

### inf_adopted_state_vector_compare ()

    int                 inf_adopted_state_vector_compare    (InfAdoptedStateVector *first,
                                                             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`.

`first` : | A InfAdoptedStateVector.
`second` : | Another InfAdoptedStateVector.
Returns : | -1, 0 or 1.

### inf_adopted_state_vector_causally_before ()

    gboolean            inf_adopted_state_vector_causally_before
                                                            (InfAdoptedStateVector *first,
                                                             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`.

`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
                                                            (InfAdoptedStateVector *first,
                                                             InfAdoptedStateVector *second,
                                                             guint inc_component);

This function does the equivalent of

    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.

`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      (InfAdoptedStateVector *first,
                                                             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`.

`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  (InfAdoptedStateVector *vec);

Returns a string representation of `vec`.

`vec` : | A InfAdoptedStateVector.
Returns : | A newly-allocated string to be freed by the caller.

### 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.

`str` : | A string representation of a InfAdoptedStateVector.
`error` : | Location to place an error, if any.
Returns : | A new InfAdoptedStateVector, or `NULL`.

### inf_adopted_state_vector_to_string_diff ()

    gchar *             inf_adopted_state_vector_to_string_diff
                                                            (InfAdoptedStateVector *vec,
                                                             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.

`vec` : | A InfAdoptedStateVector.
`orig` : | Another InfAdoptedStateVector.
Returns : | A newly allocated string to be freed by the caller.

### inf_adopted_state_vector_from_string_diff ()

    InfAdoptedStateVector * inf_adopted_state_vector_from_string_diff
                                                            (const gchar *str,
                                                             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.

`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.

## See Also

InfAdoptedAlgorithm