.TH erl_format 3erl "erl_interface 3.9.2" "Ericsson AB" "C Library Functions"
.SH NAME
erl_format \- Create and match Erlang terms.
.SH DESCRIPTION
.LP
This module contains two routines: one general function for creating Erlang terms and one for pattern matching Erlang terms\&.
.SH EXPORTS
.LP
.B
ETERM *erl_format(FormatStr, ...)
.br
.RS
.LP
Types:

.RS 3
char *FormatStr;
.br
.RE
.RE
.RS
.LP
A general function for creating Erlang terms using a format specifier and a corresponding set of arguments, much in the way \fIprintf()\fR\& works\&.
.LP
\fIFormatStr\fR\& is a format specification string\&. The valid format specifiers are as follows:
.RS 2
.TP 2
*
\fI~i\fR\& - Integer
.LP
.TP 2
*
\fI~f\fR\& - Floating point
.LP
.TP 2
*
\fI~a\fR\& - Atom
.LP
.TP 2
*
\fI~s\fR\& - String
.LP
.TP 2
*
\fI~w\fR\& - Arbitrary Erlang term
.LP
.RE

.LP
For each format specifier included in \fIFormatStr\fR\&, there must be a corresponding argument following \fIFormatStr\fR\&\&. An Erlang term is built according to \fIFormatStr\fR\& with values and Erlang terms substituted from the corresponding arguments, and according to the individual format specifiers\&. For example:
.LP
.nf

erl_format("[{name,~a},{age,~i},{data,~w}]",
           "madonna",
           21,
           erl_format("[{adr,~s,~i}]","E-street",42));
        
.fi
.LP
This creates an \fI(ETERM *)\fR\& structure corresponding to the Erlang term \fI[{name,madonna},{age,21},{data,[{adr,"E-street",42}]}]\fR\&
.LP
The function returns an Erlang term, or \fINULL\fR\& if \fIFormatStr\fR\& does not describe a valid Erlang term\&.
.RE

.LP
.B
int erl_match(Pattern, Term)
.br
.RS
.LP
Types:

.RS 3
ETERM *Pattern,*Term;
.br
.RE
.RE
.RS
.LP
This function is used to perform pattern matching similar to that done in Erlang\&. For matching rules and more examples, see section \fB Pattern Matching\fR\& in the Erlang Reference Manual\&.
.RS 2
.TP 2
*
\fIPattern\fR\& is an Erlang term, possibly containing unbound variables\&.
.LP
.TP 2
*
\fITerm\fR\& is an Erlang term that we wish to match against \fIPattern\fR\&\&.
.LP
.RE

.LP
\fITerm\fR\& and \fIPattern\fR\& are compared and any unbound variables in \fIPattern\fR\& are bound to corresponding values in \fITerm\fR\&\&.
.LP
If \fITerm\fR\& and \fIPattern\fR\& can be matched, the function returns a non-zero value and binds any unbound variables in \fIPattern\fR\&\&. If \fITerm\fR\& and \fIPattern\fR\& do not match, \fI0\fR\& is returned\&. For example:
.LP
.nf

ETERM *term, *pattern, *pattern2;
term1    = erl_format("{14,21}");
term2    = erl_format("{19,19}");
pattern1 = erl_format("{A,B}");
pattern2 = erl_format("{F,F}");
if (erl_match(pattern1, term1)) {
  /* match succeeds:
   * A gets bound to 14, 
   * B gets bound to 21 
   */
  ...  
}
if (erl_match(pattern2, term1)) {
  /* match fails because F cannot be 
   * bound to two separate values, 14 and 21
   */
  ...
}
if (erl_match(pattern2, term2)) {
  /* match succeeds and F gets bound to 19 */
  ...
}
        
.fi
.LP
\fIerl_var_content()\fR\& can be used to retrieve the content of any variables bound as a result of a call to \fIerl_match()\fR\&\&.
.RE