Bridge Calculator C API
C API for Bridge Calculator double dummy solver by Piotr Beling

Bridge Calculator API header file. More...
Go to the source code of this file.
Macros  
#define  BCALC_VERSION 14020 
Version of bcalc engine API. More...  
#define  BCALC_PLAYER_NORTH 0 
North player. More...  
#define  BCALC_PLAYER_EAST 1 
East player. More...  
#define  BCALC_PLAYER_SOUTH 2 
South player. More...  
#define  BCALC_PLAYER_WEST 3 
West player. More...  
#define  bcalc_playerSymbol(player) ("NESW"[player]) 
Convert player number to player symbol. More...  
#define  bcalc_nextHand(hand, delta) (((hand)+(delta))&3) 
Calculate hand relative to given one. More...  
#define  bcalc_declarerToLeader(declarer) bcalc_nextHand(declarer, 3) 
Calculate leader hand using declarer hand. More...  
#define  BCALC_SUIT_CLUBS 0 
Club suit number. More...  
#define  BCALC_SUIT_DIAMONDS 1 
Diamond suit number. More...  
#define  BCALC_SUIT_HEARTS 2 
Hearts suit number. More...  
#define  BCALC_SUIT_SPADES 3 
Spades suit number. More...  
#define  BCALC_NT 4 
No trump. More...  
#define  bcalc_suitSymbol(suit) ("CDHSN"[suit]) 
Convert suit number to its ASCII symbol. More...  
Typedefs  
typedef struct BCalcDDS  BCalcDDS 
Handler to bcalc double dummy solver. More...  
Functions  
unsigned  bcalc_runtimeVersion () 
Get the version of the API used by the runtime library. More...  
BCalcDDS *  bcalcDDS_new (const char *format, const char *hands, int strain, int leader) 
Construct new solver. More...  
BCalcDDS *  bcalcDDS_clone (BCalcDDS *to_clone) 
Clone the state of the solver to_clone . More...  
void  bcalcDDS_delete (BCalcDDS *solver) 
Delete double dummy solver, free its memory. More...  
const char *  bcalcDDS_getLastError (const BCalcDDS *solver) 
Get last error string. More...  
void  bcalcDDS_clearError (BCalcDDS *solver) 
Clear error message. More...  
void  bcalcDDS_exec (BCalcDDS *solver, const char *cmds) 
Execute commands which can modify the state of given solver (current situation in game represented by it). More...  
int  bcalcDDS_getTricksToTake (BCalcDDS *solver) 
Calculate number of tricks possible to take (same as bcalcDDS_getTricksToTakeEx(solver, 1, 0)). More...  
int  bcalcDDS_getTricksToTakeEx (BCalcDDS *solver, int tricks_target, const char *card) 
If tricks_target == 1, calculate number of tricks possible to take. More...  
int  bcalcDDS_getTrump (BCalcDDS *solver) 
Get strain. More...  
void  bcalcDDS_setTrumpAndReset (BCalcDDS *solver, int new_trump) 
Set new strain and reset deal to initial state (undo all tricks). More...  
void  bcalcDDS_setPlayerOnLeadAndReset (BCalcDDS *solver, int new_leader) 
Reset deal to initial state (undo all tricks) and change player on lead. More...  
int *  bcalcDDS_getTricksTaken (BCalcDDS *solver, int *result) 
Get numbers of tricks which have been already taken by players in game connected with solver . More...  
int  bcalcDDS_getCardsLeftCount (BCalcDDS *solver) 
Get number of cards which left to play in game connected with solver . More...  
char *  bcalcDDS_getCards (BCalcDDS *solver, char *result, int player, int suit) 
Get cards owned by given player in given suit . More...  
int  bcalcDDS_getPlayerToPlay (BCalcDDS *solver) 
Get player which should play now. More...  
char *  bcalcDDS_getCardsToPlay (BCalcDDS *solver, char *result, int suit) 
Get cards possible to play in given suit by player who should play. More...  
int  bcalcDDS_getPlayedCard (BCalcDDS *solver, unsigned whenIndex, int *suit, char *cardSymbol) 
Get card played as a whenIndex (when card played on first lead has index 0). More...  
int  bcalcDDS_getPlayedCardsCount (BCalcDDS *solver) 
Get number of cards which have been already played. More...  
Bridge Calculator API header file.
#define bcalc_declarerToLeader  (  declarer  )  bcalc_nextHand(declarer, 3) 
Calculate leader hand using declarer
hand.
declarer 
declarer
is declarer #define bcalc_nextHand  (  hand,  
delta  
)  (((hand)+(delta))&3) 
Calculate hand relative to given one.
hand  one of BCALC_PLAYER_* 
delta  clockwise delta, +1 to next player (in clockwise) 
#define BCALC_NT 4 
No trump.
#define BCALC_PLAYER_EAST 1 
East player.
#define BCALC_PLAYER_NORTH 0 
North player.
#define BCALC_PLAYER_SOUTH 2 
South player.
#define BCALC_PLAYER_WEST 3 
West player.
#define bcalc_playerSymbol  (  player  )  ("NESW"[player]) 
Convert player number to player symbol.
player  player number, one of BCALC_PLAYER_* 
#define BCALC_SUIT_CLUBS 0 
Club suit number.
#define BCALC_SUIT_DIAMONDS 1 
Diamond suit number.
#define BCALC_SUIT_HEARTS 2 
Hearts suit number.
#define BCALC_SUIT_SPADES 3 
Spades suit number.
#define bcalc_suitSymbol  (  suit  )  ("CDHSN"[suit]) 
Convert suit
number to its ASCII symbol.
suit  suit, one of BCALC_SUIT_* 
#define BCALC_VERSION 14020 
Version of bcalc engine API.
Bridge Calculator program version (unsigned integer in form YYMMN) on which base engine. Note that engine is released less often than program (in some program release engine is not changed).
Handler to bcalc double dummy solver.
Double dummy solver represents game with history of play. It also stores many values which was calculated for it.
Usualy you should only use pointer to this type.
unsigned bcalc_runtimeVersion  (  ) 
Get the version of the API used by the runtime library.
void bcalcDDS_clearError  (  BCalcDDS *  solver  ) 
Clear error message.
After call, bcalcDDS_getLastError(solver) will return NULL.
solver  bcalc double dummy solver 
Clone the state of the solver to_clone
.
to_clone  solver to clone 
to_clone
or NULL (in case of out of memory, or if to_clone
is NULL). Returned copy, as well as to_clone
, must by freed, after use, by bcalcDDS_delete void bcalcDDS_delete  (  BCalcDDS *  solver  ) 
Delete double dummy solver, free its memory.
solver  constructed by bcalcDDS_new, double dummy solver to delete, it is safe to pass NULL pointer (function do nothing in such a case) 
void bcalcDDS_exec  (  BCalcDDS *  solver, 
const char *  cmds  
) 
Execute commands which can modify the state of given solver
(current situation in game represented by it).
solver  bcalc double dummy solver 
cmds  commands to execute 
Commands should be separated by spaces and each can be one of:
char* bcalcDDS_getCards  (  BCalcDDS *  solver, 
char *  result,  
int  player,  
int  suit  
) 
Get cards owned by given player
in given suit
.
solver  bcalc double dummy solver 
player  player, one of BCALC_PLAYER_* or player ASCII symbol (one of: 'n', 'N', 'e', 'E', 's', 'S', 'w', 'W') 
suit  suit, one of BCALC_SUIT_* or suit symbol in ASCII (one of: 'c', 'C', 'd', 'D', 'h', 'H', 's', 'S') 
result  buffer, place for results, safe length is 14 (13 cards and terminated zero) 
result
, zeroended string, suits written using symbols from: AKQJT98765432, in case of error result
in unchanged form int bcalcDDS_getCardsLeftCount  (  BCalcDDS *  solver  ) 
Get number of cards which left to play in game connected with solver
.
solver  bcalc double dummy solver 
char* bcalcDDS_getCardsToPlay  (  BCalcDDS *  solver, 
char *  result,  
int  suit  
) 
Get cards possible to play in given suit
by player who should play.
solver  bcalc double dummy solver 
result  buffer, place for results, safe length is 14 (13 cards and terminated zero) 
suit  suit, one of BCALC_SUIT_* or suit symbol in ASCII (one of: 'c', 'C', 'd', 'D', 'h', 'H', 's', 'S') 
result
, zeroended string, suits written using symbols from: AKQJT98765432, in case of error result
in unchanged form const char* bcalcDDS_getLastError  (  const BCalcDDS *  solver  ) 
Get last error string.
solver  bcalc double dummy solver 
int bcalcDDS_getPlayedCard  (  BCalcDDS *  solver, 
unsigned  whenIndex,  
int *  suit,  
char *  cardSymbol  
) 
Get card played as a whenIndex
(when card played on first lead has index 0).
solver  bcalc double dummy solver 
whenIndex  card index, from 0 to bcalcDDS_getPlayedCardsCount(solver)1 
suit  place to save suit (if not NULL), one of BCALC_SUIT_* 
cardSymbol  place to store card symbol (if not NULL) 
1
only if card with given index was played,0
if index is larger than bcalcDDS_getPlayedCardsCount(solver)1 (error is not set in such situation and suit
and cardSymbol
are not changed). int bcalcDDS_getPlayedCardsCount  (  BCalcDDS *  solver  ) 
Get number of cards which have been already played.
solver  bcalc double dummy solver 
int bcalcDDS_getPlayerToPlay  (  BCalcDDS *  solver  ) 
Get player which should play now.
solver  bcalc double dummy solver 
solver
int* bcalcDDS_getTricksTaken  (  BCalcDDS *  solver, 
int *  result  
) 
Get numbers of tricks which have been already taken by players in game connected with solver
.
solver  bcalc double dummy solver 
result  buffer, array of minimum length of 4, place to store calculated numbers of tricks 
result
array, number of tricks taken by players, use BCALC_PLAYER_* as this array indexes int bcalcDDS_getTricksToTake  (  BCalcDDS *  solver  ) 
Calculate number of tricks possible to take (same as bcalcDDS_getTricksToTakeEx(solver, 1, 0)).
solver  bcalc double dummy solver 
int bcalcDDS_getTricksToTakeEx  (  BCalcDDS *  solver, 
int  tricks_target,  
const char *  card  
) 
If tricks_target
== 1, calculate number of tricks possible to take.
If tricks_target
>= 0 check if tricks_target
number of tricks are possible to take. Optionaly, if card
!= 0: it suppose that player to play starts with playing card
.
solver  bcalc double dummy solver 
tricks_target  (optional, 1 to ignore) target number of tricks to take by player to play 
card  if not 0 must include description of one card, held by player to play, in format: <C><S>  where <C> is card symbol, <S> is suit symbol (can also be 'x' for smallest possible card following played suit) 
tricks_target
== 1, it returns number of tricks possible to take (in future) by line which plays in current situation.tricks_target
>= 0, it returns 1 only if line which plays in current situation can take tricks_target
tricks in future.card
has wrong format) it returns 1. int bcalcDDS_getTrump  (  BCalcDDS *  solver  ) 
Get strain.
solver  bcalc double dummy solver 
solver
BCalcDDS* bcalcDDS_new  (  const char *  format, 
const char *  hands,  
int  strain,  
int  leader  
) 
Construct new solver.
Each solver has own memory and it is thread safety to operate on multiple solvers at the same time, but it is not safety to call more than one bcalcDDS_* function for one solver at the same time.
format  Format of hands , for example "NESW", "ESWN", ..., "PBN", "LIN":

