head	8.7;
access;
symbols;
locks; strict;
comment	@ * @;


8.7
date	2026.05.11.12.01.10;	author mcalabre;	state Exp;
branches;
next	8.6;

8.6
date	2026.03.29.13.53.56;	author mcalabre;	state Exp;
branches
	8.6.1.1;
next	8.5;

8.5
date	2025.12.06.13.47.41;	author mcalabre;	state Exp;
branches
	8.5.1.1;
next	8.4;

8.4
date	2024.10.28.13.56.16;	author mcalabre;	state Exp;
branches
	8.4.1.1;
next	8.3;

8.3
date	2024.05.13.16.33.00;	author mcalabre;	state Exp;
branches
	8.3.1.1;
next	8.2;

8.2
date	2023.11.16.10.00.29;	author mcalabre;	state Exp;
branches
	8.2.1.1;
next	8.1;

8.1
date	2023.07.05.17.12.07;	author mcalabre;	state Exp;
branches
	8.1.1.1;
next	8.0;

8.0
date	2023.07.01.06.15.04;	author mcalabre;	state Exp;
branches
	8.0.1.1;
next	7.13;

7.13
date	2022.10.07.03.43.35;	author mcalabre;	state Exp;
branches
	7.13.1.1;
next	7.12;

7.12
date	2022.09.09.04.57.58;	author mcalabre;	state Exp;
branches
	7.12.1.1;
next	7.11;

7.11
date	2022.04.26.06.13.52;	author mcalabre;	state Exp;
branches
	7.11.1.1;
next	7.10;

7.10
date	2022.04.23.14.25.15;	author mcalabre;	state Exp;
branches
	7.10.1.1;
next	7.9;

7.9
date	2022.03.25.15.14.48;	author mcalabre;	state Exp;
branches
	7.9.1.1;
next	7.8;

7.8
date	2022.03.25.06.11.49;	author mcalabre;	state Exp;
branches
	7.8.1.1;
next	7.7;

7.7
date	2021.07.12.06.36.49;	author mcalabre;	state Exp;
branches
	7.7.1.1;
next	7.6;

7.6
date	2021.04.13.12.57.01;	author mcalabre;	state Exp;
branches
	7.6.1.1;
next	7.5;

7.5
date	2021.03.20.05.54.58;	author mcalabre;	state Exp;
branches
	7.5.1.1;
next	7.4;

7.4
date	2021.01.31.02.24.51;	author mcalabre;	state Exp;
branches
	7.4.1.1;
next	7.3;

7.3
date	2020.06.03.03.37.02;	author mcalabre;	state Exp;
branches
	7.3.1.1;
next	7.2;

7.2
date	2020.03.09.07.31.23;	author mcalabre;	state Exp;
branches
	7.2.1.1;
next	7.1;

7.1
date	2019.12.31.13.25.19;	author mcalabre;	state Exp;
branches
	7.1.1.1;
next	6.4;

6.4
date	2019.08.15.09.30.18;	author mcalabre;	state Exp;
branches
	6.4.1.1;
next	6.3;

6.3
date	2019.07.12.07.33.39;	author mcalabre;	state Exp;
branches
	6.3.1.1;
next	6.2;

6.2
date	2018.10.20.10.03.13;	author mcalabre;	state Exp;
branches
	6.2.1.1;
next	6.1;

6.1
date	2018.10.19.08.35.17;	author mcalabre;	state Exp;
branches
	6.1.1.1;
next	5.20;

5.20
date	2018.10.05.05.32.41;	author mcalabre;	state Exp;
branches
	5.20.1.1;
next	5.19;

5.19
date	2018.07.26.15.37.04;	author mcalabre;	state Exp;
branches
	5.19.1.1;
next	5.18;

5.18
date	2018.01.10.08.32.14;	author mcalabre;	state Exp;
branches
	5.18.1.1;
next	5.17;

5.17
date	2017.09.18.08.44.23;	author mcalabre;	state Exp;
branches
	5.17.1.1;
next	5.16;

5.16
date	2017.01.15.04.25.01;	author mcalabre;	state Exp;
branches
	5.16.1.1;
next	5.15;

5.15
date	2016.04.05.12.55.10;	author mcalabre;	state Exp;
branches
	5.15.1.1;
next	5.14;

5.14
date	2016.02.07.10.49.31;	author mcalabre;	state Exp;
branches
	5.14.1.1;
next	5.13;

5.13
date	2016.01.26.08.51.13;	author mcalabre;	state Exp;
branches
	5.13.1.1;
next	5.12;

5.12
date	2015.11.15.02.13.00;	author mcalabre;	state Exp;
branches
	5.12.1.1;
next	5.11;

5.11
date	2015.10.18.09.13.05;	author mcalabre;	state Exp;
branches
	5.11.1.1;
next	5.10;

5.10
date	2015.10.09.08.19.15;	author mcalabre;	state Exp;
branches
	5.10.1.1;
next	5.9;

5.9
date	2015.07.21.09.20.01;	author mcalabre;	state Exp;
branches
	5.9.1.1;
next	5.8;

5.8
date	2015.07.08.11.03.59;	author mcalabre;	state Exp;
branches
	5.8.1.1;
next	5.7;

5.7
date	2015.06.29.02.44.16;	author mcalabre;	state Exp;
branches
	5.7.1.1;
next	5.6;

5.6
date	2015.06.14.07.11.24;	author mcalabre;	state Exp;
branches
	5.6.1.1;
next	5.5;

5.5
date	2015.05.05.13.16.31;	author mcalabre;	state Exp;
branches
	5.5.1.1;
next	5.4;

5.4
date	2015.04.21.14.41.05;	author mcalabre;	state Exp;
branches
	5.4.1.1;
next	5.3;

5.3
date	2015.04.21.02.50.51;	author mcalabre;	state Exp;
branches
	5.3.1.1;
next	5.2;

5.2
date	2015.04.15.12.35.07;	author mcalabre;	state Exp;
branches
	5.2.1.1;
next	5.1;

5.1
date	2015.04.07.10.56.36;	author mcalabre;	state Exp;
branches
	5.1.1.1;
next	5.0;

5.0
date	2015.04.05.12.24.59;	author mcalabre;	state Exp;
branches
	5.0.1.1;
next	4.25;

4.25
date	2014.12.14.14.29.36;	author mcalabre;	state Exp;
branches
	4.25.1.1;
next	4.24;

4.24
date	2014.09.18.15.25.00;	author mcalabre;	state Exp;
branches
	4.24.1.1;
next	4.23;

4.23
date	2014.05.13.05.50.51;	author mcalabre;	state Exp;
branches
	4.23.1.1;
next	4.22;

4.22
date	2014.04.12.15.03.52;	author mcalabre;	state Exp;
branches
	4.22.1.1;
next	4.21;

4.21
date	2014.03.24.05.12.27;	author mcalabre;	state Exp;
branches
	4.21.1.1;
next	4.20;

4.20
date	2013.12.18.05.42.49;	author mcalabre;	state Exp;
branches
	4.20.1.1;
next	4.19;

4.19
date	2013.09.29.14.17.51;	author mcalabre;	state Exp;
branches
	4.19.1.1;
next	4.18;

4.18
date	2013.07.13.10.00.04;	author mcalabre;	state Exp;
branches
	4.18.1.1;
next	4.17;

4.17
date	2013.01.29.05.29.20;	author cal103;	state Exp;
branches
	4.17.1.1;
next	4.16;

4.16
date	2012.11.07.04.42.44;	author cal103;	state Exp;
branches
	4.16.1.1;
next	4.15;

4.15
date	2012.09.26.14.26.05;	author cal103;	state Exp;
branches
	4.15.1.1;
next	4.14;

4.14
date	2012.07.13.10.02.27;	author cal103;	state Exp;
branches
	4.14.1.1;
next	4.13;

4.13
date	2012.03.14.07.39.30;	author cal103;	state Exp;
branches
	4.13.1.1;
next	4.12;

4.12
date	2012.02.29.07.57.56;	author cal103;	state Exp;
branches
	4.12.1.1;
next	4.11;

4.11
date	2012.02.20.23.30.02;	author cal103;	state Exp;
branches
	4.11.1.1;
next	4.10;

4.10
date	2012.02.05.23.41.44;	author cal103;	state Exp;
branches
	4.10.1.1;
next	4.9;

4.9
date	2012.01.24.05.40.29;	author cal103;	state Exp;
branches
	4.9.1.1;
next	4.8;

4.8
date	2011.08.15.08.05.53;	author cal103;	state Exp;
branches
	4.8.1.1;
next	4.7;

4.7
date	2011.02.07.07.03.42;	author cal103;	state Exp;
branches
	4.7.1.1;
next	4.6;

4.6
date	2010.11.16.06.15.31;	author cal103;	state Exp;
branches
	4.6.1.1;
next	4.5;

4.5
date	2010.07.16.07.01.25;	author cal103;	state Exp;
branches
	4.5.1.1;
next	4.4;

4.4
date	2009.08.06.07.41.33;	author cal103;	state Exp;
branches
	4.4.1.1;
next	4.3;

4.3
date	2007.12.27.05.41.36;	author cal103;	state Exp;
branches
	4.3.1.1;
next	4.2;

4.2
date	2005.09.21.13.21.57;	author cal103;	state Exp;
branches
	4.2.1.1;
next	4.1;

4.1
date	2005.08.25.07.26.29;	author cal103;	state Exp;
branches;
next	0.0;

0.0
date	2005.08.25.07.06.15;	author cal103;	state Exp;
branches;
next	;

4.2.1.1
date	2005.12.05.02.39.43;	author cal103;	state Exp;
branches;
next	4.2.1.2;

4.2.1.2
date	2006.08.02.00.14.58;	author cal103;	state Exp;
branches;
next	4.2.1.3;

4.2.1.3
date	2007.08.02.04.56.39;	author cal103;	state Exp;
branches;
next	4.2.1.4;

4.2.1.4
date	2007.08.08.08.40.48;	author cal103;	state Exp;
branches;
next	4.2.1.5;

4.2.1.5
date	2007.12.03.05.02.17;	author cal103;	state Exp;
branches;
next	;

4.3.1.1
date	2007.12.27.13.23.47;	author cal103;	state Exp;
branches;
next	4.3.1.2;

4.3.1.2
date	2008.04.02.06.17.13;	author cal103;	state Exp;
branches;
next	4.3.1.3;

4.3.1.3
date	2009.07.22.05.10.07;	author cal103;	state Exp;
branches;
next	;

4.4.1.1
date	2009.08.10.08.52.49;	author cal103;	state Exp;
branches;
next	4.4.1.2;

4.4.1.2
date	2010.01.19.03.42.50;	author cal103;	state Exp;
branches;
next	4.4.1.3;

4.4.1.3
date	2010.07.07.08.21.53;	author cal103;	state Exp;
branches;
next	;

4.5.1.1
date	2010.07.16.07.05.31;	author cal103;	state Exp;
branches;
next	;

4.6.1.1
date	2010.11.16.06.16.19;	author cal103;	state Exp;
branches;
next	4.6.1.2;

4.6.1.2
date	2011.01.14.06.33.16;	author cal103;	state Exp;
branches;
next	;

4.7.1.1
date	2011.02.07.07.04.22;	author cal103;	state Exp;
branches;
next	4.7.1.2;

4.7.1.2
date	2011.07.21.03.48.09;	author cal103;	state Exp;
branches;
next	4.7.1.3;

4.7.1.3
date	2011.08.09.02.43.50;	author cal103;	state Exp;
branches;
next	4.7.1.4;

4.7.1.4
date	2011.08.10.06.52.12;	author cal103;	state Exp;
branches;
next	;

4.8.1.1
date	2011.08.15.08.07.06;	author cal103;	state Exp;
branches;
next	4.8.1.2;

4.8.1.2
date	2012.01.24.05.23.06;	author cal103;	state Exp;
branches;
next	;

4.9.1.1
date	2012.01.24.05.41.45;	author cal103;	state Exp;
branches;
next	;

4.10.1.1
date	2012.02.05.23.42.46;	author cal103;	state Exp;
branches;
next	;

4.11.1.1
date	2012.02.20.23.31.13;	author cal103;	state Exp;
branches;
next	;

4.12.1.1
date	2012.02.29.07.59.10;	author cal103;	state Exp;
branches;
next	;

4.13.1.1
date	2012.03.14.07.40.37;	author cal103;	state Exp;
branches;
next	4.13.1.2;

4.13.1.2
date	2012.07.13.03.34.20;	author cal103;	state Exp;
branches;
next	;

4.14.1.1
date	2012.07.13.10.04.44;	author cal103;	state Exp;
branches;
next	4.14.1.2;

4.14.1.2
date	2012.09.26.07.53.12;	author cal103;	state Exp;
branches;
next	;

4.15.1.1
date	2012.09.26.14.27.51;	author cal103;	state Exp;
branches;
next	;

4.16.1.1
date	2012.11.07.04.45.56;	author cal103;	state Exp;
branches;
next	4.16.1.2;

4.16.1.2
date	2012.11.28.13.04.03;	author cal103;	state Exp;
branches;
next	4.16.1.3;

4.16.1.3
date	2013.01.29.05.09.44;	author cal103;	state Exp;
branches;
next	;

4.17.1.1
date	2013.01.29.05.32.32;	author cal103;	state Exp;
branches;
next	;

4.18.1.1
date	2013.07.13.10.02.37;	author mcalabre;	state Exp;
branches;
next	;

4.19.1.1
date	2013.09.29.14.20.38;	author mcalabre;	state Exp;
branches;
next	4.19.1.2;

4.19.1.2
date	2013.12.17.14.54.43;	author mcalabre;	state Exp;
branches;
next	4.19.1.3;

4.19.1.3
date	2013.12.17.14.58.48;	author mcalabre;	state Exp;
branches;
next	;

4.20.1.1
date	2013.12.18.05.46.55;	author mcalabre;	state Exp;
branches;
next	4.20.1.2;

4.20.1.2
date	2014.03.21.06.32.19;	author mcalabre;	state Exp;
branches;
next	;

4.21.1.1
date	2014.03.24.05.15.28;	author mcalabre;	state Exp;
branches;
next	;

4.22.1.1
date	2014.04.12.15.06.32;	author mcalabre;	state Exp;
branches;
next	;

4.23.1.1
date	2014.05.13.05.53.49;	author mcalabre;	state Exp;
branches;
next	;

4.24.1.1
date	2014.09.18.15.28.09;	author mcalabre;	state Exp;
branches;
next	;

4.25.1.1
date	2014.12.14.14.32.45;	author mcalabre;	state Exp;
branches;
next	4.25.1.2;

4.25.1.2
date	2015.01.06.01.01.06;	author mcalabre;	state Exp;
branches;
next	;

5.0.1.1
date	2015.04.05.12.28.00;	author mcalabre;	state Exp;
branches;
next	;

5.1.1.1
date	2015.04.07.11.01.10;	author mcalabre;	state Exp;
branches;
next	;

5.2.1.1
date	2015.04.15.12.39.14;	author mcalabre;	state Exp;
branches;
next	;

