Contents

DH_Format

 Next
 

Function:

Outputs a text string that can include one or more dynamically varying numeric values.

Inputs:

Format    A text string that may contain place holders where the values of numeric  variables will be substituted into the string.

  • The place holders also control the formatting of the numeric values, and are called format specifications.  (See Notes below.)

  • Characters in the Format string other than format specifications are copied to Text Out without change.

Var   A numeric value to be inserted into the string at the position marked by a format specification.

  • This pin autoduplicates.

  • Up to 10 variables can be used.

Outputs:

Text Out   The output text string, with the current numeric value(s) from the Var input(s) substituted for the format specifications.

  
 
Notes:

The Var inputs take regular SE voltage type inputs. The Format and Text Out pins are the newer "blue" types, so that the module can easily be integrated with other sub-controls. The file DH_Controls_demo.se1 shows an example of this module being used in conjunction with other SynthEdit and DH Sub Controls.

Format Specifications:

A format specification starts with a % and ends with a letter f.

Before getting into the details, here are 3 examples, showing the inputs and outputs on each pin. The format specifications are in light blue.

 

Inputs

Output
  Format pin Var pin(s) Text Out pin
1 %.0f 126.999 127
2 Cutoff = %.1f Hz 2.551 Cutoff = 2.6 Hz
3 %.2f/%.2f 98.34
100.0		 98.34/100.00

Notice that:

  • Each format specification starts with a % and ends with a letter f.

  • The format specifications get replaced by the Var values.

  • The number of format specifications equals the number of Var pins.

  • Any characters that aren't part of a format specification are simply copied from the Format pin to Text Out.

  • The number of decimal places is specified by the number that follows the decimal point in the format specification.

  • Format specifications are assigned to Var pins left to right, top down.

Additional, working examples can be found in the DH_Controls_demo.se1 file.


The general form of a format specification is:

% always 1st character
- minus sign left justifies number (optional )
0 zero causes padding with 0s rather than
spaces to meet min width (optional )
min width number to specify the minimum width (optional )
. decimal point to separate min width from precision (required if precision used)
precision number of decimal places to display (optional)
conversion character normally f for our purposes, but see Q3 below
 

Here are a couple of more advanced examples to illustrate:

 

Inputs

Output
  Format pin Var pin(s) Text Out pin
4 %-6.0f 123 123
5 %07.3f 0.9995 001.000

Explanation:
4) min width of 6, left justified, rounded to nearest whole number
5) min width of 7, zero padded, rounded to 3 decimal places


A few more tricks:

Q1. What if you actually want to display a % sign?

A. Just use 2 of them: %%

For example:

 

Inputs

Output
  Format pin Var pin(s) Text Out pin
6 Volume: %.1f%% 78.456 78.5%


Q2. Suppose I have a list of format strings in a DH_TextArray, and not all require the same number of variables. How can this be handled?

A. If there are fewer format specifications than Var pins, the format specs are assigned to the Var pins in the normal left to right, top down manner, and the
remaining pins are ignored.

Q3. What if I need to skip a pin in the above scenario? Suppose I have a format string with 2 format specs, but they need the values from the 1st and 3rd Var pins?

A. You can "hide" a Var pin by using a format spec with a special conversion character of 'h' in the place where that variable would normally be assigned. In example 7, %h is used to hide the 2nd pin.

 

Inputs

Output
  Format pin Var pin(s) Text Out pin
7 LFO%.0f%h - Osc%.0f 2
5.33
3		 LFO2 - Osc3


Q. What if I have more format specs than Var pins?

A. You will get an error message at the Text Out pin.


The format specification conventions used here are adopted from the C programming language. Additional details about these format specifications and conversion characters can be found in any reference on C/C++ programming under the topic formatted printing, or the printf function. Because the SE inputs to the Var pins are float type variables, only those conversion characters suitable for floats will produce meaningful results in a DH_Format Format string. (Note that the h conversion character is specific to the DH_Format module, and is not a part of the C or C++ language or libraries.)
 

Top

 Next