From: Sven Verdoolaege <skimo@kotnet.org>
Date: Mon, 19 Apr 2010 09:27:52 +0000 (+0200)
Subject: doc: document setting and getting of dimension names
X-Git-Tag: isl-0.03~230
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=1fa4cd2c6838d24d8ca8416ca786f66278d8d525;p=platform%2Fupstream%2Fisl.git

doc: document setting and getting of dimension names
---

diff --git a/doc/user.pod b/doc/user.pod
index f26a292..0fab92b 100644
--- a/doc/user.pod
+++ b/doc/user.pod
@@ -387,6 +387,24 @@ specification of the original set or map.
 		__isl_keep isl_basic_map *bmap);
 	__isl_give isl_dim *isl_map_get_dim(__isl_keep isl_map *map);
 
+The names of the individual dimensions may be set or read off
+using the following functions.
+
+	#include <isl_dim.h>
+	__isl_give isl_dim *isl_dim_set_name(__isl_take isl_dim *dim,
+				 enum isl_dim_type type, unsigned pos,
+				 __isl_keep const char *name);
+	__isl_keep const char *isl_dim_get_name(__isl_keep isl_dim *dim,
+				 enum isl_dim_type type, unsigned pos);
+
+Note that C<isl_dim_get_name> returns a pointer to some internal
+data structure, so the result can only be used while the
+corresponding C<isl_dim> is alive.
+Also note that every function that operates on two sets or relations
+requires that both arguments have the same parameters.  This also
+means that if one of the arguments has named parameters, then the
+other needs to have named parameters too and the names need to match.
+
 =head2 Input and Output
 
 C<isl> supports its own input/output format, which is similar
diff --git a/include/isl_dim.h b/include/isl_dim.h
index 21de287..557d4a4 100644
--- a/include/isl_dim.h
+++ b/include/isl_dim.h
@@ -48,10 +48,10 @@ __isl_give isl_dim *isl_dim_copy(__isl_keep isl_dim *dim);
 struct isl_dim *isl_dim_cow(struct isl_dim *dim);
 void isl_dim_free(__isl_take isl_dim *dim);
 
-struct isl_dim *isl_dim_set_name(struct isl_dim *dim,
+__isl_give isl_dim *isl_dim_set_name(__isl_take isl_dim *dim,
 				 enum isl_dim_type type, unsigned pos,
-				 const char *name);
-const char *isl_dim_get_name(struct isl_dim *dim,
+				 __isl_keep const char *name);
+__isl_keep const char *isl_dim_get_name(__isl_keep isl_dim *dim,
 				 enum isl_dim_type type, unsigned pos);
 
 struct isl_dim *isl_dim_extend(struct isl_dim *dim,