5.3.1.1
date	2015.04.21.02.54.02;	author mcalabre;	state Exp;
branches;
next	;

5.4.1.1
date	2015.04.21.14.44.28;	author mcalabre;	state Exp;
branches;
next	5.4.1.2;

5.4.1.2
date	2015.04.23.11.03.11;	author mcalabre;	state Exp;
branches;
next	;

5.5.1.1
date	2015.05.05.13.21.00;	author mcalabre;	state Exp;
branches;
next	;

5.6.1.1
date	2015.06.14.07.14.44;	author mcalabre;	state Exp;
branches;
next	;

5.7.1.1
date	2015.06.29.02.47.24;	author mcalabre;	state Exp;
branches;
next	;

5.8.1.1
date	2015.07.08.11.07.18;	author mcalabre;	state Exp;
branches;
next	;

5.9.1.1
date	2015.07.21.09.28.07;	author mcalabre;	state Exp;
branches;
next	;

5.10.1.1
date	2015.10.09.08.22.35;	author mcalabre;	state Exp;
branches;
next	;

5.11.1.1
date	2015.10.18.09.16.27;	author mcalabre;	state Exp;
branches;
next	;

5.12.1.1
date	2015.11.15.02.16.14;	author mcalabre;	state Exp;
branches;
next	5.12.1.2;

5.12.1.2
date	2016.01.25.05.17.04;	author mcalabre;	state Exp;
branches;
next	;

5.13.1.1
date	2016.01.26.08.54.32;	author mcalabre;	state Exp;
branches;
next	;

5.14.1.1
date	2016.02.07.10.52.44;	author mcalabre;	state Exp;
branches;
next	;

5.15.1.1
date	2016.04.05.12.58.35;	author mcalabre;	state Exp;
branches;
next	5.15.1.2;

5.15.1.2
date	2017.01.15.04.14.00;	author mcalabre;	state Exp;
branches;
next	;

5.16.1.1
date	2017.01.15.04.28.59;	author mcalabre;	state Exp;
branches;
next	;

5.17.1.1
date	2017.09.18.08.45.59;	author mcalabre;	state Exp;
branches;
next	5.17.1.2;

5.17.1.2
date	2018.01.10.08.25.34;	author mcalabre;	state Exp;
branches;
next	;

5.18.1.1
date	2018.01.10.08.33.04;	author mcalabre;	state Exp;
branches;
next	5.18.1.2;

5.18.1.2
date	2018.07.23.13.05.10;	author mcalabre;	state Exp;
branches;
next	;

5.19.1.1
date	2018.07.26.15.41.40;	author mcalabre;	state Exp;
branches;
next	;

5.20.1.1
date	2018.10.05.05.33.33;	author mcalabre;	state Exp;
branches;
next	;

6.1.1.1
date	2018.10.19.08.36.15;	author mcalabre;	state Exp;
branches;
next	;

6.2.1.1
date	2018.10.20.10.04.15;	author mcalabre;	state Exp;
branches;
next	6.2.1.2;

6.2.1.2
date	2019.05.10.01.56.50;	author mcalabre;	state Exp;
branches;
next	;

6.3.1.1
date	2019.07.12.07.34.37;	author mcalabre;	state Exp;
branches;
next	;

6.4.1.1
date	2019.08.15.09.31.29;	author mcalabre;	state Exp;
branches;
next	6.4.1.2;

6.4.1.2
date	2019.12.31.02.33.13;	author mcalabre;	state Exp;
branches;
next	6.4.1.3;

6.4.1.3
date	2019.12.31.03.28.03;	author mcalabre;	state Exp;
branches;
next	;

7.1.1.1
date	2019.12.31.13.28.19;	author mcalabre;	state Exp;
branches;
next	;

7.2.1.1
date	2020.03.09.07.34.50;	author mcalabre;	state Exp;
branches;
next	;

7.3.1.1
date	2020.06.03.03.38.10;	author mcalabre;	state Exp;
branches;
next	7.3.1.2;

7.3.1.2
date	2020.08.17.11.19.09;	author mcalabre;	state Exp;
branches;
next	7.3.1.3;

7.3.1.3
date	2021.01.19.14.09.10;	author mcalabre;	state Exp;
branches;
next	7.3.1.4;

7.3.1.4
date	2021.01.28.12.10.42;	author mcalabre;	state Exp;
branches;
next	7.3.1.5;

7.3.1.5
date	2021.01.28.12.29.30;	author mcalabre;	state Exp;
branches;
next	7.3.1.6;

7.3.1.6
date	2021.01.29.11.36.26;	author mcalabre;	state Exp;
branches;
next	;

7.4.1.1
date	2021.01.31.02.26.24;	author mcalabre;	state Exp;
branches;
next	;

7.5.1.1
date	2021.03.20.05.56.42;	author mcalabre;	state Exp;
branches;
next	;

7.6.1.1
date	2021.04.13.13.00.35;	author mcalabre;	state Exp;
branches;
next	;

7.7.1.1
date	2021.07.12.06.38.27;	author mcalabre;	state Exp;
branches;
next	7.7.1.2;

7.7.1.2
date	2022.03.25.06.05.59;	author mcalabre;	state Exp;
branches;
next	;

7.8.1.1
date	2022.03.25.06.14.14;	author mcalabre;	state Exp;
branches;
next	;

7.9.1.1
date	2022.03.25.15.16.40;	author mcalabre;	state Exp;
branches;
next	;

7.10.1.1
date	2022.04.23.14.26.54;	author mcalabre;	state Exp;
branches;
next	;

7.11.1.1
date	2022.04.26.06.15.32;	author mcalabre;	state Exp;
branches;
next	;

7.12.1.1
date	2022.09.09.05.00.36;	author mcalabre;	state Exp;
branches;
next	;

7.13.1.1
date	2022.10.07.03.45.47;	author mcalabre;	state Exp;
branches;
next	7.13.1.2;

7.13.1.2
date	2023.06.15.04.17.20;	author mcalabre;	state Exp;
branches;
next	;

8.0.1.1
date	2023.07.01.06.22.44;	author mcalabre;	state Exp;
branches;
next	;

8.1.1.1
date	2023.07.05.17.15.00;	author mcalabre;	state Exp;
branches;
next	;

8.2.1.1
date	2023.11.16.10.05.57;	author mcalabre;	state Exp;
branches;
next	8.2.1.2;

8.2.1.2
date	2024.04.02.14.01.58;	author mcalabre;	state Exp;
branches;
next	;

8.3.1.1
date	2024.05.13.16.35.39;	author mcalabre;	state Exp;
branches;
next	;

8.4.1.1
date	2024.10.28.13.58.41;	author mcalabre;	state Exp;
branches;
next	8.4.1.2;

8.4.1.2
date	2025.12.06.13.37.16;	author mcalabre;	state Exp;
branches;
next	;

8.5.1.1
date	2025.12.06.14.05.15;	author mcalabre;	state Exp;
branches;
next	8.5.1.2;

8.5.1.2
date	2026.03.29.13.36.17;	author mcalabre;	state Exp;
branches;
next	;

8.6.1.1
date	2026.03.29.14.19.26;	author mcalabre;	state Exp;
branches;
next	;


desc
@Header file and usage notes for the FITS WCS units specification parsing,
translation and conversion functions.
@


8.7
log
@WCSLIB 8.7
@
text
@/*============================================================================
  WCSLIB 8.7 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2026, Mark Calabretta

  This file is part of WCSLIB.

  WCSLIB is free software: you can redistribute it and/or modify it under the
  terms of the GNU Lesser General Public License as published by the Free
  Software Foundation, either version 3 of the License, or (at your option)
  any later version.

  WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
  more details.

  You should have received a copy of the GNU Lesser General Public License
  along with WCSLIB.  If not, see http://www.gnu.org/licenses.

  Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
  http://www.atnf.csiro.au/computing/software/wcs
  $Id: wcsunits.h,v 8.6.1.1 2026/03/29 14:19:26 mcalabre Exp mcalabre $
*=============================================================================
*
* WCSLIB 8.7 - C routines that implement the FITS World Coordinate System
* (WCS) standard.  Refer to the README file provided with WCSLIB for an
* overview of the library.
*
*
* Summary of the wcsunits routines
* --------------------------------
* Routines in this suite deal with units specifications and conversions, as
* described in
*
=   "Representations of world coordinates in FITS",
=   Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
*
* The Flexible Image Transport System (FITS), a data format widely used in
* astronomy for data interchange and archive, is described in
*
=   "Definition of the Flexible Image Transport System (FITS), version 3.0",
=   Pence, W.D., Chiappetti, L., Page, C.G., Shaw, R.A., & Stobie, E. 2010,
=   A&A, 524, A42 - http://dx.doi.org/10.1051/0004-6361/201015362
*
* See also http://fits.gsfc.nasa.gov
*
* These routines perform basic units-related operations:
*
*   - wcsunitse(): given two unit specifications, derive the conversion from
*     one to the other.
*
*   - wcsutrne(): translates certain commonly used but non-standard unit
*     strings.  It is intended to be called before wcsulexe() which only
*     handles standard FITS units specifications.
*
*   - wcsulexe(): parses a standard FITS units specification of arbitrary
*     complexity, deriving the conversion to canonical units.
*
*
* wcsunitse() - FITS units specification conversion
* -------------------------------------------------
* wcsunitse() derives the conversion from one system of units to another.
*
* A deprecated form of this function, wcsunits(), lacks the wcserr**
* parameter.
*
* Given:
*   have      const char []
*                       FITS units specification to convert from (null-
*                       terminated), with or without surrounding square
*                       brackets (for inline specifications); text following
*                       the closing bracket is ignored.
*
*   want      const char []
*                       FITS units specification to convert to (null-
*                       terminated), with or without surrounding square
*                       brackets (for inline specifications); text following
*                       the closing bracket is ignored.
*
* Returned:
*   scale,
*   offset,
*   power     double*   Convert units using
*
=                         pow(scale*value + offset, power);
*
*                       Normally offset is zero except for log() or ln()
*                       conversions, e.g. "log(MHz)" to "ln(Hz)".  Likewise,
*                       power is normally unity except for exp() conversions,
*                       e.g. "exp(ms)" to "exp(/Hz)".  Thus conversions
*                       ordinarily consist of
*
=                         value *= scale;
*
*   err       struct wcserr **
*                       If enabled, for function return values > 1, this
*                       struct will contain a detailed error message, see
*                       wcserr_enable().  May be NULL if an error message is
*                       not desired.  Otherwise, the user is responsible for
*                       deleting the memory allocated for the wcserr struct.
*
* Function return value:
*             int       Status return value:
*                          0: Success.
*                        1-9: Status return from wcsulexe().
*                         10: Non-conformant unit specifications.
*                         11: Non-conformant functions.
*
*                       scale is zeroed on return if an error occurs.
*
*
* wcsutrne() - Translation of non-standard unit specifications
* ------------------------------------------------------------
* wcsutrne() translates certain commonly used but non-standard unit strings,
* e.g. "DEG", "MHZ", "KELVIN", that are not recognized by wcsulexe(), refer to
* the notes below for a full list.  Compounds are also recognized, e.g.
* "JY/BEAM" and "KM/SEC/SEC".  Extraneous embedded blanks are removed.
*
* A deprecated form of this function, wcsutrn(), lacks the wcserr** parameter.
*
* Given:
*   ctrl      int       Although "S" is commonly used to represent seconds,
*                       its translation to "s" is potentially unsafe since the
*                       standard recognizes "S" formally as Siemens, however
*                       rarely that may be used.  The same applies to "H" for
*                       hours (Henry), and "D" for days (Debye).  This
*                       bit-flag controls what to do in such cases:
*                         1: Translate "S" to "s".
*                         2: Translate "H" to "h".
*                         4: Translate "D" to "d".
*                       Thus ctrl == 0 doesn't do any unsafe translations,
*                       whereas ctrl == 7 does all of them.
*
* Given and returned:
*   unitstr   char []   Null-terminated character array containing the units
*                       specification to be translated.
*
*                       Inline units specifications in a FITS header
*                       keycomment are also handled.  If the first non-blank
*                       character in unitstr is '[' then the unit string is
*                       delimited by its matching ']'.  Blanks preceding '['
*                       will be stripped off, but text following the closing
*                       bracket will be preserved without modification.
*
*   err       struct wcserr **
*                       If enabled, for function return values > 1, this
*                       struct will contain a detailed error message, see
*                       wcserr_enable().  May be NULL if an error message is
*                       not desired.  Otherwise, the user is responsible for
*                       deleting the memory allocated for the wcserr struct.
*
* Function return value:
*             int       Status return value:
*                        -1: No change was made, other than stripping blanks
*                            (not an error).
*                         0: Success.
*                         9: Internal parser error.
*                        12: Potentially unsafe translation, whether applied
*                            or not (see notes).
*
* Notes:
*   1: Translation of non-standard unit specifications: apart from leading and
*      trailing blanks, a case-sensitive match is required for the aliases
*      listed below, in particular the only recognized aliases with metric
*      prefixes are "KM", "KHZ", "MHZ", and "GHZ".  Potentially unsafe
*      translations of "D", "H", and "S", shown in parentheses, are optional.
*
=        Unit       Recognized aliases
=        ----       ----------------------------------------------------------
=        Angstrom   Angstroms angstrom angstroms
=        arcmin     arcmins, ARCMIN, ARCMINS
=        arcsec     arcsecs, ARCSEC, ARCSECS
=        beam       BEAM
=        byte       Byte
=        d          day, days, (D), DAY, DAYS
=        deg        degree, degrees, Deg, Degree, Degrees, DEG, DEGREE,
=                   DEGREES
=        GHz        GHZ
=        h          hr, (H), HR
=        Hz         hz, HZ
=        kHz        KHZ
=        Jy         JY
=        K          kelvin, kelvins, Kelvin, Kelvins, KELVIN, KELVINS
=        km         KM
=        m          metre, meter, metres, meters, M, METRE, METER, METRES,
=                   METERS
=        min        MIN
=        MHz        MHZ
=        Ohm        ohm
=        Pa         pascal, pascals, Pascal, Pascals, PASCAL, PASCALS
=        pixel      pixels, PIXEL, PIXELS
=        rad        radian, radians, RAD, RADIAN, RADIANS
=        s          sec, second, seconds, (S), SEC, SECOND, SECONDS
=        V          volt, volts, Volt, Volts, VOLT, VOLTS
=        yr         year, years, YR, YEAR, YEARS
*
*      The aliases "angstrom", "ohm", and "Byte" for (Angstrom, Ohm, and byte)
*      are recognized by wcsulexe() itself as an unofficial extension of the
*      standard, but they are converted to the standard form here.
*
*
* wcsulexe() - FITS units specification parser
* --------------------------------------------
* wcsulexe() parses a standard FITS units specification of arbitrary
* complexity, deriving the scale factor required to convert to canonical
* units - basically SI with degrees and "dimensionless" additions such as
* byte, pixel and count.
*
* A deprecated form of this function, wcsulex(), lacks the wcserr** parameter.
*
* Given:
*   unitstr   const char []
*                       Null-terminated character array containing the units
*                       specification, with or without surrounding square
*                       brackets (for inline specifications); text following
*                       the closing bracket is ignored.
*
* Returned:
*   func      int*      Special function type, see note 4:
*                         0: None
*                         1: log()  ...base 10
*                         2: ln()   ...base e
*                         3: exp()
*
*   scale     double*   Scale factor for the unit specification; multiply a
*                       value expressed in the given units by this factor to
*                       convert it to canonical units.
*
*   units     double[WCSUNITS_NTYPE]
*                       A units specification is decomposed into powers of 16
*                       fundamental unit types: angle, mass, length, time,
*                       count, pixel, etc.  Preprocessor macro WCSUNITS_NTYPE
*                       is defined to dimension this vector, and others such
*                       WCSUNITS_PLANE_ANGLE, WCSUNITS_LENGTH, etc. to access
*                       its elements.
*
*                       Corresponding character strings, wcsunits_types[] and
*                       wcsunits_units[], are predefined to describe each
*                       quantity and its canonical units.
*
*   err       struct wcserr **
*                       If enabled, for function return values > 1, this
*                       struct will contain a detailed error message, see
*                       wcserr_enable().  May be NULL if an error message is
*                       not desired.  Otherwise, the user is responsible for
*                       deleting the memory allocated for the wcserr struct.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Invalid numeric multiplier.
*                         2: Dangling binary operator.
*                         3: Invalid symbol in INITIAL context.
*                         4: Function in invalid context.
*                         5: Invalid symbol in EXPON context.
*                         6: Unbalanced bracket.
*                         7: Unbalanced parenthesis.
*                         8: Consecutive binary operators.
*                         9: Internal parser error.
*
*                       scale and units[] are zeroed on return if an error
*                       occurs.
*
* Notes:
*   1: wcsulexe() is permissive in accepting whitespace in all contexts in a
*      units specification where it does not create ambiguity (e.g. not
*      between a metric prefix and a basic unit string), including in strings
*      like "log (m ** 2)" which is formally disallowed.
*
*   2: Supported extensions:
*      - "angstrom" (OGIP usage) is allowed in addition to "Angstrom".
*      - "ohm"      (OGIP usage) is allowed in addition to "Ohm".
*      - "Byte"   (common usage) is allowed in addition to "byte".
*
*   3: Table 6 of WCS Paper I lists eleven units for which metric prefixes are
*      allowed.  However, in this implementation only prefixes greater than
*      unity are allowed for "a" (annum), "yr" (year), "pc" (parsec), "bit",
*      and "byte", and only prefixes less than unity are allowed for "mag"
*      (stellar magnitude).
*
*      Metric prefix "P" (peta) is specifically forbidden for "a" (annum) to
*      avoid confusion with "Pa" (Pascal, not peta-annum).  Note that metric
*      prefixes are specifically disallowed for "h" (hour) and "d" (day) so
*      that "ph" (photons) cannot be interpreted as pico-hours, nor "cd"
*      (candela) as centi-days.
*
*   4: Function types log(), ln() and exp() may only occur at the start of the
*      units specification.  The scale and units[] returned for these refers
*      to the string inside the function "argument", e.g. to "MHz" in log(MHz)
*      for which a scale of 1e6 will be returned.
*
*
* Global variable: const char *wcsunits_errmsg[] - Status return messages
* -----------------------------------------------------------------------
* Error messages to match the status value returned from each function.
*
*
* Global variable: const char *wcsunits_types[] - Names of physical quantities
* ----------------------------------------------------------------------------
* Names for physical quantities to match the units vector returned by
* wcsulexe():
*   -  0: plane angle
*   -  1: solid angle
*   -  2: charge
*   -  3: mole
*   -  4: temperature
*   -  5: luminous intensity
*   -  6: mass
*   -  7: length
*   -  8: time
*   -  9: beam
*   - 10: bin
*   - 11: bit
*   - 12: count
*   - 13: stellar magnitude
*   - 14: pixel
*   - 15: solar ratio
*   - 16: voxel
*
*
* Global variable: const char *wcsunits_units[] - Names of units
* --------------------------------------------------------------
* Names for the units (SI) to match the units vector returned by wcsulexe():
*   -  0: degree
*   -  1: steradian
*   -  2: Coulomb
*   -  3: mole
*   -  4: Kelvin
*   -  5: candela
*   -  6: kilogram
*   -  7: metre
*   -  8: second
*
* The remainder are dimensionless.
*===========================================================================*/

