This page is a snapshot from the LWG issues list, see the Library Active Issues List for more information and the meaning of C++20 status.

2139. What is a user-defined type?

Section: 16.4.5.2.1 [namespace.std], 19.5 [syserr], 20.2.8.1 [allocator.uses.trait], 22.10.15.2 [func.bind.isbind], 22.10.15.3 [func.bind.isplace], 22.10.19 [unord.hash], 21.3.8.7 [meta.trans.other], 28.3.3.1 [locale], 28.3.4.2.5 [locale.codecvt], 28.6.11.1.5 [re.regiter.incr] Status: C++20 Submitter: Loïc Joly Opened: 2012-03-08 Last modified: 2021-02-25

Priority: 4

View other active issues in [namespace.std].

View all other issues in [namespace.std].

View all issues with C++20 status.

Discussion:

The expression "user-defined type" is used in several places in the standard, but I'm not sure what it means. More specifically, is a type defined in the standard library a user-defined type?

From my understanding of English, it is not. From most of the uses of this term in the standard, it seem to be considered as user defined. In some places, I'm hesitant, e.g. 16.4.5.2.1 [namespace.std] p1:

A program may add a template specialization for any standard library template to namespace std only if the declaration depends on a user-defined type and the specialization meets the standard library requirements for the original template and is not explicitly prohibited.

Does it mean we are allowed to add in the namespace std a specialization for std::vector<std::pair<T, U>>, for instance?

Additional remarks from the reflector discussion: The traditional meaning of user-defined types refers to class types and enum types, but the library actually means here user-defined types that are not (purely) library-provided. Presumably a new term - like user-provided type - should be introduced and properly defined.

[ 2012-10 Portland: Move to Deferred ]

The issue is real, in that we never define this term and rely on a "know it when I see it" intuition. However, there is a fear that any attempt to pin down a definition is more likely to introduce bugs than solve them - getting the wording for this precisely correct is likely far more work than we are able to give it.

There is unease at simple closing as NAD, but not real enthusiasm to provide wording either. Move to Deferred as we are not opposed to some motivated individual coming back with full wording to review, but do not want to go out of our way to encourage someone to work on this in preference to other issues.

[2014-02-20 Re-open Deferred issues as Priority 4]

[2015-03-05 Jonathan suggests wording]

I dislike the suggestion to change to "user-provided" type because I already find the difference between user-declared / user-provided confusing for special member functions, so I think it would be better to use a completely different term. The core language uses "user-defined conversion sequence" and "user-defined literal" and similar terms for things which the library provides, so I think we should not refer to "user" at all to distinguish entities defined outside the implementation from things provided by the implementation.

I propose "program-defined type" (and "program-defined specialization"), defined below. The P/R below demonstrates the scope of the changes required, even if this name isn't adopted. I haven't proposed a change for "User-defined facets" in [locale].

[Lenexa 2015-05-06]

RS, HT: The core language uses "user-defined" in a specific way, including library things but excluding core language things, let's use a different term.

MC: Agree.

RS: "which" should be "that", x2

RS: Is std::vector<MyType> a "program-defined type"?

MC: I think it should be.

TK: std::vector<int> seems to take the same path.

JW: std::vector<MyType> isn't program-defined, we don't need it to be, anything that depends on that also depends on =MyType.

TK: The type defined by an "explicit template specialization" should be a program-defined type.

RS: An implicit instantiation of a "program-defined partial specialization" should also be a program-defined type.

JY: This definition formatting is horrible and ugly, can we do better?

RS: Checking ISO directives.

RS: Define "program-defined type" and "program-defined specialization" instead, to get rid of the angle brackets.

JW redrafting.

[2017-09-12]

Jonathan revises wording as per Lenexa discussion

Previous resolution [SUPERSEDED]:

