PrayTimes Library - Prayer Times Calculation in C

مكتبة أوقات الصلاة - حساب أوقات الصلاة بلغة C

A complete C implementation of Dr. Hamid Zarrabi-Zadeh's astronomical prayer time calculation algorithm with comprehensive error handling, validation, and bilingual support.

🤖 Note: This project is 100% generated by AI. It demonstrates AI's capability in creating production-ready code with comprehensive testing, documentation, and error handling.

Features

Core Features

• Multiple Calculation Methods: Support for 5 different Islamic calculation methods

  • Umm Al-Qura University (جامعة أم القرى)
  • Muslim World League (رابطة العالم الإسلامي)
  • Islamic Society of North America (جمعية إسلامية)
  • Egyptian General Authority (الهيئة المصرية)
  • Karachi Islamic University (جامعة كراتشي)

• Juristic Schools: Support for different Islamic juristic schools

  • Standard Method (Shafi'i, Maliki, Hanbali) - Shadow length = 1
  • Hanafi Method - Shadow length = 2

• 7 Prayer Times Calculation:

  1. Fajr (الفجر) - Pre-dawn prayer
  2. Sunrise (الشروق) - Sunrise
  3. Dhuhr (الظهر) - Noon prayer
  4. Asr (العصر) - Afternoon prayer
  5. Sunset (الغروب) - Sunset
  6. Maghrib (المغرب) - Evening prayer
  7. Isha (العشاء) - Night prayer

Quality Assurance

• 38 Comprehensive Unit Tests - Full coverage of functionality

  • Input validation tests
  • Calculation accuracy tests
  • Global location tests
  • Error handling tests

• Bilingual Error Messages - Arabic and English support

• Input Validation - Robust validation for all parameters

• Error Handling - Proper error codes and messages

Code Quality

• No External Dependencies - Only standard C library
• Efficient Implementation - Optimized astronomical calculations
• Well-Documented - Bilingual comments in Arabic and English
• Type-Safe - Proper use of enums and error codes

Building the Library

Requirements

• GCC or compatible C compiler
• Make build tool
• Standard C library (libc)
• Math library (libm)

Build Commands

# Build the shared library
make lib

# Build and run unit tests
make run-test

# Build example program
make example

# Debug build (with symbols)
make debug

# Clean all build artifacts
make clean

# Show help
make help

# Show project information
make info

# CI pipeline (clean, build, test)
make ci

Library API

Main Function

/**
 * Calculate prayer times for a given date and location
 *
 * @param year          Year (1900-2100)
 * @param month         Month (1-12)
 * @param day           Day (1-31)
 * @param lat           Latitude (-90 to 90)
 * @param lng           Longitude (-180 to 180)
 * @param timezone      Timezone offset from GMT
 * @param method        Calculation method (CalcMethod enum)
 * @param asr_method    Juristic method for Asr (AsrJuristicMethod enum)
 * @param times_out     Output array of size TIMES_COUNT for results
 *
 * @return Error code (PrayerTimesError)
 */
PrayerTimesError get_prayer_times(int year, int month, int day,
                                   double lat, double lng, double timezone,
                                   CalcMethod method, AsrJuristicMethod asr_method,
                                   double times_out[TIMES_COUNT]);

Helper Functions

/**
 * Convert decimal time to hours and minutes
 * Example: 5.5 becomes 5:30
 *
 * @param decimal_time Decimal time value
 * @param[out] hours   Hours output
 * @param[out] minutes Minutes output
 */
void decimal_to_time(double decimal_time, int* hours, int* minutes);

/**
 * Get error message in specified language
 *
 * @param error    Error code (PrayerTimesError)
 * @param language Language: ERR_LANG_ARABIC or ERR_LANG_ENGLISH
 * @return Error message string
 */
const char* get_error_message(PrayerTimesError error, ErrorMessageLanguage language);

Usage Example

Basic Usage

#include <stdio.h>
#include "include/libpt.h"

int main() {
    // Create array to store prayer times
    double times[TIMES_COUNT];

    // Set date and location (Algiers, Algeria)
    int year = 2026, month = 6, day = 9;
    double lat = 34.6667;   // Latitude
    double lng = 3.25;      // Longitude
    double timezone = 1.0;  // GMT+1

    // Calculate prayer times
    PrayerTimesError err = get_prayer_times(
        year, month, day,
        lat, lng, timezone,
        METHOD_MWL,      // Calculation method
        ASR_STANDARD,    // Juristic method
        times
    );

    // Check for errors
    if (err != PT_SUCCESS) {
        printf("Error: %s\n", get_error_message(err, ERR_LANG_ENGLISH));
        return 1;
    }

    // Display prayer times
    const char *names[TIMES_COUNT] = {
        "Fajr", "Sunrise", "Dhuhr", "Asr",
        "Sunset", "Maghrib", "Isha"
    };

    for (int i = 0; i < TIMES_COUNT; i++) {
        int hours, minutes;
        decimal_to_time(times[i], &hours, &minutes);
        printf("%s: %02d:%02d\n", names[i], hours, minutes);
    }

    return 0;
}

Error Handling

// Example with different error checking
PrayerTimesError err = get_prayer_times(2026, 13, 32, 0, 0, 0,
                                         METHOD_MWL, ASR_STANDARD, times);

if (err != PT_SUCCESS) {
    // Get error message in your preferred language
    printf("English: %s\n", get_error_message(err, ERR_LANG_ENGLISH));
    printf("Arabic:  %s\n", get_error_message(err, ERR_LANG_ARABIC));
}

Enums and Constants

PrayerTimeIndex

typedef enum {
    TIME_FAJR,      // Fajr prayer (0)
    TIME_SUNRISE,   // Sunrise (1)
    TIME_DHUHR,     // Dhuhr prayer (2)
    TIME_ASR,       // Asr prayer (3)
    TIME_SUNSET,    // Sunset (4)
    TIME_MAGHRIB,   // Maghrib prayer (5)
    TIME_ISHA,      // Isha prayer (6)
    TIMES_COUNT     // Array size (7)
} PrayerTimeIndex;

CalcMethod

typedef enum {
    METHOD_UMM_AL_QURA,  // Umm Al-Qura University
    METHOD_MWL,          // Muslim World League
    METHOD_ISNA,         // Islamic Society of North America
    METHOD_EGYPT,        // Egyptian General Authority
    METHOD_KARACHI       // Karachi Islamic University
} CalcMethod;

AsrJuristicMethod

typedef enum {
    ASR_STANDARD,  // Standard: shadow length = 1
    ASR_HANAFI     // Hanafi: shadow length = 2
} AsrJuristicMethod;

ErrorMessageLanguage

typedef enum {
    ERR_LANG_ARABIC,   // Arabic messages
    ERR_LANG_ENGLISH   // English messages
} ErrorMessageLanguage;

PrayerTimesError

typedef enum {
    PT_SUCCESS = 0,            // Operation succeeded
    PT_ERR_INVALID_YEAR,       // Year out of range (1900-2100)
    PT_ERR_INVALID_MONTH,      // Month out of range (1-12)
    PT_ERR_INVALID_DAY,        // Day invalid for month
    PT_ERR_INVALID_LATITUDE,   // Latitude out of range (-90 to 90)
    PT_ERR_INVALID_LONGITUDE,  // Longitude out of range (-180 to 180)
    PT_ERR_INVALID_TIMEZONE,   // Timezone out of range (-12 to 14)
    PT_ERR_NULL_OUTPUT,        // Output array pointer is NULL
    PT_ERR_POLAR_REGION        // Results may be inaccurate in polar regions
} PrayerTimesError;

Testing

Running Tests

# Build and run all tests with results summary
make run-test

# Run only the test executable
./tests/test_libpt

Test Coverage

The test suite (38 tests total) covers:

1. Input Validation (10 tests)

   • Invalid years
   • Invalid months
   • Invalid days
   • Invalid latitude/longitude
   • Invalid timezone
   • NULL output pointer

2. Prayer Times Calculations (8 tests)

   • Calculation accuracy
   • Time ordering verification
   • Reasonable time ranges

3. Calculation Methods (3 tests)

   • Different methods produce different results
   • Method-specific parameters

4. Juristic Schools (2 tests)

   • Hanafi method produces later Asr time
   • Standard method comparison

5. Time Conversion (4 tests)

   • Decimal to time conversion
   • Edge cases and boundaries

6. Global Locations (4 tests)

   • High latitude (London)
   • Equatorial region (Jakarta)
   • Southern hemisphere (Sydney)
   • Medium latitude (Cairo)

7. Error Messages (6 tests)

   • English messages
   • Arabic messages
   • All error types

Project Structure

PrayTimesLibrary/
├── Makefile           # Build system configuration
├── README.md          # This file
├── src/
│   ├── libpt.h        # Header file with API definitions
│   └── libpt.c        # Main library implementation
├── tests/
│   ├── test_libpt.c   # Comprehensive unit tests
│   ├── example.c      # Usage examples
│   └── test_libpt     # Compiled test executable (after make test)
└── bin/
    ├── libpt.so       # Compiled shared library (after make lib)
    └── example        # Compiled example program (after make example)

Mathematical Background

The library implements the astronomical calculations developed by Dr. Hamid Zarrabi-Zadeh, which:

1. Calculates the sun's position on any given date
2. Determines declination and equation of time
3. Computes solar angles for prayer times
4. Adjusts for local timezone and geographic coordinates
5. Handles special cases (polar regions, DST, etc.)

The algorithm is based on:

• Julian Date calculations for precise astronomical positioning
• Analemma equation of time for sun position accuracy
• Geographic coordinate transformation for local calculations

Limitations

• Year range: 1900-2100 (astronomical calculations most accurate in this range)
• High precision for latitudes between -66° and +66° (tropical and temperate zones)
• Results in polar regions (lat > 66°) may be less accurate due to extreme sun angles
• All times are in 24-hour decimal format (0.0-24.0)

Contributing

To contribute improvements:

1. Add test cases for new features
2. Ensure all tests pass: make run-test
3. Follow existing code style and bilingual comments
4. Update documentation

License

MIT / Public Domain - Free for closed-source commercial use

References

• Dr. Hamid Zarrabi-Zadeh's prayer time calculation algorithm
• Islamic astronomical computations and jurisprudence
• Geographic coordinate systems and timezone handling

Support

For issues or questions:

1. Check the test suite for usage examples
2. Review error messages for guidance
3. Refer to the API documentation in header files
4. Examine the example programs

---

Version: 1.0 Language: C (ISO C99 compatible) Last Updated: 2026-06-16