#ifndef WCSLIB_WCSUNITS
#define WCSLIB_WCSUNITS

#include "wcserr.h"

#ifdef __cplusplus
extern "C" {
#endif


extern const char *wcsunits_errmsg[];

enum wcsunits_errmsg_enum {
  UNITSERR_SUCCESS            =  0,	// Success.
  UNITSERR_BAD_NUM_MULTIPLIER =  1,	// Invalid numeric multiplier.
  UNITSERR_DANGLING_BINOP     =  2,	// Dangling binary operator.
  UNITSERR_BAD_INITIAL_SYMBOL =  3,	// Invalid symbol in INITIAL context.
  UNITSERR_FUNCTION_CONTEXT   =  4,	// Function in invalid context.
  UNITSERR_BAD_EXPON_SYMBOL   =  5,	// Invalid symbol in EXPON context.
  UNITSERR_UNBAL_BRACKET      =  6,	// Unbalanced bracket.
  UNITSERR_UNBAL_PAREN        =  7,	// Unbalanced parenthesis.
  UNITSERR_CONSEC_BINOPS      =  8,	// Consecutive binary operators.
  UNITSERR_PARSER_ERROR       =  9,	// Internal parser error.
  UNITSERR_BAD_UNIT_SPEC      = 10,	// Non-conformant unit specifications.
  UNITSERR_BAD_FUNCS          = 11,	// Non-conformant functions.
  UNITSERR_UNSAFE_TRANS       = 12	// Potentially unsafe translation.
};

extern const char *wcsunits_types[];
extern const char *wcsunits_units[];

#define WCSUNITS_PLANE_ANGLE 0
#define WCSUNITS_SOLID_ANGLE 1
#define WCSUNITS_CHARGE      2
#define WCSUNITS_MOLE        3
#define WCSUNITS_TEMPERATURE 4
#define WCSUNITS_LUMINTEN    5
#define WCSUNITS_MASS        6
#define WCSUNITS_LENGTH      7
#define WCSUNITS_TIME        8
#define WCSUNITS_BEAM        9
#define WCSUNITS_BIN        10
#define WCSUNITS_BIT        11
#define WCSUNITS_COUNT      12
#define WCSUNITS_MAGNITUDE  13
#define WCSUNITS_PIXEL      14
#define WCSUNITS_SOLRATIO   15
#define WCSUNITS_VOXEL      16

#define WCSUNITS_NTYPE      17


int wcsunitse(const char have[], const char want[], double *scale,
              double *offset, double *power, struct wcserr **err);

int wcsutrne(int ctrl, char unitstr[], struct wcserr **err);

int wcsulexe(const char unitstr[], int *func, double *scale,
             double units[WCSUNITS_NTYPE], struct wcserr **err);

// Deprecated.
int wcsunits(const char have[], const char want[], double *scale,
             double *offset, double *power);
int wcsutrn(int ctrl, char unitstr[]);
int wcsulex(const char unitstr[], int *func, double *scale,
            double units[WCSUNITS_NTYPE]);

#ifdef __cplusplus
}
#endif

#endif // WCSLIB_WCSUNITS
@


8.6
log
@WCSLIB 8.6
@
text
@d2 1
a2 1
  WCSLIB 8.6 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcsunits.h,v 8.5.1.2 2026/03/29 13:36:17 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 8.6 - C routines that implement the FITS World Coordinate System
@


8.6.1.1
log
@WCSLIB 8.6 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 8.6 2026/03/29 13:53:56 mcalabre Exp $
@


8.5
log
@WCSLIB 8.5
@
text
@d2 2
a3 2
  WCSLIB 8.5 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2025, Mark Calabretta
d21 2
a22 2
  http://www.atnf.csiro.au/people/Mark.Calabretta
  $Id: wcsunits.h,v 8.4.1.2 2025/12/06 13:37:16 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 8.5 - C routines that implement the FITS World Coordinate System
@


8.5.1.1
log
@WCSLIB 8.5 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 8.5 2025/12/06 13:47:41 mcalabre Exp $
@


8.5.1.2
log
@Updated date in copyright notice.
@
text
@d3 1
a3 1
  Copyright (C) 1995-2026, Mark Calabretta
d21 2
a22 2
  http://www.atnf.csiro.au/computing/software/wcs
  $Id: wcsunits.h,v 8.5.1.1 2025/12/06 14:05:15 mcalabre Exp mcalabre $
@


8.4
log
@WCSLIB 8.4
@
text
@d2 2
a3 2
  WCSLIB 8.4 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2024, Mark Calabretta
d22 1
a22 1
  $Id: wcsunits.h,v 8.3.1.1 2024/05/13 16:35:39 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 8.4 - C routines that implement the FITS World Coordinate System
@


8.4.1.1
log
@WCSLIB 8.4 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 8.4 2024/10/28 13:56:16 mcalabre Exp $
@


8.4.1.2
log
@Updated date in copyright notice.
@
text
@d3 1
a3 1
  Copyright (C) 1995-2025, Mark Calabretta
d22 1
a22 1
  $Id: wcsunits.h,v 8.4.1.1 2024/10/28 13:58:41 mcalabre Exp mcalabre $
@


8.3
log
@WCSLIB 8.3
@
text
@d2 1
a2 1
  WCSLIB 8.3 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcsunits.h,v 8.2.1.2 2024/04/02 14:01:58 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 8.3 - C routines that implement the FITS World Coordinate System
@


8.3.1.1
log
@WCSLIB 8.3 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 8.3 2024/05/13 16:33:00 mcalabre Exp $
@


8.2
log
@WCSLIB 8.2
@
text
@d2 2
a3 2
  WCSLIB 8.2 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2023, Mark Calabretta
d22 1
a22 1
  $Id: wcsunits.h,v 8.1.1.1 2023/07/05 17:15:00 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 8.2 - C routines that implement the FITS World Coordinate System
@


8.2.1.1
log
@WCSLIB 8.2 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 8.2 2023/11/16 10:00:29 mcalabre Exp $
@


8.2.1.2
log
@Updated date in copyright notice.
@
text
@d3 1
a3 1
  Copyright (C) 1995-2024, Mark Calabretta
d22 1
a22 1
  $Id: wcsunits.h,v 8.2.1.1 2023/11/16 10:05:57 mcalabre Exp mcalabre $
@


8.1
log
@WCSLIB 8.1
@
text
@d2 1
a2 1
  WCSLIB 8.1 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcsunits.h,v 8.0.1.1 2023/07/01 06:22:44 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 8.1 - C routines that implement the FITS World Coordinate System
@


8.1.1.1
log
@WCSLIB 8.1 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 8.1 2023/07/05 17:12:07 mcalabre Exp $
@


8.0
log
@WCSLIB 8.0
@
text
@d2 1
a2 1
  WCSLIB 8.0 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcsunits.h,v 7.13.1.2 2023/06/15 04:17:20 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 8.0 - C routines that implement the FITS World Coordinate System
@


8.0.1.1
log
@WCSLIB 8.0 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 8.0 2023/07/01 06:15:04 mcalabre Exp $
@


7.13
log
@WCSLIB 7.13
@
text
@d2 2
a3 2
  WCSLIB 7.13 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2022, Mark Calabretta
d22 1
a22 1
  $Id: wcsunits.h,v 7.12.1.1 2022/09/09 05:00:36 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.13 - C routines that implement the FITS World Coordinate System
@


7.13.1.1
log
@WCSLIB 7.13 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 7.13 2022/10/07 03:43:35 mcalabre Exp $
@


7.13.1.2
log
@Updated date in copyright notice.
@
text
@d3 1
a3 1
  Copyright (C) 1995-2023, Mark Calabretta
d22 1
a22 1
  $Id: wcsunits.h,v 7.13.1.1 2022/10/07 03:45:47 mcalabre Exp mcalabre $
@


7.12
log
@WCSLIB 7.12
@
text
@d2 1
a2 1
  WCSLIB 7.12 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcsunits.h,v 7.11.1.1 2022/04/26 06:15:32 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.12 - C routines that implement the FITS World Coordinate System
@


7.12.1.1
log
@WCSLIB 7.12 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 7.12 2022/09/09 04:57:58 mcalabre Exp $
@


7.11
log
@WCSLIB 7.11
@
text
@d2 1
a2 1
  WCSLIB 7.11 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcsunits.h,v 7.10.1.1 2022/04/23 14:26:54 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.11 - C routines that implement the FITS World Coordinate System
@


7.11.1.1
log
@WCSLIB 7.11 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 7.11 2022/04/26 06:13:52 mcalabre Exp $
@


7.10
log
@WCSLIB 7.10
@
text
@d2 1
a2 1
  WCSLIB 7.10 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcsunits.h,v 7.9.1.1 2022/03/25 15:16:40 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.10 - C routines that implement the FITS World Coordinate System
@


7.10.1.1
log
@WCSLIB 7.10 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 7.10 2022/04/23 14:25:15 mcalabre Exp $
@


7.9
log
@WCSLIB 7.9
@
text
@d2 1
a2 1
  WCSLIB 7.9 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcsunits.h,v 7.8.1.1 2022/03/25 06:14:14 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.9 - C routines that implement the FITS World Coordinate System
@


7.9.1.1
log
@WCSLIB 7.9 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 7.9 2022/03/25 15:14:48 mcalabre Exp $
@


7.8
log
@WCSLIB 7.8
@
text
@d2 1
a2 1
  WCSLIB 7.8 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcsunits.h,v 7.7.1.2 2022/03/25 06:05:59 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.8 - C routines that implement the FITS World Coordinate System
@


7.8.1.1
log
@WCSLIB 7.8 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 7.8 2022/03/25 06:11:49 mcalabre Exp $
@


7.7
log
@WCSLIB 7.7
@
text
@d2 2
a3 2
  WCSLIB 7.7 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2021, Mark Calabretta
d22 1
a22 1
  $Id: wcsunits.h,v 7.6.1.1 2021/04/13 13:00:35 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.7 - C routines that implement the FITS World Coordinate System
@


7.7.1.1
log
@WCSLIB 7.7 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 7.7 2021/07/12 06:36:49 mcalabre Exp $
@


7.7.1.2
log
@Updated date in copyright notice.
@
text
@d3 1
a3 1
  Copyright (C) 1995-2022, Mark Calabretta
d22 1
a22 1
  $Id: wcsunits.h,v 7.7.1.1 2021/07/12 06:38:27 mcalabre Exp mcalabre $
@


7.6
log
@WCSLIB 7.6
@
text
@d2 1
a2 1
  WCSLIB 7.6 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcsunits.h,v 7.5.1.1 2021/03/20 05:56:42 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.6 - C routines that implement the FITS World Coordinate System
@


7.6.1.1
log
@WCSLIB 7.6 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 7.6 2021/04/13 12:57:01 mcalabre Exp $
@


7.5
log
@WCSLIB 7.5
@
text
@d2 1
a2 1
  WCSLIB 7.5 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcsunits.h,v 7.4.1.1 2021/01/31 02:26:24 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.5 - C routines that implement the FITS World Coordinate System
@


7.5.1.1
log
@WCSLIB 7.5 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 7.5 2021/03/20 05:54:58 mcalabre Exp $
@


7.4
log
@WCSLIB 7.4
@
text
@d2 1
a2 1
  WCSLIB 7.4 - an implementation of the FITS WCS standard.
d22 1
a22 1
  $Id: wcsunits.h,v 7.3.1.6 2021/01/29 11:36:26 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.4 - C routines that implement the FITS World Coordinate System
@


7.4.1.1
log
@WCSLIB 7.4 development branch.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 7.4 2021/01/31 02:24:51 mcalabre Exp $
@


7.3
log
@WCSLIB 7.3
@
text
@d2 2
a3 3

  WCSLIB 7.3 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2020, Mark Calabretta
a19 2
  Direct correspondence concerning WCSLIB to mark@@calabretta.id.au

d22 1
a22 1
  $Id: wcsunits.h,v 7.2.1.1 2020/03/09 07:34:50 mcalabre Exp mcalabre $
d25 1
a25 1
* WCSLIB 7.3 - C routines that implement the FITS World Coordinate System
d162 38
a199 36
*   Translation of non-standard unit specifications: apart from leading and
*   trailing blanks, a case-sensitive match is required for the aliases listed
*   below, in particular the only recognized aliases with metric prefixes are
*   "KM", "KHZ", "MHZ", and "GHZ".  Potentially unsafe translations of "D",
*   "H", and "S", shown in parentheses, are optional.
*
=     Unit       Recognized aliases
=     ----       -------------------------------------------------------------
=     Angstrom   angstrom
=     arcmin     arcmins, ARCMIN, ARCMINS
=     arcsec     arcsecs, ARCSEC, ARCSECS
=     beam       BEAM
=     byte       Byte
=     d          day, days, (D), DAY, DAYS
=     deg        degree, degrees, Deg, Degree, Degrees, DEG, DEGREE, DEGREES
=     GHz        GHZ
=     h          hr, (H), HR
=     Hz         hz, HZ
=     kHz        KHZ
=     Jy         JY
=     K          kelvin, kelvins, Kelvin, Kelvins, KELVIN, KELVINS
=     km         KM
=     m          metre, meter, metres, meters, M, METRE, METER, METRES, METERS
=     min        MIN
=     MHz        MHZ
=     Ohm        ohm
=     Pa         pascal, pascals, Pascal, Pascals, PASCAL, PASCALS
=     pixel      pixels, PIXEL, PIXELS
=     rad        radian, radians, RAD, RADIAN, RADIANS
=     s          sec, second, seconds, (S), SEC, SECOND, SECONDS
=     V          volt, volts, Volt, Volts, VOLT, VOLTS
=     yr         year, years, YR, YEAR, YEARS
*
*   The aliases "angstrom", "ohm", and "Byte" for (Angstrom, Ohm, and byte)
*   are recognized by wcsulexe() itself as an unofficial extension of the
*   standard, but they are converted to the standard form here.
d350 13
a362 15
  UNITSERR_SUCCESS            =  0,	/* Success. */
  UNITSERR_BAD_NUM_MULTIPLIER =  1,	/* Invalid numeric multiplier. */
  UNITSERR_DANGLING_BINOP     =  2,	/* Dangling binary operator. */
  UNITSERR_BAD_INITIAL_SYMBOL =  3,	/* Invalid symbol in INITIAL
					   context. */
  UNITSERR_FUNCTION_CONTEXT   =  4,	/* Function in invalid context. */
  UNITSERR_BAD_EXPON_SYMBOL   =  5,	/* Invalid symbol in EXPON context. */
  UNITSERR_UNBAL_BRACKET      =  6,	/* Unbalanced bracket. */
  UNITSERR_UNBAL_PAREN        =  7,	/* Unbalanced parenthesis. */
  UNITSERR_CONSEC_BINOPS      =  8,	/* Consecutive binary operators. */
  UNITSERR_PARSER_ERROR       =  9,	/* Internal parser error. */
  UNITSERR_BAD_UNIT_SPEC      = 10,	/* Non-conformant unit
					   specifications. */
  UNITSERR_BAD_FUNCS          = 11,	/* Non-conformant functions. */
  UNITSERR_UNSAFE_TRANS       = 12	/* Potentially unsafe translation. */
d397 1
a397 1
/* Deprecated. */
d408 1
a408 1
#endif /* WCSLIB_WCSUNITS */
@


7.3.1.1
log
@WCSLIB 7.3 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 7.3 2020/06/03 03:37:02 mcalabre Exp $
@


7.3.1.2
log
@Switched to C99 style commenting (i.e. using //) within the code.
@
text
@d2 1
d25 1
a25 1
  $Id: wcsunits.h,v 7.3.1.1 2020/06/03 03:38:10 mcalabre Exp mcalabre $
d351 15
a365 13
  UNITSERR_SUCCESS            =  0,	// Success.
  UNITSERR_BAD_NUM_MULTIPLIER =  1,	// Invalid numeric multiplier.
  UNITSERR_DANGLING_BINOP     =  2,	// Dangling binary operator.
  UNITSERR_BAD_INITIAL_SYMBOL =  3,	// Invalid symbol in INITIAL context.
  UNITSERR_FUNCTION_CONTEXT   =  4,	// Function in invalid context.
  UNITSERR_BAD_EXPON_SYMBOL   =  5,	// Invalid symbol in EXPON context.
  UNITSERR_UNBAL_BRACKET      =  6,	// Unbalanced bracket.
  UNITSERR_UNBAL_PAREN        =  7,	// Unbalanced parenthesis.
  UNITSERR_CONSEC_BINOPS      =  8,	// Consecutive binary operators.
  UNITSERR_PARSER_ERROR       =  9,	// Internal parser error.
  UNITSERR_BAD_UNIT_SPEC      = 10,	// Non-conformant unit specifications.
  UNITSERR_BAD_FUNCS          = 11,	// Non-conformant functions.
  UNITSERR_UNSAFE_TRANS       = 12	// Potentially unsafe translation.
d400 1
a400 1
// Deprecated.
d411 1
a411 1
#endif // WCSLIB_WCSUNITS
@


7.3.1.3
log
@Updated date in copyright notice.
@
text
@d3 1
a3 1
  Copyright (C) 1995-2021, Mark Calabretta
d24 1
a24 1
  $Id: wcsunits.h,v 7.3.1.2 2020/08/17 11:19:09 mcalabre Exp mcalabre $
@


7.3.1.4
log
@Allow 'Angstroms' and 'angstroms' as additional synonyms for 'Angstrom'.
@
text
@d24 1
a24 1
  $Id: wcsunits.h,v 7.3.1.3 2021/01/19 14:09:10 mcalabre Exp mcalabre $
d172 1
a172 1
=     Angstrom   Angstroms angstrom angstroms
@


7.3.1.5
log
@Removed my email address from the copyright notice.
@
text
@d20 2
d24 1
a24 1
  $Id: wcsunits.h,v 7.3.1.4 2021/01/28 12:10:42 mcalabre Exp mcalabre $
@


7.3.1.6
log
@Numbered entries in the Notes section in the prologue so that they will be
indented properly in the manual.
@
text
@d22 1
a22 1
  $Id: wcsunits.h,v 7.3.1.5 2021/01/28 12:29:30 mcalabre Exp mcalabre $
d162 36
a197 38
*   1: Translation of non-standard unit specifications: apart from leading and
*      trailing blanks, a case-sensitive match is required for the aliases
*      listed below, in particular the only recognized aliases with metric
*      prefixes are "KM", "KHZ", "MHZ", and "GHZ".  Potentially unsafe
*      translations of "D", "H", and "S", shown in parentheses, are optional.
*
=        Unit       Recognized aliases
=        ----       ----------------------------------------------------------
=        Angstrom   Angstroms angstrom angstroms
=        arcmin     arcmins, ARCMIN, ARCMINS
=        arcsec     arcsecs, ARCSEC, ARCSECS
=        beam       BEAM
=        byte       Byte
=        d          day, days, (D), DAY, DAYS
=        deg        degree, degrees, Deg, Degree, Degrees, DEG, DEGREE,
=                   DEGREES
=        GHz        GHZ
=        h          hr, (H), HR
=        Hz         hz, HZ
=        kHz        KHZ
=        Jy         JY
=        K          kelvin, kelvins, Kelvin, Kelvins, KELVIN, KELVINS
=        km         KM
=        m          metre, meter, metres, meters, M, METRE, METER, METRES,
=                   METERS
=        min        MIN
=        MHz        MHZ
=        Ohm        ohm
=        Pa         pascal, pascals, Pascal, Pascals, PASCAL, PASCALS
=        pixel      pixels, PIXEL, PIXELS
=        rad        radian, radians, RAD, RADIAN, RADIANS
=        s          sec, second, seconds, (S), SEC, SECOND, SECONDS
=        V          volt, volts, Volt, Volts, VOLT, VOLTS
=        yr         year, years, YR, YEAR, YEARS
*
*      The aliases "angstrom", "ohm", and "Byte" for (Angstrom, Ohm, and byte)
*      are recognized by wcsulexe() itself as an unofficial extension of the
*      standard, but they are converted to the standard form here.
@


7.2
log
@WCSLIB 7.2
@
text
@d3 1
a3 1
  WCSLIB 7.2 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 7.1.1.1 2019/12/31 13:28:19 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 7.2 - C routines that implement the FITS World Coordinate System
@


7.2.1.1
log
@WCSLIB 7.2 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 7.2 2020/03/09 07:31:23 mcalabre Exp $
@


7.1
log
@WCSLIB 7.1
@
text
@d3 1
a3 1
  WCSLIB 7.1 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 6.4.1.3 2019/12/31 03:28:03 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 7.1 - C routines that implement the FITS World Coordinate System
@


7.1.1.1
log
@WCSLIB 7.1 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 7.1 2019/12/31 13:25:19 mcalabre Exp $
@


6.4
log
@WCSLIB 6.4
@
text
@d3 2
a4 2
  WCSLIB 6.4 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2019, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 6.3.1.1 2019/07/12 07:34:37 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 6.4 - C routines that implement the FITS World Coordinate System
d141 1
a141 1
*                       Inline units specifications in the a FITS header
@


6.4.1.1
log
@WCSLIB 6.4 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 6.4 2019/08/15 09:30:18 mcalabre Exp $
@


6.4.1.2
log
@Fixed a typo in the prologue.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 6.4.1.1 2019/08/15 09:31:29 mcalabre Exp mcalabre $
d141 1
a141 1
*                       Inline units specifications in a FITS header
@


6.4.1.3
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2020, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 6.4.1.2 2019/12/31 02:33:13 mcalabre Exp mcalabre $
@


6.3
log
@WCSLIB 6.3
@
text
@d3 1
a3 1
  WCSLIB 6.3 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 6.2.1.2 2019/05/10 01:56:50 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 6.3 - C routines that implement the FITS World Coordinate System
@


6.3.1.1
log
@WCSLIB 6.3 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 6.3 2019/07/12 07:33:39 mcalabre Exp $
@


6.2
log
@WCSLIB 6.2
@
text
@d3 2
a4 2
  WCSLIB 6.2 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2018, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 6.1.1.1 2018/10/19 08:36:15 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 6.2 - C routines that implement the FITS World Coordinate System
@


6.2.1.1
log
@WCSLIB 6.2 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 6.2 2018/10/20 10:03:13 mcalabre Exp $
@


6.2.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2019, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 6.2.1.1 2018/10/20 10:04:15 mcalabre Exp mcalabre $
@


6.1
log
@WCSLIB 6.1
@
text
@d3 1
a3 1
  WCSLIB 6.1 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.20.1.1 2018/10/05 05:33:33 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 6.1 - C routines that implement the FITS World Coordinate System
@


6.1.1.1
log
@WCSLIB 6.1 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 6.1 2018/10/19 08:35:17 mcalabre Exp $
@


5.20
log
@WCSLIB 5.20
@
text
@d3 1
a3 1
  WCSLIB 5.20 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.19.1.1 2018/07/26 15:41:40 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.20 - C routines that implement the FITS World Coordinate System
@


5.20.1.1
log
@WCSLIB 5.20 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.20 2018/10/05 05:32:41 mcalabre Exp $
@


5.19
log
@WCSLIB 5.19
@
text
@d3 1
a3 1
  WCSLIB 5.19 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.18.1.2 2018/07/23 13:05:10 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.19 - C routines that implement the FITS World Coordinate System
@


5.19.1.1
log
@WCSLIB 5.19 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.19 2018/07/26 15:37:04 mcalabre Exp $
@


5.18
log
@WCSLIB 5.18
@
text
@d3 1
a3 1
  WCSLIB 5.18 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.17.1.2 2018/01/10 08:25:34 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.18 - C routines that implement the FITS World Coordinate System
d179 1
a179 1
=     deg        degree, degrees, DEG, DEGREE, DEGREES
@


5.18.1.1
log
@WCSLIB 5.18 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.18 2018/01/10 08:32:14 mcalabre Exp $
@


5.18.1.2
log
@Recognise 'Deg', 'Degree', and 'Degrees' as aliases for 'deg'.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.18.1.1 2018/01/10 08:33:04 mcalabre Exp mcalabre $
d179 1
a179 1
=     deg        degree, degrees, Deg, Degree, Degrees, DEG, DEGREE, DEGREES
@


5.17
log
@WCSLIB 5.17
@
text
@d3 2
a4 2
  WCSLIB 5.17 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2017, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 5.16.1.1 2017/01/15 04:28:59 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.17 - C routines that implement the FITS World Coordinate System
@


5.17.1.1
log
@WCSLIB 5.17 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.17 2017/09/18 08:44:23 mcalabre Exp $
@


5.17.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2018, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 5.17.1.1 2017/09/18 08:45:59 mcalabre Exp mcalabre $
@


5.16
log
@WCSLIB 5.16
@
text
@d3 1
a3 1
  WCSLIB 5.16 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.15.1.2 2017/01/15 04:14:00 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.16 - C routines that implement the FITS World Coordinate System
@


5.16.1.1
log
@WCSLIB 5.16 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.16 2017/01/15 04:25:01 mcalabre Exp $
@


5.15
log
@WCSLIB 5.15
@
text
@d3 2
a4 2
  WCSLIB 5.15 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2016, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 5.14.1.1 2016/02/07 10:52:44 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.15 - C routines that implement the FITS World Coordinate System
@


5.15.1.1
log
@WCSLIB 5.15 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.15 2016/04/05 12:55:10 mcalabre Exp $
@


5.15.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2017, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 5.15.1.1 2016/04/05 12:58:35 mcalabre Exp mcalabre $
@


5.14
log
@WCSLIB 5.14
@
text
@d3 1
a3 1
  WCSLIB 5.14 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.13.1.1 2016/01/26 08:54:32 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.14 - C routines that implement the FITS World Coordinate System
@


5.14.1.1
log
@WCSLIB 5.14 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.14 2016/02/07 10:49:31 mcalabre Exp $
@


5.13
log
@WCSLIB 5.13
@
text
@d3 1
a3 1
  WCSLIB 5.13 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.12.1.2 2016/01/25 05:17:04 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.13 - C routines that implement the FITS World Coordinate System
@


5.13.1.1
log
@WCSLIB 5.13 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.13 2016/01/26 08:51:13 mcalabre Exp $
@


5.12
log
@WCSLIB 5.12
@
text
@d3 2
a4 2
  WCSLIB 5.12 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2015, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 5.11.1.1 2015/10/18 09:16:27 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.12 - C routines that implement the FITS World Coordinate System
@


5.12.1.1
log
@WCSLIB 5.12 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.12 2015/11/15 02:13:00 mcalabre Exp $
@


5.12.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2016, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 5.12.1.1 2015/11/15 02:16:14 mcalabre Exp mcalabre $
@


5.11
log
@WCSLIB 5.11
@
text
@d3 1
a3 1
  WCSLIB 5.11 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.10.1.1 2015/10/09 08:22:35 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.11 - C routines that implement the FITS World Coordinate System
@


5.11.1.1
log
@WCSLIB 5.11 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.11 2015/10/18 09:13:05 mcalabre Exp $
@


5.10
log
@WCSLIB 5.10
@
text
@d3 1
a3 1
  WCSLIB 5.10 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.9.1.1 2015/07/21 09:28:07 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.10 - C routines that implement the FITS World Coordinate System
@


5.10.1.1
log
@WCSLIB 5.10 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.10 2015/10/09 08:19:15 mcalabre Exp $
@


5.9
log
@WCSLIB 5.9
@
text
@d3 1
a3 1
  WCSLIB 5.9 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.8.1.1 2015/07/08 11:07:18 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.9 - C routines that implement the FITS World Coordinate System
@


5.9.1.1
log
@WCSLIB 5.9 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.9 2015/07/21 09:20:01 mcalabre Exp $
@


5.8
log
@WCSLIB 5.8
@
text
@d3 1
a3 1
  WCSLIB 5.8 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.7.1.1 2015/06/29 02:47:24 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.8 - C routines that implement the FITS World Coordinate System
@


5.8.1.1
log
@WCSLIB 5.8 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.8 2015/07/08 11:03:59 mcalabre Exp $
@


5.7
log
@WCSLIB 5.7
@
text
@d3 1
a3 1
  WCSLIB 5.7 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.6.1.1 2015/06/14 07:14:44 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.7 - C routines that implement the FITS World Coordinate System
@


5.7.1.1
log
@WCSLIB 5.7 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.7 2015/06/29 02:44:16 mcalabre Exp $
@


5.6
log
@WCSLIB 5.6
@
text
@d3 1
a3 1
  WCSLIB 5.6 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.5.1.1 2015/05/05 13:21:00 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.6 - C routines that implement the FITS World Coordinate System
@


5.6.1.1
log
@WCSLIB 5.6 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.6 2015/06/14 07:11:24 mcalabre Exp $
@


5.5
log
@WCSLIB 5.5
@
text
@d3 1
a3 1
  WCSLIB 5.5 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.4.1.2 2015/04/23 11:03:11 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.5 - C routines that implement the FITS World Coordinate System
@


5.5.1.1
log
@WCSLIB 5.5 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.5 2015/05/05 13:16:31 mcalabre Exp $
@


5.4
log
@WCSLIB 5.4
@
text
@d3 1
a3 1
  WCSLIB 5.4 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.3.1.1 2015/04/21 02:54:02 mcalabre Exp mcalabre $
d28 3
a30 2
* WCSLIB 5.4 - C routines that implement the FITS World Coordinate System
* (WCS) standard.  Refer to
d32 8
a39 2
*   "Representations of world coordinates in FITS",
*   Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
d44 3
a46 3
*   "Definition of the Flexible Image Transport System (FITS), version 3.0",
*   Pence, W.D., Chiappetti, L., Page, C.G., Shaw, R.A., & Stobie, E. 2010,
*   A&A, 524, A42 - http://dx.doi.org/10.1051/0004-6361/201015362
d50 1
a50 7
* Refer to the README file provided with WCSLIB for an overview of the
* library.
*
*
* Summary of the wcsunits routines
* --------------------------------
* Routines in this suite deal with units specifications and conversions:
@


5.4.1.1
log
@WCSLIB 5.4 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.4 2015/04/21 14:41:05 mcalabre Exp $
@


5.4.1.2
log
@Boilerplate change to the prologue to ensure that references to the WCS
Papers appear in the doxygen manual.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.4.1.1 2015/04/21 14:44:28 mcalabre Exp mcalabre $
d29 1
a29 2
* (WCS) standard.  Refer to the README file provided with WCSLIB for an
* overview of the library.
d31 2
a32 8
*
* Summary of the wcsunits routines
* --------------------------------
* Routines in this suite deal with units specifications and conversions, as
* described in
*
=   "Representations of world coordinates in FITS",
=   Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
d37 3
a39 3
=   "Definition of the Flexible Image Transport System (FITS), version 3.0",
=   Pence, W.D., Chiappetti, L., Page, C.G., Shaw, R.A., & Stobie, E. 2010,
=   A&A, 524, A42 - http://dx.doi.org/10.1051/0004-6361/201015362
d43 7
a49 1
* These routines perform basic units-related operations:
@


5.3
log
@WCSLIB 5.3
@
text
@d3 1
a3 1
  WCSLIB 5.3 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.2.1.1 2015/04/15 12:39:14 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.3 - C routines that implement the FITS World Coordinate System
@


5.3.1.1
log
@WCSLIB 5.3 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.3 2015/04/21 02:50:51 mcalabre Exp $
@


5.2
log
@WCSLIB 5.2
@
text
@d3 1
a3 1
  WCSLIB 5.2 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.1.1.1 2015/04/07 11:01:10 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.2 - C routines that implement the FITS World Coordinate System
@


5.2.1.1
log
@WCSLIB 5.2 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.2 2015/04/15 12:35:07 mcalabre Exp $
@


5.1
log
@WCSLIB 5.1
@
text
@d3 1
a3 1
  WCSLIB 5.1 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 5.0.1.1 2015/04/05 12:28:00 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.1 - C routines that implement the FITS World Coordinate System
@


5.1.1.1
log
@WCSLIB 5.1 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.1 2015/04/07 10:56:36 mcalabre Exp $
@


5.0
log
@WCSLIB 5.0
@
text
@d3 1
a3 1
  WCSLIB 5.0 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 4.25.1.2 2015/01/06 01:01:06 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 5.0 - C routines that implement the FITS World Coordinate System
@


5.0.1.1
log
@WCSLIB 5.0 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 5.0 2015/04/05 12:24:59 mcalabre Exp $
@


4.25
log
@WCSLIB 4.25
@
text
@d3 2
a4 2
  WCSLIB 4.25 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2014, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 4.24.1.1 2014/09/18 15:28:09 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.25 - C routines that implement the FITS World Coordinate System
@


4.25.1.1
log
@WCSLIB 4.25 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.25 2014/12/14 14:29:36 mcalabre Exp $
@


4.25.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2015, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 4.25.1.1 2014/12/14 14:32:45 mcalabre Exp mcalabre $
@


4.24
log
@WCSLIB 4.24
@
text
@d3 1
a3 1
  WCSLIB 4.24 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 4.23.1.1 2014/05/13 05:53:49 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.24 - C routines that implement the FITS World Coordinate System
@


4.24.1.1
log
@WCSLIB 4.24 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.24 2014/09/18 15:25:00 mcalabre Exp $
@


4.23
log
@WCSLIB 4.23
@
text
@d3 1
a3 1
  WCSLIB 4.23 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 4.22.1.1 2014/04/12 15:06:32 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.23 - C routines that implement the FITS World Coordinate System
@


4.23.1.1
log
@WCSLIB 4.23 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.23 2014/05/13 05:50:51 mcalabre Exp $
@


4.22
log
@WCSLIB 4.22
@
text
@d3 1
a3 1
  WCSLIB 4.22 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 4.21.1.1 2014/03/24 05:15:28 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.22 - C routines that implement the FITS World Coordinate System
@


4.22.1.1
log
@WCSLIB 4.22 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.22 2014/04/12 15:03:52 mcalabre Exp $
@


4.21
log
@WCSLIB 4.21
@
text
@d3 1
a3 1
  WCSLIB 4.21 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 4.20.1.2 2014/03/21 06:32:19 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.21 - C routines that implement the FITS World Coordinate System
@


4.21.1.1
log
@WCSLIB 4.21 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.21 2014/03/24 05:12:27 mcalabre Exp $
@


4.20
log
@WCSLIB 4.20
@
text
@d3 2
a4 2
  WCSLIB 4.20 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2013, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 4.19.1.3 2013/12/17 14:58:48 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.20 - C routines that implement the FITS World Coordinate System
@


4.20.1.1
log
@WCSLIB 4.20 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.20 2013/12/18 05:42:49 mcalabre Exp $
@


4.20.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2014, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 4.20.1.1 2013/12/18 05:46:55 mcalabre Exp mcalabre $
@


4.19
log
@WCSLIB 4.19
@
text
@d3 1
a3 1
  WCSLIB 4.19 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 4.18.1.1 2013/07/13 10:02:37 mcalabre Exp mcalabre $
d28 1
a28 1
* WCSLIB 4.19 - C routines that implement the FITS World Coordinate System
d37 3
a39 2
*   "Definition of The Flexible Image Transport System (FITS)",
*   Hanisch, R.J., Farris, A., Greisen, E.W., et al. 2001, A&A, 376, 359
d41 1
a41 2
* which formalizes NOST 100-2.0, a document produced by the NASA/Science
* Office of Standards and Technology, see http://fits.gsfc.nasa.gov.
d161 1
a161 1
*                             or not (see notes).
@


4.19.1.1
log
@WCSLIB 4.19 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.19 2013/09/29 14:17:51 mcalabre Exp $
@


4.19.1.2
log
@Updated the reference for the published FITS definition.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.19.1.1 2013/09/29 14:20:38 mcalabre Exp mcalabre $
d37 2
a38 3
*   "Definition of the Flexible Image Transport System (FITS), version 3.0",
*   Pence, W.D., Chiappetti, L., Page, C.G., Shaw, R.A., & Stobie, E. 2010,
*   A&A, 524, A42 - http://dx.doi.org/10.1051/0004-6361/201015362
d40 2
a41 1
* See also http://fits.gsfc.nasa.gov
@


4.19.1.3
log
@Trivial formatting.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.19.1.2 2013/12/17 14:54:43 mcalabre Exp mcalabre $
d161 1
a161 1
*                            or not (see notes).
@


4.18
log
@WCSLIB 4.18
@
text
@d3 1
a3 1
  WCSLIB 4.18 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 4.17.1.1 2013/01/29 05:32:32 cal103 Exp cal103 $
d28 1
a28 1
* WCSLIB 4.18 - C routines that implement the FITS World Coordinate System
@


4.18.1.1
log
@WCSLIB 4.18 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.18 2013/07/13 10:00:04 mcalabre Exp $
@


4.17
log
@WCSLIB 4.17
@
text
@d3 1
a3 1
  WCSLIB 4.17 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 4.16.1.3 2013/01/29 05:09:44 cal103 Exp cal103 $
d28 1
a28 1
* WCSLIB 4.17 - C routines that implement the FITS World Coordinate System
@


4.17.1.1
log
@WCSLIB 4.17 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.17 2013/01/29 05:29:20 cal103 Exp $
@


4.16
log
@WCSLIB 4.16
@
text
@d3 2
a4 2
  WCSLIB 4.16 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2012, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 4.15.1.1 2012/09/26 14:27:51 cal103 Exp cal103 $
d28 1
a28 1
* WCSLIB 4.16 - C routines that implement the FITS World Coordinate System
d396 2
a397 2
int wcsulexe(const char unitstr[], int *func, double *scale, double units[],
             struct wcserr **err);
d403 2
a404 1
int wcsulex(const char unitstr[], int *func, double *scale, double units[]);
@


4.16.1.1
log
@WCSLIB 4.16 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.16 2012/11/07 04:42:44 cal103 Exp $
@


4.16.1.2
log
@Indicate the expected size of the array, units[WCSUNITS_NTYPE], in the
function prototype for wcsulexe() and wcsulex().
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.16.1.1 2012/11/07 04:45:56 cal103 Exp cal103 $
d396 2
a397 2
int wcsulexe(const char unitstr[], int *func, double *scale,
             double units[WCSUNITS_NTYPE], struct wcserr **err);
d403 1
a403 2
int wcsulex(const char unitstr[], int *func, double *scale,
            double units[WCSUNITS_NTYPE]);
@


4.16.1.3
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2013, Mark Calabretta
d25 1
a25 1
  $Id: wcsunits.h,v 4.16.1.2 2012/11/28 13:04:03 cal103 Exp cal103 $
@


4.15
log
@WCSLIB 4.15
@
text
@d3 1
a3 1
  WCSLIB 4.15 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 4.14.1.2 2012/09/26 07:53:12 cal103 Exp cal103 $
d28 1
a28 1
* WCSLIB 4.15 - C routines that implement the FITS World Coordinate System
@


4.15.1.1
log
@WCSLIB 4.15 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.15 2012/09/26 14:26:05 cal103 Exp $
@


4.14
log
@WCSLIB 4.14
@
text
@d3 1
a3 1
  WCSLIB 4.14 - an implementation of the FITS WCS standard.
d25 1
a25 1
  $Id: wcsunits.h,v 4.13.1.2 2012/07/13 03:34:20 cal103 Exp cal103 $
d28 1
a28 1
* WCSLIB 4.14 - C routines that implement the FITS World Coordinate System
d101 2
a102 1
*                       not desired.
d151 2
a152 1
*                       not desired.
d245 2
a246 1
*                       not desired.
@


4.14.1.1
log
@WCSLIB 4.14 development branch.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.14 2012/07/13 10:02:27 cal103 Exp $
@


4.14.1.2
log
@In the prologue of wcsunitse(), wcsutrne(), and wcsulexe(), advise that
the user is responsible for deleting the memory allocated for the
wcserr struct.
@
text
@d25 1
a25 1
  $Id: wcsunits.h,v 4.14.1.1 2012/07/13 10:04:44 cal103 Exp cal103 $
d101 1
a101 2
*                       not desired.  Otherwise, the user is responsible for
*                       deleting the memory allocated for the wcserr struct.
d150 1
a150 2
*                       not desired.  Otherwise, the user is responsible for
*                       deleting the memory allocated for the wcserr struct.
d243 1
a243 2
*                       not desired.  Otherwise, the user is responsible for
*                       deleting the memory allocated for the wcserr struct.
@


4.13
log
@WCSLIB 4.13
@
text
@d3 1
a3 1
  WCSLIB 4.13 - an implementation of the FITS WCS standard.
d19 1
a19 1
  along with WCSLIB.  If not, see <http://www.gnu.org/licenses/>.
d21 5
a25 11
  Correspondence concerning WCSLIB may be directed to:
    Internet email: mcalabre@@atnf.csiro.au
    Postal address: Dr. Mark Calabretta
                    Australia Telescope National Facility, CSIRO
                    PO Box 76
                    Epping NSW 1710
                    AUSTRALIA

  Author: Mark Calabretta, Australia Telescope National Facility
  http://www.atnf.csiro.au/~mcalabre/index.html
  $Id: wcsunits.h,v 4.12.1.1 2012/02/29 07:59:10 cal103 Exp cal103 $
d28 1
a28 1
* WCSLIB 4.13 - C routines that implement the FITS World Coordinate System
@


4.13.1.1
log
@WCSLIB 4.13 development branch.
@
text
@d31 1
a31 1
  $Id: wcsunits.h,v 4.13 2012/03/14 07:39:30 cal103 Exp $
@


4.13.1.2
log
@Changed contact details.
@
text
@d19 1
a19 1
  along with WCSLIB.  If not, see http://www.gnu.org/licenses.
d21 11
a31 5
  Direct correspondence concerning WCSLIB to mark@@calabretta.id.au

  Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
  http://www.atnf.csiro.au/people/Mark.Calabretta
  $Id: wcsunits.h,v 4.13.1.1 2012/03/14 07:40:37 cal103 Exp cal103 $
@


4.12
log
@WCSLIB 4.12
@
text
@d3 1
a3 1
  WCSLIB 4.12 - an implementation of the FITS WCS standard.
d31 1
a31 1
  $Id: wcsunits.h,v 4.11.1.1 2012/02/20 23:31:13 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.12 - C routines that implement the FITS World Coordinate System
@


4.12.1.1
log
@WCSLIB 4.12 development branch.
@
text
@d31 1
a31 1
  $Id: wcsunits.h,v 4.12 2012/02/29 07:57:56 cal103 Exp $
@


4.11
log
@WCSLIB 4.11
@
text
@d3 1
a3 1
  WCSLIB 4.11 - an implementation of the FITS WCS standard.
d31 1
a31 1
  $Id: wcsunits.h,v 4.10.1.1 2012/02/05 23:42:46 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.11 - C routines that implement the FITS World Coordinate System
@


4.11.1.1
log
@WCSLIB 4.11 development branch.
@
text
@d31 1
a31 1
  $Id: wcsunits.h,v 4.11 2012/02/20 23:30:02 cal103 Exp $
@


4.10
log
@WCSLIB 4.10
@
text
@d3 1
a3 1
  WCSLIB 4.10 - an implementation of the FITS WCS standard.
d31 1
a31 1
  $Id: wcsunits.h,v 4.9.1.1 2012/01/24 05:41:45 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.10 - C routines that implement the FITS World Coordinate System
@


4.10.1.1
log
@WCSLIB 4.10 development branch.
@
text
@d31 1
a31 1
  $Id: wcsunits.h,v 4.10 2012/02/05 23:41:44 cal103 Exp $
@


4.9
log
@WCSLIB 4.9
@
text
@d3 1
a3 1
  WCSLIB 4.9 - an implementation of the FITS WCS standard.
d31 1
a31 1
  $Id: wcsunits.h,v 4.8.1.2 2012/01/24 05:23:06 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.9 - C routines that implement the FITS World Coordinate System
@


4.9.1.1
log
@WCSLIB 4.9 development branch.
@
text
@d31 1
a31 1
  $Id: wcsunits.h,v 4.9 2012/01/24 05:40:29 cal103 Exp $
@


4.8
log
@WCSLIB 4.8
@
text
@d3 2
a4 2
  WCSLIB 4.8 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2011, Mark Calabretta
d31 1
a31 1
  $Id: wcsunits.h,v 4.7.1.4 2011/08/10 06:52:12 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.8 - C routines that implement the FITS World Coordinate System
@


4.8.1.1
log
@WCSLIB 4.8 development branch.
@
text
@d31 1
a31 1
  $Id: wcsunits.h,v 4.8 2011/08/15 08:05:53 cal103 Exp $
@


4.8.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2012, Mark Calabretta
d31 1
a31 1
  $Id: wcsunits.h,v 4.8.1.1 2011/08/15 08:07:06 cal103 Exp cal103 $
@


4.7
log
@WCSLIB 4.7
@
text
@d3 1
a3 1
  WCSLIB 4.7 - an implementation of the FITS WCS standard.
d31 1
a31 1
  $Id: wcsunits.h,v 4.6.1.2 2011/01/14 06:33:16 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.7 - C routines that implement the FITS World Coordinate System
d57 1
a57 1
*   - wcsunits(): given two unit specifications, derive the conversion from
d60 2
a61 2
*   - wcsutrn(): translates certain commonly used but non-standard unit
*     strings.  It is intended to be called before wcsulex() which only
d64 1
a64 1
*   - wcsulex(): parses a standard FITS units specification of arbitrary
d68 6
a73 3
* wcsunits() - FITS units specification conversion
* ------------------------------------------------
* wcsunits() derives the conversion from one system of units to another.
d94 1
a94 1

d103 6
d112 1
a112 1
*                        1-9: Status return from wcsulex().
d119 4
a122 4
* wcsutrn() - Translation of non-standard unit specifications
* -----------------------------------------------------------
* wcsutrn() translates certain commonly used but non-standard unit strings,
* e.g. "DEG", "MHZ", "KELVIN", that are not recognized by wcsulex(), refer to
d126 2
d152 6
d202 1
a202 1
*   are recognized by wcsulex() itself as an unofficial extension of the
d206 3
a208 3
* wcsulex() - FITS units specification parser
* -------------------------------------------
* wcsulex() parses a standard FITS units specification of arbitrary
d213 2
d245 6
d268 1
a268 1
*   1: wcsulex() is permissive in accepting whitespace in all contexts in a
d304 1
a304 1
* wcsulex():
d326 1
a326 1
* Names for the units (SI) to match the units vector returned by wcsulex():
d343 2
d352 18
d394 9
a404 1

a405 1

a407 1

@


4.7.1.1
log
@WCSLIB 4.7 development branch.
@
text
@d31 1
a31 1
  $Id: wcsunits.h,v 4.7 2011/02/07 07:03:42 cal103 Exp $
@


4.7.1.2
log
@Added error messaging based on wcserr.  Changes supplied by Michael
Droettboom (STScI) with respect to the released WCSLIB 4.7 sources.
@
text
@a71 4
* An alternate form of this function, wcsunits_err(), has an additional
* wcserr* parameter for retrieving detailed error messages.  See
* wcserr.h for more information.
* 
a116 4
* An alternate form of this function, wcsutrn_err(), has an additional
* wcserr* parameter for retrieving detailed error messages.  See
* wcserr.h for more information.
* 
d140 1
a140 1
*                       
a195 4
* An alternate form of this function, wcsulex_err(), has an additional
* wcserr* parameter for retrieving detailed error messages.  See
* wcserr.h for more information.
* 
d225 1
a225 1
*                       
a317 2
#include "wcserr.h"

a324 16
enum wcsunits_errmsg_enum {
  UNITSERR_SUCCESS            = 0, /* Success */
  UNITSERR_BAD_NUM_MULTIPLIER = 1, /* Invalid numeric multiplier */
  UNITSERR_DANGLING_BINOP     = 2, /* Dangling binary operator */
  UNITSERR_BAD_INITIAL_SYMBOL = 3, /* Invalid symbol in INITIAL context */
  UNITSERR_FUNCTION_CONTEXT   = 4, /* Function in invalid context */
  UNITSERR_BAD_EXPON_SYMBOL   = 5, /* Invalid symbol in EXPON context */
  UNITSERR_UNBAL_BRACKET      = 6, /* Unbalanced bracket */
  UNITSERR_UNBAL_PAREN        = 7, /* Unbalanced parenthesis */
  UNITSERR_CONSEC_BINOPS      = 8, /* Consecutive binary operators */
  UNITSERR_PARSER_ERROR       = 9, /* Internal parser error */
  UNITSERR_BAD_UNIT_SPEC      = 10,/* Non-conformant unit specifications */
  UNITSERR_BAD_FUNCS          = 11,/* Non-conformant functions */
  UNITSERR_UNSAFE_TRANS       = 12 /* Potentially unsafe translation */
};

a351 3
int wcsunits_err(const char have[], const char want[], double *scale,
                 double *offset, double *power, struct wcserr *err);
  
a353 2
int wcsutrn_err(int ctrl, char unitstr[], struct wcserr *err);
  
d356 1
a356 3
int wcsulex_err(const char unitstr[], int *func, double *scale, double units[],
                struct wcserr *err);
  
@


4.7.1.3
log
@Revised implementation of Michael Droettboom's error messaging system.
@
text
@d31 1
a31 1
  $Id: wcsunits.h,v 4.7.1.1 2011/02/07 07:04:22 cal103 Exp cal103 $
d57 1
a57 1
*   - wcsunitse(): given two unit specifications, derive the conversion from
d60 2
a61 2
*   - wcsutrne(): translates certain commonly used but non-standard unit
*     strings.  It is intended to be called before wcsulexe() which only
d64 1
a64 1
*   - wcsulexe(): parses a standard FITS units specification of arbitrary
d68 8
a75 7
* wcsunitse() - FITS units specification conversion
* -------------------------------------------------
* wcsunitse() derives the conversion from one system of units to another.
*
* A deprecated form of this function, wcsunits(), lacks the wcserr**
* parameter.
*
d95 1
a95 1
*
a103 5
*   err       struct wcserr **
*                       For function return values > 1, this struct will
*                       contain a detailed error message.  May be NULL if an
*                       error message is not desired.
*
d107 1
a107 1
*                        1-9: Status return from wcsulexe().
d114 4
a117 4
* wcsutrne() - Translation of non-standard unit specifications
* ------------------------------------------------------------
* wcsutrne() translates certain commonly used but non-standard unit strings,
* e.g. "DEG", "MHZ", "KELVIN", that are not recognized by wcsulexe(), refer to
d121 4
a124 2
* A deprecated form of this function, wcsutrn(), lacks the wcserr** parameter.
*
d148 1
a148 6
*
*   err       struct wcserr **
*                       When the return value >= 2, this structure will
*                       contain a detailed error message.  May be NULL if an
*                       error message is not desired.
*
d193 1
a193 1
*   are recognized by wcsulexe() itself as an unofficial extension of the
d197 3
a199 3
* wcsulexe() - FITS units specification parser
* --------------------------------------------
* wcsulexe() parses a standard FITS units specification of arbitrary
d204 4
a207 2
* A deprecated form of this function, wcsulex(), lacks the wcserr** parameter.
*
d237 1
a237 6
*
*   err       struct wcserr **
*                       When the return value >= 2, this structure will
*                       contain a detailed error message.  May be NULL if an
*                       error message is not desired.
*
d255 1
a255 1
*   1: wcsulexe() is permissive in accepting whitespace in all contexts in a
d291 1
a291 1
* wcsulexe():
d313 1
a313 1
* Names for the units (SI) to match the units vector returned by wcsulexe():
d340 13
a352 15
  UNITSERR_SUCCESS            =  0,	/* Success. */
  UNITSERR_BAD_NUM_MULTIPLIER =  1,	/* Invalid numeric multiplier. */
  UNITSERR_DANGLING_BINOP     =  2,	/* Dangling binary operator. */
  UNITSERR_BAD_INITIAL_SYMBOL =  3,	/* Invalid symbol in INITIAL
					   context. */
  UNITSERR_FUNCTION_CONTEXT   =  4,	/* Function in invalid context. */
  UNITSERR_BAD_EXPON_SYMBOL   =  5,	/* Invalid symbol in EXPON context. */
  UNITSERR_UNBAL_BRACKET      =  6,	/* Unbalanced bracket. */
  UNITSERR_UNBAL_PAREN        =  7,	/* Unbalanced parenthesis. */
  UNITSERR_CONSEC_BINOPS      =  8,	/* Consecutive binary operators. */
  UNITSERR_PARSER_ERROR       =  9,	/* Internal parser error. */
  UNITSERR_BAD_UNIT_SPEC      = 10,	/* Non-conformant unit
					   specifications. */
  UNITSERR_BAD_FUNCS          = 11,	/* Non-conformant functions. */
  UNITSERR_UNSAFE_TRANS       = 12	/* Potentially unsafe translation. */
a378 9
int wcsunitse(const char have[], const char want[], double *scale,
              double *offset, double *power, struct wcserr **err);

int wcsutrne(int ctrl, char unitstr[], struct wcserr **err);

int wcsulexe(const char unitstr[], int *func, double *scale, double units[],
             struct wcserr **err);

/* Deprecated. */
d381 4
d386 3
d391 3
@


4.7.1.4
log
@Clarify that detailed error messages are only returned in wcserr if enabled.
@
text
@d31 1
a31 1
  $Id: wcsunits.h,v 4.7.1.3 2011/08/09 02:43:50 cal103 Exp cal103 $
d104 3
a106 4
*                       If enabled, for function return values > 1, this
*                       struct will contain a detailed error message, see
*                       wcserr_enable().  May be NULL if an error message is
*                       not desired.
d152 3
a154 4
*                       If enabled, for function return values > 1, this
*                       struct will contain a detailed error message, see
*                       wcserr_enable().  May be NULL if an error message is
*                       not desired.
d244 3
a246 4
*                       If enabled, for function return values > 1, this
*                       struct will contain a detailed error message, see
*                       wcserr_enable().  May be NULL if an error message is
*                       not desired.
@


4.6
log
@WCSLIB 4.6
@
text
@d3 2
a4 2
  WCSLIB 4.6 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2010, Mark Calabretta
d31 1
a31 1
  $Id: wcsunits.h,v 4.5.1.1 2010/07/16 07:05:31 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.6 - C routines that implement the FITS World Coordinate System
@


4.6.1.1
log
@WCSLIB 4.6 development branch.
@
text
@d31 1
a31 1
  $Id: wcsunits.h,v 4.6 2010/11/16 06:15:31 cal103 Exp $
@


4.6.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2011, Mark Calabretta
d31 1
a31 1
  $Id: wcsunits.h,v 4.6.1.1 2010/11/16 06:16:19 cal103 Exp cal103 $
@


4.5
log
@WCSLIB 4.5
@
text
@d3 1
a3 1
  WCSLIB 4.5 - an implementation of the FITS WCS standard.
d31 1
a31 1
  $Id: wcsunits.h,v 4.4.1.3 2010/07/07 08:21:53 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.5 - C routines that implement the FITS World Coordinate System
@


4.5.1.1
log
@WCSLIB 4.5 development branch.
@
text
@d31 1
a31 1
  $Id: wcsunits.h,v 4.5 2010/07/16 07:01:25 cal103 Exp $
@


4.4
log
@WCSLIB 4.4
@
text
@d3 2
a4 2
  WCSLIB 4.4 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2009, Mark Calabretta
d31 1
a31 1
  $Id: wcsunits.h,v 4.3.1.3 2009/07/22 05:10:07 cal103 Exp cal103 $
d34 1
a34 1
* WCSLIB 4.4 - C routines that implement the FITS World Coordinate System
d102 4
a105 4
*                           0: Success.
*                         1-9: Status return from wcsulex().
*                          10: Non-conformant unit specifications.
*                          11: Non-conformant functions.
d143 5
a147 5
*                         -1: No change was made, other than stripping blanks
*                             (not an error).
*                          0: Success.
*                          9: Internal parser error.
*                         12: Potentially unsafe translation, whether applied
@


4.4.1.1
log
@WCSLIB 4.4 development branch.
@
text
@d31 1
a31 1
  $Id: wcsunits.h,v 4.4 2009/08/06 07:41:33 cal103 Exp $
@


4.4.1.2
log
@Updated date in copyright notice.
@
text
@d4 1
a4 1
  Copyright (C) 1995-2010, Mark Calabretta
d31 1
a31 1
  $Id: wcsunits.h,v 4.4.1.1 2009/08/10 08:52:49 cal103 Exp cal103 $
@


4.4.1.3
log
@Minor tweaks to indentation for status return values following relaxation
of requirements by doxextr.l.
@
text
@d31 1
a31 1
  $Id: wcsunits.h,v 4.4.1.2 2010/01/19 03:42:50 cal103 Exp cal103 $
d102 4
a105 4
*                          0: Success.
*                        1-9: Status return from wcsulex().
*                         10: Non-conformant unit specifications.
*                         11: Non-conformant functions.
d143 5
a147 5
*                        -1: No change was made, other than stripping blanks
*                            (not an error).
*                         0: Success.
*                         9: Internal parser error.
*                        12: Potentially unsafe translation, whether applied
@


4.3
log
@WCSLIB 4.3
@
text
@d3 2
a4 2
    WCSLIB 4.3 - an implementation of the FITS WCS standard.
    Copyright (C) 1995-2007, Mark Calabretta
d6 1
a6 1
    This file is part of WCSLIB.
d8 24
a31 24
    WCSLIB is free software: you can redistribute it and/or modify it under
    the terms of the GNU Lesser General Public License as published by the
    Free Software Foundation, either version 3 of the License, or (at your
    option) any later version.

    WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
    FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
    more details.

    You should have received a copy of the GNU Lesser General Public License
    along with WCSLIB.  If not, see <http://www.gnu.org/licenses/>.

    Correspondence concerning WCSLIB may be directed to:
       Internet email: mcalabre@@atnf.csiro.au
       Postal address: Dr. Mark Calabretta
                       Australia Telescope National Facility, CSIRO
                       PO Box 76
                       Epping NSW 1710
                       AUSTRALIA

    Author: Mark Calabretta, Australia Telescope National Facility
    http://www.atnf.csiro.au/~mcalabre/index.html
    $Id: wcsunits.h,v 4.2.1.5 2007/12/03 05:02:17 cal103 Exp cal103 $
d34 2
a35 2
*   WCSLIB 4.3 - C routines that implement the FITS World Coordinate System
*   (WCS) standard.  Refer to
d37 2
a38 2
*      "Representations of world coordinates in FITS",
*      Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
d40 2
a41 2
*   The Flexible Image Transport System (FITS), a data format widely used in
*   astronomy for data interchange and archive, is described in
d43 2
a44 2
*      "Definition of The Flexible Image Transport System (FITS)",
*      Hanisch, R.J., Farris, A., Greisen, E.W., et al. 2001, A&A, 376, 359
d46 2
a47 2
*   which formalizes NOST 100-2.0, a document produced by the NASA/Science
*   Office of Standards and Technology, see http://fits.gsfc.nasa.gov.
d49 2
a50 2
*   Refer to the README file provided with WCSLIB for an overview of the
*   library.
d53 3
a55 3
*   Summary of the wcsunits routines
*   --------------------------------
*   Routines in this suite deal with units specifications and conversions:
d57 2
a58 2
*      wcsunits(): given two unit specifications, derive the conversion from
*         one to the other.
d60 3
a62 3
*      wcsutrn(): translates certain commonly used but non-standard unit
*         strings.  It is intended to be called before wcsulex() which only
*         handles standard FITS units specifications.
d64 2
a65 2
*      wcsulex(): parses a standard FITS units specification of arbitrary
*         complexity, deriving the conversion to canonical units.
d68 3
a70 3
*   FITS units specification conversion; wcsunits()
*   -----------------------------------------------
*   wcsunits() derives the conversion from one system of units to another.
d72 6
a77 6
*   Given:
*      have     const char []
*                        FITS units specification to convert from (null-
*                        terminated), with or without surrounding square
*                        brackets (for inline specifications); text following
*                        the closing bracket is ignored.
d79 5
a83 5
*      want     const char []
*                        FITS units specification to convert to (null-
*                        terminated), with or without surrounding square
*                        brackets (for inline specifications); text following
*                        the closing bracket is ignored.
d85 4
a88 6
*   Returned:
*      scale    double*  Convert units using (scale*value + offset)^power.
*      offset   double*  Normally offset == 0.0 except for log() or ln()
*      power    double*  conversions, e.g. log(MHz) to ln(Hz).  Likewise,
*                        power == 1.0 except for exp() conversions, e.g.
*                        exp(ms) to exp(/Hz).
d90 12
a101 2
*   Function return value:
*               int      Status return value:
d103 1
a103 1
*                         1-9: (status return from wcsulex(), see below.)
d107 1
a107 43
*                        scale is zeroed on return if an error occurs.
*
*
*   Translation of non-standard unit specifications; wcsutrn()
*   ----------------------------------------------------------
*   wcsutrn() translates certain commonly used but non-standard unit strings,
*   e.g. "DEG", "MHZ", "KELVIN", that are not recognized by wcsulex().  A full
*   list is given below.  Compounds are also recognized, e.g. "JY/BEAM" and
*   "KM/SEC/SEC".  Extraneous embedded blanks are removed.
*
*   Given:
*      ctrl     int      Although "S" is commonly used to represent seconds,
*                        its translation to "s" is potentially unsafe since
*                        the standard recognizes "S" formally as Siemens,
*                        however rarely that may be used.  The same applies
*                        to "H" for hours (Henry), and "D" for days (Debye).
*                        This bit-flag controls what to do in such cases:
*                           1: Translate "S" to "s".
*                           2: Translate "H" to "h".
*                           4: Translate "D" to "d".
*                        Thus ctrl == 0 doesn't do any unsafe translations,
*                        whereas ctrl == 7 does all of them.
*
*   Given and returned:
*      unitstr  char []  Null-terminated character array containing the units
*                        specification to be translated.
*
*                        Inline units specifications in the comment field of
*                        a FITS header keyrecord are also handled.  If the
*                        first non-blank character in unitstr is '[' then the
*                        unit string is delimited by its matching ']'.  Blanks
*                        preceding '[' will be stripped off, but text
*                        following the closing bracket will be preserved
*                        without modification.
*
*   Function return value:
*               int      Status return value:
*                          -1: No change was made, other than stripping blanks
*                              (not an error).
*                           0: Success.
*                          12: Potentially unsafe translation, whether applied
*                              or not (see above).
*
a108 35
*   FITS units specification parser; wcsulex()
*   ------------------------------------------
*   wcsulex() parses a standard FITS units specification of arbitrary
*   complexity, deriving the scale factor required to convert to canonical
*   units - basically SI with degrees and "dimensionless" additions such as
*   byte, pixel and count.
*
*   Given:
*      unitstr  const char []
*                        Null-terminated character array containing the units
*                        specification, with or without surrounding square
*                        brackets (for inline specifications); text following
*                        the closing bracket is ignored.
*
*   Returned:
*      func     int*     Special function type (see Note 4 below)
*                          0: None
*                          1: log()  ...base 10
*                          2: ln()   ...base e
*                          3: exp()
*
*      scale    double*  Scale factor for the unit specification; multiply a
*                        value expressed in the given units by this factor to
*                        convert it to canonical units.
*
*      units    double[WCSUNITS_NTYPE]
*                        A units specification is decomposed into powers of 17
*                        fundamental unit types: angle, mass, length, time,
*                        count, pixel, etc.  Preprocessor macros are defined
*                        below to dimension this vector and access its
*                        elements.
*
*                        Corresponding character strings, wcsunits_types[] and
*                        wcsunits_units[], are predefined to describe each
*                        quantity and its canonical units.
d110 73
a182 80
*   Function return value:
*               int      Status return value:
*                           0: Success.
*                           1: Invalid numeric multiplier.
*                           2: Dangling binary operator.
*                           3: Invalid symbol in INITIAL context.
*                           4: Function in invalid context.
*                           5: Invalid symbol in EXPON context.
*                           6: Unbalanced bracket.
*                           7: Unbalanced parenthesis.
*                           8: Consecutive binary operators.
*                           9: Internal parser error.
*
*                        scale and units[] are zeroed on return if an error
*                        occurs.
*
*
*   Notes
*   -----
*    1) The parser is permissive in accepting whitespace in all contexts in a
*       units specification where it does not create ambiguity (e.g. not
*       between a metric prefix and a basic unit string), including in strings
*       like "log (m ** 2)" which is formally disallowed.
*
*    2) "angstrom" is allowed here in addition to "Angstrom" (OGIP usage).
*       "ohm"      is allowed here in addition to "Ohm"  (OGIP usage).
*       "Byte"     is allowed here in addition to "byte" (common usage).
*
*    3) Table 6 of WCS Paper I lists eleven units for which metric prefixes
*       are allowed.  However, in this implementation only prefixes greater
*       than unity are allowed for "a" (annum), "yr" (year), "pc" (parsec),
*       "bit", and "byte", and only prefixes less than unity are allowed for
*       "mag" (stellar magnitude).
*
*       Metric prefix "P" (peta) is specifically forbidden for "a" (annum) to
*       avoid confusion with "Pa" (Pascal, not peta-annum).  Note that metric
*       prefixes are specifically disallowed for "h" (hour) and "d" (day) so
*       that "ph" (photons) cannot be interpreted as pico-hours, nor "cd"
*       (candela) as centi-days.
*
*    4) Function types log(), ln() and exp() may only occur at the start of
*       the units specification.  The scale and units[] for these refers to
*       the string inside the function "argument", e.g. to "MHz" in log(MHz)
*       for which a scale of 1e6 will be returned.
*
*
*   Translation of non-standard unit specifications
*   -----------------------------------------------
*   Apart from leading and trailing blanks, a case-sensitive match is required
*   for the aliases listed below, in particular the only recognized aliases
*   with metric prefixes are "KM", "KHZ", "MHZ", and "GHZ".  Potentially
*   unsafe translations of "D", "H", and "S", shown in parentheses, are
*   optional.
*
*     Unit       Recognized aliases
*     ----       -------------------------------------------------------------
*      Angstrom  angstrom
*      arcmin    arcmins, ARCMIN, ARCMINS
*      arcsec    arcsecs, ARCSEC, ARCSECS
*      beam      BEAM
*      byte      Byte
*      d         day, days, (D), DAY, DAYS
*      deg       degree, degrees, DEG, DEGREE, DEGREES
*      GHz       GHZ
*      h         hr, (H), HR
*      Hz        hz, HZ
*      kHz       KHZ
*      Jy        JY
*      K         kelvin, kelvins, Kelvin, Kelvins, KELVIN, KELVINS
*      km        KM
*      m         metre, meter, metres, meters, M, METRE, METER, METRES, METERS
*      min       MIN
*      MHz       MHZ
*      Ohm       ohm
*      Pa        pascal, pascals, Pascal, Pascals, PASCAL, PASCALS
*      pixel     pixels, PIXEL, PIXELS
*      rad       radian, radians, RAD, RADIAN, RADIANS
*      s         sec, second, seconds, (S), SEC, SECOND, SECONDS
*      V         volt, volts, Volt, Volts, VOLT, VOLTS
*      yr        year, years, YR, YEAR, YEARS
d186 1
a186 1
*   standard (see above), but they are converted to the standard form here.
d189 122
a310 4
*   Status return values
*   --------------------
*   Error messages to match the status value returned from each function are
*   encoded in the wcsunits_errmsg character array.
d312 1
d349 6
a354 3
int wcsunits(const char [], const char [], double *, double *, double *);
int wcsutrn(int, char []);
int wcsulex(const char [], int *, double *, double []);
@


