---
title: "Slice Metadata Directives"
url: https://docs.zeroc.com/ice/3.8/slice/slice-metadata-directives
language: cpp
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# Slice Metadata Directives

Programming language: C++. Other languages: [C#](https://docs.zeroc.com/ice/3.8/slice/slice-metadata-directives/csharp.md), [Java](https://docs.zeroc.com/ice/3.8/slice/slice-metadata-directives/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/slice/slice-metadata-directives/js.md), [MATLAB](https://docs.zeroc.com/ice/3.8/slice/slice-metadata-directives/matlab.md), [PHP](https://docs.zeroc.com/ice/3.8/slice/slice-metadata-directives/php.md), [Python](https://docs.zeroc.com/ice/3.8/slice/slice-metadata-directives/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/slice/slice-metadata-directives/ruby.md), [Swift](https://docs.zeroc.com/ice/3.8/slice/slice-metadata-directives/swift.md).

## Overview

A metadata directive gives the Slice compilers an instruction about a Slice definition or a Slice file. Most directives customize the code generated for one language mapping, and start with the prefix of this mapping, such as `java:`:

```slice
["java:type:java.util.LinkedList<Integer>"] sequence<int> IntSeq;
```

The general directives have no prefix. For example, `format` selects how Ice marshals class instances, and `deprecated` marks a definition as deprecated.

You place directives in square brackets before the definition they apply to, separated by commas or in consecutive lists, as in `["amd"]["deprecated"]`:

```slice
["amd", "deprecated"]
interface Greeter
{
    string greet(string name);
}
```

A file directive applies to a whole Slice file. You place it in double square brackets before any definition in this file; it can follow `#include` directives:

```slice
[["cpp:dll-export:WIDGET_API"]]
```

Each directive applies only to certain kinds of definitions, listed in its description below.

## General Metadata Directives

### amd

`["amd"]`. Applies to interfaces and operations.

In C++, C#, and Java, the skeleton provides an asynchronous method for the operation, or for each operation of the interface, instead of a synchronous method. Instead of using this directive, you can also derive your servant class from the asynchronous skeleton; see [Operations](https://docs.zeroc.com/ice/3.8/slice/operations/cpp.md). The other Slice compilers ignore this directive.

### deprecated

`["deprecated"]` or `["deprecated:message"]`. Applies to interfaces, operations, classes, exceptions, structs, sequences, dictionaries, enumerations, enumerators, constants, and fields.

This directive marks a definition as deprecated; see [Deprecating Slice Definitions](https://docs.zeroc.com/ice/3.8/slice/deprecating-slice-definitions.md).

### format

`["format:compact"]` or `["format:sliced"]`. Applies to interfaces and operations.

This directive selects the [encoding format](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/slicing-values-and-exceptions/cpp.md) of the class instances marshaled as the arguments or result of an operation: `format:compact` selects the compact format, and `format:sliced` selects the sliced format. On an interface, it applies to all the operations of the interface; on an operation, it overrides the `format` directive of the enclosing interface.

When neither an operation nor its enclosing interface selects a format, the [Ice.Default.SlicedFormat](https://docs.zeroc.com/ice/3.8/property-reference/ice-default-properties/cpp.md#ice.default.slicedformat) property selects it.

> **Note**
>
> This directive does not apply to user exceptions: Ice always marshals them in the sliced format.

### marshaled-result

`["marshaled-result"]`. Applies to interfaces and operations.

This directive lets a servant marshal the results of an operation as soon as it computes them, typically while it holds the lock that protects the data it returns. The mapped skeleton method returns a “marshaled result” struct or class whose constructor marshals the return value and out parameters immediately.

On an interface, this directive applies to every operation that the interface defines. The Slice compiler changes the mapping of an operation only when its return type or one of its out parameters is a class, struct, sequence, or dictionary. This directive affects the server-side mapping in C++, C#, and Java, and has no effect on the client-side mapping.

For example:

```slice
module M
{
    sequence<int> IntSeq;
    sequence<IntSeq> IntIntSeq;
    sequence<string> StringSeq;

    class Grid
    {
        StringSeq xLabels;
        StringSeq yLabels;
        IntIntSeq values;
    }

    interface GridIntf
    {
        // We want to marshal the returned Grid object within a lock,
        // and return a consistent object not affected by concurrent calls to
        // clearValues.
        ["marshaled-result"]
        ["cs:identifier:GetGrid"]
        Grid getGrid();

        void clearValues();
    }
}
```

The mapped skeleton member function for `getGrid` is:

```cpp
GetGridMarshaledResult getGrid(const Ice::Current& current) = 0;
```

where `GetGridMarshaledResult` is a generated class with a constructor that accepts a parameter for the return value, followed by `Current`:

```cpp
// Generated server-side code
class GetGridMarshaledResult : public Ice::MarshaledResult
{
public:
    // Marshals returnValue immediately.
    GetGridMarshaledResult(const GridPtr& returnValue, const Ice::Current& current);
};
```

A typical implementation of the `getGrid` operation in your servant would be:

```cpp
GridServant::GetGridMarshaledResult
GridServant::getGrid(const Ice::Current& current)
{
   lock_guard lock(_mutex);
   // marshal _grid data member within synchronization
   return GetGridMarshaledResult{_grid, current};
}
```

> **Warning**
>
> A marshaled-result instance is specific to a request. Do not cache a marshaled result and return it for another request.

### oneway

`["oneway"]`. Applies to operations.

This directive restricts an operation to oneway invocations. The operation cannot have a return type, out parameters, or an exception specification.

### suppress-warning

`[["suppress-warning"]]` or `[["suppress-warning:category, ..."]]`. Applies to a Slice file.

This directive suppresses Slice compiler warnings for all the definitions in the Slice file. Without a category, it suppresses all warnings; with one or more categories, it suppresses only the warnings in these categories:

| **Category** | **Description** |
| --- | --- |
| `all` | Suppress all Slice compiler warnings. Equivalent to `[["suppress-warning"]]`. |
| `deprecated` | Suppress warnings related to deprecated features. |
| `invalid-comment` | Suppress warnings related to invalid doc comments. |

## Language-Specific Metadata Directives

C++ metadata directives use the `cpp` prefix.

### cpp:array

`["cpp:array"]`. Applies to sequence parameters of operations.

This directive maps the parameter to a [pair of pointers](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/sequences/cpp.md).

### cpp:const

`["cpp:const"]`. Applies to operations.

This directive makes the pure virtual member function of the skeleton class `const`.

> **Note**
>
> The generated skeleton code calls servant member functions using a `shared_ptr<non-const-T>`. Adding this `const` only affects your own servant implementation code.

### cpp:custom-print

`["cpp:custom-print"]`. Applies to enumerations, structs, classes, and exceptions.

This directive tells the Slice compiler that you implement the printing of this type yourself:

- For an enum `E`, the Slice compiler declares `std::ostream& operator<<(std::ostream&, E)` in the enclosing namespace, but does not implement this operator.
- For a struct `S`, the Slice compiler declares `std::ostream& operator<<(std::ostream&, const S&)` in the enclosing namespace, but does not implement this operator.
- For a class or exception, the Slice compiler declares the member function `void ice_print(std::ostream& os) const override` in the mapped C++ class, but does not implement this member function.

The default printing is described in [Printing Enumerators](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/enumerations/cpp.md#printing-enumerators), [Printing Structs](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/structures/cpp.md#printing-structs), [Printing Classes](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/cpp.md#printing-classes), and [Exception Printing](https://docs.zeroc.com/ice/3.8/slice/exceptions/cpp.md#exception-printing).

### cpp:dll-export

`[["cpp:dll-export:SYMBOL"]]`. Applies to a Slice file.

This directive exports the symbols of the generated code from a DLL (on Windows) or a shared library (on other platforms). The Slice compiler adds `SYMBOL` to the exported declarations. The generated header defines `SYMBOL` to export these declarations when `SYMBOL_EXPORTS` is defined, and to import them otherwise; the generated source file defines `SYMBOL_EXPORTS`.

### cpp:doxygen

`[["cpp:doxygen:include:header"]]`. Applies to a Slice file.

This directive adds a doc comment with `@headerfile` and `header` to all generated C++ classes.

### cpp:header-ext

`[["cpp:header-ext:extension"]]`. Applies to a Slice file.

This directive sets the file extension of the generated header file, instead of the default `.h`.

### cpp:identifier

`["cpp:identifier:name"]`. Applies to any definition, parameter, or field.

The generated C++ code uses `name` instead of the Slice identifier. For example:

```slice
struct Descriptor
{
    ["cpp:identifier:blueprint"]
    string template;
}
```

The field `template` maps to `blueprint` in C++. The default mapping, `template`, is a C++ keyword.

### cpp:ice\_print

`["cpp:ice_print"]`. Applies to exceptions.

This directive is a deprecated alias for `cpp:custom-print`.

### cpp:include

`[["cpp:include:header"]]`. Applies to a Slice file.

This directive adds `#include <header>` to the generated header file, typically for a type you select with `cpp:type`.

### cpp:source-ext

`[["cpp:source-ext:extension"]]`. Applies to a Slice file.

This directive sets the file extension of the generated source file, instead of the default `.cpp`.

### cpp:source-include

`[["cpp:source-include:header"]]`. Applies to a Slice file.

This directive adds `#include <header>` to the generated source file, for example when the generated code needs the complete definition of a type that the generated header does not include.

### cpp:type

`["cpp:type:type"]`. Applies to sequences and dictionaries.

On a [sequence](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/sequences/cpp.md) or [dictionary](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/dictionaries/cpp.md), or on a parameter or field of such a type, this directive maps it to the C++ type `type`.

### cpp:type:string and cpp:type:wstring

`["cpp:type:string"]` or `["cpp:type:wstring"]`. Applies to strings, and to modules, interfaces, classes, structs, and exceptions.

Slice strings [map by default](https://docs.zeroc.com/ice/3.8/slice/basic-types/cpp.md) to `std::string`. `cpp:type:wstring` maps them to `std::wstring` instead, and `cpp:type:string` maps them back to `std::string`. On a module, interface, class, struct, or exception, these directives apply to all the strings it contains:

```slice
module A
{
    ["cpp:type:wstring"] struct Struct1
    {
        string s1; // Maps to std::wstring
        ["cpp:type:string"] string s2; // Maps to std::string
    }
}
```

### cpp:view-type

`["cpp:view-type:type"]`. Applies to sequence parameters of operations.

This directive maps the parameter to the C++ type `type`, a view that does not own the elements, where the generated code only reads the sequence, such as an in parameter of a proxy function.
