Add x, y, and z shorthands to id and range classes

The numbering of dimensions in SYCL is aligned with the numbering of dimensions
in ISO C++, such that the highest-numbered dimension is the fastest-moving.

This numbering is inconvenient when working with generic functions compatible
with one-, two-, or three-dimensional ranges, since developers must account
somehow for differences in the numbering of the dimensions. One common solution
is to define helper functions called x(), y() and z() to encapsulate this
logic. This solution can also assist with the migration of code from other
languages (e.g., OpenCL and CUDA), and may provide a simpler mental model for
SYCL developers working with images or other forms of graphics interop.

This commit adds x(), y() and z() functions directly to the id and range
classes, providing a consistent way for SYCL developers to use this indexing
pattern, rather than relying on each SYCL code base to define and maintain
compatible index abstractions.

adoc/chapters/programming_interface.adoc

@@ -11977,6 +11977,30 @@ size_t operator[](int dimension) const
    a@ Return the value of the specified dimension of the
       [code]#range#.
 
+a@
+[source]
+----
+size_t x() const noexcept;
+----
+   a@ Return the value of dimension [code]#Dimensions - 1# of the [code]#range#
+      object.
+
+a@
+[source]
+----
+size_t y() const noexcept;
+----
+   a@ Return the value of dimension [code]#Dimensions - 2# of the [code]#range#
+      object, or 1 if [code]#Dimensions < 2#.
+
+a@
+[source]
+----
+size_t z() const noexcept;
+----
+   a@ Return the value of dimension [code]#Dimensions - 3# of the [code]#range#
+      object, or 1 if [code]#Dimensions < 3#.
+
 a@
 [source]
 ----
@@ -12322,6 +12346,30 @@ size_t operator[](int dimension) const
    a@ Return the value of the requested dimension of the [code]#id#
       object.
 
+a@
+[source]
+----
+size_t x() const noexcept;
+----
+   a@ Return the value of dimension [code]#Dimensions - 1# of the [code]#id#
+      object.
+
+a@
+[source]
+----
+size_t y() const noexcept;
+----
+   a@ Return the value of dimension [code]#Dimensions - 2# of the [code]#id#
+      object, or 1 if [code]#Dimensions < 2#.
+
+a@
+[source]
+----
+size_t z() const noexcept;
+----
+   a@ Return the value of dimension [code]#Dimensions - 3# of the [code]#id#
+      object, or 1 if [code]#Dimensions < 3#.
+
 a@
 [source]
 ----

adoc/headers/id.h

@@ -27,6 +27,10 @@ template <int Dimensions = 1> class id {
   size_t& operator[](int dimension);
   size_t operator[](int dimension) const;
 
+  size_t x() const noexcept;
+  size_t y() const noexcept;
+  size_t z() const noexcept;
+
   // only available if Dimensions == 1
   operator size_t() const;
 

adoc/headers/range.h

@@ -24,6 +24,10 @@ template <int Dimensions = 1> class range {
   size_t& operator[](int dimension);
   size_t operator[](int dimension) const;
 
+  size_t x() const noexcept;
+  size_t y() const noexcept;
+  size_t z() const noexcept;
+
   size_t size() const;
 
   // OP is: +, -, *, /, %, <<, >>, &, |, ^, &&, ||, <, >, <=, >=