4.3.1.1
log
@WCSLIB 4.3 development branch.
@
text
@d3 2
a4 2
    WCSLIB 4.4 - an implementation of the FITS WCS standard.
    Copyright (C) 1995-2008, Mark Calabretta
d31 1
a31 1
    $Id: wcsunits.h,v 4.3 2007/12/27 05:41:36 cal103 Exp cal103 $
d34 1
a34 1
*   WCSLIB 4.4 - C routines that implement the FITS World Coordinate System
@


4.3.1.2
log
@Replaced references to text "above" or "below" with "(see ... above|below)"
so that they can be parsed out of the doxygen markup.
@
text
@d31 1
a31 1
    $Id: wcsunits.h,v 4.3.1.1 2007/12/27 13:23:47 cal103 Exp cal103 $
d95 1
a95 1
*                         1-9: Status return from wcsulex() (see below).
d106 2
a107 2
*   list is elsewhere (see below).  Compounds are also recognized, e.g.
*   "JY/BEAM" and "KM/SEC/SEC".  Extraneous embedded blanks are removed.
d158 1
a158 2
*      func     int*     Special function type, discussed in Note 4 (see
*                        below):
d172 1
a172 1
*                        (see below) to dimension this vector and access its
@


4.3.1.3
log
@Changes required for generation of the manual using doxextr and doxygen,
including naming of arguments in function prototypes.
@
text
@d3 2
a4 2
  WCSLIB 4.4 - an implementation of the FITS WCS standard.
  Copyright (C) 1995-2009, Mark Calabretta
