Bridge Calculator API header file. More...

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

Detailed Description

Bridge Calculator API header file.

Macro Definition Documentation

#define bcalc_declarerToLeader ( declarer ) bcalc_nextHand(declarer, 3)

Calculate leader hand using declarer hand.

Parameters

declarer

Returns: player on lead in deal where declarer is declarer

#define bcalc_nextHand	(	hand,
		delta
	)	(((hand)+(delta))&3)

Calculate hand relative to given one.

Parameters

hand	one of BCALC_PLAYER_*
delta	clock-wise delta, +1 to next player (in clock-wise)

Returns: calculated hand, one of BCALC_PLAYER_* value

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

Parameters

player player number, one of BCALC_PLAYER_*

Returns: player symbol, one of 'N', 'E', 'S', 'W'

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

Parameters

suit	suit, one of BCALC_SUIT_*

Returns: suit symbol, one of 'C', 'D', 'H', 'S', 'N' (for NT)

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

See Also: bcalc_runtimeVersion

Typedef Documentation

typedef struct BCalcDDS BCalcDDS

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.

Function Documentation

unsigned bcalc_runtimeVersion ( )

Get the version of the API used by the runtime library.

Returns: the version of the API used by the (typically: dynamic) runtime library

See Also: BCALC_VERSION

void bcalcDDS_clearError ( BCalcDDS * solver )

Clear error message.

After call, bcalcDDS_getLastError(solver) will return NULL.

Parameters

solver bcalc double dummy solver

BCalcDDS* bcalcDDS_clone ( BCalcDDS * to_clone )

Clone the state of the solver to_clone.

Parameters

to_clone solver to clone

Returns: copy of 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.

Parameters

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

Parameters

solver	bcalc double dummy solver
cmds	commands to execute

Commands should be separated by spaces and each can be one of:

<C><S> - where <C> is card symbol (like: A, Q, T, 6), <S> is suit symbol (one of: C, D, H, S), play choosen card
x - play smallest possible card following played suit
u - unplay one card
ut - unplay last trick
ua - unplay all tricks

char* bcalcDDS_getCards	(	BCalcDDS *	solver,
		char *	result,
		int	player,
		int	suit
	)

Get cards owned by given player in given suit.

Parameters

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)

Returns: result, zero-ended 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.

Parameters

solver bcalc double dummy solver

Returns: how many cards left to play to deal end, integer from 0 to 52

char* bcalcDDS_getCardsToPlay	(	BCalcDDS *	solver,
		char *	result,
		int	suit
	)

Get cards possible to play in given suit by player who should play.

Parameters

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')

Returns: result, zero-ended 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.

Parameters

solver bcalc double dummy solver

Returns: last error message or NULL if no error, pointer to internal solver buffer (valid up to next bcalcDDS_* call for solver passed as argument)

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

Parameters

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)

Returns

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.

Parameters

solver bcalc double dummy solver

Returns: number of cards which have been already played

int bcalcDDS_getPlayerToPlay ( BCalcDDS * solver )

Get player which should play now.

Parameters

solver bcalc double dummy solver

Returns: player which should play now in game connected with given solver

int* bcalcDDS_getTricksTaken	(	BCalcDDS *	solver,
		int *	result
	)

Get numbers of tricks which have been already taken by players in game connected with solver.

Parameters

solver	bcalc double dummy solver
result	buffer, array of minimum length of 4, place to store calculated numbers of tricks

Returns: 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)).

Parameters

solver bcalc double dummy solver

Returns: number of tricks possible to take (in future) by line which plays in current situation

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.

Parameters

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)

Returns

If tricks_target == -1, it returns number of tricks possible to take (in future) by line which plays in current situation.
If tricks_target >= 0, it returns 1 only if line which plays in current situation can take tricks_target tricks in future.
In case of error (possible when card has wrong format) it returns -1.

int bcalcDDS_getTrump ( BCalcDDS * solver )

Get strain.

Parameters

solver bcalc double dummy solver

Returns: strain of game connected with 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.

Parameters

format	Format of `hands`, for example "NESW", "ESWN", ..., "PBN", "LIN": "PBN" is Portable Bridge Notation like format, "lin" is BBO .lin like format, rest show order of hands.
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')

Returns: Constructed solver or NULL in case of out of memory. Returned solver can have error set in case of deal parser error, invalidate strain or leader (see bcalcDDS_getLastError) and in such case you should not use that solver. In all cases constructed solver should be freed, after use, by bcalcDDS_delete.

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 leader-strains 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.

Parameters

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

Parameters

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')

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation