engine.texinfo

@node Engine, Register, Top Level, Top
@chapter Engine
@cindex The Engine

The Engine provides an interface to a financial engine with three basic
financial entities: Accounts, Transactions (known as Journal Entries in
accounting practice), and Splits (known as Ledger Entries). These three
entities are the central data structures of the GnuCash financial data
model.

In addition, the Engine provides the abstraction of Account Groups
(collections of related accounts) and GNCBooks. A GNCBook abstracts both
a set of related GnuCash data (financial entities plus additional
information such as budgets, per-file preferences, etc.) plus a
file-editing session allowing transparent support for locking and
implementation with other backends such as SQL.

The Engine code contains no GUI code whatsoever and is designed to
be created as a shared library for use by other programs.

@menu
* Engine Introduction::         
* Using and Extending the Engine API::  
* Globally Unique Identifiers::  
* Numeric Library::             
* Key-Value Pair Frames::       
* Splits::                      
* Transactions::                
* Accounts::                    
* Account Groups::              
* GNCBooks::                    
* Scrub::                       
@end menu


@node Engine Introduction, Using and Extending the Engine API, Engine, Engine
@section Introduction

Splits (@pxref{Splits}), or "Ledger Entries" are the fundamental
accounting units. Each Split consists of a quantity (number of dollar
bills, number of shares, etc.), the price of that quantity (the price of
one dollar is 1.00 dollars, etc.), a Memo, a pointer to the parent
Transaction, a pointer to the debited Account, a reconciled flag and
timestamp, an "Action" field, and a key-value frame which can store
arbitrary data (@pxref{Key-Value Pair Frames}).

Transactions (@pxref{Transactions}) embody the notion of "double entry"
accounting. A Transaction consists of a date, a description, a number, a
list of one or more Splits, and a key-value frame. When double-entry
rules are enforced, the total value of the splits is zero.  Note that if
there is just one split, its value must be zero for double-entry
accounting; this is useful because a zero-valued split can store a price
(useful for e.g. tracking stocks). If there are two splits, then the
value of one must be positive, the other negative: this denotes that one
account is credited, and another is debited by an equal amount. Positive
Split values are 'debits' and negative Split values are 'credits'.
Ensuring the Splits to 'add up' to zero causes a double-entry accounting
system to always balance.

The engine does not enforce double-entry accounting, but provides an API
to enable user-code to find unbalanced transactions and 'repair' them so
that they are in balance. @xref{Scrub}.

Note the sum of the values of Splits in a Transaction is always computed
with respect to a currency; thus splits can be balanced even when they
are in different currencies, as long as they share a common currency.
The conversion price is simply the price stored in the Split. This
feature allows currency-trading accounts to be established.

Every Split must point at its parent Transaction, and that Transaction
must in turn include that Split in the Transaction's list of Splits. A
Split can belong to at most one Transaction. These relationships are
forced by the engine. The engine user cannnot accidentally destroy this
relationship as long as they stick to using the API and never access
internal structures directly.

Splits are grouped into Accounts (@pxref{Accounts}) which are also known
as "Ledgers" in accouting practice. Each Account consists of a list of
Splits that debit that Account. To ensure consistency, if a Split points
at an Account, then the Account must point at the Split, and vice-versa.
A Split can belong to at most one Account. Besides merely containing a
list of Splits, the Account structure also give the Account a name, a
code number, description and notes fields, a key-value frame, a pointer
to the currency that is used for all splits in this account, and a
pointer to the "security" used for all splits in this account. The
"security" can be the name of a stock (e.g. "IBM", "McDonald's"), or
another currency (e.g. "USD", "GBP").  The security is used during
Transaction balancing to enable trading between accounts denominated in
different currencies, or to, for example, move stocks from one Account
to another.

Accounts can be arranged in a hierarchical tree. The nodes of the tree
are called "Account Groups" (@pxref{Account Groups}). By accounting
convention, the value of an Account is equal to the value of all of its
Splits plus the value of all of its sub-Accounts.


@node Using and Extending the Engine API, Globally Unique Identifiers, Engine Introduction, Engine
@section Using and Extending the Engine API

Engine API calls are named using a specific convention. For example,
the function to access the Memo field of a Split is
@code{xaccSplitGetMemo}.  The prefix @code{xacc} comes
first@footnote{The @code{xacc} prefix is a historical artifact. GnuCash
was derived from X-Accountant by Robin Clark.}, followed by the name of
the entity for which the API call applies (@code{Split}), followed by
the action performed by the call (@code{Get}), followed by the name of
the field being accessed (@code{Memo}). Future API calls should conform
to this naming convention.

The formal arguments to Engine API calls always begin with the entity to
which the call applies. Thus, the arguments to @code{xaccSplitSetMemo}
are the @code{Split} pointer followed by the pointer to a memo
string. Future API calls should also conform to this convention.

Engine API calls should be implemented to behave as gracefully as
possible with unexpected input. Specifically, public API calls should
gracefully handle @code{NULL} pointer arguments. User code should be
able to handle @code{NULL} return values from Engine calls as well.


@node Globally Unique Identifiers, Numeric Library, Using and Extending the Engine API, Engine
@section Globally Unique Identifiers
@cindex Globally Unique Identifier
@tindex GUID

It is common for Engine structures to reference other Engine structures.
For example, an Account must reference its Splits, its parent Account
Group, and its child Account Group. Furthermore, other GnuCash modules
may need to reference Engine structures. For example, a GUI
implementation may wish to save a list of Accounts which the user has
open when the application exits in order to restore that same state upon
the next invocation.

One way to uniquely identify an Engine structure, at least while the
program is running, is using the C pointer which points to the
structure. C pointers have the advantage of speed, but also have some
disadvantages:

@itemize

@item
Pointers cannot be used in data files and are not persistant across
different program invocations.

@item
When an entity is destroyed, every other structure which references that
entity through a direct pointer must be immediately updated to prevent
illegal accesses.

@end itemize

The @dfn{GUID} (Globally Unique Identifier) provides a way to reference
Engine structures that is more flexible than C pointers. Each Engine
structure has an associated GUID which can be used to reference that
structure. Engine GUIDs have the following features:

@itemize

@item
The GUID is permanent, i.e., it persists between invocations of GnuCash.

@item
The GUID is guaranteed to be unique with the set of all Splits,
Transactions, and Accounts in the hierarchy of which the structure
is a member.

@item
With very high probability, the GUID is unique among all GUIDs
created by any invocation of GnuCash, all over the world.

@item
GUIDs can be efficiently encoded in a string representation.

@end itemize


@menu
* When to use GUIDs::           
* GUID Types::                  
* How to use GUIDs::            
* GUIDs and GnuCash Entities::  
* The GUID Generator::          
@end menu

@node When to use GUIDs, GUID Types, Globally Unique Identifiers, Globally Unique Identifiers
@subsection When to use GUIDs
@cindex When to use GUIDs

Although GUIDs are very flexible, the engine structures like Accounts
will probably continue to use C pointers for the forseeable future,
since they are much faster (and in certain respects more convenient)
than using GUIDs. In general, however, it is much safer to use GUIDs.
In particular, you should consider using GUIDs if any of the following
is true:

@itemize

@item
You need to save a reference to an engine structure in a file.

@item
You need to save a reference to an engine structure that could
be deleted in between accesses to the saved reference.

@end itemize


@node GUID Types, How to use GUIDs, When to use GUIDs, Globally Unique Identifiers
@subsection GUID Types
@tindex GNCIdType

The GUIDs in GnuCash are typed using the enum @code{GNCIdType}.
Possible values and their meanings for GUID types are:

@table @code

@item GNC_ID_NONE
The GUID does not currently refer to a GnuCash entity, though it
could refer to one in the future.

@item GNC_ID_NULL
The GUID does not, and never will, refer to a GnuCash entity.

@item GNC_ID_ACCOUNT
The GUID refers to an Account (@pxref{Accounts}).

@item GNC_ID_TRANS
The GUID refers to a Transation (@pxref{Transactions}).

@item GNC_ID_SPLIT
The GUID refers to a Split (@pxref{Splits}).

@end table

@deftypefun GNCIdType xaccGUIDType (const GUID * @var{guid})
Return the type associated with @var{guid}.
@end deftypefun

@deftypefun {const GUID *} xaccGUIDNull (void)
Return a GUID which is guaranteed to always have type @code{GNC_ID_NULL}.
@end deftypefun


@node How to use GUIDs, GUIDs and GnuCash Entities, GUID Types, Globally Unique Identifiers
@subsection How to use GUIDs

The Engine API functions which access the GUID for a specific entity
return a pointer to the GUID. @strong{Note:} Do not store the pointer
itself! Instead, store a copy of the GUID. Storing the pointer itself
would present some of the same problems as using the account pointer
directly. Example:

@example
@{
  GUID saved_guid;
  Account *account;

  account = < something to get an Account pointer >

  saved_guid = *xaccAccountGetGuid(account);

  ...

  account = xaccAccountLookup(&saved_guid);

  ...
@}
@end example

You can compare two GUIDs for equality with the following function.

@deftypefun gboolean guid_equal(const GUID * @var{guid_1}, const GUID * @var{guid_2})
Compare two guids and return TRUE if they are both non-NULL and equal.
@end deftypefun


You can encode and decode GUIDs and their string representations using the
next two functions.

@deftypefun {char *} guid_to_string(const GUID * @var{guid})
Return a null-terminated string encoding of @var{guid}. String encodings
of identifiers are hex numbers printed only with the characters @code{0}
through @code{9} and @code{a} through @code{f}.  The encoding will
always be @code{GUID_ENCODING_LENGTH} characters long. The returned
string should be freed when no longer needed.
@end deftypefun

@deftypefun gboolean string_to_guid(const char * @var{string}, GUID * @var{guid})
Given a string, decode an id into @var{guid} if @var{guid} is
non-NULL. The function returns TRUE if the string was a valid 32
character hexadecimal number. This function accepts both upper and lower
case hex digits. If the return value is FALSE, the effect on @var{guid}
is undefined.
@end deftypefun


@node GUIDs and GnuCash Entities, The GUID Generator, How to use GUIDs, Globally Unique Identifiers
@subsection GUIDs and GnuCash Entities

This section documents a low-level API for associating entities with
GUIDs. User code and general engine code should not use this API;
instead use the API documented in the sections for the specific GnuCash
entities such as Accounts and Transactions.

@deftypefun void xaccGUIDNew(GUID * @var{guid})
Generate a new guid. This function is guaranteed to return a guid that
is unique within the scope of all GnuCash entities being managed by the
the current invocation of GnuCash. GnuCash routines should always use
this function and not @code{guid_new}!
@end deftypefun

@deftypefun {void *} xaccLookupEntity(const GUID * @var{guid}, GNCIdType @var{entity_type})
Lookup an entity given an id and a type. If there is no entity
associated with the id, or if it has a different type, NULL is returned.
@end deftypefun

@deftypefun void xaccStoreEntity(void * @var{entity}, const GUID * @var{guid}, GNCIdType entity_type)
Store the given entity under the given id with the given type.
@end deftypefun

@deftypefun void xaccRemoveEntity(const GUID * @var{guid})
Remove any existing association between an entity and the given id. The
entity is not changed in any way.
@end deftypefun


@node The GUID Generator,  , GUIDs and GnuCash Entities, Globally Unique Identifiers
@subsection The GUID Generator
@cindex The GUID Generator

GUIDs are created by the GUID generator. The API for this generator is
low-level and should not be used by user-code.

@deftypefun void guid_init (void)
Initialize the GUID generator with a variety of random sources including
common system files and /dev/random.
@end deftypefun

@deftypefun void guid_init_with_salt (const void * @var{salt}, size_t @var{salt_len})
Initialize the GUID generator with guid_init() and with the given
sequence of arbitrary binary data.
@end deftypefun

@deftypefun void guid_init_only_salt (const void * @var{salt}, size_t @var{salt_len})
Initialize the GUID generator using only the given sequence of arbitrary
binary data. This provides a way to reliably obtain a given sequence of
GUIDs.
@end deftypefun

@deftypefun void guid_new (GUID * @var{guid})
Create a new GUID and store it in @var{guid}. This is a low-level function!
GnuCash code should use @code{xaccGUIDNew}.
@end deftypefun


@node Numeric Library, Key-Value Pair Frames, Globally Unique Identifiers, Engine
@section Numeric Library
@cindex Numeric Library
@tindex gnc_numeric

Financial quantities in GnuCash (Split quantities and values) are stored
as exact quantities measured in the smallest denominational unit of the
appropriate currency. For example, 100.50 US Dollars would be stored as
(10050 / 100) US Dollars. GnuCash uses the @code{gnc_numeric} datatype
to store financial quantities.

The @code{gnc_numeric} API provides data types and functions for
manipulating exact numeric quantities. While the @code{gnc_numeric}
library was developed to represent and operate on exact financial
quantities in GnuCash, the library is also (hopefully) suitable for use
in any application where exact numeric representation for rational
numbers is needed.

A @code{gnc_numeric} value represents a number in rational form, with a
64-bit @code{long long} integer as numerator and denominator. If more
precision, a higher-precision representation of irrational numbers, or a
wider dynamic range is needed, a floating point format may be
appropriate. There are reasonable rational approximations to common
irrational constants (@pxref{Numeric Example}), but the transcendental
functions have not been implemented for @code{gnc_numeric} objects.

@menu
* Standard Numeric Arguments::  
* Creating Numeric Objects::    
* Basic Arithmetic Operations::  
* Numeric Comparisons and Predicates::  
* Numeric Denominator Conversion::  
* Numeric Floating Point Conversion::  
* Numeric String Conversion::   
* Numeric Error Handling ::     
* Numeric Example::             
@end menu

@node Standard Numeric Arguments, Creating Numeric Objects, Numeric Library, Numeric Library
@subsection Standard Numeric Arguments
@cindex Standard Numeric Arguments

It is useful to specify a denominator in cases where it is known that
the output value is of constrained precision. For example, monetary
transactions must be executed in an integer number of the "smallest
currency unit" of the transaction. In US Dollars, the smallest currency
unit is the cent, and all monetary transactions must be done in units of
cents. Therefore, any fractional cents in a computed price must be
rounded away.

Most of the @code{gnc_numeric} arithmetic functions take two arguments
in addition to their numeric args: @var{denom}, which is the denominator
to use in the output @code{gnc_numeric object}, and @var{how}, which
describes how the arithmetic result is to be converted to that
denominator. This combination of output denominator and rounding policy
allows the results of financial and other exact computations to be
properly rounded to the appropriate units.