d6 1
a6 1
  This file is part of WCSLIB.
d8 24
a31 24
  WCSLIB is free software: you can redistribute it and/or modify it under the
  terms of the GNU Lesser General Public License as published by the Free
  Software Foundation, either version 3 of the License, or (at your option)
  any later version.

  WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
  more details.

  You should have received a copy of the GNU Lesser General Public License
  along with WCSLIB.  If not, see <http://www.gnu.org/licenses/>.

  Correspondence concerning WCSLIB may be directed to:
    Internet email: mcalabre@@atnf.csiro.au
    Postal address: Dr. Mark Calabretta
                    Australia Telescope National Facility, CSIRO
                    PO Box 76
                    Epping NSW 1710
                    AUSTRALIA

  Author: Mark Calabretta, Australia Telescope National Facility
  http://www.atnf.csiro.au/~mcalabre/index.html
  $Id: wcsunits.h,v 4.3.1.2 2008/04/02 06:17:13 cal103 Exp cal103 $
d34 2
a35 2
* WCSLIB 4.4 - C routines that implement the FITS World Coordinate System
* (WCS) standard.  Refer to
d37 2
a38 2
*   "Representations of world coordinates in FITS",
*   Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
d40 2
a41 2
* The Flexible Image Transport System (FITS), a data format widely used in
* astronomy for data interchange and archive, is described in
d43 2
a44 2
*   "Definition of The Flexible Image Transport System (FITS)",
*   Hanisch, R.J., Farris, A., Greisen, E.W., et al. 2001, A&A, 376, 359
d46 2
a47 2
* which formalizes NOST 100-2.0, a document produced by the NASA/Science
* Office of Standards and Technology, see http://fits.gsfc.nasa.gov.
d49 2
a50 2
* Refer to the README file provided with WCSLIB for an overview of the
* library.
d53 3
a55 3
* Summary of the wcsunits routines
* --------------------------------
* Routines in this suite deal with units specifications and conversions:
d57 2
a58 2
*   - wcsunits(): given two unit specifications, derive the conversion from
*     one to the other.
d60 3
a62 3
*   - wcsutrn(): translates certain commonly used but non-standard unit
*     strings.  It is intended to be called before wcsulex() which only
*     handles standard FITS units specifications.
d64 2
a65 2
*   - wcsulex(): parses a standard FITS units specification of arbitrary
*     complexity, deriving the conversion to canonical units.
d68 3
a70 3
* wcsunits() - FITS units specification conversion
* ------------------------------------------------
* wcsunits() derives the conversion from one system of units to another.
d72 6
a77 6
* Given:
*   have      const char []
*                       FITS units specification to convert from (null-
*                       terminated), with or without surrounding square
*                       brackets (for inline specifications); text following
*                       the closing bracket is ignored.
d79 5
a83 5
*   want      const char []
*                       FITS units specification to convert to (null-
*                       terminated), with or without surrounding square
*                       brackets (for inline specifications); text following
*                       the closing bracket is ignored.
d85 6
a90 4
* Returned:
*   scale,
*   offset,
*   power     double*   Convert units using
d92 8
a99 7
=                         pow(scale*value + offset, power);

