document the syntax sugar

Author: gavinking

documentation/src/main/asciidoc/querylanguage/Expressions.adoc

@@ -900,6 +900,18 @@ select substring(title, 1, position(' for Dummies' in title)) from Book
 select substring(title from 1 for position(' for Dummies' in title)) from Book  /* ANSI SQL-style */
 ----
 
+Alternatively, slicing may be performed using an operator, which is just syntax sugar for the `substring()` function:
+
+[source, hql]
+----
+select title[1:position(' for Dummies' in title)] from Book         /* Operator-style */
+----
+
+[source,hql]
+----
+select name.first[1]||name.last[1] as initials from Author
+----
+
 [discrete]
 ===== Trimming strings
 The `trim()` function follows the syntax and semantics of ANSI SQL.
@@ -1179,6 +1191,21 @@ On supported platforms, HQL provides a rich suite of functions for working with:
 - link:{doc-user-guide-url}#hql-functions-xml[XML]
 
 The use of these functions is outside the scope of this guide.
+However, we note that the following language constructs work with arrays, and are implemented as syntactic sugar for the underlying functions:
+
+[[array-syntax-sugar]]
+|===
+| Syntax | Interpretation
+
+| `[1, 2]` | Instantiate an array
+| `array[1]` | Array element
+| `array[1:2]` | Array slice
+| `length(array)` | Length of an array
+| `position(element in array)` | Position of an element within an array
+| `cast(array as String)` | Typecast array to string
+| `element in array` or `array contains element` | Determine if an element belongs to an array
+| `array includes subarray` | Determine if the elements of one array include all the elements of a second array
+|===
 
 [[embedding-sql]]
 ==== Embedding SQL expressions

hibernate-core/src/main/java/org/hibernate/boot/spi/AbstractDelegatingMetadata.java

@@ -41,7 +41,9 @@
  *
  * @author Gunnar Morling
  *
+ * @deprecated Not used
  */
+@Deprecated(since = "7", forRemoval = true)
 public abstract class AbstractDelegatingMetadata implements MetadataImplementor {
 
 	private final MetadataImplementor delegate;

hibernate-core/src/main/java/org/hibernate/boot/spi/AbstractDelegatingMetadataBuilderImplementor.java

@@ -33,7 +33,10 @@
  *
  * @param <T> The specific subclass; Allows subclasses to narrow the return type of the contract methods
  *            to a specialization of {@link MetadataBuilderImplementor}.
+ *
+ * @deprecated Not used
  */
+@Deprecated(since = "7", forRemoval = true)
 public abstract class AbstractDelegatingMetadataBuilderImplementor<T extends MetadataBuilderImplementor>  implements MetadataBuilderImplementor {
 
 	private final MetadataBuilderImplementor delegate;

hibernate-core/src/main/java/org/hibernate/boot/spi/AbstractDelegatingMetadataBuildingOptions.java

@@ -26,8 +26,10 @@
  *
  * @author Gunnar Morling
  * @author Steve Ebersole
+ *
+ * @deprecated Not used
  */
-@SuppressWarnings("unused")
+@Deprecated(since = "7", forRemoval = true)
 public abstract class AbstractDelegatingMetadataBuildingOptions implements MetadataBuildingOptions, JpaOrmXmlPersistenceUnitDefaultAware {
 
 	private final MetadataBuildingOptions delegate;

hibernate-core/src/main/java/org/hibernate/boot/spi/AbstractDelegatingSessionFactoryBuilder.java

@@ -33,7 +33,10 @@
  *
  * @param <T> The specific subclass; Allows subclasses to narrow the return type of the contract methods
  *            to a specialization of {@link MetadataBuilderImplementor}.
+ *
+ * @deprecated Not used
  */
+@Deprecated(since = "7", forRemoval = true)
 public abstract class AbstractDelegatingSessionFactoryBuilder<T extends SessionFactoryBuilder> implements SessionFactoryBuilder {
 	private final SessionFactoryBuilder delegate;
 

hibernate-core/src/main/java/org/hibernate/boot/spi/AbstractDelegatingSessionFactoryBuilderImplementor.java

@@ -11,7 +11,10 @@
  *
  * @param <T> The specific subclass; Allows subclasses to narrow the return type of the contract methods
  *            to a specialization of {@link MetadataBuilderImplementor}.
+ *
+ * @deprecated Not used
  */
+@Deprecated(since = "7", forRemoval = true)
 public abstract class AbstractDelegatingSessionFactoryBuilderImplementor<T extends SessionFactoryBuilderImplementor>
 		extends AbstractDelegatingSessionFactoryBuilder<T> implements SessionFactoryBuilderImplementor {
 

hibernate-core/src/main/java/org/hibernate/boot/spi/AbstractDelegatingSessionFactoryOptions.java

@@ -47,7 +47,10 @@
  *           have at least a default implementation.
  *
  * @author Steve Ebersole
+ *
+ * @deprecated Not used
  */
+@Deprecated(since = "7", forRemoval = true)
 public class AbstractDelegatingSessionFactoryOptions implements SessionFactoryOptions {
 	private final SessionFactoryOptions delegate;