DN can either be a string or an array as returned by explodeDN(),
which is useful when constructing a DN. The DN array may have be
indexed (each array value is a OCL=VALUE pair) or associative (array key
is OCL and value is VALUE).
It performs the following operations on the given DN:
- Removes the leading 'OID.' characters if the type is an OID instead of
a name.
- Escapes all RFC 2253 special characters (",", "+", """, "\", "<", ">",
";", "#", "="), slashes ("/"), and any other character where the ASCII
code is < 32 as \hexpair.
- Converts all leading and trailing spaces in values to be \20.
- If an RDN contains multiple parts, the parts are re-ordered so that
the attribute type names are in alphabetical order.
$options is a list of name/value pairs, valid options are:
- casefold: Controls case folding of attribute type names. Attribute
values are not affected by this option. The default is to
uppercase. Valid values are:
- lower: Lowercase attribute type names.
- upper: Uppercase attribute type names.
- none: Do not change attribute type names.
- reverse: If true, the RDN sequence is reversed.
- separator: Separator to use between RDNs. Defaults to comma (',').
The empty string "" is a valid DN, so be sure not to do a "$can_dn ==
false" test, because an empty string evaluates to false. Use the "==="
operator instead.