*                       Normally offset is zero except for log() or ln()
*                       conversions, e.g. "log(MHz)" to "ln(Hz)".  Likewise,
*                       power is normally unity except for exp() conversions,
*                       e.g. "exp(ms)" to "exp(/Hz)".  Thus conversions
*                       ordinarily consist of
a100 1
=                         value *= scale;
d102 36
a137 2
* Function return value:
*             int       Status return value:
d139 2
a140 3
*                         1-9: Status return from wcsulex().
*                          10: Non-conformant unit specifications.
*                          11: Non-conformant functions.
a141 1
*                       scale is zeroed on return if an error occurs.
d143 36
d180 80
a259 73
* wcsutrn() - Translation of non-standard unit specifications
* -----------------------------------------------------------
* wcsutrn() translates certain commonly used but non-standard unit strings,
* e.g. "DEG", "MHZ", "KELVIN", that are not recognized by wcsulex(), refer to
* the notes below for a full list.  Compounds are also recognized, e.g.
* "JY/BEAM" and "KM/SEC/SEC".  Extraneous embedded blanks are removed.
*
* Given:
*   ctrl      int       Although "S" is commonly used to represent seconds,
*                       its translation to "s" is potentially unsafe since the
*                       standard recognizes "S" formally as Siemens, however
*                       rarely that may be used.  The same applies to "H" for
*                       hours (Henry), and "D" for days (Debye).  This
*                       bit-flag controls what to do in such cases:
*                         1: Translate "S" to "s".
*                         2: Translate "H" to "h".
*                         4: Translate "D" to "d".
*                       Thus ctrl == 0 doesn't do any unsafe translations,
*                       whereas ctrl == 7 does all of them.
*
* Given and returned:
*   unitstr   char []   Null-terminated character array containing the units
*                       specification to be translated.
*
*                       Inline units specifications in the a FITS header
*                       keycomment are also handled.  If the first non-blank
*                       character in unitstr is '[' then the unit string is
*                       delimited by its matching ']'.  Blanks preceding '['
*                       will be stripped off, but text following the closing
*                       bracket will be preserved without modification.
*
* Function return value:
*             int       Status return value:
*                         -1: No change was made, other than stripping blanks
*                             (not an error).
*                          0: Success.
*                          9: Internal parser error.
*                         12: Potentially unsafe translation, whether applied
*                             or not (see notes).
*
* Notes:
*   Translation of non-standard unit specifications: apart from leading and
*   trailing blanks, a case-sensitive match is required for the aliases listed
*   below, in particular the only recognized aliases with metric prefixes are
*   "KM", "KHZ", "MHZ", and "GHZ".  Potentially unsafe translations of "D",
*   "H", and "S", shown in parentheses, are optional.
*
=     Unit       Recognized aliases
=     ----       -------------------------------------------------------------
=     Angstrom   angstrom
=     arcmin     arcmins, ARCMIN, ARCMINS
=     arcsec     arcsecs, ARCSEC, ARCSECS
=     beam       BEAM
=     byte       Byte
=     d          day, days, (D), DAY, DAYS
=     deg        degree, degrees, DEG, DEGREE, DEGREES
=     GHz        GHZ
=     h          hr, (H), HR
=     Hz         hz, HZ
=     kHz        KHZ
=     Jy         JY
=     K          kelvin, kelvins, Kelvin, Kelvins, KELVIN, KELVINS
=     km         KM
=     m          metre, meter, metres, meters, M, METRE, METER, METRES, METERS
=     min        MIN
=     MHz        MHZ
=     Ohm        ohm
=     Pa         pascal, pascals, Pascal, Pascals, PASCAL, PASCALS
=     pixel      pixels, PIXEL, PIXELS
=     rad        radian, radians, RAD, RADIAN, RADIANS
=     s          sec, second, seconds, (S), SEC, SECOND, SECONDS
=     V          volt, volts, Volt, Volts, VOLT, VOLTS
=     yr         year, years, YR, YEAR, YEARS
d263 1
a263 1
*   standard, but they are converted to the standard form here.
d266 4
a269 122
* wcsulex() - FITS units specification parser
* -------------------------------------------
* wcsulex() parses a standard FITS units specification of arbitrary
* complexity, deriving the scale factor required to convert to canonical
* units - basically SI with degrees and "dimensionless" additions such as
* byte, pixel and count.
*
* Given:
*   unitstr   const char []
*                       Null-terminated character array containing the units
*                       specification, with or without surrounding square
*                       brackets (for inline specifications); text following
*                       the closing bracket is ignored.
*
* Returned:
*   func      int*      Special function type, see note 4:
*                         0: None
*                         1: log()  ...base 10
*                         2: ln()   ...base e
*                         3: exp()
*
*   scale     double*   Scale factor for the unit specification; multiply a
*                       value expressed in the given units by this factor to
*                       convert it to canonical units.
*
*   units     double[WCSUNITS_NTYPE]
*                       A units specification is decomposed into powers of 16
*                       fundamental unit types: angle, mass, length, time,
*                       count, pixel, etc.  Preprocessor macro WCSUNITS_NTYPE
*                       is defined to dimension this vector, and others such
*                       WCSUNITS_PLANE_ANGLE, WCSUNITS_LENGTH, etc. to access
*                       its elements.
*
*                       Corresponding character strings, wcsunits_types[] and
*                       wcsunits_units[], are predefined to describe each
*                       quantity and its canonical units.
*
* Function return value:
*             int       Status return value:
*                         0: Success.
*                         1: Invalid numeric multiplier.
*                         2: Dangling binary operator.
*                         3: Invalid symbol in INITIAL context.
*                         4: Function in invalid context.
*                         5: Invalid symbol in EXPON context.
*                         6: Unbalanced bracket.
*                         7: Unbalanced parenthesis.
*                         8: Consecutive binary operators.
*                         9: Internal parser error.
*
*                       scale and units[] are zeroed on return if an error
*                       occurs.
*
* Notes:
*   1: wcsulex() is permissive in accepting whitespace in all contexts in a
*      units specification where it does not create ambiguity (e.g. not
*      between a metric prefix and a basic unit string), including in strings
*      like "log (m ** 2)" which is formally disallowed.
*
*   2: Supported extensions:
*      - "angstrom" (OGIP usage) is allowed in addition to "Angstrom".
*      - "ohm"      (OGIP usage) is allowed in addition to "Ohm".
*      - "Byte"   (common usage) is allowed in addition to "byte".
*
*   3: Table 6 of WCS Paper I lists eleven units for which metric prefixes are
*      allowed.  However, in this implementation only prefixes greater than
*      unity are allowed for "a" (annum), "yr" (year), "pc" (parsec), "bit",
*      and "byte", and only prefixes less than unity are allowed for "mag"
*      (stellar magnitude).
*
*      Metric prefix "P" (peta) is specifically forbidden for "a" (annum) to
*      avoid confusion with "Pa" (Pascal, not peta-annum).  Note that metric
*      prefixes are specifically disallowed for "h" (hour) and "d" (day) so
*      that "ph" (photons) cannot be interpreted as pico-hours, nor "cd"
*      (candela) as centi-days.
*
*   4: Function types log(), ln() and exp() may only occur at the start of the
*      units specification.  The scale and units[] returned for these refers
*      to the string inside the function "argument", e.g. to "MHz" in log(MHz)
*      for which a scale of 1e6 will be returned.
*
*
* Global variable: const char *wcsunits_errmsg[] - Status return messages
* -----------------------------------------------------------------------
* Error messages to match the status value returned from each function.
*
*
* Global variable: const char *wcsunits_types[] - Names of physical quantities
* ----------------------------------------------------------------------------
* Names for physical quantities to match the units vector returned by
* wcsulex():
*   -  0: plane angle
*   -  1: solid angle
*   -  2: charge
*   -  3: mole
*   -  4: temperature
*   -  5: luminous intensity
*   -  6: mass
*   -  7: length
*   -  8: time
*   -  9: beam
*   - 10: bin
*   - 11: bit
*   - 12: count
*   - 13: stellar magnitude
*   - 14: pixel
*   - 15: solar ratio
*   - 16: voxel
*
*
* Global variable: const char *wcsunits_units[] - Names of units
* --------------------------------------------------------------
* Names for the units (SI) to match the units vector returned by wcsulex():
*   -  0: degree
*   -  1: steradian
*   -  2: Coulomb
*   -  3: mole
*   -  4: Kelvin
*   -  5: candela
*   -  6: kilogram
*   -  7: metre
*   -  8: second
a270 1
* The remainder are dimensionless.
d307 3
a309 6
int wcsunits(const char have[], const char want[], double *scale,
             double *offset, double *power);

int wcsutrn(int ctrl, char unitstr[]);

int wcsulex(const char unitstr[], int *func, double *scale, double units[]);
@


4.2
log
@WCSLIB 4.2
@
text
@d2 30
a31 29
*
*   WCSLIB 4.2 - an implementation of the FITS WCS standard.
*   Copyright (C) 1995-2005, Mark Calabretta
*
*   WCSLIB is free software; you can redistribute it and/or modify it under
*   the terms of the GNU General Public License as published by the Free
*   Software Foundation; either version 2 of the License, or (at your option)
*   any later version.
*
*   WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
*   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
*   FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
*   details.
*
*   You should have received a copy of the GNU General Public License along
*   with WCSLIB; if not, write to the Free Software Foundation, Inc.,
*   59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
*
*   Correspondence concerning WCSLIB may be directed to:
*      Internet email: mcalabre@@atnf.csiro.au
*      Postal address: Dr. Mark Calabretta
*                      Australia Telescope National Facility, CSIRO
*                      PO Box 76
*                      Epping NSW 1710
*                      AUSTRALIA
*
*   Author: Mark Calabretta, Australia Telescope National Facility
*   http://www.atnf.csiro.au/~mcalabre/index.html
*   $Id: wcsunits.h,v 4.1 2005/08/25 07:26:29 cal103 Exp cal103 $
d34 1
a34 1
*   WCSLIB 4.2 - C routines that implement the FITS World Coordinate System
d38 1
a38 1
*      Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061
d49 3
d53 2
a54 2
*   Summary of routines
*   -------------------
d127 3
a129 3
*                        a FITS header card are also handled.  If the first
*                        non-blank character in unitstr is '[' then the unit
*                        string is delimited by its matching ']'.  Blanks
d312 1
a312 1
};
@


4.2.1.1
log
@WCSLIB 4.2 development branch.
@
text
@d3 1
a3 1
*   WCSLIB 4.3 - an implementation of the FITS WCS standard.
d30 1
a30 1
*   $Id: wcsunits.h,v 4.2 2005/09/21 13:21:57 cal103 Exp cal103 $
d33 1
a33 1
*   WCSLIB 4.3 - C routines that implement the FITS World Coordinate System
@


4.2.1.2
log
@Removed an extraneous ';' following the closing '}' of the 'extern "C" {'
block provided for use in C++.
@
text
@d4 1
a4 1
*   Copyright (C) 1995-2006, Mark Calabretta
d30 1
a30 1
*   $Id: wcsunits.h,v 4.2.1.1 2005/12/05 02:39:43 cal103 Exp cal103 $
d37 1
a37 1
*      Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
d308 1
a308 1
}
@


4.2.1.3
log
@Replaced use of the obsolete term "card".
@
text
@d4 1
a4 1
*   Copyright (C) 1995-2007, Mark Calabretta
d30 1
a30 1
*   $Id: wcsunits.h,v 4.2.1.2 2006/08/02 00:14:58 cal103 Exp cal103 $
d123 3
a125 3
*                        a FITS header keyrecord are also handled.  If the
*                        first non-blank character in unitstr is '[' then the
*                        unit string is delimited by its matching ']'.  Blanks
@


4.2.1.4
log
@Referenced the README file for an overview of the library.
@
text
@d30 1
a30 1
*   $Id: wcsunits.h,v 4.2.1.3 2007/08/02 04:56:39 cal103 Exp cal103 $
a47 2
*   Refer to the README file provided with WCSLIB for an overview of the
*   library.
d49 2
a50 3
*
*   Summary of the wcsunits routines
*   --------------------------------
@


4.2.1.5
log
@Switched to LGPL 3.0.
@
text
@d2 29
a30 30

    WCSLIB 4.3 - an implementation of the FITS WCS standard.
    Copyright (C) 1995-2007, Mark Calabretta

    This file is part of WCSLIB.

    WCSLIB is free software: you can redistribute it and/or modify it under
    the terms of the GNU Lesser General Public License as published by the
    Free Software Foundation, either version 3 of the License, or (at your
    option) any later version.

    WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
    FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
    more details.

    You should have received a copy of the GNU Lesser General Public License
    along with WCSLIB.  If not, see <http://www.gnu.org/licenses/>.

    Correspondence concerning WCSLIB may be directed to:
       Internet email: mcalabre@@atnf.csiro.au
       Postal address: Dr. Mark Calabretta
                       Australia Telescope National Facility, CSIRO
                       PO Box 76
                       Epping NSW 1710
                       AUSTRALIA

    Author: Mark Calabretta, Australia Telescope National Facility
    http://www.atnf.csiro.au/~mcalabre/index.html
    $Id: wcsunits.h,v 4.2.1.4 2007/08/08 08:40:48 cal103 Exp cal103 $
@


4.1
log
@WCSLIB 4.1: initial revision.
@
text
@d3 1
a3 1
*   WCSLIB 4.1 - an implementation of the FITS WCS standard.
d30 1
a30 1
*   $Id$
d33 1
a33 1
*   WCSLIB 4.1 - C routines that implement the FITS World Coordinate System
@


0.0
log
@Empty revision
@
text
@d1 311
@
