Binbufs

You won’t need to know about the internal structure of a Binbuf, so you can use the void * type to refer to one. More...

Collaboration diagram for Binbufs:

Functions
void *	binbuf_new (void)
	Use binbuf_new() to create and initialize a Binbuf. More...
void	binbuf_vinsert (void *x, char *fmt,...)
	Use binbuf_vinsert() to append a Max message to a Binbuf adding a semicolon. More...
void	binbuf_insert (void *x, t_symbol *s, short argc, t_atom *argv)
	Use binbuf_insert() to append a Max message to a Binbuf adding a semicolon. More...
void *	binbuf_eval (void *x, short ac, t_atom *av, void *to)
	Use binbuf_eval to evaluate a Max message in a Binbuf, passing it arguments. More...
short	binbuf_getatom (void *x, long *p1, long *p2, t_atom *ap)
	Use binbuf_getatom to retrieve a single t_atom from a Binbuf. More...
short	binbuf_text (void *x, char **srcText, long n)
	Use binbuf_text() to convert a text handle to a Binbuf. More...
short	binbuf_totext (void *x, char **dstText, t_ptr_size *sizep)
	Use binbuf_totext() to convert a Binbuf into a text handle. More...
void	binbuf_set (void *x, t_symbol *s, short argc, t_atom *argv)
	Use binbuf_set() to change the entire contents of a Binbuf. More...
void	binbuf_append (void *x, t_symbol *s, short argc, t_atom *argv)
	Use binbuf_append to append t_atoms to a Binbuf without modifying them. More...
short	readatom (char *outstr, char **text, long *n, long e, t_atom *ap)
	Use readatom() to read a single t_atom from a text buffer. More...

Detailed Description

You won’t need to know about the internal structure of a Binbuf, so you can use the void * type to refer to one.

Function Documentation

void binbuf_append	(	void *	x,
		t_symbol *	s,
		short	argc,
		t_atom *	argv
	)

Use binbuf_append to append t_atoms to a Binbuf without modifying them.

Parameters

x	Binbuf to receive the items.
s	Ignored. Pass NULL.
argc	Count of items in the argv array.
argv	Array of atoms to add to the Binbuf.

void* binbuf_eval	(	void *	x,
		short	ac,
		t_atom *	av,
		void *	to
	)

Use binbuf_eval to evaluate a Max message in a Binbuf, passing it arguments.

binbuf_eval() is an advanced function that evaluates the message in a Binbuf with arguments in argv, and sends it to receiver.

Parameters

x	Binbuf containing the message.
ac	Count of items in the argv array.
av	Array of t_atoms as the arguments to the message.
to	Receiver of the message.

Returns

The result of sending the message.

short binbuf_getatom	(	void *	x,
		long *	p1,
		long *	p2,
		t_atom *	ap
	)

Use binbuf_getatom to retrieve a single t_atom from a Binbuf.

Parameters

x	Binbuf containing the desired t_atom.
p1	Offset into the Binbuf's array of types. Modified to point to the next t_atom.
p2	Offset into the Binbuf's array of data. Modified to point to the next t_atom.
ap	Location of a t_atom where the retrieved data will be placed.

Returns

1 if there were no t_atoms at the specified offsets, 0 if there's a legitimate t_atom returned in result.

Remarks

To get the first t_atom, set both typeOffset and stuffOffset to 0. Here's an example of getting all the items in a Binbuf:

t_atom holder; 
long to, so; 

to = 0; 
so = 0; 
while (!binbuf_getatom(x, &to, &so, &holder)){
   // do something with the t_atom
}

void binbuf_insert	(	void *	x,
		t_symbol *	s,
		short	argc,
		t_atom *	argv
	)

Use binbuf_insert() to append a Max message to a Binbuf adding a semicolon.

Parameters

x	Binbuf to receive the items.
s	Ignored. Pass NULL.
argc	Count of items in the argv array.
argv	Array of t_atoms to add to the Binbuf.

Remarks

You'll use binbuf_insert() instead of binbuf_append() if you were saving your object into a Binbuf and wanted a semicolon at the end. If the message is part of a file that will later be evaluated, such as a Patcher file, the first argument argv[0] will be the receiver of the message and must be a Symbol. binbuf_vinsert() is easier to use than binbuf_insert(), since you don't have to format your data into an array of Atoms first.

binbuf_insert() will also convert the t_symbols #1 through #9 into $1 through $9. This is used for saving patcher files that take arguments; you will probably never save these symbols as part of anything you are doing.

void* binbuf_new

(

void

)

Use binbuf_new() to create and initialize a Binbuf.

Returns

Returns a new binbuf if successful, otherwise NULL.

void binbuf_set	(	void *	x,
		t_symbol *	s,
		short	argc,
		t_atom *	argv
	)

Use binbuf_set() to change the entire contents of a Binbuf.

The previous contents of the Binbuf are destroyed.

Parameters

x	Binbuf to receive the items.
s	Ignored. Pass NULL.
argc	Count of items in the argv array.
argv	Array of t_atoms to put in the Binbuf.