Valid values for @var{denom} are:

@table @code

@item n (positive int)
Use the number @code{n} as the denominator of the output value.

@item GNC_DENOM_RECIPROCAL (n)
Use the value @code{1/n} as the denominator of the output value.

@item GNC_DENOM_AUTO
Compute an appropriate denominator automatically. Flags in the @var{how}
argument will specify how to compute the denominator.

@end table


Valid values for @var{how} are bitwise combinations of zero or one
"rounding instructions" with zero or one "denominator types". 

Rounding instructions control how fractional parts in the specified
denominator affect the result. For example, if a computed result is
"3/4" but the specified denominator for the return value is 2, should
the return value be "1/2" or "2/2"?  

Possible rounding instructions are:

@table @code

@item GNC_RND_FLOOR
Round toward -infinity

@item GNC_RND_CEIL
Round toward +infinity

@item GNC_RND_TRUNC
Truncate fractions (round toward zero)

@item GNC_RND_PROMOTE
Promote fractions (round away from zero)

@item GNC_RND_ROUND
Use unbiased ("banker's") rounding. This rounds to the nearest integer,
and to the nearest even integer when there are two equidistant nearest
integers. This is generally the one you should use for financial
quantities.

@item GNC_RND_ROUND_HALF_UP
Round to the nearest integer, rounding away from zero when there are two
equidistant nearest integers.

@item GNC_RND_ROUND_HALF_DOWN
Round to the nearest integer, rounding toward zero when there are two
equidistant nearest integers.

@item GNC_RND_NEVER
Never round at all, and signal an error if there is a fractional result
in a computation.

@end table


The denominator type specifies how to compute a denominator if
@code{GNC_DENOM_AUTO} is specified as the @var{denom}. Valid denominator
types are:

@table @code

@item GNC_DENOM_EXACT
Use any denominator which gives an exactly correct ratio of numerator to
denominator. Use EXACT when you do not wish to lose any information in
the result but also do not want to spend any time finding the "best"
denominator.

@item GNC_DENOM_REDUCE
Reduce the result value by common factor elimination, using the smallest
possible value for the denominator that keeps the correct ratio. The
numerator and denominator of the result are relatively prime. This can
be computationally expensive for large fractions.

@item GNC_DENOM_LCD
Find the least common multiple of the arguments' denominators and use
that as the denominator of the result.

@item GNC_DENOM_FIXED
All arguments are required to have the same denominator, that
denominator is to be used in the output, and an error is to be signaled
if any argument has a different denominator.

@end table


To use traditional rational-number operational semantics (all results
are exact and are reduced to relatively-prime fractions) pass the
argument @code{GNC_DENOM_AUTO} as @var{denom} and @code{GNC_DENOM_REDUCE
| GNC_RND_NEVER} as @var{how}.

To enforce strict financial semantics (such that all operands must have
the same denominator as each other and as the result), use
@var{GNC_DENOM_AUTO} as @var{denom} and @code{GNC_DENOM_FIXED |
GNC_RND_NEVER} as @var{how}.


@node Creating Numeric Objects, Basic Arithmetic Operations, Standard Numeric Arguments, Numeric Library
@subsection Creating Numeric Objects
@cindex Creating Numeric Objects

@deftypefun gnc_numeric gnc_numeric_create (int @var{num}, int @var{denom})
Create a @code{gnc_numeric} object with a value of "@var{num} / @var{denom}".
@end deftypefun

@deftypefun gnc_numeric gnc_numeric_zero ()
Create a @code{gnc_numeric} object with a value of 0. 
@end deftypefun


@node Basic Arithmetic Operations, Numeric Comparisons and Predicates, Creating Numeric Objects, Numeric Library
@subsection Basic Arithmetic Operations
@cindex Basic Arithmetic Operations

See @ref{Standard Numeric Arguments} for a description of the @var{denom}
and @var{how} arguments to each arithmetic function.