hands  Players hands. Each player must have the same number of cards. To get situation inside trick, you should create trick's beginning situation and call bcalcDDS_exec to play cards included in current trick. 
strain  one of BCALC_SUIT_* or BCALC_NT constant or ASCII symbol of strain (one of: 'c', 'C', 'd', 'D', 'h', 'H', 's', 'S', 'n', 'N') 
leader  player on lead, one of BCALC_PLAYER_* constant or player ASCII symbol (one of: 'n', 'N', 'e', 'E', 's', 'S', 'w', 'W') 
void bcalcDDS_setPlayerOnLeadAndReset  (  BCalcDDS *  solver, 
int  new_leader  
) 
Reset deal to initial state (undo all tricks) and change player on lead.
Note that this doesn't clear transposition table, so calculation results which was colecting with an other player on lead will be still use. So if you need to iterate over all leaderstrains pairs, and calculate number of tricks to take for each, it is much more effective to iterate over strains in outer loop and over leaders in inner loop.
solver  bcalc double dummy solver 
new_leader  player on lead, one of BCALC_PLAYER_* constant or player ASCII symbol (one of: 'n', 'N', 'e', 'E', 's', 'S', 'w', 'W') 
void bcalcDDS_setTrumpAndReset  (  BCalcDDS *  solver, 
int  new_trump  
) 
Set new strain and reset deal to initial state (undo all tricks).
solver  bcalc double dummy solver 
new_trump  new strain to set for game connected with solver , one of BCALC_SUIT_* or BCALC_NT constant or ASCII symbol (one of: 'c', 'C', 'd', 'D', 'h', 'H', 's', 'S', 'n', 'N') 