short binbuf_text	(	void *	x,
		char **	srcText,
		long	n
	)

Use binbuf_text() to convert a text handle to a Binbuf.

binbuf_text() parses the text in the handle srcText and converts it into binary format. Use it to evaluate a text file or text line entry into a Binbuf.

Parameters

x	Binbuf to contain the converted text. It must have already been created with binbuf_new. Its previous contents are destroyed.
srcText	Handle to the text to be converted. It need not be terminated with a 0.
n	Number of characters in the text.

Returns

If binbuf_text encounters an error during its operation, a non-zero result is returned, otherwise it returns 0.

Remarks

Note: Commas, symbols containing a dollar sign followed by a number 1-9, and semicolons are identified by special pseudo-type constants for you when your text is binbuf-ized.

The following constants in the a_type field of Atoms returned by binbuf_getAtom identify the special symbols A_SEMI, A_COMMA, and A_DOLLAR.

For a t_atom of the pseudo-type A_DOLLAR, the a_w.w_long field of the t_atom contains the number after the dollar sign in the original text or symbol.

Using these pseudo-types may be helpful in separating 'sentences' and 'phrases' in the input language you design. For example, the old pop-up umenu object allowed users to have spaces in between words by requiring the menu items be separated by commas. It's reasonably easy, using binbuf_getatom(), to find the commas in a Binbuf in order to determine the beginning of a new item when reading the atomized text to be displayed in the menu.

If you want to use a literal comma or semicolon in a symbol, precede it with a backslash (\) character. The backslash character can be included by using two backslashes in a row.

short binbuf_totext	(	void *	x,
		char **	dstText,
		t_ptr_size *	sizep
	)

Use binbuf_totext() to convert a Binbuf into a text handle.

binbuf_totext() converts a Binbuf into text and places it in a handle. Backslashes are added to protect literal commas and semicolons contained in symbols. The pseudo-types are converted into commas, semicolons, or dollar-sign and number, without backslashes preceding them. binbuf_text can read the output of binbuf_totext and make the same Binbuf.

Parameters

x	Binbuf with data to convert to text.
dstText	Pre-existing handle where the text will be placed. dstText will be resized to accomodate the text.
sizep	Where binbuf_totext() returns the number of characters in the converted text handle.

Returns

If binbuf_totext runs out of memory during its operation, it returns a non-zero result, otherwise it returns 0.

void binbuf_vinsert	(	void *	x,
		char *	fmt,
			...
	)

Use binbuf_vinsert() to append a Max message to a Binbuf adding a semicolon.

Parameters

x	Binbuf containing the desired t_atom.
fmt	A C-string containing one or more letters corresponding to the types of each element of the message. s for t_symbol*, l for long, or f for float.
...	Elements of the message, passed directly to the function as Symbols, longs, or floats.

Remarks

binbuf_vinsert() works somewhat like a printf() for Binbufs. It allows you to pass a number of arguments of different types and insert them into a Binbuf. The entire message will then be terminated with a semicolon. Only 16 items can be passed to binbuf_vinsert().

The example below shows the implementation of a normal object's save method. The save method requires that you build a message that begins with #N (the new object) , followed by the name of your object (in this case, represented by the t_symbol myobject), followed by any arguments your instance creation function requires. In this example, we save the values of two fields m_val1 and m_val2 defined as longs.

void myobject_save (myObject *x, Binbuf *dstBuf) 
{ 
   binbuf_vinsert(dstBuf, "ssll", gensym("#N"), 
       gensym("myobject"), 
       x->m_val1, x->m_val2); 
}

Suppose that such an object had written this data into a file. If you opened the file as text, you would see the following:

#N myobject 10 20; 
#P newobj 218 82 30 myobject; 

The first line will result in a new myobject object to be created; the creation function receives the arguments 10 and 20. The second line contains the text of the object box. The newobj message to a patcher creates the object box user interface object and attaches it to the previously created myobject object. Normally, the newex message is used. This causes the object to be created using the arguments that were typed into the object box.

short readatom	(	char *	outstr,
		char **	text,
		long *	n,
		long	e,
		t_atom *	ap
	)

Use readatom() to read a single t_atom from a text buffer.

Parameters

outstr	C-string of 256 characters that will receive the next text item read from the buffer.
text	Handle to the text buffer to be read.
n	Starts at 0, and is modified by readatom to point to the next item in the text buffer.
e	Number of characters in text.
ap	Where the resulting t_atom read from the text buffer is placed.

Returns

readatom() returns non-zero if there is more text to read, and zero if it has reached the end of the text. Note that this return value has the opposite logic from that of binbuf_getatom().

Remarks

This function provides access to the low-level Max text evaluator used by binbuf_text(). It is designed to operate on a handle of characters (text) and called in a loop, as in the example shown below.

long index = 0; 
t_atom dst; 
char outstr[256]; 

while (readatom(outstr,textHandle,&index,textLength,&dst)) 
{ 
   // do something with the resulting t_atom
} 

An alternative to using readatom is to turn your text into a Binbuf using binbuf_text(), then call binbuf_getatom() in a loop.