@deftypefun gnc_numeric gnc_numeric_add (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
Return the sum of @var{a} and @var{b}.
@end deftypefun

@deftypefun gnc_numeric gnc_numeric_sub (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
Return "@var{a} - @var{b}".
@end deftypefun

@deftypefun gnc_numeric gnc_numeric_mul (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
Return the product of @var{a} and @var{b}.
@end deftypefun

@deftypefun gnc_numeric gnc_numeric_div (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
Return "@var{a} / @var{b}".
@end deftypefun

@deftypefun gnc_numeric gnc_numeric_neg (gnc_numeric @var{a})
Return "-@var{a}".
@end deftypefun

@deftypefun gnc_numeric gnc_numeric_abs (gnc_numeric @var{a})
Return the absolute value of @var{a}.
@end deftypefun

@deftypefun gnc_numeric gnc_numeric_add_fixed (gnc_numeric @var{a}, gnc_numeric @var{b})
Equivalent to @code{gnc_numeric_add} on @var{a} and @var{b} with
@code{GNC_DENOM_AUTO} for @var{denom} and @code{GNC_DENOM_FIXED |
GNC_RND_NEVER} for @var{how}.
@end deftypefun

@deftypefun gnc_numeric gnc_numeric_sub_fixed (gnc_numeric @var{a}, gnc_numeric @var{b})
Equivalent to @code{gnc_numeric_sub} on @var{a} and @var{b} with
@code{GNC_DENOM_AUTO} for @var{denom} and @code{GNC_DENOM_FIXED |
GNC_RND_NEVER} for @var{how}.
@end deftypefun

@deftypefun gnc_numeric gnc_numeric_add_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
The same as @code{gnc_numeric_add}, but uses @var{error} for accumulating
conversion roundoff error.
@end deftypefun

@deftypefun gnc_numeric gnc_numeric_sub_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
The same as @code{gnc_numeric_sub}, but uses @var{error} for accumulating
conversion roundoff error.
@end deftypefun

@deftypefun gnc_numeric gnc_numeric_mul_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
The same as @code{gnc_numeric_mul}, but uses @var{error} for accumulating
conversion roundoff error.
@end deftypefun

@deftypefun gnc_numeric gnc_numeric_div_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
The same as @code{gnc_numeric_div}, but uses @var{error} for accumulating
conversion roundoff error.
@end deftypefun


@node Numeric Comparisons and Predicates, Numeric Denominator Conversion, Basic Arithmetic Operations, Numeric Library
@subsection Numeric Comparisons and Predicates
@cindex Numeric Comparisons and Predicates

@deftypefun int gnc_numeric_zero_p (gnc_numeric @var{a})
Returns 1 if @code{@var{a} == 0}, otherwise returns 0.
@end deftypefun

@deftypefun int gnc_numeric_positive_p (gnc_numeric @var{a})
Returns 1 if @code{@var{a} > 0}, otherwise returns 0.
@end deftypefun

@deftypefun int gnc_numeric_negative_p (gnc_numeric @var{a})
Returns 1 if @code{@var{a} > 0}, otherwise returns 0.
@end deftypefun

@deftypefun int gnc_numeric_compare (gnc_numeric @var{a}, gnc_numeric @var{b})
Returns +1 if @code{@var{a} > @var{b}}, -1 if @code{@var{b} > @var{a}}, 0 if @code{@var{a} == @var{b}}.
@end deftypefun

@deftypefun int gnc_numeric_eq (gnc_numeric @var{a}, gnc_numeric @var{b})
Returns 1 if @code{numerator(@var{a}) == numerator(@var{b})} and
@code{denominator(@var{a}) == denominator(@var{b})}, otherwise returns 0.
@end deftypefun

@deftypefun int gnc_numeric_equal (gnc_numeric @var{a}, gnc_numeric @var{b})
Returns 1 if the fraction represented by @var{a} is equal to the fraction
represented by @var{b}, otherwise returns 0.
@end deftypefun

@deftypefun int gnc_numeric_same (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
Convert both @var{a} and @var{b} to @var{denom} (@pxref{Standard Numeric
Arguments} and compare numerators of the result.

@example
  For example, if @code{@var{a} == 7/16} and @code{@var{b} == 3/4},
  @code{gnc_numeric_same(@var{a}, @var{b}, 2, GNC_RND_TRUNC) == 1}
  because both 7/16 and 3/4 round to 1/2 under truncation. However,
  @code{gnc_numeric_same(@var{a}, @var{b}, 2, GNC_RND_ROUND) == 0}
  because 7/16 rounds to 1/2 under unbiased rounding but 3/4 rounds
  to 2/2.
@end example
@end deftypefun


@node Numeric Denominator Conversion, Numeric Floating Point Conversion, Numeric Comparisons and Predicates, Numeric Library
@subsection Numeric Denominator Conversion
@cindex Numeric Denominator Conversion

@deftypefun gnc_numeric gnc_numeric_convert (gnc_numeric @var{in}, gint64 @var{denom}, gint @var{how})
Convert @var{in} to the specified denominator under standard arguments
@var{denom} and @var{how}. @xref{Standard Numeric Arguments}.
@end deftypefun

@deftypefun gnc_numeric gnc_numeric_convert_with_error (gnc_numeric @var{in}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
Same as @code{gnc_numeric_convert}, but return a remainder value for
accumulating conversion error.
@end deftypefun

@deftypefun gnc_numeric gnc_numeric_reduce (gnc_numeric @var{in})
Return @var{in} reduced by GCF reduction.
@end deftypefun


@node Numeric Floating Point Conversion, Numeric String Conversion, Numeric Denominator Conversion, Numeric Library
@subsection Numeric Floating Point Conversion
@cindex Numeric Floating Point Conversion

@deftypefun gnc_numeric double_to_gnc_numeric (double @var{arg}, gint64 @var{denom}, gint @var{how})
Convert a floating-point number to a @code{gnc_numeric}. Both @var{denom}
and @var{how} are used as in arithmetic, but @code{GNC_DENOM_AUTO} is 
not recognized.
@end deftypefun

@deftypefun double gnc_numeric_to_double (gnc_numeric @var{arg})
Convert @var{arg} to a @code{double} value.
@end deftypefun


@node Numeric String Conversion, Numeric Error Handling , Numeric Floating Point Conversion, Numeric Library
@subsection Numeric String Conversion
@cindex Numeric String Conversion

@deftypefun {gchar *} gnc_numeric_to_string (gnc_numeric @var{n})
Return a string representation of @var{n}. The string must be
freed with @code{g_free}.
@end deftypefun

@deftypefun {const gchar *} string_to_gnc_numeric (const {gchar *} @var{str}, {gnc_numeric *} @var{n})
Read a @code{gnc_numeric} from @var{str}, skipping any leading
whitespace, and returning a pointer to just past the last byte
read. Return NULL on error.
@end deftypefun


@node Numeric Error Handling , Numeric Example, Numeric String Conversion, Numeric Library
@subsection Numeric Error Handling 
@cindex Numeric Error Handling 

@deftypefun int gnc_numeric_check (gnc_numeric @var{num})
Check @var{num} for the possibility that it is an error signal rather
than a proper value. Possible return codes are:

@table @code

@item GNC_ERROR_OK
No error condition
     
@item GNC_ERROR_ARG
An improper argument was passed to a function

@item GNC_ERROR_OVERFLOW
An overflow occurred while calculating a result 

@item GNC_ERROR_DENOM_DIFF
@code{GNC_DENOM_FIXED} was specified, but argument denominators differed.

@item GNC_ERROR_REMAINDER
@code{GNC_RND_NEVER} was specified, but the result could not be
converted to the desired denominator without a remainder.

@end table

@end deftypefun

@deftypefun gnc_numeric gnc_numeric_error (int error_code)
Create a @code{gnc_numeric} object that signals the error condition
noted by @var{error_code} rather than a number.
@end deftypefun


@node Numeric Example,  , Numeric Error Handling , Numeric Library
@subsection Numeric Example
@cindex Numeric Example

The following program finds the best @code{gnc_numeric} approximation to
the @file{math.h} constant @code{M_PI} given a maximum denominator. For
large denominators, the @code{gnc_numeric} approximation is accurate to
more decimal places than will generally be needed, but in some cases
this may not be good enough. For example,

@example
    M_PI                   = 3.14159265358979323846
    245850922 / 78256779   = 3.14159265358979311599  (16 sig figs)
    3126535 / 995207       = 3.14159265358865047446  (12 sig figs)
    355 / 113              = 3.14159292035398252096  (7 sig figs)
@end example

@example
#include <glib.h>
#include "gnc-numeric.h"
#include <math.h>

int
main(int argc, char ** argv)
@{
  gnc_numeric approx, best;
  double err, best_err=1.0;
  double m_pi = M_PI;
  gint64 denom;
  gint64 max;

  sscanf(argv[1], "%Ld", &max);
  
  for (denom = 1; denom < max; denom++)
  @{
    approx = double_to_gnc_numeric (m_pi, denom, GNC_RND_ROUND);
    err    = m_pi - gnc_numeric_to_double (approx);
    if (fabs (err) < fabs (best_err))
    @{
      best = approx;
      best_err = err;
      printf ("%Ld / %Ld = %.30f\n", gnc_numeric_num (best),
              gnc_numeric_denom (best), gnc_numeric_to_double (best));
    @}
  @}
@}
@end example


@node Key-Value Pair Frames, Splits, Numeric Library, Engine
@section Key-Value Pair Frames
@cindex Key-Value Pairs

The number and types of data items which are associated with the
financial abstractions (Accounts, Transactions, and Splits) can vary
widely. For example, an Account which represents a user's checking
account might need to store the bank name, a telephone number, and a
username for online banking purposes. Another Account representing the
user's ownership of a stock might need to store information about
retrieving price quotes online such as the ticker symbol and the
exchange.

To meet this need for varying data storage, the GnuCash accounting
entities use Key-Value Pair Frames (hereafter referred to as the
datatype @code{kvp_frame}). A @code{kvp_frame} is a set of associations
between character strings (keys) and @code{kvp_value} structures. A
@code{kvp_value} is a union with possible types enumerated in the
@code{kvp_value_t} enum which indicates the type of data stored in a
@code{kvp_value} object.

@menu
* Key-Value Policy::            
* kvp_frame::                   
* kvp_value::                   
* kvp_list::                    
@end menu


@node Key-Value Policy, kvp_frame, Key-Value Pair Frames, Key-Value Pair Frames
@subsection Key-Value Policy
@cindex Key-Value Policy

This section defines the policy that programmers should follow
when using key-value pairs to store information. Because of the
large amount of information which can potentially be stored using
this mechanism, it is important to follow these guidelines so
that order will be maintained.

The following rules should be followed for using key-value pairs:

@itemize

@item
The document @file{src/engine/kvp_doc.txt} should be used to document the
use of keys and values. Please consult this document before planning any
use of new keys.

@item
Key strings should be in all lower case with the '-' character
separating words. If possible, use only alphanumeric characters and
'-'. Example: @code{bank-info}. Because the '/' character is useful for
describing keys in sub-frames (@code{bank-info/routing-number}), do not
use the '/' character in key names.

@item
Favor longer, descriptive key strings over short ones. Example:
@code{online-banking-info} is better than @code{onln-bnk}.

@item
Make use of the fact that frames can be stored in frames. If a group
of keys are used for a related purpose, consider storing them together
in a sub-frame.

@item
Values should generally not be accessed directly through keys, but
should rather be accessed through specific API calls. The API calls
do not necessarily need to part a part of the Engine API. For example,
the GUI would probably define keys that the Engine does not need to
know about.

@item
The same key should not be used for different engine structures (Accounts,
Transactions, Splits), unless the key's value has the same type and the
same basic purpose.

@end itemize


@node kvp_frame, kvp_value, Key-Value Policy, Key-Value Pair Frames
@subsection kvp_frame
@tindex kvp_frame

A @code{kvp_frame} is the datatype used to associate key strings with
@code{kvp_value} objects (@pxref{kvp_value}).

@deftypefun kvp_frame* kvp_frame_new (void)
Create and initialize a new @code{kvp_frame} object and return
a pointer to it.
@end deftypefun

@deftypefun void kvp_frame_delete(kvp_frame * @var{frame})
Free all memory associated with @var{frame}.
@end deftypefun

@deftypefun kvp_frame* kvp_frame_copy(const kvp_frame * frame)
Return a deep copy of @var{frame}.
@end deftypefun

@deftypefun void kvp_frame_set_slot(kvp_frame * @var{frame}, const char * @var{key}, const kvp_value * @var{value})
Associate @var{key} with @var{value} in @var{frame}.
@end deftypefun

@deftypefun kvp_value* kvp_frame_get_slot(kvp_frame * @var{frame}, const char * @var{key})
Return the @code{kvp_value} object associated with @var{key}
in @var{frame} or return @code{NULL} if there is no association
for @var{key}. The value returned is not a copy.
@end deftypefun


@node kvp_value, kvp_list, kvp_frame, Key-Value Pair Frames
@subsection kvp_value
@tindex kvp_value
@tindex kvp_value_t

The @code{kvp_value} object stores the 'value' part of a key-value
association in a @code{kvp_frame} object.

@deftypefun void kvp_value_delete(kvp_value * @var{value})
Free all of the memory associated with @var{value}.
@end deftypefun

@deftypefun kvp_value* kvp_value_copy(const kvp_value * @var{value})
Return a deep copy of @var{value}.
@end deftypefun

@deftypefun kvp_value_t kvp_value_get_type(const kvp_value * @var{value})
Return the type of value stored in @var{value}.
@end deftypefun

A @code{kvp_value_t} enum must have one of the following values:

@table @code

@item KVP_TYPE_NONE
Indicates the abscence of a value in a @code{kvp_frame}.

@item KVP_TYPE_INT64
A @code{gint64} value.

@item KVP_TYPE_FLOAT64
A @code{double} value.

@item KVP_TYPE_STRING
A @code{char *} value of arbitrary length.

@item KVP_TYPE_GUID
A @code{GUID} value. @xref{Globally Unique Identifiers}.

@item KVP_TYPE_BINARY
Arbitrary binary data.

@item KVP_TYPE_LIST
A @code{kvp_list} item which contains a list of @code{kvp_value} items.

@item KVP_TYPE_FRAME
A @code{kvp_frame} object. Thus, frames may contain other frames in a
recursive manner.

@end table

@subsubsection Value Constructors

The following functions create and return @code{kvp_value} objects with
particular values. In the case of pointer arguments, deep copies are
performed.

@deftypefun kvp_value* kvp_value_new_int64(gint64 @var{value})
@end deftypefun
@deftypefun kvp_value* kvp_value_new_float64(double @var{value})
@end deftypefun
@deftypefun kvp_value* kvp_value_new_string(const char * @var{value})
@end deftypefun
@deftypefun kvp_value* kvp_value_new_guid(const GUID * @var{guid})
@end deftypefun
@deftypefun kvp_value* kvp_value_new_binary(const void * @var{data}, int @var{datasize})
@end deftypefun
@deftypefun kvp_value* kvp_value_new_list(const kvp_list * @var{value})
@end deftypefun
@deftypefun kvp_value* kvp_value_new_frame(const kvp_frame * @var{value});
@end deftypefun

@subsubsection Value Accessors

The following functions access the value of a given @code{kvp_value}
object. If the type of the object does not correspond to that named
in the function, @code{NULL}, @code{0}, or @code{0.0} is returned
as appropriate.

@deftypefun gint64 kvp_value_get_int64(const kvp_value * @var{value})
@end deftypefun
@deftypefun double kvp_value_get_float64(const kvp_value * @var{value})
@end deftypefun
@deftypefun char* kvp_value_get_string(const kvp_value * @var{value})
@end deftypefun
@deftypefun GUID* kvp_value_get_guid(const kvp_value * @var{value})
@end deftypefun
@deftypefun void* kvp_value_get_binary(const kvp_value * @var{value}, int * @var{size_return})
@end deftypefun
@deftypefun kvp_list* kvp_value_get_list(const kvp_value * @var{value})
@end deftypefun
@deftypefun kvp_frame* kvp_value_get_frame(const kvp_value * @var{value})
@end deftypefun


@node kvp_list,  , kvp_value, Key-Value Pair Frames
@subsection kvp_list
@tindex kvp_list

A @code{kvp_list} object abstract a list of @code{kvp_value} objects.

@deftypefun kvp_list* kvp_list_new()
Return a newly allocated @code{kvp_list} object.
@end deftypefun

@deftypefun void kvp_list_delete(kvp_list * @var{list})
Free all memory associated with @var{list}, including the
@code{kvp_value} objects in @var{list}.
@end deftypefun

@deftypefun kvp_list* kvp_list_copy(const kvp_list * @var{list})
Return a deep copy of @var{list}.
@end deftypefun

@deftypefun gboolean kvp_list_null_p(const kvp_list * @var{list})
Return @code{TRUE} if @var{list} is the empty list.
@end deftypefun

@deftypefun kvp_value* kvp_list_car(kvp_list * @var{list})
If @var{list} is @code{NULL} or the empty list, return @code{NULL}.
Otherwise, return the first @code{kvp_value} object in the list.
@end deftypefun

@deftypefun kvp_list* kvp_list_cdr(kvp_list * @var{list})
If @var{list} is @code{NULL} or the empty list, return @code{NULL}.
Otherwise, return a @code{kvp_list} object consisting of @var{list}
with the first value removed. NOTE: the returned list is not a copy!
@end deftypefun

@deftypefun kvp_list* kvp_list_cons(kvp_value * @var{car}, kvp_list * @var{cdr})
If either @var{car} or @var{cdr} is @code{NULL}, return @code{NULL}. Otherwise,
return a @code{kvp_list} object consisting of the value of @var{car} followed
by the values of @var{cdr}. This function uses 'hand-over' semantics, i.e.,
the arguments @var{car} and @var{cdr} are no longer the responsibility of
the caller and should not be accessed after the function returns.
@end deftypefun


@node Splits, Transactions, Key-Value Pair Frames, Engine
@section Splits
@tindex Split

A Split is the Engine abstraction of an accounting entry in an Account
Ledger. In accounting terms, a Split is a Ledger Entry. As such, it
contains the following pieces of information:

@table @asis

@item A parent Account
The Account of which it is an entry.

@item A parent Transaction.
In accounting terms, this is the Journal Entry which this Ledger Entry
is linked to.

@item A 'share quantity'
This is the number of 'shares' which have been debited to the parent
Account. This quantity may be negative, in which case the Split
represents a 'credit'. Shares are given in units of the security of the
Account, unless the security field is blank, in which case shares are
given in units of the Account currency. @xref{Accounts}.

@item A 'price'
This represents the price of the shares. The price is a ratio of the
parent Account currency to the parent Account security. For most Accounts,
the security is blank, and thus the price is @code{1.0}, since the currency
effectively is the security. @xref{Accounts}.

@item A 'reconciled' flag
This flag represents the reconciled status of the Split. Possible
reconciliation states for a Split are:

  @table @asis

  @item Not Reconciled
  The Split has not been reconciled or cleared.

  @item Cleared
  The Split has been cleared, but not reconciled.

  @item Reconciled
  The Split has been reconciled with a statement.

  @item Frozen
  The Split has been frozen into the accounting period.

  @end table

@end table

In addition to the above, Splits contain a Memo field, an Action field,
and a key-value pair frame. The Memo and Action fields are for arbitrary
user input.


@menu
* General Split API::           
* Split Getters::               
* Split Setters::               
@end menu

@node General Split API, Split Getters, Splits, Splits
@subsection General Split API

@deftypefun {Split *} xaccMallocSplit (void)
Allocate, initialize, and return a new Split.
@end deftypefun

@deftypefun void xaccSplitDestroy (Split * @var{split})
Update @var{split}'s parent Account and Transaction in a consistent
manner, completely unlinking of @var{split} and freeing its memory. The
goal of this routine is to perform the removal and destruction of the
Split in an atomic fashion, with no chance of accidentally leaving the
accounting structure out-of-balance or otherwise inconsistent.

If the deletion of the Split leaves the Transaction with no Splits, then
the Transaction will be marked for deletion, but will not be deleted
until the @code{xaccTransCommitEdit()} routine is called.
@end deftypefun

@deftypefun {const GUID *} xaccSplitGetGUID (Split * @var{split})
Return the GUID of @var{split}.
@end deftypefun 

@deftypefun {Split *} xaccSplitLookup (const GUID * @var{guid})
Return the split associated with @var{GUID}, or @code{NULL} if there is
no such split.
@end deftypefun

@deftypefun {kvp_value *} xaccSplitGetSlot(Split * @var{split}, const char * @var{key})
Return the @code{kvp_value} associated with @var{key} in @var{split}.
If there is none, @code{NULL} is returned.
@end deftypefun

@deftypefun void xaccSplitSetSlot(Split * @var{split}, const char * @var{key}, const kvp_value * @var{value})
Associate a copy of @var{value} with @var{key} in @var{split}.
@end deftypefun


@node Split Getters, Split Setters, General Split API, Splits
@subsection Split Getters

@deftypefun {Account *} xaccSplitGetAccount (Split * @var{split})
Return the parent Account of @var{split}.
@end deftypefun

@deftypefun {Transaction *} xaccSplitGetParent (Split * @var{split})
Return the parent Transaction of @var{split}.
@end deftypefun

@deftypefun gnc_numeric xaccSplitGetShareAmount (Split * @var{split})
Return the 'share quantity' of @var{split}.
@end deftypefun

@deftypefun gnc_numeric xaccSplitGetSharePrice (Split * @var{split})
Return the 'share price' of @var{split}.
@end deftypefun

@deftypefun gnc_numeric xaccSplitGetValue (Split * @var{split})
Return the value of @var{split}, which is equal to the share quantity
multiplied by the share price.
@end deftypefun

@deftypefun gnc_numeric xaccSplitGetBaseValue (Split * @var{split}, const char * @var{base_currency})
Return either the share quantity or the value of @var{split}, depending
upon whether @var{base_currency} matches the security or currency of the
parent Account, respectively. No other value for @var{base_currency} is
legal.
@end deftypefun

@deftypefun char xaccSplitGetReconcile (Split * @var{split})
Return the value of the reconcile flag in @var{split}. Possible
values for the flag are:

  @table @code

  @item NREC
  Not Reconciled

  @item CREC
  Cleared

  @item YREC
  Reconciled

  @item FREC
  Frozen

  @end table

@end deftypefun

@deftypefun void xaccSplitGetDateReconciledTS (Split * @var{split}, Timespec * @var{ts})
Fill @var{ts} with the reconciled date of @var{split}.
@end deftypefun

@deftypefun {const char *} xaccSplitGetMemo (Split * @var{split})
Return the Memo field of @var{split}.
@end deftypefun

@deftypefun {const char *} xaccSplitGetAction (Split * @var{split})
Return the Action field of @var{split}.
@end deftypefun

@deftypefun gnc_numeric xaccSplitGetBalance (Split * @var{split})
Return the balance of @var{split}'s parent Account up to and including
@var{split}. See @ref{Accounts} for details.
@end deftypefun

@deftypefun gnc_numeric xaccSplitGetClearedBalance (Split * @code{split})
Return the cleared balance of @var{split}'s parent Account up to and
including @var{split}. See @ref{Accounts} for details.
@end deftypefun

@deftypefun gnc_numeric xaccSplitGetReconciledBalance (Split * @code{split})
Return the reconciled balance of @var{split}'s parent Account up to and
including @var{split}. See @ref{Accounts} for details.
@end deftypefun

@deftypefun gnc_numeric xaccSplitGetShareBalance (Split * @var{split})
Return the share balance of @var{split}'s parent Account up to and
including @var{split}. See @ref{Accounts} for details.
@end deftypefun

@deftypefun gnc_numeric xaccSplitGetShareClearedBalance (Split * @code{split})
Return the share cleared balance of @var{split}'s parent Account up to
and including @var{split}. See @ref{Accounts} for details.
@end deftypefun

@deftypefun gnc_numeric xaccSplitGetShareReconciledBalance (Split * @code{split})
Return the share reconciled balance of @var{split}'s parent Account up
to and including @var{split}. See @ref{Accounts} for details.
@end deftypefun


@node Split Setters,  , Split Getters, Splits
@subsection Split Setters

@deftypefun void xaccSplitSetMemo (Split * @var{split}, const char * @var{memo})
Set the memo field of @var{split} to @var{memo}.
@end deftypefun

@deftypefun void xaccSplitSetAction (Split * @var{split}, const char * @var{action})
Set the action field of @var{split} to @var{memo}. The action field is
an arbitrary string, but is intended to be conveniently limited to a
menu of selections such as "Buy", "Sell", "Interest", etc.
@end deftypefun

@deftypefun void xaccSplitSetReconcile (Split * @var{split}, char @var{reconciled_flag})
Set the reconciled flag of @var{split} to @var{reconciled_flag}. For the
possible values and meanings of @var{reconciled_flag}, see @ref{Split Getters}.
@end deftypefun

@deftypefun void xaccSplitSetDateReconciledSecs (Split * @var{split}, time_t @var{time})
Set the reconciliation date of @var{split} to @var{time}.
@end deftypefun

@deftypefun void xaccSplitSetDateReconciledTS (Split * @var{split}, Timespec * @var{ts})
Set the reconciliation date of @var{split} to @var{ts}.
@end deftypefun

@deftypefun void xaccSplitSetShareAmount (Split * @var{split}, gnc_numeric amount)
Set the share quantity of @var{split} to @var{amount}.
@end deftypefun

@deftypefun void xaccSplitSetSharePrice (Split * @var{split}, gnc_numeric @var{price})
Set the share price of @var{split} to @var{price}.
@end deftypefun

@deftypefun void xaccSplitSetSharePriceAndAmount (Split * @var{split}, gnc_numeric @var{price}, gnc_numeric @var{amount})
Set both the share price and share quantity of @var{split}. This routine
is more efficent than calling @code{xaccSplitSetShareAmount} and
@code{xaccSplitSetSharePrice} in succesion.
@end deftypefun

@deftypefun void xaccSplitSetValue (Split * @var{split}, gnc_numeric @var{value})
Adjust the share quantity of @var{split} so that @var{split}'s value is
equal to @var{value}.
@end deftypefun

@deftypefun void xaccSplitSetBaseValue (Split * @var{split}, gnc_numeric @var{value}, const char * @var{base_currency})
Set either the share quantity or value of @var{split} depending upon
whether @var{base_currency} is the security or current of @var{split}'s
parent Account. @xref{Accounts}.
@end deftypefun


@node Transactions, Accounts, Splits, Engine
@section Transactions
@tindex Transaction

A Transaction is the Engine abstraction of an accounting entry in a
Journal. In accounting terms, a Transaction is a Journal Entry. As
such, it contains the following pieces of information:

@table @asis

@item A list of Ledger Entries, or Splits
The list of debits and credits which make up this Transaction. As in
accounting, a Transaction is balanced when the sum of the debits equals
the sum of the credits.

@item The entry date
The date the transaction was entered into GnuCash.

@item The post date
The date the transaction was posted. This is often the date the
transaction was recorded by the bank, or the date the user initiated
the transaction (i.e., wrote the check, made the ATM withdrawal).

@item A transaction number field
This field is intended to hold a transaction number, such as a
check number or an ID assigned by a bank to an electronic transfer.

@item A description
A textual description of the transaction.

@end table

In addition to the above, Transactions contain a key-value pair frame.


@subsection The Transaction Edit Cycle

The Engine supports (and, in fact, requires) a 2-phase commit/rollback
cycle for modifying Transactions and their constituent Splits. A Transaction
must be opened for editing using @code{xaccTransBeginEdit()} before any of
the following actions may be taken.

@itemize

@item
Modifying any field of a Transaction.

@item
Modifying any Split belonging to the Transaction. That includes
re-parenting a Split to a different Account or a different Transaction.
In the case of re-parenting to a new Transaction, both Transactions must
be opened for editing.

@item
Deleting any Split belonging to the Transaction.

@item
Adding a Split to the transaction.

@item
Deleting the Transaction.

@end itemize

After the desired changes have been made, they must either be committed
using @code{xaccTransCommitEdit()} or rolled back using
@code{xaccTransRollbackEdit()}. Rolling back a transaction will undo any
changes which have been made to it or to its Splits since it was opened
for editing.


@menu
* General Transaction API::     
* Transaction Getters::         
* Transaction Setters::         
@end menu


@node General Transaction API, Transaction Getters, Transactions, Transactions
@subsection General Transaction API

@deftypefun {Transaction *} xaccMallocTransaction (void)
Allocate, initialize, and return a new Transaction.
@end deftypefun

@deftypefun void xaccTransAppendSplit (Transaction * @var{trans}, Split * @var{split})
Append @var{split} to the collection of Splits in @var{trans}. If the
Split is already a part of another Transaction, it will be removed from
that Transaction first.
@end deftypefun

@deftypefun void xaccTransDestroy (Transaction * {trans})
Remove all of the Splits from each of their accounts and free the memory
associated with them. This routine must be followed by either an
@code{xaccTransCommitEdit()} in which case the transaction memory will
be freed, or by @code{xaccTransRollbackEdit()}, in which case all the
original Splits are put back into place.
@end deftypefun

@deftypefun void xaccTransBeginEdit (Transaction * @var{trans})
This method must be called before any changes are made to @var{trans} or
any of its component Splits. If this is not done, errors will result.
@end deftypefun

@deftypefun void xaccTransCommitEdit (Transaction * @var{trans})
This method indicates that the changes to @var{trans} and its Splits are
complete and should be made permanent. Note this routine may result in
the deletion of the transaction, if the Transaction is "empty" (has no
Splits) or if @code{xaccTransDestroy()} was called on the Transaction.
@end deftypefun

@deftypefun void xaccTransRollbackEdit (Transaction * @var{trans})
Rejects all changes made to @var{trans} and its Splits, and sets
@var{trans} back to where it was before the @code{xaccTransBeginEdit()}
call. This includes restoring any deleted Splits, removing any added
Splits, and undoing the effects of @code{xaccTransDestroy()}, as well
as restoring share quantities, memos, descriptions, etc.
@end deftypefun

@deftypefun gboolean xaccTransIsOpen (Transaction * @var{trans})
Return @code{TRUE} if @var{trans} is open for editing. Otherwise, it
returns @code{FALSE}.
@end deftypefun

@deftypefun {const GUID *} xaccTransGetGUID (Transaction * @var{trans})
Return the GUID of @var{trans}.
@end deftypefun 

@deftypefun {Transaction *} xaccTransLookup (const GUID * @var{guid})
Return the Transaction associated with @var{GUID}, or @code{NULL} if
there is no such Transaction.
@end deftypefun

@deftypefun {kvp_value *} xaccTransGetSlot(Transaction * @var{trans}, const char * @var{key})
Return the @code{kvp_value} associated with @var{key} in @var{trans}.
If there is none, @code{NULL} is returned.
@end deftypefun

@deftypefun void xaccTransSetSlot(Split * @var{trans}, const char * @var{key}, const kvp_value * @var{value})
Associate a copy of @var{value} with @var{key} in @var{trans}.
@end deftypefun


@node Transaction Getters, Transaction Setters, General Transaction API, Transactions
@subsection Transaction Getters

@deftypefun {Split *} xaccTransGetSplit (Transaction * @var{trans}, int @var{i})
Return the @var{I}th Split of @var{trans}.
@end deftypefun

@deftypefun {const char *} xaccTransGetNum (Transaction * @var{trans})
Return the number field of @var{trans}.
@end deftypefun

@deftypefun {const char *} xaccTransGetDescription (Transaction * @var{trans})
Return the description field of @var{trans}.
@end deftypefun

@deftypefun time_t xaccTransGetDate (Transaction * @var{trans})
Return the post date of @var{trans} as a @code{time_t} value.
@end deftypefun

@deftypefun {long long} xaccTransGetDateL (Transaction * @var{trans})
Return the post date of @var{trans} as a @code{long long} value.
@end deftypefun

@deftypefun void xaccTransGetDateTS (Transaction * @var{trans}, Timespec * @var{ts})
Return the post date of @var{trans} in @var{ts}.
@end deftypefun

@deftypefun void xaccTransGetDateEnteredTS (Transaction * @var{trans}, Timespec * @var{ts})
Return the entry date of @var{trans} in @var{ts}.
@end deftypefun

@deftypefun {char *} xaccTransGetDateStr (Transaction * @var{trans})
Return a string representing the post date of @var{trans}, or NULL if
@var{trans} is NULL. The string must be freed with @code{free()} after
use.
@end deftypefun

@deftypefun int xaccTransCountSplits (Transaction * @var{trans})
Return the number of Splits in @var{trans}.
@end deftypefun


@node Transaction Setters,  , Transaction Getters, Transactions
@subsection Transaction Setters

Remember, before you modify a Transaction, you must open it for editing
with @code{xaccTransBeginEdit}.

@deftypefun void xaccTransSetDate (Transaction * @var{trans}, int @var{day}, int @var{mon}, int @var{year})
Set the post date of @var{trans} with @var{day}, @var{month}, and @var{year}.
@end deftypefun

@deftypefun void xaccTransSetDateSecs (Transaction * @var{trans}, time_t @var{time})
Set the post date of @var{trans} using a @code{time_t} value.
@end deftypefun

@deftypefun void xaccTransSetDateToday (Transaction * @var{trans})
Set the post date of @var{trans} to the current time.
@end deftypefun

@deftypefun void xaccTransSetDateTS (Transaction * @var{trans}, const Timespec * @var{ts})
Set the post date of @var{trans} from @var{ts}.
@end deftypefun

@deftypefun void xaccTransSetDateEnteredSecs (Transaction *trans, time_t time)
Set the entry date of @var{trans} from a @code{time_t} value.
@end deftypefun

@deftypefun void xaccTransSetDateEnteredTS (Transaction * @var{trans}, const Timespec * @var{ts})
Set the entry date of @var{trans} from @var{ts}.
@end deftypefun

@deftypefun void xaccTransSetNum (Transaction * @var{trans}, const char * @var{num})
Set the number field of @var{trans} to @var{num}.
@end deftypefun

@deftypefun void xaccTransSetDescription (Transaction * @var{trans}, const char * @var{desc})
Set the description field of @var{trans} to @var{desc}.
@end deftypefun


@node Accounts, Account Groups, Transactions, Engine
@section Accounts
@tindex Account


@node Account Groups, GNCBooks, Accounts, Engine
@section Account Groups
@tindex AccountGroup


@node GNCBooks, Scrub, Account Groups, Engine
@section GNCBooks
@tindex GNCBook

The @dfn{GNCBook} interface encapsulate all the information about a
gnucash dataset, including the methods used to read and write the
dataset to datastores.  This class provides several important services:

@itemize

@item
Prevents multiple users from editing the same file at the same time,
thus avoiding lost data due to race conditions. Thus an 'open book'
implies that the associated file is locked.

@item
Provides a search path for the file to be edited. This should simplify
install & maintenance problems for users who may not have a good grasp
of what a file system is, or where they want to keep their data files.

@end itemize

The current implementation assumes the use of files and file locks;
however, the API was designed to be general enough to allow the use
of generic URL's, and/or implementation on top of SQL or other
database/persistant object technology.

@menu
* GNCBook API::                 
@end menu


@node GNCBook API,  , GNCBooks, GNCBooks
@subsection GNCBook API

@deftypefun {GNCBook *} gnc_book_new (void)
Allocate, initialize, and return a new GNCBook. The new book will contain
a newly allocated AccountGroup.
@end deftypefun

@deftypefun void gnc_book_destroy (GNCBook * @var{book})
End any editing session associated with @var{book}, and free all
memory associated with it.
@end deftypefun

@deftypefun gboolean gnc_book_begin (GNCBook * @var{book}, const char * @var{book_id})
Begins a new book editing sesssion. It takes as an argument the book id.
The book id must be a string in the form of a URI/URL.  In the current
implementation, only one type of URI is supported, and that is the file
URI: anything of the form @url{file:/home/somewhere/somedir/file.xac}
The path part must be a valid path.  The file-part must be a valid
gnucash data file. Paths may be relative or absolute. If the path is
relative; that is, if the argument is @url{file:somefile.xac} then a
sequence of search paths are checked for a file of this name.

If the file exists, can be opened and read, and a lock can be obtained
then a lock will be obtained and the function returns TRUE. Otherwise
the function returns FALSE.
@end deftypefun

@deftypefun gboolean (*GNCBookLockFailHandler) (const char * @var{file})
A function prototype for lock fail handlers used below.
@end deftypefun

@deftypefun gboolean gnc_book_begin_file (GNCBook * @var{book}, const char * @var{filename}, GNCBookLockFailHandler @var{handler})
This routine is identical to the gnc_book_begin() routine, except that
the argument is a filename (i.e. the five letters @code{file:} should
not be prepended) and there is an additional function argument. This
function is called if gnc_book_begin_file fails to obtain a lock for the
file. If it returns TRUE, the file is loaded anyway. If it returns
FALSE, or the handler is NULL, a failed lock attempt will abort the
load. The lock fail handler is passed the filename of the data file
being loaded.
@end deftypefun

@deftypefun gboolean gnc_book_load (GNCBook * @var{book})
Load the data associated with the book. The function returns TRUE on
success.
@end deftypefun

@deftypefun int gnc_book_get_error (GNCBook * @var{book})
Obtain the reason for a failure. Standard errno values are used. Calling
this routine resets the error value. This routine allows an
implementation of multiple error values, e.g. in a stack, where this
routine pops the top value. The current implementation has a stack that
is one-deep.

Some important error values:

@table @code

@item EINVAL
bad argument

@item ETXTBSY
book id is in use; it's locked by someone else

@item ENOSYS
unsupported URI type

@item ERANGE
file path too long

@item ENOLCK
book not open when @code{gnc_book_save()} was called.

@end table
@end deftypefun

@deftypefun {AccountGroup *} gnc_book_get_group (GNCBook * @var{book})
Return the current top-level account group.
@end deftypefun

@deftypefun void gnc_book_set_group (GNCBook * @var{book}, AccountGroup * @var{topgroup})
Set the topgroup to a new value.
@end deftypefun

@deftypefun {const char *} gnc_book_get_file_path (GNCBook * @var{book})
Return the fully-qualified file path for the book. That is, if a
relative or partial filename was for the book, then it had to have been
fully resolved to open the book. This routine returns the result of this
resolution.
@end deftypefun

@deftypefun gboolean gnc_book_save_may_clobber_data (GNCBook * @var{book})
Return TRUE if saving the book would overwrite other information.
@end deftypefun

@deftypefun void gnc_book_save (GNCBook * @var{book})
Commit all changes that have been made to the book.
@end deftypefun

@deftypefun void gnc_book_end (GNCBook * @var{book})
Release the session lock. It will @emph{not} save the account group to
a file. Thus, this method acts as an "abort" or "rollback" primitive.
@end deftypefun


@node Scrub,  , GNCBooks, Engine
@section Scrub