This wording is relative to N4296.

  1. Add a new sub-clause to [definitions]:

    17.3.? [defns.program.defined]

    program-defined

    <type> a class type or enumeration type which is not part of the C++ standard library and not defined by the implementation. [Note: Types defined by the implementation include extensions (4.1 [intro.compliance]) and internal types used by the library. — end note]

    program-defined

    <specialization> an explicit template specialization or partial specialization which is not part of the C++ standard library and not defined by the implementation.

  2. Change 16.4.5.2.1 [namespace.std] paragraph 1+2:

    -1- The behavior of a C++ program is undefined if it adds declarations or definitions to namespace std or to a namespace within namespace std unless otherwise specified. A program may add a template specialization for any standard library template to namespace std only if the declaration depends on a userprogram-defined type and the specialization meets the standard library requirements for the original template and is not explicitly prohibited.

    -2- The behavior of a C++ program is undefined if it declares

    […]

    A program may explicitly instantiate a template defined in the standard library only if the declaration depends on the name of a userprogram-defined type and the instantiation meets the standard library requirements for the original template.

  3. Change 19.5 [syserr] paragraph 4:

    -4- The is_error_code_enum and is_error_condition_enum may be specialized for userprogram-defined types to indicate that such types are eligible for class error_code and class error_condition automatic conversions, respectively.

  4. Change 20.2.8.1 [allocator.uses.trait] paragraph 1:

    -1- Remarks: automatically detects […]. A program may specialize this template to derive from true_type for a userprogram-defined type T that does not have a nested allocator_type but nonetheless can be constructed with an allocator where either: […]

  5. Change 22.10.15.2 [func.bind.isbind] paragraph 2:

    -2- Instantiations of the is_bind_expression template […]. A program may specialize this template for a userprogram-defined type T to have a BaseCharacteristic of true_type to indicate that T should be treated as a subexpression in a bind call.

  6. Change 22.10.15.3 [func.bind.isplace] paragraph 2:

    -2- Instantiations of the is_placeholder template […]. A program may specialize this template for a userprogram-defined type T to have a BaseCharacteristic of integral_constant<int, N> with N > 0 to indicate that T should be treated as a placeholder type.

  7. Change 22.10.19 [unord.hash] paragraph 1:

    The unordered associative containers defined in 23.5 use specializations of the class template hash […], the instantiation hash<Key> shall:

    • […]

    • […]

    • […]

    • […]

    • satisfy the requirement that the expression h(k), where h is an object of type hash<Key> and k is an object of type Key, shall not throw an exception unless hash<Key> is a userprogram-defined specialization that depends on at least one userprogram-defined type.

  8. Change 21.3.8.6 [meta.trans.ptr] Table 57 (common_type row):

    Table 57 — Other transformations
    Template Condition Comments
    …
    template <class... T>
    struct common_type;         		  The member typedef type shall be
    defined or omitted as specified below.
    […]. A program may
    specialize this trait if at least one
    template parameter in the
    specialization is a userprogram-defined type.
    […]
    …

  9. Change 28.3.4.2.5 [locale.codecvt] paragraph 3:

    -3- The specializations required in Table 81 (22.3.1.1.1) […]. Other encodings can be converted by specializing on a userprogram-defined stateT type.[…]

  10. Change 28.6.11.1.5 [re.regiter.incr] paragraph 8:

    -8- [Note: This means that a compiler may call an implementation-specific search function, in which case a userprogram-defined specialization of regex_search will not be called. — end note]

[2018-3-14 Wednesday evening issues processing; move to Ready]

After this lands, we need to audit Annex C to find "user-defined type" Example: [diff.cpp03.containers]/3

[2018-06 Rapperswil: Adopted]

Proposed resolution:

This wording is relative to N4687.

  1. Add a new sub-clause to [definitions]:

    20.3.? [defns.program.defined.spec]

    program-defined specialization

    explicit template specialization or partial specialization that is not part of the C++ standard library and not defined by the implementation

    20.3.? [defns.program.defined.type]

    program-defined type

    class type or enumeration type that is not part of the C++ standard library and not defined by the implementation, or an instantiation of a program-defined specialization

    [Drafting note: ISO directives say the following Note should be labelled as a "Note to entry" but the C++ WP doesn't follow that rule (yet). — end drafting note]

    [Note: Types defined by the implementation include extensions (4.1 [intro.compliance]) and internal types used by the library. — end note]

  2. Change 16.4.5.2.1 [namespace.std] paragraph 1+2:

    -1- The behavior of a C++ program is undefined if it adds declarations or definitions to namespace std or to a namespace within namespace std unless otherwise specified. A program may add a template specialization for any standard library template to namespace std only if the declaration depends on a userprogram-defined type and the specialization meets the standard library requirements for the original template and is not explicitly prohibited.

    -2- The behavior of a C++ program is undefined if it declares

    […]

    A program may explicitly instantiate a template defined in the standard library only if the declaration depends on the name of a userprogram-defined type and the instantiation meets the standard library requirements for the original template.

  3. Change 19.5 [syserr] paragraph 4:

    -4- The is_error_code_enum and is_error_condition_enum may be specialized for userprogram-defined types to indicate that such types are eligible for class error_code and class error_condition automatic conversions, respectively.

  4. Change 20.2.8.1 [allocator.uses.trait] paragraph 1:

    -1- Remarks: automatically detects […]. A program may specialize this template to derive from true_type for a userprogram-defined type T that does not have a nested allocator_type but nonetheless can be constructed with an allocator where either: […]

  5. Change 22.10.15.2 [func.bind.isbind] paragraph 2:

    -2- Instantiations of the is_bind_expression template […]. A program may specialize this template for a userprogram-defined type T to have a BaseCharacteristic of true_type to indicate that T should be treated as a subexpression in a bind call.

  6. Change 22.10.15.3 [func.bind.isplace] paragraph 2:

    -2- Instantiations of the is_placeholder template […]. A program may specialize this template for a userprogram-defined type T to have a BaseCharacteristic of integral_constant<int, N> with N > 0 to indicate that T should be treated as a placeholder type.

  7. Change 22.10.19 [unord.hash] paragraph 1:

    The unordered associative containers defined in 23.5 use specializations of the class template hash […], the instantiation hash<Key> shall:

  8. Change 21.3.8.6 [meta.trans.ptr] Table 57 (common_type row):

    Table 57 — Other transformations
    Template Condition Comments
    …
    template <class... T>
    struct common_type;         		  The member typedef type shall be
    defined or omitted as specified below.
    […]. A program may
    specialize this trait if at least one
    template parameter in the
    specialization is a userprogram-defined type.
    […]
    …

  9. Change 28.3.4.2.5 [locale.codecvt] paragraph 3:

    -3- The specializations required in Table 81 (22.3.1.1.1) […]. Other encodings can be converted by specializing on a userprogram-defined stateT type.[…]

  10. Change 28.6.11.1.5 [re.regiter.incr] paragraph 8:

    -8- [Note: This means that a compiler may call an implementation-specific search function, in which case a userprogram-defined specialization of regex_search will not be called. — end note]